signer-api.yml

openapi: "3.0.2"
info:
  title: Signer API
  version: "0.1.0"
  description: API that allows commit modules to request generic signatures from validators
tags:
  - name: Signer
  - name: Management
paths:
  /signer/v1/get_pubkeys:
    get:
      summary: Get a list of public keys for which signatures may be requested
      tags:
        - Signer
      security:
        - BearerAuth: []
      responses:
        "200":
          description: "All public keys available to the module: consensus pubkeys (BLS) and proxy pubkeys (BLS and ECDSA)"
          content:
            application/json:
              schema:
                type: object
                properties:
                  keys:
                    description: List of mappings between consensus pubkeys and their proxies
                    type: array
                    items:
                      type: object
                      properties:
                        consensus:
                          description: Consensus validator pubkey
                          $ref: "#/components/schemas/BlsPubkey"
                        proxy_bls:
                          description: BLS proxy validator pubkeys
                          type: array
                          items:
                            $ref: "#/components/schemas/BlsPubkey"
                        proxy_ecdsa:
                          description: ECDSA proxy validator pubkeys
                          type: array
                          items:
                            $ref: "#/components/schemas/EcdsaPubkey"
        "500":
          description: Internal error
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - message
                properties:
                  code:
                    type: number
                    example: 500
                  message:
                    type: string
                    example: "Internal error"

  /signer/v1/request_signature:
    post:
      summary: Send a signature request
      tags:
        - Signer
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [type, pubkey, object_root]
              properties:
                type:
                  description: Type of the sign request
                  type: string
                  enum: [consensus, proxy_bls, proxy_ecdsa]
                pubkey:
                  description: Public key of the validator
                  oneOf:
                    - $ref: "#/components/schemas/BlsPubkey"
                    - $ref: "#/components/schemas/EcdsaPubkey"
                object_root:
                  description: The root of the object to be signed
                  type: string
                  format: hex
                  pattern: "^0x[a-fA-F0-9]{64}$"
                  example: "0x3e9f4a78b5c21d64f0b8e3d9a7f5c02b4d1e67a3c8f29b5d6e4a3b1c8f72e6d9"
            examples:
              Consensus:
                value:
                  type: "consensus"
                  pubkey: "0xa3ffa9241f78279f1af04644cb8c79c2d8f02bcf0e28e2f186f6dcccac0a869c2be441fda50f0dea895cfce2e53f0989"
                  object_root: "0x3e9f4a78b5c21d64f0b8e3d9a7f5c02b4d1e67a3c8f29b5d6e4a3b1c8f72e6d9"
              ProxyBls:
                value:
                  type: "proxy_bls"
                  pubkey: "0xa3ffa9241f78279f1af04644cb8c79c2d8f02bcf0e28e2f186f6dcccac0a869c2be441fda50f0dea895cfce2e53f0989"
                  object_root: "0x3e9f4a78b5c21d64f0b8e3d9a7f5c02b4d1e67a3c8f29b5d6e4a3b1c8f72e6d9"
              ProxyEcdsa:
                value:
                  type: "proxy_ecdsa"
                  pubkey: "0x023b2806b1b1dfa34dd90b01546906cef3e4c8e0fc0cba60480e9eb4d0a0828311"
                  object_root: "0x3e9f4a78b5c21d64f0b8e3d9a7f5c02b4d1e67a3c8f29b5d6e4a3b1c8f72e6d9"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/BlsSignature"
                  - $ref: "#/components/schemas/EcdsaSignature"
              examples:
                Consensus:
                  value: "0xa3ffa9241f78279f1af04644cb8c79c2d8f02bcf0e28e2f186f6dcccac0a869c2be441fda50f0dea895cfce2e53f0989a3ffa9241f78279f1af04644cb8c79c2d8f02bcf0e28e2f186f6dcccac0a869c2be441fda50f0dea895cfce2e53f0989"
                ProxyBls:
                  value: "0xa3ffa9241f78279f1af04644cb8c79c2d8f02bcf0e28e2f186f6dcccac0a869c2be441fda50f0dea895cfce2e53f0989a3ffa9241f78279f1af04644cb8c79c2d8f02bcf0e28e2f186f6dcccac0a869c2be441fda50f0dea895cfce2e53f0989"
                ProxyEcdsa:
                  value: "0xe6a0c0c41a6d4af9794882c18c5280376cbfb7921453612dea02ed8f47b1208455f07931dc12c4b70c4e8ae216db0136000ec2cf17244189f012de356ac46cec"
        "404":
          description: Unknown value (pubkey, etc.)
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - message
                properties:
                  code:
                    type: number
                    example: 404
                  message:
                    type: string
                    example: "Unknown pubkey"
        "500":
          description: Internal error
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - message
                properties:
                  code:
                    type: number
                    example: 500
                  message:
                    type: string
                    example: "Internal error"

  /signer/v1/generate_proxy_key:
    post:
      summary: Request a proxy key be generated for a specific consensus pubkey
      tags:
        - Signer
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [pubkey, scheme]
              properties:
                pubkey:
                  description: a validator BLS public key for which to generate a proxy key
                  allOf:
                    - $ref: "#/components/schemas/BlsPubkey"
                scheme:
                  description: signature scheme to generate proxy keypair for
                  type: string
                  enum: [bls, ecdsa]
            examples:
              Bls:
                value:
                  pubkey: "0xa9e9cff900de07e295a044789fd4bdb6785eb0651ad282f9e76d12afd87e75180bdd64caf2e315b815d7322bd31ab48a"
                  scheme: "bls"
              Ecdsa:
                value:
                  pubkey: "0xa9e9cff900de07e295a044789fd4bdb6785eb0651ad282f9e76d12afd87e75180bdd64caf2e315b815d7322bd31ab48a"
                  scheme: "ecdsa"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: object
                    properties:
                      delegator:
                        description: the validator BLS public key for which the proxy key was generated (the same one as requested)
                        allOf:
                          - $ref: "#/components/schemas/BlsPubkey"
                      proxy:
                        description: the generated proxy public key
                        oneOf:
                          - $ref: "#/components/schemas/BlsPubkey"
                          - $ref: "#/components/schemas/EcdsaPubkey"
                  signature:
                    description: The signature of the proxy delegation
                    allOf:
                      - $ref: "#/components/schemas/BlsSignature"
              examples:
                Bls:
                  value:
                    message:
                      delegator: "0xa9e9cff900de07e295a044789fd4bdb6785eb0651ad282f9e76d12afd87e75180bdd64caf2e315b815d7322bd31ab48a"
                      proxy: "0xb646318d81b7cff3f8aae5040eab11927b4a99542c02970a1ab8069a83e5b76b302705d0b5e0054831ce2af72088bf30"
                    signature: "0x88274f2d78d30ae429cc16f5c64657b491ccf26291c821cf953da34f16d60947d4f245decdce4a492e8d8f949482051b184aaa890d5dd97788387689335a1fee37cbe55c0227f81b073ce6e93b45f96169f497ed322d3d384d79ccaa7846d5ab"
                Ecdsa:
                  value:
                    message:
                      delegator: "0xa9e9cff900de07e295a044789fd4bdb6785eb0651ad282f9e76d12afd87e75180bdd64caf2e315b815d7322bd31ab48a"
                      proxy: "0x023b2806b1b1dfa34dd90b01546906cef3e4c8e0fc0cba60480e9eb4d0a0828311"
                    signature: "0xb5b5b71d1701cc45086af3d3d86bf9d3c509442835e5b9f7734923edc9a6c538e743d70613cdef90b7e5b171fbbe6a29075b3f155e4bd66d81ff9dbc3b6d7fa677d169b2ceab727ffa079a31fe1fc0e478752e9da9566a9408e4db24ac6104db"
        "404":
          description: Unknown value (pubkey, etc.)
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - message
                properties:
                  code:
                    type: number
                    example: 404
                  message:
                    type: string
                    example: "Unknown pubkey"
        "500":
          description: Internal error
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - message
                properties:
                  code:
                    type: number
                    example: 500
                  message:
                    type: string
                    example: "Internal error"

  /status:
    get:
      summary: Get the status of the Signer API module
      tags:
        - Management
      responses:
        "200":
          description: Success
          content:
            text/plain:
              schema:
                type: string
                example: "OK"

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    BlsPubkey:
      type: string
      format: hex
      pattern: "^0x[a-fA-F0-9]{96}$"
      example: "0xa9e9cff900de07e295a044789fd4bdb6785eb0651ad282f9e76d12afd87e75180bdd64caf2e315b815d7322bd31ab48a"
    EcdsaPubkey:
      type: string
      format: hex
      pattern: "^0x[a-fA-F0-9]{66}$"
      example: "0x023b2806b1b1dfa34dd90b01546906cef3e4c8e0fc0cba60480e9eb4d0a0828311"
    BlsSignature:
      type: string
      format: hex
      pattern: "^0x[a-fA-F0-9]{192}$"
      example: "0xa3ffa9241f78279f1af04644cb8c79c2d8f02bcf0e28e2f186f6dcccac0a869c2be441fda50f0dea895cfce2e53f0989a3ffa9241f78279f1af04644cb8c79c2d8f02bcf0e28e2f186f6dcccac0a869c2be441fda50f0dea895cfce2e53f0989"
    EcdsaSignature:
      type: string
      format: hex
      pattern: "^0x[a-fA-F0-9]{128}$"
      example: "0xe6a0c0c41a6d4af9794882c18c5280376cbfb7921453612dea02ed8f47b1208455f07931dc12c4b70c4e8ae216db0136000ec2cf17244189f012de356ac46cec"