moda.yaml

openapi: 3.1.0
info:
  title: Moda
  description: A standard Data Availability interface for modular rollup stacks.
  termsOfService: https://github.com/example/repo/TERMS
  contact:
    email: example@example.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.11
servers:
  - url: https://example.com/api/v1
tags:
  - name: /blob
    description: These endpoints are used to submit and retreive blobs.
    externalDocs:
      description: Learn more
      url: https://docs.example.com/
  - name: /batch
    description: These endpoints are used to batch submit and retreive blobs.
    externalDocs:
      description: Learn more
      url: https://docs.example.com/
paths:
  /blob:
    post:
      tags:
        - blob
      summary: Get blob
      description: Get a blob by its identifier.
      operationId: blob
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlobRequest'
            examples:
              celestia:
                $ref: '#/components/examples/BlobIdentifier_celestia'
              ethereum:
                $ref: '#/components/examples/BlobIdentifier_ethereum'
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlobResponse'
              examples:
                celestia:
                  $ref: '#/components/examples/Blob_celestia'
                ethereum:
                  $ref: '#/components/examples/Blob_ethereum'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /blob/commit:
    post:
      description: Commits a blob and return its commitment.
      operationId: commitBlob
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Blob'
            examples:
              celestia:
                $ref: '#/components/examples/Blob_celestia'
              ethereum:
                $ref: '#/components/examples/Blob_ethereum'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlobCommitment'
              examples:
                celestia:
                  $ref: '#/components/examples/BlobCommitment_celestia'
                ethereum:
                  $ref: '#/components/examples/BlobCommitment_ethereum'
          description: Expected response to a valid request
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Commit blob
      tags:
      - blob
  /blob/submit:
    post:
      tags:
        - blob
      summary: Submit blob
      description: Submits a blob and return its identifier.
      operationId: submitBlob
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitBlobRequest'
            examples:
              celestia:
                $ref: '#/components/examples/Blob_celestia'
              ethereum:
                $ref: '#/components/examples/Blob_ethereum'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitBlobResponse'
              examples:
                celestia:
                  $ref: '#/components/examples/SubmitBlobResponse_celestia'
                ethereum:
                  $ref: '#/components/examples/SubmitBlobResponse_ethereum'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /blob/validate:
    post:
      tags:
        - blob
      summary: Validate blob
      description: Validates a blob using its commitment and proof.
      operationId: validateBlob
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                commitment:
                  $ref: '#/components/schemas/BlobCommitment'
                proof:
                  $ref: '#/components/schemas/BlobProof'
              required:
                - commitment
                - proof
            examples:
              celestia:
                $ref: '#/components/examples/BlobValidate_celestia'
              ethereum:
                $ref: '#/components/examples/BlobValidate_ethereum'
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                type: string
                example: 'true'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /batch/blob:
    post:
      tags:
        - batch
      summary: Get blobs
      description: Get multiple blob by their identifiers.
      operationId: blobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/BlobRequest'
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BlobResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /batch/blob/commit:
    post:
      tags:
      - batch
      summary: Commit blobs
      description: Commits multiple blobs and return their commitments.
      operationId: commitBlobs
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Blob'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BlobCommitment'
          description: Expected response to a valid request
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
  /batch/blob/submit:
    post:
      tags:
        - batch
      summary: Submit blobs
      description: Submits multiple blobs and return their identifiers.
      operationId: submitBlobs
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/SubmitBlobRequest'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SubmitBlobResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /batch/blob/validate:
    post:
      tags:
        - batch
      summary: Validate blobs
      description: Validates multiple blobs using their commitments and proofs.
      operationId: validateBlobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  commitment:
                    $ref: '#/components/schemas/BlobCommitment'
                  proof:
                    $ref: '#/components/schemas/BlobProof'
                required:
                  - commitment
                  - proof
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example: ['true']
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Blob:
      description: Blob contains the blob data.
      type: object
      properties:
        data:
          type: string
    BlobIdentifier:
      description: Blob Identifier uniquely identifies the blob along with its block inclusion details.
      type: object
      properties:
        id:
          type: string
    BlobCommitment:
      description: Blob commitment commits to the blob. It does _not_ yet contain block inclusion details.
      type: object
      properties:
        commitment:
          type: string
          description: Commitment to the blob.
    BlobProof:
      description: Blob Proof contains the proof of a submitted blob.
      type: object
      properties:
        proof:
          type: string
          description: Proof of the blob.
    BlobRequest:
      description: A BlobRequest is used to request a blob by its identifier.
      type: object
      properties:
        blob_identifier:
          $ref: '#/components/schemas/BlobIdentifier'
    BlobResponse:
      description: A BlobResponse contains the requested blob with the data.
      type: object
      required:
        - blob
      properties:
        blob:
          $ref: '#/components/schemas/Blob'
    SubmitBlobRequest:
      description: A SubmitBlobRequest is used to submit a blob on the /blob endpoint.
      type: object
      required:
        - blob
      properties:
        blob:
          $ref: '#/components/schemas/Blob'
    SubmitBlobResponse:
      description: A SubmitBlobResponse contains the blob identifier of a submitted blob.
      type: object
      properties:
        blob_identifier:
          $ref: '#/components/schemas/BlobIdentifier'
        proof:
          $ref: '#/components/schemas/BlobProof'
    Error:
      description: >-
        Instead of utilizing HTTP status codes to describe node errors (which
        often do not have a good analog), rich errors are returned using this
        object.
      type: object
      required:
        - code
        - message
        - retriable
      properties:
        code:
          description: >-
            Code is a network-specific error code. If desired, this code can be
            equivalent to an HTTP status code.
          type: integer
          format: int32
          minimum: 0
        message:
          description: Message is a network-specific error message.
          type: string
        retriable:
          description: >-
            An error is retriable if the same request may succeed if submitted
            again.
          type: boolean
  examples:
    Blob_celestia:
      value:
        blob:
          data: aGVsbG8gd29ybGQ=
    Blob_ethereum:
      value:
        blob:
          data: '0x9f2f64008201838c8f859da4b85d16097cde000000100754383749a8ec464a497669b80a231f00'
    BlobCommitment_celestia:
      value:
        commitment:
          commitment: I6VBbcCIpcliy0hYTCLdX13m18ImVdABclJupNGuekrSB
    BlobCommitment_ethereum:
      value:
        commitment:
          commitment: '0x010657f37554c781402a22917dee2f75def7ab966d7b770905398eba3c444014'
    BlobIdentifier_celestia:
      value:
        blob_identifier:
          id: I6VBbcCIpcliy0hYTCLdX13m18ImVdABclJupNGuekrSBAAAAAAAAA==
      summary: celestia blob commitment followed by inclusion height
    BlobIdentifier_ethereum:
      value:
        blob_identifier:
          id: '0x690657f37554c781402a22917dee2f75def7ab966d7b770905398eba3c444014ad10000000000000'
      summary: ethereum block root followed by index
    BlobProof_celestia:
      value: >-
        5b7b227374617274223a362c22656e64223a382c226e6f646573223a5b22414141414141414141414141414141414141
    BlobProof_ethereum:
      value: >-
        9655064c7f1b5dfae71d4c4844ba2ccc7c0751122d510eca1cbd628841cb07e4fa560f720c738b4cdd44b5ad1c8cf481
    BlobValidate_celestia:
      value:
        commitment:
          commitment: I6VBbcCIpcliy0hYTCLdX13m18ImVdABclJupNGuekrSB
        proof:
          proof: 5b7b227374617274223a362c22656e64223a382c226e6f646573223a5b22414141414141414141414141414141414141
    BlobValidate_ethereum:
      value:
        commitment:
          commitment: '0x010657f37554c781402a22917dee2f75def7ab966d7b770905398eba3c444014'
        proof:
          proof: 9655064c7f1b5dfae71d4c4844ba2ccc7c0751122d510eca1cbd628841cb07e4fa560f720c738b4cdd44b5ad1c8cf481
    SubmitBlobResponse_celestia:
      value:
        blob_identifier:
          id: I6VBbcCIpcliy0hYTCLdX13m18ImVdABclJupNGuekrSBAAAAAAAAA==
        proof:
          proof: 5b7b227374617274223a362c22656e64223a382c226e6f646573223a5b22414141414141414141414141414141414141
      summary: celestia blob commitment followed by inclusion height
    SubmitBlobResponse_ethereum:
      value:
        blob_identifier:
          id: '0x690657f37554c781402a22917dee2f75def7ab966d7b770905398eba3c444014ad10000000000000'
        proof:
          proof: 9655064c7f1b5dfae71d4c4844ba2ccc7c0751122d510eca1cbd628841cb07e4fa560f720c738b4cdd44b5ad1c8cf481
      summary: ethereum block root followed by index