mirror of
https://github.com/alexgo-io/stacks-puppet-node.git
synced 2026-01-12 22:43:42 +08:00
674 lines
24 KiB
YAML
674 lines
24 KiB
YAML
openapi: 3.0.2
|
|
servers:
|
|
- url: http://localhost:20443/
|
|
description: Local
|
|
info:
|
|
title: Stacks 2.0+ RPC API
|
|
version: '1.0.0'
|
|
description: |
|
|
This is the documentation for the `stacks-node` RPC interface.
|
|
|
|
paths:
|
|
/v2/transactions:
|
|
post:
|
|
summary: Broadcast raw transaction
|
|
tags:
|
|
- Transactions
|
|
description: Broadcast raw transactions on the network. You can use the [@stacks/transactions](https://github.com/blockstack/stacks.js) project to generate a raw transaction payload.
|
|
operationId: post_core_node_transactions
|
|
requestBody:
|
|
content:
|
|
application/octet-stream:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
example: binary format of 00000000010400bed38c2aadffa348931bcb542880ff79d607afec000000000000000000000000000000c800012b0b1fff6cccd0974966dcd665835838f0985be508e1322e09fb3d751eca132c492bda720f9ef1768d14fdabed6127560ba52d5e3ac470dcb60b784e97dc88c9030200000000000516df0ba3e79792be7be5e50a370289accfc8c9e032000000000000303974657374206d656d6f00000000000000000000000000000000000000000000000000
|
|
responses:
|
|
200:
|
|
description: Transaction id of successful post of a raw tx to the node's mempool
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
example: '"e161978626f216b2141b156ade10501207ae535fa365a13ef5d7a7c9310a09f2"'
|
|
400:
|
|
description: Rejections result in a 400 error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ./api/transaction/post-core-node-transactions-error.schema.json
|
|
example:
|
|
$ref: ./api/transaction/post-core-node-transactions-error.example.json
|
|
/v2/burn_ops/{burn_height}/{op_type}:
|
|
get:
|
|
summary: Get burn operations
|
|
description: Get all burn operations of type `op_type` successfully read at `burn_height`. Valid `op_type`s are `peg_in`, `peg_out_request` and `peg_out_fulfill`.
|
|
tags:
|
|
- Info
|
|
operationId: get_burn_ops
|
|
responses:
|
|
200:
|
|
description: Burn operations list
|
|
content:
|
|
application/json:
|
|
examples:
|
|
peg_in:
|
|
value:
|
|
$ref: ./api/core-node/get-burn-ops-peg-in.example.json
|
|
peg_out_request:
|
|
value:
|
|
$ref: ./api/core-node/get-burn-ops-peg-out-request.example.json
|
|
peg_out_fulfill:
|
|
value:
|
|
$ref: ./api/core-node/get-burn-ops-peg-out-fulfill.example.json
|
|
/v2/contracts/interface/{contract_address}/{contract_name}:
|
|
get:
|
|
summary: Get contract interface
|
|
description: Get contract interface using a `contract_address` and `contract name`
|
|
tags:
|
|
- Smart Contracts
|
|
operationId: get_contract_interface
|
|
responses:
|
|
200:
|
|
description: Contract interface
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ./api/core-node/get-contract-interface.schema.json
|
|
example:
|
|
$ref: ./api/core-node/get-contract-interface.example.json
|
|
parameters:
|
|
- name: contract_address
|
|
in: path
|
|
required: true
|
|
description: Stacks address
|
|
schema:
|
|
type: string
|
|
- name: contract_name
|
|
in: path
|
|
required: true
|
|
description: Contract name
|
|
schema:
|
|
type: string
|
|
- name: tip
|
|
in: query
|
|
schema:
|
|
type: string
|
|
description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest
|
|
known tip (includes unconfirmed state).
|
|
/v2/map_entry/{contract_address}/{contract_name}/{map_name}:
|
|
post:
|
|
summary: Get specific data-map inside a contract
|
|
tags:
|
|
- Smart Contracts
|
|
operationId: get_contract_data_map_entry
|
|
description: |
|
|
Attempt to fetch data from a contract data map. The contract is identified with [Stacks Address] and [Contract Name] in the URL path. The map is identified with [Map Name].
|
|
|
|
The key to lookup in the map is supplied via the POST body. This should be supplied as the hex string serialization of the key (which should be a Clarity value). Note, this is a JSON string atom.
|
|
|
|
In the response, `data` is the hex serialization of the map response. Note that map responses are Clarity option types, for non-existent values, this is a serialized none, and for all other responses, it is a serialized (some ...) object.
|
|
responses:
|
|
200:
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ./api/core-node/get-contract-data-map-entry.schema.json
|
|
example:
|
|
$ref: ./api/core-node/get-contract-data-map-entry.example.json
|
|
400:
|
|
description: Failed loading data map
|
|
parameters:
|
|
- name: contract_address
|
|
in: path
|
|
required: true
|
|
description: Stacks address
|
|
schema:
|
|
type: string
|
|
- name: contract_name
|
|
in: path
|
|
required: true
|
|
description: Contract name
|
|
schema:
|
|
type: string
|
|
- name: map_name
|
|
in: path
|
|
required: true
|
|
description: Map name
|
|
schema:
|
|
type: string
|
|
- name: proof
|
|
in: query
|
|
description: Returns object without the proof field when set to 0
|
|
schema:
|
|
type: integer
|
|
- name: tip
|
|
in: query
|
|
schema:
|
|
type: string
|
|
description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest
|
|
known tip (includes unconfirmed state).
|
|
x-codegen-request-body-name: key
|
|
requestBody:
|
|
description: Hex string serialization of the lookup key (which should be a Clarity value)
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: string
|
|
|
|
/v2/contracts/source/{contract_address}/{contract_name}:
|
|
get:
|
|
summary: Get contract source
|
|
tags:
|
|
- Smart Contracts
|
|
operationId: get_contract_source
|
|
description: Returns the Clarity source code of a given contract, along with the block height it was published in, and the MARF proof for the data
|
|
responses:
|
|
200:
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ./api/core-node/get-contract-source.schema.json
|
|
example:
|
|
$ref: ./api/core-node/get-contract-source.example.json
|
|
parameters:
|
|
- name: contract_address
|
|
in: path
|
|
required: true
|
|
description: Stacks address
|
|
schema:
|
|
type: string
|
|
- name: contract_name
|
|
in: path
|
|
required: true
|
|
description: Contract name
|
|
schema:
|
|
type: string
|
|
- name: proof
|
|
in: query
|
|
description: Returns object without the proof field if set to 0
|
|
schema:
|
|
type: integer
|
|
- name: tip
|
|
in: query
|
|
schema:
|
|
type: string
|
|
description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest
|
|
known tip (includes unconfirmed state).
|
|
required: false
|
|
|
|
/v2/contracts/call-read/{contract_address}/{contract_name}/{function_name}:
|
|
post:
|
|
summary: Call read-only function
|
|
tags:
|
|
- Smart Contracts
|
|
operationId: call_read_only_function
|
|
description: |
|
|
Call a read-only public function on a given smart contract.
|
|
|
|
The smart contract and function are specified using the URL path. The arguments and the simulated tx-sender are supplied via the POST body in the following JSON format:
|
|
responses:
|
|
200:
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ./api/contract/post-call-read-only-fn.schema.json
|
|
examples:
|
|
success:
|
|
$ref: ./api/contract/post-call-read-only-fn-success.example.json
|
|
fail:
|
|
$ref: ./api/contract/post-call-read-only-fn-fail.example.json
|
|
parameters:
|
|
- name: contract_address
|
|
in: path
|
|
required: true
|
|
description: Stacks address
|
|
schema:
|
|
type: string
|
|
- name: contract_name
|
|
in: path
|
|
required: true
|
|
description: Contract name
|
|
schema:
|
|
type: string
|
|
- name: function_name
|
|
in: path
|
|
required: true
|
|
description: Function name
|
|
schema:
|
|
type: string
|
|
- name: tip
|
|
in: query
|
|
schema:
|
|
type: string
|
|
description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest
|
|
known tip (includes unconfirmed state).
|
|
required: false
|
|
requestBody:
|
|
description: map of arguments and the simulated tx-sender where sender is either a Contract identifier or a normal Stacks address, and arguments is an array of hex serialized Clarity values.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: './entities/contracts/read-only-function-args.schema.json'
|
|
example:
|
|
sender: 'SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info'
|
|
arguments:
|
|
- '0x0011...'
|
|
- '0x00231...'
|
|
|
|
/v2/accounts/{principal}:
|
|
get:
|
|
summary: Get account info
|
|
tags:
|
|
- Accounts
|
|
operationId: get_account_info
|
|
description: |
|
|
Get the account data for the provided principal
|
|
|
|
Where balance is the hex encoding of a unsigned 128-bit integer (big-endian), nonce is a unsigned 64-bit integer, and the proofs are provided as hex strings.
|
|
|
|
For non-existent accounts, this does not 404, rather it returns an object with balance and nonce of 0.
|
|
parameters:
|
|
- name: principal
|
|
in: path
|
|
description: Stacks address or a Contract identifier (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`)
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: proof
|
|
in: query
|
|
description: Returns object without the proof field if set to 0
|
|
schema:
|
|
type: integer
|
|
- name: tip
|
|
in: query
|
|
schema:
|
|
type: string
|
|
description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest
|
|
known tip (includes unconfirmed state).
|
|
responses:
|
|
200:
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ./api/core-node/get-account-data.schema.json
|
|
example:
|
|
$ref: ./api/core-node/get-account-data.example.json
|
|
|
|
/v2/fees/transaction:
|
|
post:
|
|
summary: Get approximate fees for the given transaction
|
|
tags:
|
|
- Fees
|
|
description: |
|
|
Get an estimated fee for the supplied transaction. This
|
|
estimates the execution cost of the transaction, the current
|
|
fee rate of the network, and returns estimates for fee
|
|
amounts.
|
|
|
|
* `transaction_payload` is a hex-encoded serialization of
|
|
the TransactionPayload for the transaction.
|
|
* `estimated_len` is an optional argument that provides the
|
|
endpoint with an estimation of the final length (in bytes)
|
|
of the transaction, including any post-conditions and
|
|
signatures
|
|
|
|
If the node cannot provide an estimate for the transaction
|
|
(e.g., if the node has never seen a contract-call for the
|
|
given contract and function) or if estimation is not
|
|
configured on this node, a 400 response is returned.
|
|
The 400 response will be a JSON error containing a `reason`
|
|
field which can be one of the following:
|
|
|
|
* `DatabaseError` - this Stacks node has had an internal
|
|
database error while trying to estimate the costs of the
|
|
supplied transaction.
|
|
* `NoEstimateAvailable` - this Stacks node has not seen this
|
|
kind of contract-call before, and it cannot provide an
|
|
estimate yet.
|
|
* `CostEstimationDisabled` - this Stacks node does not perform
|
|
fee or cost estimation, and it cannot respond on this
|
|
endpoint.
|
|
|
|
The 200 response contains the following data:
|
|
|
|
* `estimated_cost` - the estimated multi-dimensional cost of
|
|
executing the Clarity VM on the provided transaction.
|
|
* `estimated_cost_scalar` - a unitless integer that the Stacks
|
|
node uses to compare how much of the block limit is consumed
|
|
by different transactions. This value incorporates the
|
|
estimated length of the transaction and the estimated
|
|
execution cost of the transaction. The range of this integer
|
|
may vary between different Stacks nodes. In order to compute
|
|
an estimate of total fee amount for the transaction, this
|
|
value is multiplied by the same Stacks node's estimated fee
|
|
rate.
|
|
* `cost_scalar_change_by_byte` - a float value that indicates how
|
|
much the `estimated_cost_scalar` value would increase for every
|
|
additional byte in the final transaction.
|
|
* `estimations` - an array of estimated fee rates and total fees to
|
|
pay in microSTX for the transaction. This array provides a range of
|
|
estimates (default: 3) that may be used. Each element of the array
|
|
contains the following fields:
|
|
* `fee_rate` - the estimated value for the current fee
|
|
rates in the network
|
|
* `fee` - the estimated value for the total fee in
|
|
microSTX that the given transaction should pay. These
|
|
values are the result of computing:
|
|
`fee_rate` x `estimated_cost_scalar`.
|
|
If the estimated fees are less than the minimum relay
|
|
fee `(1 ustx x estimated_len)`, then that minimum relay
|
|
fee will be returned here instead.
|
|
|
|
|
|
Note: If the final transaction's byte size is larger than
|
|
supplied to `estimated_len`, then applications should increase
|
|
this fee amount by:
|
|
|
|
`fee_rate` x `cost_scalar_change_by_byte` x (`final_size` - `estimated_size`)
|
|
|
|
operationId: post_fee_transaction
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ./api/core-node/post-fee-transaction.schema.json
|
|
example:
|
|
$ref: ./api/core-node/post-fee-transaction.example.json
|
|
responses:
|
|
200:
|
|
description: Estimated fees for the transaction
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ./api/core-node/post-fee-transaction-response.schema.json
|
|
example:
|
|
$ref: ./api/core-node/post-fee-transaction-response.example.json
|
|
|
|
/v2/fees/transfer:
|
|
get:
|
|
summary: Get estimated fee
|
|
tags:
|
|
- Fees
|
|
operationId: get_fee_transfer
|
|
description: Get an estimated fee rate for STX transfer transactions. This a a fee rate / byte, and is returned as a JSON integer
|
|
responses:
|
|
200:
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ./api/core-node/get-fee-transfer.schema.json
|
|
example:
|
|
$ref: ./api/core-node/get-fee-transfer.example.json
|
|
|
|
/v2/info:
|
|
get:
|
|
summary: Get Core API info
|
|
description: Get Core API information
|
|
tags:
|
|
- Info
|
|
operationId: get_core_api_info
|
|
responses:
|
|
200:
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ./api/core-node/get-info.schema.json
|
|
example:
|
|
$ref: ./api/core-node/get-info.example.json
|
|
|
|
/v2/pox:
|
|
get:
|
|
summary: Get PoX details
|
|
description: Get Proof of Transfer (PoX) information. Can be used for Stacking.
|
|
tags:
|
|
- Info
|
|
operationId: get_pox_info
|
|
responses:
|
|
200:
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ./api/core-node/get-pox.schema.json
|
|
example:
|
|
$ref: ./api/core-node/get-pox.example.json
|
|
parameters:
|
|
- name: tip
|
|
in: query
|
|
schema:
|
|
type: string
|
|
description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest
|
|
known tip (includes unconfirmed state).
|
|
|
|
/v2/traits/{contract_address}/{contract_name}/{trait_contract_address}/{trait_contract_name}/{trait_name}:
|
|
get:
|
|
summary: Get trait implementation details
|
|
description: Determine whether or not a specified trait is implemented (either explicitly or implicitly) within a given contract.
|
|
tags:
|
|
- Smart Contracts
|
|
operationId: get_is_trait_implemented
|
|
responses:
|
|
200:
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ./api/trait/get-is-trait-implemented.schema.json
|
|
example:
|
|
$ref: ./api/trait/get-is-trait-implemented.example.json
|
|
parameters:
|
|
- name: contract_address
|
|
in: path
|
|
required: true
|
|
description: Stacks address
|
|
schema:
|
|
type: string
|
|
- name: contract_name
|
|
in: path
|
|
required: true
|
|
description: Contract name
|
|
schema:
|
|
type: string
|
|
- name: trait_contract_address
|
|
in: path
|
|
required: true
|
|
description: Trait Stacks address
|
|
schema:
|
|
type: string
|
|
- name: trait_contract_name
|
|
in: path
|
|
required: true
|
|
description: Trait contract name
|
|
schema:
|
|
type: string
|
|
- name: trait_name
|
|
in: path
|
|
required: true
|
|
description: Trait name
|
|
schema:
|
|
type: string
|
|
- name: tip
|
|
in: query
|
|
schema:
|
|
type: string
|
|
description: |
|
|
The Stacks chain tip to query from.
|
|
If tip == "latest", the query will be run from the latest known tip (includes unconfirmed state).
|
|
If the tip is left unspecified, the stacks chain tip will be selected (only includes confirmed state).
|
|
|
|
/v2/constant_val/{contract_address}/{contract_name}/{constant_name}:
|
|
post:
|
|
summary: Get the value of a constant inside a contract
|
|
tags:
|
|
- Smart Contracts
|
|
operationId: get_constant_val
|
|
description: |
|
|
Attempt to fetch the value of a constant inside a contract. The contract is identified with [Stacks Address] and [Contract Name] in the URL path. The constant is identified with [Constant Name].
|
|
|
|
In the response, `data` is the hex serialization of the constant value.
|
|
responses:
|
|
200:
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ./api/core-node/get-constant-val.schema.json
|
|
example:
|
|
$ref: ./api/core-node/get-constant-val.example.json
|
|
400:
|
|
description: Failed to retrieve constant value from contract
|
|
parameters:
|
|
- name: contract_address
|
|
in: path
|
|
required: true
|
|
description: Stacks address
|
|
schema:
|
|
type: string
|
|
- name: contract_name
|
|
in: path
|
|
required: true
|
|
description: Contract name
|
|
schema:
|
|
type: string
|
|
- name: constant_name
|
|
in: path
|
|
required: true
|
|
description: Constant name
|
|
schema:
|
|
type: string
|
|
- name: tip
|
|
in: query
|
|
schema:
|
|
type: string
|
|
description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest
|
|
known tip (includes unconfirmed state).
|
|
|
|
/v2/block_proposal:
|
|
post:
|
|
summary: Validate a proposed Stacks block
|
|
tags:
|
|
- Mining
|
|
operationId: post_block_proposal
|
|
description: |
|
|
Used by stackers to validate a proposed Stacks block from a miner.
|
|
|
|
**This API endpoint requires a basic Authorization header.**
|
|
responses:
|
|
202:
|
|
description: Block proposal has been accepted for processing. The result will be returned via the event observer.
|
|
content:
|
|
application/json:
|
|
example:
|
|
$ref: ./api/core-node/post-block-proposal-response.example.json
|
|
403:
|
|
description: Request not over loopback interface
|
|
429:
|
|
description: There is an ongoing proposal validation being processed, the new request cannot be accepted
|
|
until the prior request has been processed.
|
|
content:
|
|
application/json:
|
|
example:
|
|
$ref: ./api/core-node/post-block-proposal-response.429.json
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
example:
|
|
$ref: ./api/core-node/post-block-proposal-req.example.json
|
|
|
|
/v2/stacker_set/{cycle_number}:
|
|
get:
|
|
summary: Fetch the stacker and signer set information for a given cycle.
|
|
tags:
|
|
- Mining
|
|
operationId: get_stacker_set
|
|
description: |
|
|
Used to get stacker and signer set information for a given cycle.
|
|
|
|
This will only return information for cycles started in Epoch-2.5 where PoX-4 was active and subsequent cycles.
|
|
responses:
|
|
200:
|
|
description: Information for the given reward cycle
|
|
content:
|
|
application/json:
|
|
example:
|
|
$ref: ./api/core-node/get_stacker_set.example.json
|
|
400:
|
|
description: Could not fetch the given reward set
|
|
content:
|
|
application/json:
|
|
example:
|
|
$ref: ./api/core-node/get_stacker_set.400.example.json
|
|
|
|
/v3/blocks/{block_id}:
|
|
get:
|
|
summary: Fetch a Nakamoto block
|
|
tags:
|
|
- Blocks
|
|
operationId: get_block_v3
|
|
description:
|
|
Fetch a Nakamoto block by its index block hash.
|
|
responses:
|
|
200:
|
|
description: The raw SIP-003-encoded block will be returned.
|
|
content:
|
|
application/octet-stream:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
404:
|
|
description: The block could not be found
|
|
content:
|
|
application/text-plain: {}
|
|
|
|
/v3/tenures/info:
|
|
get:
|
|
summary: Fetch metadata about the ongoing Nakamoto tenure
|
|
tags:
|
|
- Blocks
|
|
operationId: get_tenure_info
|
|
description:
|
|
Fetch metadata about the ongoing Nakamoto tenure. This information is sufficient to obtain and authenticate the highest complete tenure, as well as obtain new tenure blocks.
|
|
responses:
|
|
200:
|
|
description: Metadata about the ongoing tenure
|
|
content:
|
|
application/json:
|
|
example:
|
|
$ref: ./api/core-node/get_tenure_info.json
|
|
|
|
/v3/tenures/{block_id}:
|
|
get:
|
|
summary: Fetch a sequence of Nakamoto blocks in a tenure
|
|
tags:
|
|
- Blocks
|
|
operationId: get_tenures
|
|
description:
|
|
Fetch a sequence of Nakamoto blocks in a tenure. The blocks will be served in order from highest to lowest. The blocks will be encoded in their SIP-003 wire format, and concatenated together.
|
|
responses:
|
|
200:
|
|
description: SIP-003-encoded Nakamoto blocks, concatenated together
|
|
content:
|
|
application/octet-stream:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
parameters:
|
|
name: stop
|
|
in: query
|
|
description:
|
|
The block ID hash of the highest block in this tenure that is already known to the caller. Neither the corresponding block nor any of its ancestors will be served. This is used to fetch tenure blocks that the caller does not have.
|
|
required: false
|
|
schema:
|
|
type: string
|
|
format: 64-character hex string
|
|
|