inspect.yaml

openapi: 3.0.0

info:
  title: Inspect-state HTTP API for Cartesi Rollups
  version: 0.6.0
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html

  description: |
    API that allows the DApp frontend to make inspect-state requests to the DApp backend.

paths:
  inspect/{payload}:
    get:
      operationId: inspect
      summary: Inspect DApp state via GET
      description: |
        This method sends an inspect-state request to the DApp backend, passing the payload string in the URL.
        The payload string should be URL-encoded; the inspect server will decode the string to UTF-8.
        If the DApp frontend needs to pass a binary string to the backend then it is advised to use the POST method.

        The response contains a status string and the reports generated by the DApp backend.
        The status string can be either 'accept', 'reject', or 'exception'.
        In case of exception, the field exception_payload will contain the exception payload;
        Otherwise, this field will be null.

        When running on machine mode, the whole Cartesi machine is rolled back after processing the inspect-state request.
        On host mode, it is advised against changing the DApp backend state when processing an inspect-state request.
        Notice that this method is synchronous, so it is not advised to be used for performing resource-intensive operations.

      parameters:
        - in: path
          name: payload
          required: true
          schema:
            type: string

      responses:
        "200":
          description: Inspect state response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InspectResult"

        default:
          description: Error response.
          content:
            text/plain:
              schema:
                $ref: "#/components/schemas/Error"

  inspect:
    post:
      operationId: inspect_post
      summary: Inspect DApp state via POST
      description: |
        Differently from the GET method, the POST method sends an inspect-state request to the DApp backend by passing its payload in the request body.
        The payload should be a binary.
        Other than that, it behaves the same way as described in the GET method.

      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary

      responses:
        "200":
          description: Inspect state response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InspectResult"

        default:
          description: Error response.
          content:
            text/plain:
              schema:
                $ref: "#/components/schemas/Error"

components:
  schemas:
    InspectResult:
      type: object
      properties:
        status:
          $ref: "#/components/schemas/CompletionStatus"
        exception_payload:
          $ref: "#/components/schemas/Payload"
        reports:
          type: array
          items:
            $ref: "#/components/schemas/Report"
        processed_input_count:
          type: integer
          description: Number of processed inputs since genesis
          example: 0
      required:
        - status
        - exception_payload
        - reports
        - processed_input_count

    CompletionStatus:
      type: string
      description: Whether inspection completed or not (and why not)
      enum:
        [
          Accepted,
          Rejected,
          Exception,
          MachineHalted,
          CycleLimitExceeded,
          TimeLimitExceeded,
        ]
      example: "Accepted"

    Payload:
      type: string
      description: |
        Payload in the Ethereum hex binary format.
        The first two characters are '0x' followed by pairs of hexadecimal numbers that correspond to one byte.
        For instance, '0xdeadbeef' corresponds to a payload with length 4 and bytes 222, 173, 190, 175.
        An empty payload is represented by the string '0x'.
      example: "0xdeadbeef"
      pattern: "^0x([0-9a-fA-F]{2})*$"
      format: hex

    Report:
      type: object
      properties:
        payload:
          $ref: "#/components/schemas/Payload"
      required:
        - payload

    Error:
      type: string
      description: Detailed error message.
      example: "The request could not be understood by the server due to malformed syntax"