sequencerApi.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://seq.ceremony.ethereum.org
tags:
  - name: Ceremony
    description: Ceremony progress and status
  - name: Lobby
    description: Staging area where participants are waiting for their contribution slot.
  - name: Contribution
    description: Contribution phase
  - name: Login
    description: Authenticates a user and starts a session
paths:
  /info/status:
    get:
      tags:
      - Ceremony
      summary: Get ceremony status
      description: Request a summary of the ceremony status (contributions, lobby size)
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CeremonyStatus'
  /info/current_state:
    get:
      tags:
      - Ceremony
      summary: Request a current transcript
      responses:
        200:
          description: See transcriptSchema.json for more detailed schema definition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchTranscript'
  /contribute:
    post:
      tags:
      - Contribution
      summary: Uploads a contribution
      description:
        Uploads a contribution and returns a signed contribution receipt
        See contributionSchema.json for more detailed schema definition.
      requestBody:
        content:
          application/json:
            schema:
                $ref: '#/components/schemas/BatchContribution'
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContributionReceipt'
        400:
          description: invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContributionError'
      security:
        - BearerAuth: []
  /contribution/abort:
    post:
      tags:
      - Contribution 
      summary: Cancel contribution attempt
      description: | 
        Indicates an error while contributing (e.g. an error when performing
        crypto calculations). Clients should use this endpoint 
        in the event of an unrecoverable error after
        contribution has started to allow other users to participate sooner.
      responses:
        200:
          description: contribution was aborted, another participant will be selected
          content:
            application/json:
              schema:
                type: object
        400:
          description: invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContributionAbortError'
      security:
        - BearerAuth: []
  /lobby/try_contribute:
    post:
      tags:
      - Lobby
      summary: Check-in and request a contribution file
      description: Check-in with the sequencer, thus confirming the client's liveness.
        Response will indicate whether the client should start working on the contribution or continue pining via /lobby/try_contribute all.
      responses:
        200:
          description: Check-in successful. See response to determine if the participant was selected to be a contributor.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/BatchContribution'
                    description: 
                      User was selected for contribution. Use the returned contribution file to calculate participant's points and then post results to /contribute
                      See contributionSchema.json for more detailed schema definition.
                  - type: object
                    properties:
                      error:
                        type: string
                        enum: ["another contribution in progress"]
        400:
          description: rate limited
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum: ["TryContributeError::RateLimited"]
                  error:
                    type: string
                    enum: ["call came too early. rate limited"]
        401:
          description: unauthorized access
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum: ["TryContributeError::UnknownSessionId"]
                  error:
                    type: string
                    enum: ["unknown session id"]
      security:
        - BearerAuth: []
  /auth/request_link:
    get:
      parameters:
        - in: query
          name: redirect_to
          schema:
            type: string
          description: After successful authentication, user will be redirected to {redirect_to}?session_id=xxx&sub=xxx&nickname=xxx&provider=xxx&exp=xxx. Session id can be used as Bearer token for authenticated endpoints."
      tags:
      - Login
      summary: Get links to Ethereum and GitHub login processes
      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:
    BatchContribution:
      type: object
      description: ""
      properties:
        contributions:
          type: array
          items:
            $ref: '#/components/schemas/Contribution'
          minItems: 4
          maxItems: 4
    BatchTranscript:
      type: object
      description: Current transcripts for all 4 sub-ceremonies
      properties:
        transcripts:
          type: array
          items:
            $ref: '#/components/schemas/Transcript'
          minItems: 4
          maxItems: 4
      required:
        - transcripts
    Contribution:
      type: object
      description: ""
      properties:
        numG1Powers:
          type: number
          format: int32
        numG2Powers:
          type: number
          format: int32
        powersOfTau:
          type: object
          properties:
            G1Powers:
              type: array
              items:
                type: string
            G2Powers:
              type: array
              items:
                type: string
          required:
            - G1Powers
            - G2Powers
        potPubkey:
          type: string
      required:
        - numG1Powers
        - numG2Powers
        - powersOfTau
        - potPubkey
    CeremonyStatus:
      type: object
      description: Overall ceremony summary metrics
      properties:
        lobby_size:
          type: number
          format: int32
        num_contributions:
          type: number
          format: int32
        sequencer_address:
          description: Public Ethereum address of sequencer server, uses captitals-based checksum. Can be used to validate contribution receipt signatures.
          type: string
    ContributionAbortError:
      type: object
      description: Contribution couldn't be aborted
      properties:
        code:
          type: string
          enum:
            - SessionError::InvalidSessionId
            - ContributeError::NotUsersTurn
        error:
          type: string
          enum:
            - "invalid Bearer token"
            - "not your turn to participate"
    ContributionError:
      type: object
      description: Contribution couldn't be accepted
      properties:
        code:
          type: string
          enum:
            - SessionError::InvalidSessionId
            - ContributeError::NotUsersTurn
            - CeremoniesError::UnexpectedNumContributions
            - CeremonyError::UnsupportedNumG1Powers
            - CeremonyError::UnsupportedNumG2Powers
            - CeremonyError::UnexpectedNumG1Powers
            - CeremonyError::UnexpectedNumG2Powers
            - CeremonyError::InconsistentNumG2Powers
            - CeremonyError::UnsupportedMoreG2Powers
            - CeremonyError::InvalidG1Power
            - CeremonyError::InvalidG2Power
            - CeremonyError::ParserError
            - CeremonyError::InvalidPubKey
            - CeremonyError::InvalidWitnessProduct
            - CeremonyError::InvalidWitnessPubKey
            - CeremonyError::PubKeyPairingFailed
            - CeremonyError::G1PairingFailed
            - CeremonyError::G2PairingFailed
            - CeremonyError::ZeroPubkey
            - CeremonyError::ZeroG1
            - CeremonyError::ZeroG2
            - CeremonyError::InvalidG1FirstValue
            - CeremonyError::InvalidG2FirstValue
            - CeremonyError::InvalidG1One
            - CeremonyError::InvalidG2One
            - CeremonyError::InvalidG2Pubkey
            - CeremonyError::DuplicateG1
            - CeremonyError::DuplicateG2
            - CeremonyError::ContributionNoEntropy
            - CeremonyError::WitnessLengthMismatch
        error:
          type: string
          enum:
            - "invalid Bearer token"
            - "not your turn to participate"
            - "contribution invalid: Unexpected number of contributions: expected {0}, got {1}"
            - "contribution invalid: Error in contribution {0}: {1}"
    ContributionReceipt:
      type: object
      description: Confirmation that a contribution was received successfully. Participant should keep the receipt to be able to validate that 1) it was signed by the sequencer 2) the contribution was included in the final transcript
      properties:
        receipt:
          type: string
          description: "serialized JSON (to avoid unordered keys) with properties: id_token: { sub: string, nickname: string, provider: string, exp: u64 }, g2: [string] "
        signature:
          type: string
          description: ECDSA eth signature of the receipt string
    Transcript:
      type: object
      description: Current transcript
      properties:
        numG1Powers:
          type: number
          format: int32
        numG2Powers:
          type: number
          format: int32
        powersOfTau:
          type: object
          properties:
            G1Powers:
              type: array
              items:
                type: string
            G2Powers:
              type: array
              items:
                type: string
          required:
            - G1Powers
            - G2Powers
        witness:
          type: object
          properties:
            runningProducts:
              type: array
              items:
                type: string
            potPubkeys:
              type: array
              items:
                type: string
          required:
            - runningProducts
            - potPubkeys
      required:
        - numG1Powers
        - numG2Powers
        - powersOfTau
        - witness
    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
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
    authWithGithub:
      type: apiKey
      name: API_KEY
      in: header
    authWithEth:
      type: oauth2
      description: Firebase OAuth
      flows:
        implicit:
          authorizationUrl: https://us-central1-trustedsetuptest.cloudfunctions.net/Auth-Auth
          scopes: {}