openapi.yaml

swagger: '2.0'

info:
  version: "0.8.0"
  title: Sawtooth Lake REST API
  description: |
    _This HTTP pragmatic REST API is built on top of Sawtooth
    Lake's existing ZMQ/Protobuf infrastructure, simplifying client
    interaction with the blockchain by exposing endpoints that
    use common HTTP/JSON standards._

paths:
  /batches:
    post:
      summary: Sends a BatchList to the validator
      description: |
        Accepts a protobuf formatted `BatchList` as an octet-stream binary
        file and submits it to the validator to be committed.

        The API will return immediately with a status of `202`. There will be
        no `data` object, only a `link` to a `/batch_status` endpoint to be
        polled to check the status of submitted batches.
      consumes:
        - application/octet-stream
      parameters:
        - name: BatchList
          in: body
          description: A binary encoded protobuf BatchList
          schema:
            $ref: "#/definitions/BatchList"
          required: true
        - $ref: "#/parameters/wait"
      responses:
        202:
          description: Batches submitted for validation, but not yet committed
          schema:
            properties:
              link:
                $ref: "#/definitions/Link"
        400:
          $ref: "#/responses/400BadRequest"
        500:
          $ref: "#/responses/500ServerError"
        503:
          $ref: "#/responses/503ServiceUnavailable"
    get:
      summary: Fetches a list of batches
      description: >
        Fetches a paginated list of batches from the validator.
      parameters:
        - $ref: "#/parameters/head"
        - $ref: "#/parameters/count"
        - $ref: "#/parameters/min"
        - $ref: "#/parameters/max"
        - $ref: "#/parameters/sort"
      responses:
        200:
          description: Successfully retrieved batches
          schema:
            properties:
              data:
                type: array
                items:
                  $ref: "#/definitions/Batch"
              head:
                $ref: "#/definitions/Head"
              link:
                $ref: "#/definitions/Link"
              paging:
                $ref: "#/definitions/Paging"
        400:
          $ref: "#/responses/400BadRequest"
        500:
          $ref: "#/responses/500ServerError"
        503:
          $ref: "#/responses/503ServiceUnavailable"

  /batches/{batch_id}:
    parameters:
      - $ref: "#/parameters/batch_id"
    get:
      summary: Fetches a particular batch
      responses:
        200:
          description: Successfully retrieved batch
          schema:
            properties:
              data:
                $ref: "#/definitions/Batch"
              head:
                $ref: "#/definitions/Head"
              link:
                $ref: "#/definitions/Link"
        400:
          $ref: "#/responses/400BadRequest"
        404:
          $ref: "#/responses/404NotFound"
        500:
          $ref: "#/responses/500ServerError"
        503:
          $ref: "#/responses/503ServiceUnavailable"

  /batch_status:
    get:
      summary: Fetches the committed statuses for a set of batches
      description: |
        Fetches an array of objects with a status and id for each batch
        requested. There are four possible statuses with string values
        `'COMMITTED'`, `'INVALID'`, `'PENDING'`, and `'UNKNOWN'`.

        The batch(es) you want to check can be specified using the `id` filter
        parameter. If a `wait` time is specified in the url, the API will wait
        to respond until all batches are committed, or the time in seconds has
        elapsed. If the value of `wait` is not set (i.e. `?wait&id=...`), or
        it is set to any non-integer value other than `false`, the wait time
        will be just shy of the api's specified timeout (usually 300).

        Note that as this route does not return full resources, the response
        will not be paginated, and there will be no `head` or `paging`
        properties.
      parameters:
        - name: id
          in: query
          description: A comma-separated list of batch ids
          type: string
          required: true
        - $ref: "#/parameters/wait"
      responses:
        200:
          description: Successfully retrieved statuses
          schema:
            properties:
              data:
                $ref: "#/definitions/BatchStatuses"
              link:
                $ref: "#/definitions/Link"
        400:
          $ref: "#/responses/400BadRequest"
        500:
          $ref: "#/responses/500ServerError"
        503:
          $ref: "#/responses/503ServiceUnavailable"

    post:
      summary: Fetches the committed statuses for a set of batches
      description: |
        Identical to `GET /batch_status`, but takes ids of batches as a JSON
        formatted POST body rather than a query parameter. This allows for many
        more batches to be checked and should be used for more than 15 ids.

        Note that since query information is not encoded in the URL, no `link`
        will be returned with this query.
      consumes:
        - application/json
      parameters:
        - name: Batch Ids
          in: body
          description: A JSON array of batch id strings
          required: true
          schema:
            type: array
            items:
              type: string
              example: 89807bfc9089e37e00d87d97357de14cfbc455cd608438d426a625a30a0da9a31c406983803c4aa27e1f32a3ff61709e8ec4b56abbc553d7d330635b5d27029c
        - $ref: "#/parameters/wait"
      responses:
        200:
          description: Successfully retrieved statuses
          schema:
            properties:
              data:
                $ref: "#/definitions/BatchStatuses"
        400:
          $ref: "#/responses/400BadRequest"
        500:
          $ref: "#/responses/500ServerError"
        503:
          $ref: "#/responses/503ServiceUnavailable"

  /state:
    get:
      summary: Fetches the data for the current state
      description: >
        Fetches a paginated list of entries for the current state, or relative
        to a particular head block. Using the `address` filter parameter, will
        narrow the list to any entries that have an address beginning with the
        characters specified.
      parameters:
        - $ref: "#/parameters/head"
        - name: address
          in: query
          type: string
          description: A partial address to filter leaves by
        - $ref: "#/parameters/count"
        - $ref: "#/parameters/min"
        - $ref: "#/parameters/max"
        - $ref: "#/parameters/sort"
      responses:
        200:
          description: Successfully retrieved state data
          schema:
            properties:
              data:
                type: array
                items:
                  $ref: "#/definitions/Entry"
              head:
                $ref: "#/definitions/Head"
              link:
                $ref: "#/definitions/Link"
              paging:
                $ref: "#/definitions/Paging"
        400:
          $ref: "#/responses/400BadRequest"
        500:
          $ref: "#/responses/500ServerError"
        503:
          $ref: "#/responses/503ServiceUnavailable"

  /state/{address}:
    parameters:
      - $ref: "#/parameters/address"
    get:
      summary: Fetches a particular leaf from the current state
      parameters:
        - $ref: "#/parameters/head"
      responses:
        200:
          description: Successfully fetched leaves
          schema:
            properties:
              data:
                type: string
                format: byte
                example: Zm9vOmJhcg==
              head:
                $ref: "#/definitions/Head"
              link:
                $ref: "#/definitions/Link"
        400:
          $ref: "#/responses/400BadRequest"
        404:
          $ref: "#/responses/404NotFound"
        500:
          $ref: "#/responses/500ServerError"
        503:
          $ref: "#/responses/503ServiceUnavailable"

  /blocks:
    get:
      summary: Fetches a list of blocks
      description: >
        Fetches a paginated list of blocks from the validator.
      parameters:
        - $ref: "#/parameters/head"
        - $ref: "#/parameters/count"
        - $ref: "#/parameters/min"
        - $ref: "#/parameters/max"
        - $ref: "#/parameters/sort"
      responses:
        200:
          description: Successfully retrieved blocks
          schema:
            properties:
              data:
                type: array
                items:
                  - $ref: "#/definitions/Block"
              head:
                $ref: "#/definitions/Head"
              link:
                $ref: "#/definitions/Link"
              paging:
                $ref: "#/definitions/Paging"
        400:
          $ref: "#/responses/400BadRequest"
        500:
          $ref: "#/responses/500ServerError"
        503:
          $ref: "#/responses/503ServiceUnavailable"

  /blocks/{block_id}:
    parameters:
      - $ref: "#/parameters/block_id"
    get:
      summary: Fetches a particlar block
      responses:
        200:
          description: Successfully retrieved block
          schema:
            properties:
              data:
                $ref: "#/definitions/Block"
              head:
                $ref: "#/definitions/Head"
              link:
                $ref: "#/definitions/Link"

        400:
          $ref: "#/responses/400BadRequest"
        404:
          $ref: "#/responses/404NotFound"
        500:
          $ref: "#/responses/500ServerError"
        503:
          $ref: "#/responses/503ServiceUnavailable"

  /transactions:
    get:
      summary: Fetches a list of transactions
      description: >
        Fetches a paginated list of transactions from the validator.
      parameters:
        - $ref: "#/parameters/head"
        - $ref: "#/parameters/count"
        - $ref: "#/parameters/min"
        - $ref: "#/parameters/max"
        - $ref: "#/parameters/sort"
      responses:
        200:
          description: Successfully retrieved transactions
          schema:
            properties:
              data:
                type: array
                items:
                  - $ref: "#/definitions/Transaction"
              head:
                $ref: "#/definitions/Head"
              link:
                $ref: "#/definitions/Link"
              paging:
                $ref: "#/definitions/Paging"
        400:
          $ref: "#/responses/400BadRequest"
        500:
          $ref: "#/responses/500ServerError"
        503:
          $ref: "#/responses/503ServiceUnavailable"

  /transactions/{transaction_id}:
    parameters:
      - $ref: "#/parameters/transaction_id"
    get:
      summary: Fetches a particular transaction
      responses:
        200:
          description: Successfully retrieved transaction
          schema:
            properties:
              data:
                $ref: "#/definitions/Block"
              head:
                $ref: "#/definitions/Head"
              link:
                $ref: "#/definitions/Link"

        400:
          $ref: "#/responses/400BadRequest"
        404:
          $ref: "#/responses/404NotFound"
        500:
          $ref: "#/responses/500ServerError"
        503:
          $ref: "#/responses/503ServiceUnavailable"

  /receipts:
    get:
      summary: Fetches the receipts for a set of transactions
      description: |
        Fetches an array of objects for each receipt requested.

        The receipt(s) you want to retrieve can be specified using the `id`
        filter parameter, where `id` refers to the transaction id of the
        transaction the receipt is associated with.
      parameters:
        - name: id
          in: query
          description: A comma-separated list of transaction ids
          type: string
          required: true
      responses:
        200:
          description: Successfully retrieved transaction receipts
          schema:
            properties:
              data:
                $ref: "#/definitions/TransactionReceipts"
              link:
                $ref: "#/definitions/Link"
        400:
          $ref: "#/responses/400BadRequest"
        500:
          $ref: "#/responses/500ServerError"
        503:
          $ref: "#/responses/503ServiceUnavailable"

    post:
      summary: Fetches the receipts for a set of transactions
      description: |
        Identical to `GET /receipts`, but takes ids of transactions as a JSON
        formatted POST body rather than a query parameter. This allows for many
        more receipts to be fetched and should be used with more than 15 ids.

        Note that since query information is not encoded in the URL, no `link`
        will be returned with this request.
      consumes:
        - application/json
      parameters:
        - name: Transaction Ids
          in: body
          description: A JSON array of transaction id strings
          required: true
          schema:
            type: array
            items:
              type: string
              example: 89807bfc9089e37e00d87d97357de14cfbc455cd608438d426a625a30a0da9a31c406983803c4aa27e1f32a3ff61709e8ec4b56abbc553d7d330635b5d27029c
        - $ref: "#/parameters/wait"
      responses:
        200:
          description: Successfully retrieved transaction receipts
          schema:
            properties:
              data:
                $ref: "#/definitions/TransactionReceipts"
              link:
                $ref: "#/definitions/Link"
        400:
          $ref: "#/responses/400BadRequest"
        500:
          $ref: "#/responses/500ServerError"
        503:
          $ref: "#/responses/503ServiceUnavailable"


responses:
  400BadRequest:
    description: Request was malformed
    schema:
      $ref: "#/definitions/Error"
  404NotFound:
    description: Address or id did not match any resource
    schema:
      $ref: "#/definitions/Error"
  500ServerError:
    description: Something went wrong within the validator
    schema:
      $ref: "#/definitions/Error"
  503ServiceUnavailable:
    description: API is unable to reach the validator
    schema:
      $ref: "#/definitions/Error"

parameters:
  address:
    name: address
    in: path
    type: string
    required: true
    description: Radix address of a leaf, or prefix for leaves
  block_id:
    name: block_id
    in: path
    type: string
    required: true
    description: Block id
  batch_id:
    name: batch_id
    in: path
    type: string
    required: true
    description: Batch id
  transaction_id:
    name: transaction_id
    in: path
    type: string
    required: true
    description: Trainsaction id
  head:
    name: head
    in: query
    type: string
    default: latest
    description: Index or id of head block
  wait:
    name: wait
    in: query
    type: integer
    description: A time in seconds to wait for commit
  count:
    name: count
    in: query
    type: integer
    default: 1000
    description: Number of items to return
  min:
    name: min
    in: query
    type: string
    description: Id or index to start paging (inclusive)
  max:
    name: max
    in: query
    type: string
    description: Id or index to end paging (inclusive)
  sort:
    name: sort
    in: query
    type: string
    description: |
      Comma-separated keys to sort a list by:
        - can reference header keys explicitly or implicitly
        - dot-notation indicates nested keys
        - starting a key with a minus-sign indicates descending order
        - ending a key with `.length` sorts by the length
        - example: `sort=header.signer_public_key,-transaction_ids.length`

definitions:
  Head:
    type: string
    example: 65cd3a3ce088b265b626f704b7f3db97b6f12e848dccb35d7806f3d0324c71b709ed360d602b8b658b94695374717e3bdb4b76f77886953777d5d008558247dd
  Link:
    type: string
    example: https://api.sawtooth.com/state?head=65cd3a3ce088b265b626f704b7f3db97b6f12e848dccb35d7806f3d0324c71b709ed360d602b8b658b94695374717e3bdb4b76f77886953777d5d008558247dd
  Paging:
    properties:
      start_index:
        type: integer
        example: 1000
      total_count:
        type: integer
        example: 54321
      previous:
        type: string
        example: https://api.sawtooth.com/state?head=65cd3a3ce088b265b626f704b7f3db97b6f12e848dccb35d7806f3d0324c71b709ed360d602b8b658b94695374717e3bdb4b76f77886953777d5d008558247dd&min=0&count=1000
      next:
        type: string
        example: https://api.sawtooth.com/state?head=65cd3a3ce088b265b626f704b7f3db97b6f12e848dccb35d7806f3d0324c71b709ed360d602b8b658b94695374717e3bdb4b76f77886953777d5d008558247dd&min=2000&count=1000

  Error:
    properties:
      code:
        type: integer
        example: 34
      title:
          type: string
          example: No Batches Submitted
      message:
        type: string
        example: >
          The protobuf BatchList you submitted was empty and contained no
          Batches. You must submit at least one Batch.

  BatchStatuses:
    type: array
    items:
      properties:
        id:
          type: string
          example: 89807bfc9089e37e00d87d97357de14cfbc455cd608438d426a625a30a0da9a31c406983803c4aa27e1f32a3ff61709e8ec4b56abbc553d7d330635b5d27029c
        status:
          type: string
          example: INVALID
          enum:
            - COMMITTED
            - INVALID
            - PENDING
            - UNKNOWN
        invalid_transactions:
          type: array
          items:
            properties:
              id:
                type: string
                example: 540a6803971d1880ec73a96cb97815a95d374cbad5d865925e5aa0432fcf1931539afe10310c122c5eaae15df61236079abbf4f258889359c4d175516934484a
              message:
                type: string
                example: Verb is \"inc\" but name \"foo\" not in state
              extended_data:
                type: string
                format: byte
                example: ZXJyb3IgZGF0YQ==

  Entry:
    properties:
      address:
        type: string
        example: 1cf12650d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c
      data:
        type: string
        format: byte
        example: Zm9vOmJhcg==

  TransactionHeader:
    properties:
      batcher_public_key:
        type: string
        example: 02d260a46457a064733153e09840c322bee1dff34445d7d49e19e60abd18fd0758
      dependencies:
        type: array
        items:
          type: string
          example: 1baee350bdb60bcee60e3d325d43283cf830b4c23b2cb17d3bb43935bd7af3761c2bee79847c72a9e396a9ae58f48add4e43f94eb83f84442c6085c1dd5d4dbe
      family_name:
        type: string
        example: intkey
      family_version:
        type: string
        example: "1.0"
      inputs:
        type: array
        items:
          type: string
          example: 1cf12650d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c
      nonce:
        type: string
        example: QAApS4L
      outputs:
        type: array
        items:
          type: string
          example: 1cf12650d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c
      payload_sha512:
        type: string
        example: fb6135ef73f4fe77367f9384b3bbbb158f4b8603c9d612157108e5c271868fce2242ee4abd7a29397ba63780c3ccab13783dfd4d9f0167beda03cdb0e37b87f4
      signer_public_key:
        type: string
        example: 038bba5708acc262464c9fe30d3de9e905a9a5fa30cedd151dd9cd09ea26d46d00
  Transaction:
    properties:
      header:
        $ref: "#/definitions/TransactionHeader"
      header_signature:
        type: string
        example: 540a6803971d1880ec73a96cb97815a95d374cbad5d865925e5aa0432fcf1931539afe10310c122c5eaae15df61236079abbf4f258889359c4d175516934484a
      payload:
        type: string
        format: binary

  TransactionReceipt:
    properties:
      transaction_id:
        type: string
        example: 540a6803971d1880ec73a96cb97815a95d374cbad5d865925e5aa0432fcf1931539afe10310c122c5eaae15df61236079abbf4f258889359c4d175516934484a
      state_changes:
        type: array
        items:
          properties:
            type:
              type: string
              example: SET
            address:
              type: string
              example: 1cf12650d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c
            value:
              type: string
              format: binary
      events:
        type: array
        items:
          properties:
            event_type:
              type: string
              example: block_commit
            attributes:
              type: array
              items:
                properties:
                  key:
                    type: string
                  value:
                    type: string
            data:
              type: string
              format: binary
      data:
        type: array
        items:
          type: string
          format: binary
  TransactionReceipts:
    type: array
    items:
      - $ref: "#/definitions/TransactionReceipt"

  BatchHeader:
    properties:
      signer_public_key:
        type: string
        example: 038bba5708acc262464c9fe30d3de9e905a9a5fa30cedd151dd9cd09ea26d46d00
      transaction_ids:
        type: array
        items:
          type: string
          example: 540a6803971d1880ec73a96cb97815a95d374cbad5d865925e5aa0432fcf1931539afe10310c122c5eaae15df61236079abbf4f258889359c4d175516934484a
  Batch:
    properties:
      header:
        $ref: "#/definitions/BatchHeader"
      header_signature:
        type: string
        example: 89807bfc9089e37e00d87d97357de14cfbc455cd608438d426a625a30a0da9a31c406983803c4aa27e1f32a3ff61709e8ec4b56abbc553d7d330635b5d27029c
      transactions:
        type: array
        items:
          $ref: "#/definitions/Transaction"
  BatchList:
    properties:
      batches:
        type: array
        items:
          $ref: "#/definitions/Batch"

  BlockHeader:
    properties:
      block_num:
        type: integer
        example: 12345
      previous_block_id:
        type: string
        example: 65cd3a3ce088b265b626f704b7f3db97b6f12e848dccb35d7806f3d0324c71b709ed360d602b8b658b94695374717e3bdb4b76f77886953777d5d008558247dd
      signer_public_key:
        type: string
        example: 02d260a46457a064733153e09840c322bee1dff34445d7d49e19e60abd18fd0758
      batch_ids:
        type: array
        items:
          type: string
          example: 89807bfc9089e37e00d87d97357de14cfbc455cd608438d426a625a30a0da9a31c406983803c4aa27e1f32a3ff61709e8ec4b56abbc553d7d330635b5d27029c
      consensus:
        type: string
        format: binary
      state_root_hash:
        type: string
        example: 708ca7fbb701799bb387f2e50deaca402e8502abe229f705693d2d4f350e1ad6
  Block:
    properties:
      header:
        $ref: "#/definitions/BlockHeader"
      header_signature:
        type: string
        example: 65cd3a3ce088b265b626f704b7f3db97b6f12e848dccb35d7806f3d0324c71b709ed360d602b8b658b94695374717e3bdb4b76f77886953777d5d008558247dd
      batches:
        type: array
        items:
          $ref: "#/definitions/Batch"