commitments-jsonrpc.yml

openapi: 3.0.0

info:
  title: "Commitments API"
  description: |
    JSON-RPC endpoints and schemas for issuing proposer commitments and relevant helper functions.
  version: "v0.0.1 - Ethereum Commitments API Specification v0.0.1"
  contact:
    name: Ethereum Commitments Github
    url: https://github.com/eth-fabric/commitments-specs/issues
  license:
    name: "MIT License and Apache 2.0 License"
    url: "https://github.com/eth-fabric/commitments-specs/"

servers:
  - url: "{server_url}"
    variables:
      server_url:
        description: "Commitments API URL"
        default: "http://localhost/"

tags:
  - name: "Commitments API"
    description: "JSON-RPC endpoints and schemas for issuing proposer commitments and relevant helper functions."

x-constants:
  MAX_CONSTRAINTS_PER_SLOT: 32

x-envelope: "jsonrpc-2.0"

paths:
  /commitmentRequest:
    post:
      operationId: "commitmentRequest"
      tags:
        - Commitments API
      summary: "Request a new SignedCommitment"
      description: |
        JSON-RPC endpoint for requesting a new SignedCommitment.
        
        A `CommitmentRequest` contains an opaque `payload` bytes input that can be decoded according to the `commitment_type`. By making a request, the user / app / wallet is asking for the Gateway to make a commitment that is enforceable via the specified `slasher` contract.

        Each `commitment_type` has its own rules for how a Gateway maps a `CommitmentRequest.payload` to a `Commitment.payload`. The `Commitment.request_hash` field is used to bind the `Commitment` to a specific `CommitmentRequest`, however this is not required to correspond 1:1.

        The `SignedCommitment` is the response to the `CommitmentRequest`. It contains the `Commitment` and the ECDSA signature over the `Commitment`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommitmentRequestInp'
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignedCommitmentOut'
        "400":
          description: "Bad Request - Invalid commitment request"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        "500":
          description: "Internal Server Error"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'

  /commitmentResult:
    post:
      operationId: "commitmentResult"
      tags:
        - Commitments API
      summary: "Request an old SignedCommitment"
      description: |
        JSON-RPC endpoint for retrieving a previously signed commitment.
        
        When supplied with a valid `request_hash`, this endpoint responds with the `SignedCommitment` object containing the same `SignedCommitment.Commitment.request_hash`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommitmentResultInp'
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignedCommitmentOut'
        "404":
          description: "Not Found - No commitment found for the given request hash"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        "500":
          description: "Internal Server Error"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'

  /slots:
    post:
      operationId: "slots"
      tags:
        - Commitments API
      summary: "Get Gateway information for upcoming slots"
      description: |
        JSON-RPC endpoint for retrieving Gateway information for upcoming slots.
        
        When called, the Gateway returns a `SlotInfo` for each upcoming L1 slot in the current or upcoming epoch. 
        Each `SlotInfo` contains a list of `Offering` objects which specify the types of commitments they offer for a given chain, e.g., inclusion preconfs for the L1.
        
        It should be noted that this endpoint does not provide guarantees that the Gateway is actually capable of providing these. 
        For example, for proposer commitments that require delegations, the user should also consult the Constraints API to verify if the Gateway received delegations for the slot in question.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SlotsInp'
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlotInfoResponseOut'
        "500":
          description: "Internal Server Error"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'

  /fee:
    post:
      operationId: "fee"
      tags:
        - Commitments API
      summary: "Get commitment fee information"
      description: |
        JSON-RPC endpoint for retrieving commitment fee information.
        
        Since each proposer commitment protocol may have differing pricing mechanisms, i.e., per-request or subscription based, 
        this endpoint is intentionally left generic. Users submit a `CommitmentRequest` and receive a `FeeInfo` object containing 
        opaque `payload` bytes and a `commitment_type` to decode the `payload` into protocol-specific pricing information.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeeInp'
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeeInfoOut'
        "400":
          description: "Bad Request - Invalid commitment request"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        "500":
          description: "Internal Server Error"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'

components:
  schemas:
    # Input schemas (for request params)
    CommitmentRequestInp:
      type: object
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
          description: JSON-RPC version
          example: "2.0"
        method:
          type: string
          enum: ["commitmentRequest"]
          description: JSON-RPC method name
          example: "commitmentRequest"
        params:
          type: object
          properties:
            commitment_type:
              type: integer
              format: uint64
              description: Type of commitment being requested
              example: 1
            payload:
              type: string
              format: byte
              description: Opaque input bytes used as part of the commitment
              example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
            slasher:
              type: string
              description: Slasher contract for resolving commitment disputes
              example: "0x1234567890123456789012345678901234567890"
          required:
            - commitment_type
            - payload
            - slasher
        id:
          oneOf:
            - type: string
            - type: integer
          description: JSON-RPC request ID
          example: 1
      required:
        - jsonrpc
        - method
        - params
        - id

    CommitmentResultInp:
      type: object
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
          description: JSON-RPC version
          example: "2.0"
        method:
          type: string
          enum: ["commitmentResult"]
          description: JSON-RPC method name
          example: "commitmentResult"
        params:
          type: object
          properties:
            request_hash:
              type: string
              format: bytes32
              description: Hash of the CommitmentRequest to retrieve
              example: "0x1234567890123456789012345678901234567890000000000000000000000000"
          required:
            - request_hash
        id:
          oneOf:
            - type: string
            - type: integer
          description: JSON-RPC request ID
          example: 1
      required:
        - jsonrpc
        - method
        - params
        - id

    SlotsInp:
      type: object
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
          description: JSON-RPC version
          example: "2.0"
        method:
          type: string
          enum: ["slots"]
          description: JSON-RPC method name
          example: "slots"
        params:
          type: object
          description: No parameters required for this method
          example: {}
        id:
          oneOf:
            - type: string
            - type: integer
          description: JSON-RPC request ID
          example: 1
      required:
        - jsonrpc
        - method
        - params
        - id

    FeeInp:
      type: object
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
          description: JSON-RPC version
          example: "2.0"
        method:
          type: string
          enum: ["fee"]
          description: JSON-RPC method name
          example: "fee"
        params:
          type: object
          properties:
            commitment_type:
              type: integer
              format: uint64
              description: Type of commitment being requested
              example: 1
            payload:
              type: string
              format: byte
              description: Opaque input bytes used as part of the commitment
              example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
            slasher:
              type: string
              description: Slasher contract for resolving commitment disputes
              example: "0x1234567890123456789012345678901234567890"
          required:
            - commitment_type
            - payload
            - slasher
        id:
          oneOf:
            - type: string
            - type: integer
          description: JSON-RPC request ID
          example: 1
      required:
        - jsonrpc
        - method
        - params
        - id

    # Output schemas (for response results)
    SignedCommitmentOut:
      type: object
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
          description: JSON-RPC version
          example: "2.0"
        result:
          type: object
          properties:
            commitment:
              type: object
              properties:
                commitment_type:
                  type: integer
                  format: uint64
                  description: The type of commitment being made
                  example: 1
                payload:
                  type: string
                  format: byte
                  description: Opaque payload bytes of the commitment
                  example: "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
                request_hash:
                  type: string
                  format: bytes32
                  description: Hash of the CommitmentRequest this Commitment is for
                  example: "0x1234567890123456789012345678901234567890000000000000000000000000"
                slasher:
                  type: string
                  description: Slasher contract for resolving commitment disputes
                  example: "0x1234567890123456789012345678901234567890"
              required:
                - commitment_type
                - payload
                - request_hash
                - slasher
            signature:
              type: string
              description: The ECDSA signature of the commitment message
              example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b"
          required:
            - commitment
            - signature
        id:
          oneOf:
            - type: string
            - type: integer
          description: JSON-RPC request ID
          example: 1
      required:
        - jsonrpc
        - result
        - id

    SlotInfoResponseOut:
      type: object
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
          description: JSON-RPC version
          example: "2.0"
        result:
          type: object
          properties:
            slots:
              type: array
              items:
                type: object
                properties:
                  slot:
                    type: integer
                    description: The L1 slot number
                    example: 1000
                  offerings:
                    type: array
                    items:
                      type: object
                      properties:
                        chain_id:
                          type: integer
                          format: uint64
                          description: The id of the target chain
                          example: 1
                        commitment_types:
                          type: array
                          items:
                            type: integer
                            format: uint64
                          description: The types of commitments offered for the target chain
                          example: [1, 2]
                      required:
                        - chain_id
                        - commitment_types
                    description: The list of chain offerings
              description: A list of slot infos
          required:
            - slots
        id:
          oneOf:
            - type: string
            - type: integer
          description: JSON-RPC request ID
          example: 1
      required:
        - jsonrpc
        - result
        - id

    FeeInfoOut:
      type: object
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
          description: JSON-RPC version
          example: "2.0"
        result:
          type: object
          properties:
            payload:
              type: string
              format: byte
              description: Opaque bytes containing fee info related to the commitment type
              example: "0xfee1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
            commitment_type:
              type: integer
              format: uint64
              description: Type of commitment being requested
              example: 1
          required:
            - payload
            - commitment_type
        id:
          oneOf:
            - type: string
            - type: integer
          description: JSON-RPC request ID
          example: 1
      required:
        - jsonrpc
        - result
        - id

    ErrorOut:
      type: object
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
          description: JSON-RPC version
          example: "2.0"
        error:
          type: object
          properties:
            code:
              type: integer
              description: JSON-RPC error code
              example: -32602
            message:
              type: string
              description: JSON-RPC error message
              example: "Invalid params"
        id:
          oneOf:
            - type: string
            - type: integer
          description: JSON-RPC request ID
          example: 1
      required:
        - jsonrpc
        - error
        - id