producer.swagger.yaml

openapi: 3.0.0
info:
  title: Producer API
  description: Nodeos Producer API Specification. See developer documentation at https://docs.eosnetwork.com for information on enabling this plugin.
  version: 1.0.0
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  contact:
    url: https://antelope.io
tags:
  - name: Protocol Version 4.0
    description: The release tag for Leap binaries is also the protocol version
servers:
  - url: "{protocol}://{host}:{port}/v1"
    variables:
      protocol:
        enum:
          - http
          - https
        default: http
      host:
        default: localhost
      port:
        default: "8080"
security:
  - {}
paths:
  /producer/pause:
    post:
      summary: pause
      description: Pause producer node. Takes no arguments and returns no values.
      operationId: pause
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OK"
        "400":
          description: client error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /producer/resume:
    post:
      summary: resume
      description: Resume producer node. Takes no arguments and returns no values.
      operationId: resume
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OK"
        "400":
          description: client error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /producer/paused:
    post:
      summary: paused
      description: Retrieves paused status for producer node. Takes no arguments and returns no values.
      operationId: paused
      responses:
        "201":
          description: OK
          content:
            text/plain:
              schema:
                description: true or false
                type: string
                example: false
        "400":
          description: client error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /producer/get_runtime_options:
    post:
      summary: get_runtime_options
      description: Retrieves runtime options for producer node.
      operationId: get_runtime_options
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Runtime_Options"
        "400":
          description: client error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /producer/update_runtime_options:
    post:
      summary: update_runtime_options
      description: Update runtime options for producer node. May post any of the runtime options in combination or alone.
      operationId: update_runtime_options
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Runtime_Options"
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OK"
        "400":
          description: client error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /producer/get_greylist:
    post:
      summary: get_greylist
      description: Retrieves the greylist for producer node.
      operationId: get_greylist
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  accounts:
                    type: array
                    description: Array of account names stored in the greylist
                    items:
                      $ref: "https://docs.eosnetwork.com/openapi/v2.0/Name.yaml"
        "400":
          description: client error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /producer/add_greylist_accounts:
    post:
      summary: add_greylist_accounts
      description: Adds accounts to greylist for producer node. At least one account is required.
      operationId: add_greylist_accounts
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                accounts:
                  type: array
                  description: List of account names to add
                  items:
                    $ref: "https://docs.eosnetwork.com/openapi/v2.0/Name.yaml"
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OK"
        "400":
          description: client error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /producer/remove_greylist_accounts:
    post:
      summary: remove_greylist_accounts
      description: Removes accounts from greylist for producer node. At least one account is required.
      operationId: remove_greylist_accounts
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                accounts:
                  type: array
                  description: List of account names to remove
                  items:
                    $ref: "https://docs.eosnetwork.com/openapi/v2.0/Name.yaml"
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OK"
        "400":
          description: client error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /producer/get_whitelist_blacklist:
    post:
      summary: get_whitelist_blacklist
      description: Retrieves the whitelist and blacklist for producer node. A JSON object containing whitelist and blacklist information.
      operationId: get_whitelist_blacklist
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  actor_whitelist:
                    type: array
                    items:
                      $ref: "https://docs.eosnetwork.com/openapi/v2.0/Name.yaml"
                  actor_blacklist:
                    type: array
                    items:
                      $ref: "https://docs.eosnetwork.com/openapi/v2.0/Name.yaml"
                  contract_whitelist:
                    type: array
                    items:
                      $ref: "https://docs.eosnetwork.com/openapi/v2.0/Name.yaml"
                  contract_blacklist:
                    type: array
                    items:
                      $ref: "https://docs.eosnetwork.com/openapi/v2.0/Name.yaml"
                  action_blacklist:
                    type: array
                    items:
                      type: array
                      description: Array of two string values, the account name as the first and action name as the second
                      items:
                        allOf:
                          - $ref: "https://docs.eosnetwork.com/openapi/v2.0/Name.yaml"
                          - $ref: "https://docs.eosnetwork.com/openapi/v2.0/CppSignature.yaml"
                  key_blacklist:
                    type: array
                    items:
                      - $ref: "https://docs.eosnetwork.com/openapi/v2.0/KeyType.yaml"
        "400":
          description: client error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /producer/set_whitelist_blacklist:
    post:
      summary: set_whitelist_blacklist
      description: Defines the whitelist and blacklist for a producer node. Takes a JSON object containing whitelist and blacklist information.
      operationId: set_whitelist_blacklist
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                actor_whitelist:
                  type: array
                  items:
                    $ref: "https://docs.eosnetwork.com/openapi/v2.0/Name.yaml"
                actor_blacklist:
                  type: array
                  items:
                    $ref: "https://docs.eosnetwork.com/openapi/v2.0/Name.yaml"
                contract_whitelist:
                  type: array
                  items:
                    $ref: "https://docs.eosnetwork.com/openapi/v2.0/Name.yaml"
                contract_blacklist:
                  type: array
                  items:
                    $ref: "https://docs.eosnetwork.com/openapi/v2.0/Name.yaml"
                action_blacklist:
                  type: array
                  items:
                    type: array
                    description: Array of two string values, the account name as the first and action name as the second
                    items:
                      anyOf:
                        - $ref: "https://docs.eosnetwork.com/openapi/v2.0/Name.yaml"
                        - $ref: "https://docs.eosnetwork.com/openapi/v2.0/CppSignature.yaml"
                key_blacklist:
                  type: array
                  items:
                    $ref: "https://docs.eosnetwork.com/openapi/v2.0/KeyType.yaml"
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OK"
        "400":
          description: client error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /producer/create_snapshot:
    post:
      summary: create_snapshot
      description: Creates a snapshot for producer node. Returns error when unable to create a snapshot.
      operationId: create_snapshot
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  head_block_id:
                    $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml"
                  head_block_num:
                    type: integer
                    description: Highest block number on the chain
                    example: 5102
                  head_block_time:
                    type: string
                    description: Highest block unix timestamp
                    example: 2020-11-16T00:00:00.000
                  version:
                    type: integer
                    description: version number
                    example: 6
                  snapshot_name:
                    type: string
                    description: The path and file name of the snapshot
                    example: /home/me/nodes/node-name/snapshots/snapshot-0000999f99999f9f999f99f99ff9999f999f9fff99ff99ffff9f9f9fff9f9999.bin
        "400":
          description: client error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /producer/schedule_snapshot:
    post:
      summary: schedule_snapshot
      description: Submits a request to automatically generate snapshots according to a schedule specified with given parameters. If request body is empty, schedules immediate snapshot generation. Returns error when unable to accept schedule.
      operationId: schedule_snapshot
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                block_spacing:
                  type: integer
                  description: Generate snapshot every block_spacing blocks
                start_block_num:
                  type: integer
                  description: Block number at which schedule starts
                  example: 5102
                end_block_num:
                  type: integer
                  description: Block number at which schedule ends
                  example: 15102
                snapshot_description:
                  type: string
                  description: Description of the snapshot
                  example: Daily snapshot

      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                    - snapshot_request_id
                    - block_spacing
                    - start_block_num
                    - end_block_num
                    - snapshot_description
                properties:
                  snapshot_request_id:
                    type: integer
                    description: Unique id identifying current snapshot request
                  block_spacing:
                    type: integer
                    description: Generate snapshot every block_spacing blocks
                  start_block_num:
                    type: integer
                    description: Block number at which schedule starts
                    example: 5102
                  end_block_num:
                    type: integer
                    description: Block number at which schedule ends
                    example: 15102
                  snapshot_description:
                    type: string
                    description: Description of the snapshot
                    example: Daily snapshot
        "400":
          description: client error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /producer/get_snapshot_requests:
    post:
      summary: get_snapshot_requests
      description: Returns a list of scheduled snapshots.
      operationId: get_snapshot_requests
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  snapshot_requests:
                    type: array
                    description: An array of scheduled snapshot requests
                    items:
                      type: object
                      required:
                          - snapshot_request_id
                          - block_spacing
                          - start_block_num
                          - end_block_num
                          - snapshot_description
                          - pending_snapshots
                      properties:
                        snapshot_request_id:
                          type: integer
                          description: Unique id identifying current snapshot request
                        block_spacing:
                          type: integer
                          description: Generate snapshot every block_spacing blocks
                        start_block_num:
                          type: integer
                          description: Block number at which schedule starts
                          example: 5102
                        end_block_num:
                          type: integer
                          description: Block number at which schedule ends
                          example: 15102
                        snapshot_description:
                          type: string
                          description: Description of the snapshot
                          example: Daily snapshot
                        pending_snapshots:
                          type: array
                          description: List of pending snapshots
                          items:
                            type: object
                            required:
                                - head_block_id
                                - head_block_num
                                - head_block_time
                                - version
                                - snapshot_name
                            properties:
                              head_block_id:
                                $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml"
                              head_block_num:
                                type: integer
                                description: Highest block number on the chain
                                example: 5102
                              head_block_time:
                                type: string
                                description: Highest block unix timestamp
                                example: 2020-11-16T00:00:00.000
                              version:
                                type: integer
                                description: version number
                                example: 6
                              snapshot_name:
                                type: string
                                description: The path and file name of the snapshot
                                example: /home/me/nodes/node-name/snapshots/snapshot-0000999f99999f9f999f99f99ff9999f999f9fff99ff99ffff9f9f9fff9f9999.bin
        "400":
          description: client error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /producer/unschedule_snapshot:
    post:
      summary: unschedule_snapshot
      description: Removes snapshot request identified by id. Returns error if referenced snapshot request does not exist.
      operationId: unschedule_snapshot
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                snapshot_request_id:
                  type: integer
                  description: snapshot id
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - snapshot_request_id
                  - block_spacing
                  - start_block_num
                  - end_block_num
                  - snapshot_description
                properties:
                  snapshot_request_id:
                    type: integer
                    description: Unique id identifying current snapshot request
                  block_spacing:
                    type: integer
                    description: Generate snapshot every block_spacing blocks
                  start_block_num:
                    type: integer
                    description: Block number at which schedule starts
                    example: 5102
                  end_block_num:
                    type: integer
                    description: Block number at which schedule ends
                    example: 15102
                  snapshot_description:
                    type: string
                    description: Description of the snapshot
                    example: Daily snapshot
        "400":
          description: client error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /producer/get_integrity_hash:
    post:
      summary: get_integrity_hash
      description: Retrieves the integrity hash for producer node
      operationId: get_integrity_hash
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: Defines the integrity hash information details
                properties:
                  head_block_id:
                    $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml"
                  integrity_hash:
                    $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml"
        "400":
          description: client error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /producer/schedule_protocol_feature_activations:
    post:
      summary: schedule_protocol_feature_activations
      description: Schedule protocol feature activation for producer node. Note some features may require pre-activation. Will return error for duplicate requests or when feature required pre-activation.
      operationId: schedule_protocol_feature_activations
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                protocol_features_to_activate:
                  type: array
                  description: List of protocol features to activate
                  items:
                    $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml"
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OK"
        "400":
          description: client error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /producer/get_supported_protocol_features:
    post:
      summary: get_supported_protocol_features
      description: Retrieves supported protocol features for producer node. Pass filters in as part of the request body.
      operationId: get_supported_protocol_features
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                exclude_disabled:
                  type: boolean
                  description: Exclude disabled protocol features
                  example: false
                  default: false
                exclude_unactivatable:
                  type: boolean
                  description: Exclude unactivatable protocol features
                  default: false
                  example: false
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                type: array
                description: Variant type, an array of strings with the supported protocol features
                items:
                  type: object
                  properties:
                    feature_digest:
                      $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml"
                    subjective_restrictions:
                      type: object
                      properties:
                        enabled:
                          type: boolean
                          example: true
                        preactivation_required:
                          type: boolean
                          example: true
                        earliest_allowed_activation_time:
                          type: string
                          example: "1970-01-01T00:00:00.000"
                        description_digest:
                          $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml"
                        dependencies:
                          type: array
                          items:
                            $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml"
                        protocol_feature_type:
                          type: string
                          example: "builtin"
                        specification:
                          type: array
                          items:
                            type: object
                            properties:
                              name:
                                type: string
                              value:
                                type: string
        "400":
          description: client error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /producer/get_account_ram_corrections:
    post:
      summary: get_account_ram_corrections
      description: Retrieves accounts with ram corrections.
      operationId: get_account_ram_corrections
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                lower_bound:
                  type: integer
                  description: lowest account key
                upper_bound:
                  type: integer
                  description: highest account key
                limit:
                  type: integer
                  description: number of rows to scan
                  default: 10
                  example: 10
                reverse:
                  type: boolean
                  description: direction of search
                  example: false
                  default: false
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - rows
                properties:
                  rows:
                    type: array
                    items:
                      type: string
                  more:
                    type: array
                    items:
                      - $ref: "https://docs.eosnetwork.com/openapi/v2.0/Name.yaml"
        "400":
          description: client error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /producer/get_unapplied_transactions:
    post:
      summary: get_unapplied_transactions
      description: Get Unapplied Transactions.
      operationId: get_unapplied_transactions
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                limit:
                  type: integer
                  description: limit number of transactions to return
                  default: 100
                  example: 100
                lower_bound:
                  $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml"
                time_limit_ms:
                  type: integer
                  default: http-max-response-time-ms
                  example: 10
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  size:
                    type: integer
                    default: 0
                    example: 12428
                  incoming_size:
                    type: integer
                    default: 0
                    example: 4475
                  trxs:
                    type: array
                    items:
                      type: object
                      properties:
                        trx_id:
                          $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml"
                        expiration:
                          type: string
                          example: "2022-09-17T16:30:16"
                        trx_type:
                          type: string
                          example: "aborted"
                        first_auth:
                          type: string
                          example: "jkbsg.wam"
                        first_receiver:
                          type: string
                          example: "m.federation"
                        first_action:
                          type: string
                          example: "mine"
                        total_actions:
                          type: integer
                          default: 0
                          example: 1
                        billed_cpu_time_us:
                          type: integer
                          default: 0
                          example: 504
                        size:
                          type: integer
                          default: 0
                          example: 934
                  more:
                    $ref: "https://docs.eosnetwork.com/openapi/v2.0/Sha256.yaml"
        "400":
          description: client error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  securitySchemes: {}
  schemas:
    Error:
      type: object
      properties:
        code:
          type: integer
          description: http return code
          example: 400
        message:
          type: string
          description: summary of error
          example: Invalid Request
        error:
          type: object
          description: details on the error
          properties:
            code:
              type: integer
              description: internal error code
              example: 3200006
            name:
              type: string
              description: name of error
              example: invalid_http_request
            what:
              type: string
              description: prettier version of error name
              example: invalid http request
            details:
              type: array
              description: list of additional information for debugging
              items:
                type: object
                properties:
                  message:
                    type: string
                    description: debugging message
                    example: Unable to parse valid input from POST body
                  file:
                    type: string
                    description: file where error was thrown
                    example: http_plugin.hpp
                  line_number:
                    type: integer
                    description: line number in file where error was thrown
                    example: 246
                  method:
                    type: string
                    description: function executed when error occurred
                    example: parse_params
    OK:
      type: object
      properties:
        result:
          type: string
          description: status
          example: ok
    Runtime_Options:
      type: object
      properties:
        max_transaction_time:
          type: integer
          description: Max transaction time
          example: 100
        max_irreversible_block_age:
          type: integer
          description: Max irreversible block age
          example: -1
        produce_time_offset_us:
          type: integer
          description: Time offset
          example: -100000
        last_block_time_offset_us:
          type: integer
          description: Last block time offset
          example: -200000
        max_scheduled_transaction_time_per_block_ms:
          type: integer
          description: Max scheduled transaction time per block in ms
          example: 100
        subjective_cpu_leeway_us:
          type: integer
          description: in micro seconds
          example: 10
        incoming_defer_ratio:
          type: string
          description: Incoming defer ratio, parsed to double
          example: "1.00000000000000000"
        greylist_limit:
          type: integer
          description: limit on number of Names supported by greylist
          example: 1000