openapi.yml

openapi: 3.0.0
info:
  title: Mantle Data Transport Later
  description: |
    Make sequencer or contract data available behind a common API
  version: 0.1.0
components:
  schemas:
    EthereumContext:
      type: object
      properties:
        blockNumber:
          type: integer
          format: "int64"
        timestamp:
          type: integer
          format: "int64"
        blockHash:
          type: string
    EnqueueEntry:
      type: object
      properties:
        index:
          type: number
        target:
          type: string
        data:
          type: string
        gasLimit:
          type: number
        origin:
          type: string
        blockNumber:
          type: number
        timestamp:
          type: number
        ctcIndex:
          type: number
    BatchEntry:
      type: object
      properties:
        index:
          type: number
        blockNumber:
          type: number
        timestamp:
          type: number
        submitter:
          type: string
        size:
          type: number
        root:
          type: string
        prevTotalElements:
          type: number
        extraData:
          type: string
        l1TransactionHash:
          type: string
    TransactionEntry:
      type: object
      properties:
        index:
          type: number
        batchIndex:
          type: number
        data:
          type: string
        blockNumber:
          type: number
        timestamp:
          type: number
        gasLimit:
          type: number
        target:
          type: string
        origin:
          type: string
        queueOrigin:
          type: string
        queueIndex:
          type: number
        decoded:
          type: object
          $ref: '#/components/schemas/DecodedSequencerBatchTransaction'
    TransactionResponse:
      type: object
      properties:
        batch:
          type: object
          $ref: '#/components/schemas/BatchEntry'
        transaction:
          type: object
          $ref: '#/components/schemas/TransactionEntry'

    TransactionBatchResponse:
      type: object
      properties:
        batch:
          type: object
          $ref: '#/components/schemas/BatchEntry'
        transactions:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/TransactionEntry'

    DecodedSequencerBatchTransaction:
      type: object
      properties:
        sig:
          type: object
          $ref: '#/components/schemas/ECDSASignature'
        gasLimit:
          type: number
        gasPrice:
          type: number
        nonce:
          type: number
        target:
          type: string
        data:
          type: string
    ECDSASignature:
      type: object
      properties:
        r:
          type: string
        s:
          type: string
        v:
          type: number
    StateRootEntry:
      type: object
      properties:
        index:
          type: number
        batchIndex:
          type: number
        value:
          type: string

    StateRootResponse:
      type: object
      properties:
        batch:
          type: object
          $ref: '#/components/schemas/BatchEntry'
        stateRoot:
          type: object
          $ref: '#/components/schemas/StateRootEntry'

    StateRootBatchResponse:
      type: object
      properties:
        batch:
          type: object
          $ref: '#/components/schemas/BatchEntry'
        stateRoots:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/StateRootEntry'

paths:
  /eth/syncing:
    get:
      summary: Returns the sync status
      description: |
        The node may still be syncing to the tip and downstream services can learn up to what
        point has been indexed.
      responses:
        '200':
          description: An object representing the progression of the service
          content:
            application/json:
              schema:
                type: object
                properties:
                  syncing:
                    type: boolean
                  currentTransactionIndex:
                    type: integer
                    format: "int64"
                  highestKnownTransactionIndex:
                    type: integer
                    format: "int64"

  /eth/context/latest:
    get:
      summary: Returns the latest Ethereum Layer one context
      description: |
        This returns the L1 blocknumber, block hash and timestamp corresponding to the most
        recently ingested block
      responses:
        '200':
          description: An object representing the Ethereum context
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EthereumContext'

  /eth/context/blocknumber/{number}:
    get:
      parameters:
        - in: path
          name: number
          schema:
            type: integer
            format: "int64"
          required: true
      summary: Returns the Ethereum Layer one context at a specific height
      description: |
        This returns the L1 blocknumber, block hash and timestamp corresponding to a specific
        Ethereum context
      responses:
        '200':
          description: An object representing the Ethereum context
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EthereumContext'

  /enqueue/latest:
    get:
      summary: Returns the latest enqueued transaction
      description: |
        This returns the latest transaction sent to the Canonical Transaction Chain `enqueue()`
      responses:
        '200':
          description: An object representing the latest enqueued transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnqueueEntry'

  /enqueue/index/{index}:
    get:
      parameters:
        - in: path
          name: index
          schema:
            type: integer
            format: "int64"
          required: true
      summary: Returns the enqueued transaction by index
      description: |
        This returns the Canonical Transaction Chain `enqueue()` by index
      responses:
        '200':
          description: An object representing the enqueued transaction by index
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnqueueEntry'

  /transaction/latest:
    get:
      summary: Returns the latest Canonical Transaction Chain transaction
      description: |
        This returns the latest transaction to be appended to the Canonical Transaction
        Chain via a `sequencerBatchAppend()` or `queueBatchAppend()`
      responses:
        '200':
          description: An object representing the latest transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnqueueEntry'

  /transaction/index/{index}:
    get:
      parameters:
        - in: path
          name: index
          schema:
            type: integer
            format: "int64"
          required: true
      summary: Returns a Canonical Transaction Chain transaction by index
      description: |
        This returns a transaction that has been appended to the Canonical Transaction
        Chain via a `sequencerBatchAppend()` or `queueBatchAppend()` by index
      responses:
        '200':
          description: An object representing a Transaction by index
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResponse'

  /batch/transaction/latest:
    get:
      summary: Returns the latest Batch to be appended to the Canonical Transaction Chain
      description: |
        This returns the latest batch that has been appended to the Canonical Transaction
        Chain via a `sequencerBatchAppend()`
      responses:
        '200':
          description: An object representing the latest batch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionBatchResponse'

  /batch/transaction/index/{index}:
    get:
      parameters:
        - in: path
          name: index
          schema:
            type: integer
            format: "int64"
          required: true
      summary: Returns the Batch to be appended to the Canonical Transaction Chain by index
      description: |
        This returns a batch that has been appended to the Canonical Transaction
        Chain via a `sequencerBatchAppend()` by index
      responses:
        '200':
          description: An object representing the latest batch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionBatchResponse'

  /stateroot/latest:
    get:
      summary: Returns the latest state root
      description: |
        This returns the latest state root appended to the State Commitment Chain
      responses:
        '200':
          description: An object representing the latest state root
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StateRootResponse'

  /stateroot/index/{index}:
    get:
      parameters:
        - in: path
          name: index
          schema:
            type: integer
            format: "int64"
          required: true
      summary: Returns the state root by index
      description: |
        This returns a state root appended to the State Commitment Chain by index
      responses:
        '200':
          description: An object representing the a state root
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StateRootResponse'

  /batch/stateroot/latest:
    get:
      summary: Returns the latest state root batch
      description: |
        This returns the latest batch of state roots appended to the State Commitment Chain
      responses:
        '200':
          description: An object representing the latest state root batch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StateRootBatchResponse'

  /batch/stateroot/index/{index}:
    get:
      summary: Returns the state root batch by index
      parameters:
        - in: path
          name: index
          schema:
            type: integer
            format: "int64"
          required: true
      description: |
        This returns a state root batch appended to the State Commitment Chain by index
      responses:
        '200':
          description: An object representing the state root batch by index
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StateRootBatchResponse'