clientApi.yml

---
openapi: 3.0.0
info:
  title: Trusted Setup MPC for KZG
  description: |
    Trusted Setup participant API.  This is a draft specification. It is subject to change without notice.
  license:
    name: CC0
    url: http://creativecommons.org/publicdomain/zero/1.0/
  version: 1.0.0
servers:
- url: https://us-central1-trustedsetuptest.cloudfunctions.net
tags:
  - name: Ceremony
    description: Ceremony progress and status
  - name: Queue
    description: Queue management
  - name: Contribution
    description: Contribution phase
  - name: Login
    description: Authenticates a user and starts a session
paths:
  /ceremony/status:
    get:
      tags:
      - Ceremony
      summary: Request a summary of the ceremony status
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CeremonyStatus'
        required: true
      responses:
        400:
          description: Invalid Order
          content:
            application/json:
              schema:
                type: object
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CeremonyStatus'
      security:
      - authWithEth: []
  /queue/leave:
    post:
      tags:
      - Queue
      summary: Request to leave the queue
      description: |
        Requests that the participant's queue position is given up. Only valid for participants who have previously joiined the queue.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Participant'
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: object
  /contribution/complete:
    post:
      tags:
      - Contribution
      summary: Returns a completed contribution
      description: Advises that the computation has completed and returns the updated
        transcript
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contribution'
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: string
  /contribution/abort:
    post:
      tags:
      - Contribution 
      summary: | 
        Indicates an error while contributing. Clients must use this endpoint 
        in the event of an unrecoverable error after
        contribution has started.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Participant'
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContributionStatus'
  /contribution/start:
    post:
      tags:
      - Contribution
      summary: Request prior transcript and start contribution
      description: Advises the participant's readiness to begin the computation. The
        server will verify the participant's eligibility to start, and, if eligible,
        return the last valid transcript.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Participant'
      responses:
        404:
          description: ID not found
          content:
            application/json:
              schema:
                type: object
        400:
          description: Invalid ID supplied
          content:
            application/json:
              schema:
                type: object
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Participant'
  /queue/checkin:
    post:
      tags:
      - Queue
      summary: Check-in and request queue status
      description: Check-in with the coordinator, thus confirming the client's liveness.
        Response will include next check-in time, and a notification to start the
        contribution phase, if the paticipant is at the head of the queue.
      requestBody:
        description: Check in and request my queue status
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParticipantQueueStatus'
        required: true
      responses:
        400:
          description: Invalid
          content:
            application/json:
              schema:
                type: object
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: object
  /queue/join:
    post:
      tags:
      - Queue
      summary: Join a ceremony
      description: Request to join the queue for a ceremony
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Participant'
      responses:
        400:
          description: Invalid status value
          content:
            application/json:
              schema:
                type: object
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ParticipantQueueStatus'
  /login:
    post:
      tags:
      - Login
      summary: Login to begin participation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthRequest'
      responses:
        403:
          description: Invalid HTTP method
          content:
            application/json:
              schema:
                type: object
        401:
          description: |
            Eth address doesn't match message signer, or account nonce is too low
          content:
            application/json:
              schema:
                type: object
        400:
          description: Invalid request. Missing parameters
          content:
            application/json:
              schema:
                type: object
        200:
          description: Successful login
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
components:
  schemas:
    ApiResponse:
      type: object
      properties:
        message:
          type: string
        type:
          type: string
        code:
          type: integer
          format: int32
    ContributionResult:
      required:
      - id
      type: object
      description: |
        The updated SRS
      properties:
        id:
          type: string
        contribution:
          type: object
    CeremonyStatus:
      type: object
      description: Overall ceremony summary metrics
    Contribution:
      type: object
      description: The prior contributor's submission, ready to be updated. Refer
        to contributionSchema.json for the description of this content.
    ContributionStatus:
      required:
      - id
      type: object
      description: |
        Used to report an error while in the computation phase
      properties:
        id:
          type: string
        reason:
          type: string
    ParticipantQueueStatus:
      required:
      - queuePosition
      - nextCheckinTime
      - queueStatus
      - id
      type: object
      description: |
        Status of the participant's queue position, including details of the next expected check-in time
      properties:
        queuePosition:
          type: integer
          format: int32
        nextCheckinTime:
          type: integer
          format: int32
        queueStatus:
          type: string
          enum:
          - notQueued
          - queued
          - readyToContribute
          - contributing
          - expired
        id:
          type: string
    Participant:
      required:
      - idType
      - id
      type: object
      properties:
        idType:
          type: string
          enum:
          - ethAddress
          - ensName
          - githubHandle
        id:
          type: string
    AuthResponse:
      type: object
      description: |
        The response to a successful authorisation request is a JWT token. This token must be retained and used in the header for all subsequent requests requiring authentication. If the  authorisation request is unsuccessful, the response will be a brief message. Response codes are a better indication of the status.
      properties:
        participant:
          type: object
        token:
          type: string
    AuthRequest:
      type: object
      description: |
        A JSON object. The sig property must contain a hex represenation of a message - 'ZKParty sign-in' - signed with the private key for ethAddress using Ethereum standard signing (i.e. the  message is prefixed by \x19Ethereum Signed Message ...) The Eth account must have a nonce >= 3 on mainnet.
      properties:
        sig:
          type: string
        ethAddress:
          type: string
  securitySchemes:
    authWithGithub:
      type: apiKey
      name: API_KEY
      in: header
    authWithEth:
      type: oauth2
      description: Firebase OAuth
      flows:
        clientCredentials:
          authorizationUrl: https://us-central1-trustedsetuptest.cloudfunctions.net/Auth-Auth
...