openapi: 3.0.0
info:
  version: '1.0.0'
  title: 'signup-sequencer'
  license:
    name: MIT
servers:
  - url: http://localhost:8080
paths:
  /metrics:
    servers:
      - url: http://localhost:9998
    get:
      summary: 'Returns Prometheus application metrics'
      responses:
        '200':
          description: 'Sample response: Details about a user by ID'
          content:
            'application/text':
              example: ''
        default:
          description: Unexpected error
  /insertIdentity:
    post:
      summary: 'Queues an insertion of a new identity into the merkle tree'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentityCommitment'
      responses:
        '202':
          description: 'Identity insert was successfully queued'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InclusionProof'
        '400':
          description: 'Invalid request'
          content:
            application/json:
              schema:
                description: 'Could not queue identity for insertion'
                type: 'string'
  /deleteIdentity:
      post:
        summary: 'Queues a specific identity to be deleted from the merkle tree'
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityCommitment'
        responses:
          '202':
            description: 'Identity has been successfully queued for deletion'
          '400':
            description: 'Invalid request'
            content:
              application/json:
                schema:
                  description: 'Identity could not be queued for deletion'
                  type: 'string'
  /inclusionProof:
    post:
      summary: 'Get Merkle inclusion proof'
      requestBody:
        description: 'details of the identity to get the inclusion proof for'
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/IdentityCommitment'
      responses:
        '200':
          description: 'A Merkle inclusion proof for an already inserted commitment'
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/InclusionProof'
        '202':
          description: 'A Merkle inclusion proof for a pending commitment'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InclusionProof'
        '400':
          description: 'Invalid request'
          content:
            application/json:
              schema:
                description: 'Could not get merkle inclusion proof for identity'
                type: 'string'
  /verifySemaphoreProof:
    post:
      summary: Verifies a Semaphore proof
      requestBody:
        description: VerifySemaphoreProof request object
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VerifySemaphoreProofRequest"
      parameters:
        - in: query
          name: maxRootAgeSeconds
          schema:
            type: integer
          description: The max age in seconds of the provided root.
                       If the root is older than this value this endpoint will return an error and a 400 response.
      responses:
        '200':
          description: Valid proof response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VerifySemaphoreProofResponse"
        '400':
          description: Invalid proof or root not found
          content:
            text/plain:
              schema:
                type: string
                example: 'invalid root'
        '500':
          description: Prover error
          content:
            text/plain:
              schema:
                type: string
                example: 'prover error'

components:
  schemas:
    IdentityCommitment:
      type: object
      properties:
        identityCommitment:
          type: string
          pattern: '^[A-F0-9]{64}$'
      example:
        identityCommitment: '0000F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2'
    FieldElement:
      type: string
      pattern: '^0x[a-f0-9]{64}$'
    InclusionProof:
      type: object
      properties:
        status: { $ref: '#/components/schemas/InclusionProofStatus' }
        root: { $ref: '#/components/schemas/FieldElement' }
        proof:
          type: array
          items:
            oneOf:
              - type: object
                properties:
                  Left: { $ref: '#/components/schemas/FieldElement' }
              - type: object
                properties:
                  Right: { $ref: '#/components/schemas/FieldElement' }
    InclusionProofStatus:
      type: string
      enum: [ 'new', 'failed', 'pending', 'mined' ]
    SemaphoreProof:
      type: array
      items:
        oneOf:
          - $ref: '#/components/schemas/G1'
          - $ref: '#/components/schemas/G2'
      minItems: 3
      maxItems: 3
    G1:
      type: array
      items:
        $ref: '#/components/schemas/FieldElement'
      minItems: 2
      maxItems: 2
    G2:
      type: array
      items:
        $ref: '#/components/schemas/G1'
      minItems: 2
      maxItems: 2
    VerifySemaphoreProofRequest:
      type: object
      properties:
        root:
          $ref: '#/components/schemas/FieldElement'
        signalHash:
          $ref: '#/components/schemas/FieldElement'
        nullifierHash:
          $ref: '#/components/schemas/FieldElement'
        externalNullifierHash:
          $ref: '#/components/schemas/FieldElement'
        proof:
          $ref: '#/components/schemas/SemaphoreProof'
      required:
        - root
        - signalHash
        - nullifierHash
        - externalNullifierHash
        - proof
    VerifySemaphoreProofResponse:
      type: object
      properties:
        root:
          type: string
        status:
          $ref: '#/components/schemas/InclusionProofStatus'
        pendingValidAsOf:
          type: string
          format: date-time
        minedValidAsOf:
          type: string
          format: date-time
          nullable: true