diff --git a/openapi/stacks-node-rpc/README.md b/openapi/stacks-node-rpc/README.md index 969f9f3651..19ac483ccd 100644 --- a/openapi/stacks-node-rpc/README.md +++ b/openapi/stacks-node-rpc/README.md @@ -1,6 +1,6 @@ # Node RPC OpenAPI spec for GitBook -Source: stacks-network/stacks-core `docs/rpc/` at commit `b62be8ee94f2a08dc58d5ff6809a6d08b813c3e9` (main after PR #7691, 2026-10-06). +Source: stacks-network/stacks-core `docs/rpc/` at commit `12ac3abebc67cf2bfd286413a1d7db47cd9c7e5d` (main after PR #7786, 2026-10-28). GitBook spec slug: `stacks-node-rpc-api-dereferenced-new` (org `hoh4mQXTl8NvI3cETroY`). ## Why the extra step @@ -12,7 +12,7 @@ GitBook spec slug: `stacks-node-rpc-api-dereferenced-new` (org `hoh4mQXTl8NvI3cE Run from a checkout of stacks-network/docs. Requires git, Node.js with npx, and Python 3. ```bash -COMMIT=b62be8ee94f2a08dc58d5ff6809a6d08b813c3e9 +COMMIT=12ac3abebc67cf2bfd286413a1d7db47cd9c7e5d SHORT=${COMMIT:0:9} OUT="$PWD/openapi/stacks-node-rpc" TMP=$(mktemp -d) @@ -26,7 +26,9 @@ npx -y @redocly/cli@2.19 lint "$OUT/stacks-node-rpc.$SHORT.json" cd - >/dev/null ``` -sha256 of `stacks-node-rpc.b62be8ee9.json`: `6bfbdf37b0380126035dfe4e46c7fbf7b4f4e8000c6e0a2979808910a48c2b32` +sha256 of `stacks-node-rpc.12ac3abeb.json`: `6fae49c3e9a6ec33f5f8495637a58d761be7c08f96ce8d3013a1bff9abfdfc6f` + +Previous build, kept until GitBook no longer points at it: `stacks-node-rpc.b62be8ee9.json` (stacks-core `b62be8ee94f2a08dc58d5ff6809a6d08b813c3e9`), sha256 `6bfbdf37b0380126035dfe4e46c7fbf7b4f4e8000c6e0a2979808910a48c2b32`. ## Updating diff --git a/openapi/stacks-node-rpc/stacks-node-rpc.12ac3abeb.json b/openapi/stacks-node-rpc/stacks-node-rpc.12ac3abeb.json new file mode 100644 index 0000000000..17a120e603 --- /dev/null +++ b/openapi/stacks-node-rpc/stacks-node-rpc.12ac3abeb.json @@ -0,0 +1,8284 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "Stacks 3.0+ RPC API", + "version": "1.0.0", + "description": "This is the documentation for the `stacks-node` RPC interface.\n", + "license": { + "name": "CC-0", + "url": "https://creativecommons.org/publicdomain/zero/1.0/" + } + }, + "servers": [ + { + "url": "http://localhost:20443", + "description": "Local Stacks Node" + } + ], + "tags": [ + { + "name": "Transactions", + "description": "Operations related to broadcasting and retrieving transactions." + }, + { + "name": "Smart Contracts", + "description": "Endpoints for interacting with Clarity smart contracts." + }, + { + "name": "Accounts", + "description": "Endpoints for retrieving account information." + }, + { + "name": "Fees", + "description": "Endpoints for fee estimation." + }, + { + "name": "Info", + "description": "General informational endpoints about the node." + }, + { + "name": "Mining", + "description": "Endpoints related to Stacks block production and mining." + }, + { + "name": "Blocks", + "description": "Operations for retrieving block and microblock data." + }, + { + "name": "Signers", + "description": "Endpoints for retrieving signer information." + }, + { + "name": "Atlas", + "description": "Operations related to the Atlas global namespace." + }, + { + "name": "Microblocks", + "description": "Operations for retrieving and submitting microblocks." + }, + { + "name": "StackerDB", + "description": "Endpoints for interacting with StackerDB instances." + } + ], + "paths": { + "/v2/transactions": { + "post": { + "summary": "Broadcast raw transaction", + "tags": [ + "Transactions" + ], + "security": [], + "description": "Broadcast raw transactions on the network. You can use the [@stacks/transactions](https://github.com/blockstack/stacks.js)\nproject to generate a raw transaction payload.\n\nThe node performs static validation checks on transactions before accepting them into the mempool, including:\n- Transaction format validation\n- Signature verification\n- Nonce checking\n- Fee validation\n- Size limits\n", + "operationId": "broadcastTransaction", + "requestBody": { + "required": true, + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary", + "minLength": 1 + }, + "example": "binary format of 00000000010400bed38c2aadffa348931bcb542880ff79d607afec000000000000000000000000000000c800012b0b1fff6cccd0974966dcd665835838f0985be508e1322e09fb3d751eca132c492bda720f9ef1768d14fdabed6127560ba52d5e3ac470dcb60b784e97dc88c9030200000000000516df0ba3e79792be7be5e50a370289accfc8c9e032000000000000303974657374206d656d6f00000000000000000000000000000000000000000000000000" + }, + "application/json": { + "schema": { + "type": "object", + "required": [ + "tx" + ], + "properties": { + "tx": { + "type": "string", + "pattern": "^[0-9a-f]+$", + "description": "Hex-encoded transaction" + }, + "attachment": { + "type": "string", + "pattern": "^[0-9a-f]+$", + "description": "Optional hex-encoded attachment for contract-call transactions" + } + } + }, + "example": { + "tx": "00000000010400bed38c2aadffa348931bcb542880ff79d607afec000000000000000000000000000000c800012b0b1fff6cccd0974966dcd665835838f0985be508e1322e09fb3d751eca132c492bda720f9ef1768d14fdabed6127560ba52d5e3ac470dcb60b784e97dc88c9030200000000000516df0ba3e79792be7be5e50a370289accfc8c9e032000000000000303974657374206d656d6f00000000000000000000000000000000000000000000000000", + "attachment": "68656c6c6f20776f726c64" + } + } + } + }, + "responses": { + "200": { + "description": "Transaction ID of successful post of a raw tx to the node's mempool.", + "content": { + "application/json": { + "schema": { + "type": "string", + "pattern": "^[0-9a-f]{64}$", + "example": "e161978626f216b2141b156ade10501207ae535fa365a13ef5d7a7c9310a09f2" + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TransactionSubmissionError" + }, + "examples": { + "transaction-submission-error": { + "$ref": "#/components/examples/transaction-submission-error.example" + } + } + }, + "text/plain": { + "schema": { + "type": "string" + }, + "example": "Failed to decode transaction" + } + } + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v2/contracts/interface/{deployer_address}/{contract_name}": { + "get": { + "summary": "Get contract interface", + "description": "Get contract interface using a `deployer_address` and `contract name`", + "tags": [ + "Smart Contracts" + ], + "security": [], + "operationId": "getContractInterface", + "parameters": [ + { + "$ref": "#/components/parameters/deployer-address" + }, + { + "$ref": "#/components/parameters/contract-name" + }, + { + "$ref": "#/components/parameters/tip" + } + ], + "responses": { + "200": { + "description": "Contract interface", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContractInterface" + }, + "examples": { + "contract-interface": { + "$ref": "#/components/examples/contract-interface.example" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v2/map_entry/{deployer_address}/{contract_name}/{map_name}": { + "post": { + "summary": "Get specific data-map inside a contract", + "tags": [ + "Smart Contracts" + ], + "security": [], + "operationId": "getContractDataMapEntry", + "description": "Attempt to fetch data from a contract data map. The contract is\nidentified with [Stacks Address] and [Contract Name] in the URL path.\nThe map is identified with [Map Name].\n\nThe key to lookup in the map is supplied via the POST body. This should\nbe supplied as the hex string serialization of the key (which should be\na Clarity value). Note, this is a JSON string.\n\nThe response is a JSON object with the following properties:\n- `data`: The hex serialization of the map response. Note that map\n responses are Clarity option types, for non-existent values, this is\n a serialized none, and for all other responses, it is a serialized\n (some ...) object.\n- `proof`: The hex serialization of the Merkle proof for the data.\n", + "parameters": [ + { + "$ref": "#/components/parameters/deployer-address" + }, + { + "$ref": "#/components/parameters/contract-name" + }, + { + "name": "map_name", + "in": "path", + "required": true, + "schema": { + "$ref": "#/components/schemas/ClarityName" + } + }, + { + "$ref": "#/components/parameters/proof" + }, + { + "$ref": "#/components/parameters/tip" + } + ], + "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", + "minLength": 2, + "pattern": "^(0x)?([0-9a-fA-F]{2})+$", + "description": "Hex-encoded Clarity value (e.g. \"0x0100000000000000000000000000000001\")", + "example": "0x0100000000000000000000000000000001" + } + } + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClarityData" + }, + "examples": { + "clarity-data": { + "$ref": "#/components/examples/clarity-data.example" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v2/contracts/source/{deployer_address}/{contract_name}": { + "get": { + "summary": "Get contract source", + "tags": [ + "Smart Contracts" + ], + "security": [], + "operationId": "getContractSource", + "description": "Returns the Clarity source code of a given contract, along with the\nblock height it was published in, and the MARF proof for the data.\n", + "parameters": [ + { + "$ref": "#/components/parameters/deployer-address" + }, + { + "$ref": "#/components/parameters/contract-name" + }, + { + "$ref": "#/components/parameters/proof" + }, + { + "$ref": "#/components/parameters/tip" + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContractSource" + }, + "examples": { + "contract-source": { + "$ref": "#/components/examples/contract-source.example" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v2/contracts/call-read/{deployer_address}/{contract_name}/{function_name}": { + "post": { + "summary": "Call read-only function", + "description": "Call a read-only public function on a given contract.\n\nThe contract is identified with [Stacks Address] and [Contract Name] in the URL path.\nThe function is identified with [Function Name].\n\nThe arguments to the function are supplied via the POST body.\nThis should be a JSON object with two main properties:\n- `sender` which should be a Stacks address or contract principal\n- `arguments` which should be an array of hex-encoded Clarity values.\n", + "tags": [ + "Smart Contracts" + ], + "security": [], + "operationId": "callReadOnlyFunction", + "parameters": [ + { + "$ref": "#/components/parameters/deployer-address" + }, + { + "$ref": "#/components/parameters/contract-name" + }, + { + "name": "function_name", + "in": "path", + "required": true, + "schema": { + "$ref": "#/components/schemas/ClarityName" + } + }, + { + "$ref": "#/components/parameters/tip" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReadOnlyFunctionArgs" + } + } + } + }, + "responses": { + "200": { + "description": "Function executed successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReadOnlyFunctionResult" + }, + "examples": { + "success": { + "$ref": "#/components/examples/read-only-function-success.example" + }, + "failure": { + "$ref": "#/components/examples/read-only-function-failure.example" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v3/contracts/fast-call-read/{deployer_address}/{contract_name}/{function_name}": { + "post": { + "summary": "Call read-only function in fast mode (no cost and memory tracking)", + "description": "Call a read-only public function on a given smart contract without cost tracking.\n\nThe contract is identified with [Stacks Address] and [Contract Name] in the URL path.\nThe function is identified with [Function Name].\n\nThe arguments to the function are supplied via the POST body.\nThis should be a JSON object with two main properties:\n- `sender` which should be a Stacks address or contract principal\n- `arguments` which should be an array of hex-encoded Clarity values.\n\n**This API endpoint requires a basic Authorization header.**\n", + "tags": [ + "Smart Contracts" + ], + "security": [ + { + "rpcAuth": [] + } + ], + "operationId": "fastCallReadOnlyFunction", + "parameters": [ + { + "$ref": "#/components/parameters/deployer-address" + }, + { + "$ref": "#/components/parameters/contract-name" + }, + { + "name": "function_name", + "in": "path", + "required": true, + "schema": { + "$ref": "#/components/schemas/ClarityName" + } + }, + { + "$ref": "#/components/parameters/tip" + } + ], + "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": "#/components/schemas/ReadOnlyFunctionArgs" + }, + "examples": { + "fast-call-request": { + "summary": "Fast call read-only function request", + "value": { + "sender": "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info", + "arguments": [ + "0x0011...", + "0x00231..." + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Function executed successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReadOnlyFunctionResult" + }, + "examples": { + "success": { + "$ref": "#/components/examples/read-only-function-success.example" + }, + "failure": { + "$ref": "#/components/examples/read-only-function-failure.example" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v2/accounts/{principal}": { + "get": { + "summary": "Get account info", + "tags": [ + "Accounts" + ], + "security": [], + "operationId": "getAccountInfo", + "description": "Get the account data for the provided principal\n\nWhere 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.\n\nFor non-existent accounts, this does not 404, rather it returns an object with balance and nonce of 0.\n\nUnder PoX-5, `unstake` keeps the amount locked and moves `unlock_height` to the first Bitcoin block of the next reward cycle. STX paired with a protocol bond stays locked until the bond ends. When the burn block height of the queried tip reaches `unlock_height`, the amount moves into `balance` with no transaction.\n", + "parameters": [ + { + "$ref": "#/components/parameters/principal" + }, + { + "$ref": "#/components/parameters/proof" + }, + { + "$ref": "#/components/parameters/tip" + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccountData" + }, + "examples": { + "account-data": { + "$ref": "#/components/examples/account-data.example" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v2/fees/transaction": { + "post": { + "summary": "Get approximate fees for the given transaction", + "tags": [ + "Fees" + ], + "security": [], + "description": "Get an estimated fee for the supplied transaction. This\nestimates the execution cost of the transaction, the current\nfee rate of the network, and returns estimates for fee\namounts.\n\n* `transaction_payload` is a hex-encoded serialization of\n the TransactionPayload for the transaction.\n* `estimated_len` is an optional argument that provides the\n endpoint with an estimation of the final length (in bytes)\n of the transaction, including any post-conditions and\n signatures\n\nIf the node cannot provide an estimate for the transaction\n(e.g., if the node has never seen a contract-call for the\ngiven contract and function) or if estimation is not\nconfigured on this node, a 400 response is returned.\nThe 400 response will be a JSON error containing a `reason`\nfield which can be one of the following:\n\n* `DatabaseError` - this Stacks node has had an internal\n database error while trying to estimate the costs of the\n supplied transaction.\n* `NoEstimateAvailable` - this Stacks node has not seen this\n kind of contract-call before, and it cannot provide an\n estimate yet.\n* `CostEstimationDisabled` - this Stacks node does not perform\n fee or cost estimation, and it cannot respond on this\n endpoint.\n\nThe 200 response contains the following data:\n\n* `estimated_cost` - the estimated multi-dimensional cost of\n executing the Clarity VM on the provided transaction.\n* `estimated_cost_scalar` - a unitless integer that the Stacks\n node uses to compare how much of the block limit is consumed\n by different transactions. This value incorporates the\n estimated length of the transaction and the estimated\n execution cost of the transaction. The range of this integer\n may vary between different Stacks nodes. In order to compute\n an estimate of total fee amount for the transaction, this\n value is multiplied by the same Stacks node\"s estimated fee\n rate.\n* `cost_scalar_change_by_byte` - a float value that indicates how\n much the `estimated_cost_scalar` value would increase for every\n additional byte in the final transaction.\n* `estimations` - an array of estimated fee rates and total fees to\n pay in microSTX for the transaction. This array provides a range of\n estimates (default: 3) that may be used. Each element of the array\n contains the following fields:\n * `fee_rate` - the estimated value for the current fee\n rates in the network\n * `fee` - the estimated value for the total fee in\n microSTX that the given transaction should pay. These\n values are the result of computing:\n `fee_rate` x `estimated_cost_scalar`.\n If the estimated fees are less than the minimum relay\n fee `(1 ustx x estimated_len)`, then that minimum relay\n fee will be returned here instead.\n\n\nNote: If the final transaction\"s byte size is larger than\nsupplied to `estimated_len`, then applications should increase\nthis fee amount by:\n\n `fee_rate` x `cost_scalar_change_by_byte` x (`final_size` - `estimated_size`)\n", + "operationId": "getFeeTransaction", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FeeTransactionRequest" + }, + "examples": { + "fee-transaction-request": { + "summary": "Fee estimation request", + "value": { + "estimated_len": 350, + "transaction_payload": "021af942874ce525e87f21bbe8c121b12fac831d02f4086765742d696e666f0b7570646174652d696e666f00000000" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Estimated fees for the transaction", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FeeTransactionResponse" + }, + "examples": { + "fee-transaction-response": { + "$ref": "#/components/examples/fee-transaction-response.example" + } + } + } + } + }, + "400": { + "description": "Fee estimation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FeeTransactionError" + } + }, + "text/plain": { + "schema": { + "type": "string" + }, + "example": "Failed to decode: Failed to parse JSON body" + } + } + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v2/fees/transfer": { + "get": { + "summary": "Get estimated fee", + "tags": [ + "Fees" + ], + "security": [], + "operationId": "getFeeTransfer", + "description": "Get an estimated fee rate for STX transfer transactions. This is a fee\nrate per byte, returned as a JSON integer (microSTX per byte).\n", + "responses": { + "200": { + "description": "Fee rate in microSTX per byte", + "content": { + "application/json": { + "schema": { + "type": "integer", + "minimum": 1, + "description": "Fee rate in microSTX per byte" + }, + "example": 3 + } + } + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v2/info": { + "get": { + "summary": "Get Core API info", + "description": "Get Core API information", + "tags": [ + "Info" + ], + "security": [], + "operationId": "getNodeInfo", + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NodeInfo" + }, + "examples": { + "node-info": { + "$ref": "#/components/examples/node-info.example" + } + } + } + } + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v2/pox": { + "get": { + "summary": "Get PoX details", + "description": "Get Proof of Transfer (PoX) information. Can be used for Stacking.", + "tags": [ + "Info" + ], + "security": [], + "operationId": "getPoxInfo", + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PoxInfo" + }, + "examples": { + "pox-info": { + "$ref": "#/components/examples/pox-info.example" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "parameters": [ + { + "$ref": "#/components/parameters/tip" + } + ] + } + }, + "/v2/traits/{deployer_address}/{contract_name}/{trait_deployer_address}/{trait_contract_name}/{trait_name}": { + "get": { + "summary": "Get trait implementation details", + "description": "Determine whether or not a specified trait is implemented (either\nexplicitly or implicitly) within a given contract.\n", + "tags": [ + "Smart Contracts" + ], + "security": [], + "operationId": "checkTraitImplementation", + "parameters": [ + { + "$ref": "#/components/parameters/deployer-address" + }, + { + "$ref": "#/components/parameters/contract-name" + }, + { + "name": "trait_deployer_address", + "in": "path", + "required": true, + "description": "Stacks address of the trait-defining contract.\n", + "schema": { + "$ref": "#/components/schemas/StandardPrincipal" + } + }, + { + "name": "trait_contract_name", + "in": "path", + "required": true, + "description": "Contract name of the trait-defining contract.", + "schema": { + "type": "string", + "pattern": "^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$", + "minLength": 1, + "maxLength": 128, + "example": "some-trait" + } + }, + { + "name": "trait_name", + "in": "path", + "required": true, + "schema": { + "$ref": "#/components/schemas/ClarityName" + }, + "example": "some-trait" + }, + { + "$ref": "#/components/parameters/tip" + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IsTraitImplemented" + }, + "examples": { + "is-trait-implemented": { + "$ref": "#/components/examples/is-trait-implemented.example" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + } + }, + "/v2/clarity/marf/{marf_key_hash}": { + "get": { + "summary": "Get the MARF value for a given key", + "tags": [ + "Smart Contracts" + ], + "security": [], + "operationId": "getClarityMarfValue", + "description": "Attempt to fetch the value of a MARF key. The key is a 64-character\nhex string representing the MARF node hash.\n", + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClarityData" + }, + "examples": { + "clarity-data": { + "$ref": "#/components/examples/clarity-data.example" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + }, + "parameters": [ + { + "name": "marf_key_hash", + "in": "path", + "required": true, + "description": "The 64-character hex-encoded hash of the MARF key.", + "schema": { + "type": "string", + "pattern": "^[0-9a-f]{64}$", + "minLength": 64, + "maxLength": 64 + } + }, + { + "$ref": "#/components/parameters/proof" + }, + { + "$ref": "#/components/parameters/tip" + } + ] + } + }, + "/v2/clarity/metadata/{deployer_address}/{contract_name}/{clarity_metadata_key}": { + "get": { + "summary": "Get the contract metadata for the metadata key", + "tags": [ + "Smart Contracts" + ], + "security": [], + "operationId": "getClarityMetadata", + "description": "Attempt to fetch the metadata of a contract. The contract is identified\nwith [Contract Address] and [Contract Name] in the URL path. The metadata\nkey is identified with [Clarity Metadata Key].\n\nIn the response, `data` is formatted as JSON.\n", + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClarityMetadata" + }, + "examples": { + "clarity-metadata": { + "$ref": "#/components/examples/clarity-metadata.example" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "parameters": [ + { + "$ref": "#/components/parameters/deployer-address" + }, + { + "$ref": "#/components/parameters/contract-name" + }, + { + "name": "clarity_metadata_key", + "in": "path", + "required": true, + "description": "Metadata key. Must be either:\n- \"analysis\" for contract analysis data\n- \"vm-metadata::N::TYPE\" where N is the epoch (1-2 digits) and TYPE is one of:\n contract, contract-size, contract-src, contract-data-size, or a valid Clarity name\n", + "schema": { + "type": "string", + "pattern": "^(analysis)|(vm-metadata::\\d{1,2}::(contract|contract-size|contract-src|contract-data-size|[a-zA-Z]([a-zA-Z0-9]|[-_!?+<>=/*])*))$", + "example": "analysis" + } + }, + { + "$ref": "#/components/parameters/tip" + } + ] + } + }, + "/v2/constant_val/{deployer_address}/{contract_name}/{constant_name}": { + "get": { + "summary": "Get the value of a constant inside a contract", + "tags": [ + "Smart Contracts" + ], + "security": [], + "operationId": "getConstantValue", + "description": "Attempt to fetch the value of a constant inside a contract. The contract\nis identified with [Stacks Address] and [Contract Name] in the URL path.\nThe constant is identified with [Constant Name].\n\nIn the response, `data` is the hex serialization of the constant value.\n", + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConstantValue" + }, + "examples": { + "constant-value": { + "$ref": "#/components/examples/constant-value.example" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "parameters": [ + { + "$ref": "#/components/parameters/deployer-address" + }, + { + "$ref": "#/components/parameters/contract-name" + }, + { + "name": "constant_name", + "in": "path", + "required": true, + "schema": { + "$ref": "#/components/schemas/ClarityName" + } + }, + { + "$ref": "#/components/parameters/tip" + } + ] + } + }, + "/v3/block_proposal": { + "post": { + "summary": "Validate a proposed Stacks block", + "tags": [ + "Mining" + ], + "operationId": "postBlockProposal", + "description": "Used by stackers to validate a proposed Stacks block from a miner.\n**This API endpoint requires a basic Authorization header.**\n", + "security": [ + { + "rpcAuth": [] + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "block", + "chain_id" + ], + "properties": { + "block": { + "type": "string", + "minLength": 400, + "pattern": "^([0-9a-fA-F]{2})+$", + "description": "Hex-encoded block data (must be valid SIP-003 serialized block, typically 200+ bytes)" + }, + "chain_id": { + "type": "integer", + "minimum": 0, + "description": "Chain ID for the block" + } + } + }, + "examples": { + "block-proposal-request": { + "summary": "Block proposal request", + "value": { + "block": "00000000000000001f00000000000927c08fb5ae5bf80e39e4168f6a3fddb0407a069d21ee68465e6856393254d2a66194f44bb01070666d5effcfb2436e209a75878fe80a04b4258a8cd34ab97c38a8dde331a2a509dd7e4b90590726866172cc138c18e80567737667f55d3f9817ce4714c91d1adfd36101141829dc0b5ea0c4944668c0005ddb6f9e2718f60014f21932a42a36ffaf58e88e77b217b2af366c15dd59e6b136ca773729832dcfc5875ec0830d04012dd5a4fa77a196646ea2b356289116fd02558c034b62d63f8a65bdd20d7ffc3fec6c266cd974be776a9e92759b90f288dcc2525b6b6bd5622c5f02e0922440e9ad1095c19b4467fd94566caa9755669d8e0000000180800000000400f64081ae6209dce9245753a4f764d6f168aae1af00000000000000000000000000000064000041dbcc7391991c1a18371eb49b879240247a3ec7f281328f53976c1218ffd65421dbb101e59370e2c972b29f48dc674b2de5e1b65acbd41d5d2689124d42c16c01010000000000051a346048df62be3a52bb6236e11394e8600229e27b000000000000271000000000000000000000000000000000000000000000000000000000000000000000", + "chain_id": 2147483648 + } + } + } + } + } + }, + "responses": { + "202": { + "description": "Block proposal has been accepted for processing.\nThe result will be returned via the event observer.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BlockProposalResponse" + }, + "examples": { + "block-proposal-accepted": { + "$ref": "#/components/examples/post-block-proposal-response.example" + } + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BlockProposalResponse" + }, + "example": { + "result": "Error", + "message": "Bad Request." + } + }, + "text/plain": { + "schema": { + "type": "string" + }, + "example": "Bad request." + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "description": "There is an ongoing proposal validation being processed, the new\nrequest cannot be accepted until the prior request has been processed.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BlockProposalResponse" + }, + "examples": { + "too-many-requests": { + "$ref": "#/components/examples/post-block-proposal-response.429.example" + } + } + } + } + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v3/stacker_set/{cycle_number}": { + "get": { + "summary": "Fetch the stacker and signer set information for a given cycle.", + "tags": [ + "Signers" + ], + "security": [], + "operationId": "getStackerSet", + "description": "Used to get stacker and signer set information for a given cycle.\n\nThis will only return information for cycles starting in Epoch 2.5\n(PoX-4) or later, including PoX-5 cycles. The response shape depends on\n`reward_set_version`: `0` for PoX-4 cycles, `1` for PoX-5 cycles.\n", + "parameters": [ + { + "name": "cycle_number", + "in": "path", + "required": true, + "description": "reward cycle number", + "schema": { + "type": "integer" + } + }, + { + "$ref": "#/components/parameters/tip" + } + ], + "responses": { + "200": { + "description": "Information for the given reward cycle", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetStackerSet" + }, + "examples": { + "stacker-set-pox4": { + "$ref": "#/components/examples/get-stacker-set-pox4.example" + }, + "stacker-set-pox5": { + "$ref": "#/components/examples/get-stacker-set-pox5.example" + } + } + } + } + }, + "400": { + "description": "Could not fetch the given reward set", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "response", + "err_msg" + ], + "properties": { + "response": { + "type": "string", + "enum": [ + "error" + ], + "description": "Response status" + }, + "err_type": { + "type": "string", + "description": "Error type classification" + }, + "err_msg": { + "type": "string", + "description": "Detailed error message" + } + } + }, + "examples": { + "stacker-set-error": { + "$ref": "#/components/examples/get-stacker-set-400.example" + } + } + } + } + }, + "404": { + "description": "Reward cycle not found or does not exist", + "content": { + "text/plain": { + "schema": { + "type": "string" + }, + "example": "No such file or directory" + } + } + } + } + } + }, + "/v3/blocks/{block_id}": { + "get": { + "summary": "Get Nakamoto block by ID", + "tags": [ + "Blocks" + ], + "security": [], + "operationId": "getNakamotoBlockById", + "description": "Get a specific Nakamoto block (Stacks 3.x+) by its index block hash. This endpoint streams\nthe block data from the Nakamoto staging blocks database where Nakamoto blocks are stored\nwith additional metadata including tenure information.\n\n**Compatibility**: Works with Nakamoto blocks only. For Stacks 2.x blocks, use `/v2/blocks/{block_id}`.\n", + "parameters": [ + { + "name": "block_id", + "in": "path", + "description": "The block's ID hash (64-character hex string)", + "required": true, + "schema": { + "type": "string", + "pattern": "^[0-9a-f]{64}$", + "minLength": 64, + "maxLength": 64, + "examples": [ + "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" + ] + } + } + ], + "responses": { + "200": { + "description": "The raw SIP-003-encoded block will be returned.", + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "405": { + "$ref": "#/components/responses/MethodNotAllowed" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v3/blocks/height/{block_height}": { + "get": { + "summary": "Fetch a Nakamoto block by its height and optional tip", + "tags": [ + "Blocks" + ], + "security": [], + "operationId": "getNakamotoBlockByHeight", + "description": "Fetch a Nakamoto block by its height and optional tip.", + "parameters": [ + { + "name": "block_height", + "in": "path", + "description": "The block's height (max 4294967295)", + "required": true, + "schema": { + "type": "integer", + "minimum": 0, + "maximum": 4294967295 + } + }, + { + "$ref": "#/components/parameters/tip" + } + ], + "responses": { + "200": { + "description": "The raw SIP-003-encoded block will be returned.", + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v3/tenures/info": { + "get": { + "summary": "Fetch metadata about the ongoing Nakamoto tenure", + "tags": [ + "Blocks" + ], + "security": [], + "operationId": "getTenureInfo", + "description": "Fetch metadata about the ongoing Nakamoto tenure. This information is\nsufficient to obtain and authenticate the highest complete tenure, as\nwell as obtain new tenure blocks.\n", + "responses": { + "200": { + "description": "Metadata about the ongoing tenure", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TenureInfo" + }, + "examples": { + "tenure-info": { + "$ref": "#/components/examples/get-tenure-info.example" + } + } + } + } + } + } + } + }, + "/v3/tenures/{block_id}": { + "get": { + "summary": "Fetch a sequence of Nakamoto blocks in a tenure", + "tags": [ + "Blocks" + ], + "security": [], + "operationId": "getTenures", + "description": "Fetch a sequence of Nakamoto blocks in a tenure. The blocks will be\nserved in order from highest to lowest. The blocks will be encoded in\ntheir SIP-003 wire format, and concatenated together.\n", + "parameters": [ + { + "name": "block_id", + "in": "path", + "description": "The tenure-start block ID of the tenure to query (64-character hex string)", + "required": true, + "schema": { + "type": "string", + "pattern": "^[0-9a-f]{64}$", + "minLength": 64, + "maxLength": 64, + "examples": [ + "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" + ] + } + }, + { + "name": "stop", + "in": "query", + "description": "The block ID hash of the highest block in this tenure that is already\nknown to the caller. Neither the corresponding block nor any of its\nancestors will be served. This is used to fetch tenure blocks that the\ncaller does not have.\n", + "required": false, + "schema": { + "type": "string", + "pattern": "^[0-9a-f]{64}$", + "minLength": 64, + "maxLength": 64 + } + } + ], + "responses": { + "200": { + "description": "SIP-003-encoded Nakamoto blocks, concatenated together", + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "405": { + "$ref": "#/components/responses/MethodNotAllowed" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v3/tenures/blocks/{consensus_hash}": { + "get": { + "summary": "Get the list of Stacks blocks in a tenure", + "tags": [ + "Blocks" + ], + "security": [], + "operationId": "getTenureBlocks", + "description": "Get the list of blocks in a tenure. The blocks will be\nshown in order from highest to lowest.\n", + "parameters": [ + { + "name": "consensus_hash", + "in": "path", + "description": "The hex-encoded consensus hash of the tenure to query (40 hexadecimal characters, without 0x prefix)", + "required": true, + "schema": { + "type": "string", + "pattern": "^[0-9a-f]{40}$" + } + } + ], + "responses": { + "200": { + "description": "List of Stacks blocks in the tenure", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TenureBlocks" + }, + "examples": { + "tenure-blocks": { + "$ref": "#/components/examples/tenure-blocks.example" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v3/tenures/blocks/hash/{burnchain_block_hash}": { + "get": { + "summary": "Get the list of Nakamoto Stacks blocks in a tenure given Bitcoin block hash", + "tags": [ + "Blocks" + ], + "security": [], + "operationId": "getTenureBlocksByHash", + "description": "Get the list of Nakamoto blocks in a tenure given the Bitcoin block hash. The blocks will be\nshown in order from highest to lowest. This is only for Nakamoto blocks, Epoch2 ones will not be shown.\n", + "parameters": [ + { + "name": "burnchain_block_hash", + "in": "path", + "description": "The hex-encoded Bitcoin block hash of the tenure to query (64 hexadecimal characters, without 0x prefix)", + "required": true, + "schema": { + "type": "string", + "pattern": "^[0-9a-f]{64}$" + } + } + ], + "responses": { + "200": { + "description": "List of Stacks blocks in the tenure", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TenureBlocks" + }, + "examples": { + "tenure-blocks": { + "$ref": "#/components/examples/tenure-blocks.example" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v3/tenures/blocks/height/{burnchain_block_height}": { + "get": { + "summary": "Get the list of Nakamoto Stacks blocks in a tenure given Bitcoin block height", + "tags": [ + "Blocks" + ], + "security": [], + "operationId": "getTenureBlocksByHeight", + "description": "Get the list of Nakamoto blocks in a tenure given the Bitcoin block height. The blocks will be\nshown in order from highest to lowest. This is only for Nakamoto blocks, Epoch2 ones will not be shown.\n", + "parameters": [ + { + "name": "burnchain_block_height", + "in": "path", + "description": "The Bitcoin block height of the tenure to query", + "required": true, + "schema": { + "type": "integer", + "minimum": 0, + "maximum": 4294967295 + } + } + ], + "responses": { + "200": { + "description": "List of Stacks blocks in the tenure", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TenureBlocks" + }, + "examples": { + "tenure-blocks": { + "$ref": "#/components/examples/tenure-blocks.example" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v3/sortitions": { + "get": { + "summary": "Get latest sortition information", + "tags": [ + "Blocks" + ], + "security": [], + "operationId": "getLatestSortitions", + "description": "Get sortition information about the latest burnchain block processed by this node.\nReturns a single-element array with the latest sortition.\n", + "responses": { + "200": { + "description": "Latest sortition information", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Sortitions" + }, + "examples": { + "latest-sortition": { + "$ref": "#/components/examples/get-sortitions.example" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v3/sortitions/latest_and_last": { + "get": { + "summary": "Get latest and last winning sortitions", + "tags": [ + "Blocks" + ], + "security": [], + "operationId": "getLatestAndLastWinningSortitions", + "description": "Get sortition information about the latest burn block with a winning miner\nAND the previous such burn block. Returns an array with two sortition objects.\n", + "responses": { + "200": { + "description": "Latest and last sortition information", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Sortitions" + }, + "examples": { + "latest-and-last-sortitions": { + "$ref": "#/components/examples/get-sortitions-latest-and-prior.example" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v3/sortitions/consensus/{consensus_hash}": { + "get": { + "summary": "Get sortition by consensus hash", + "tags": [ + "Blocks" + ], + "security": [], + "operationId": "getSortitionByConsensusHash", + "description": "Get sortition information for a specific consensus hash.\nReturns a single-element array with the matching sortition.\n", + "parameters": [ + { + "name": "consensus_hash", + "in": "path", + "required": true, + "description": "Hex-encoded consensus hash (40 characters)", + "schema": { + "type": "string", + "pattern": "^[0-9a-f]{40}$" + } + } + ], + "responses": { + "200": { + "description": "Sortition information for the consensus hash", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Sortitions" + }, + "examples": { + "sortition-by-consensus": { + "$ref": "#/components/examples/get-sortitions.example" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v3/sortitions/burn/{burn_header_hash}": { + "get": { + "summary": "Get sortition by burn header hash", + "tags": [ + "Blocks" + ], + "security": [], + "operationId": "getSortitionByBurnHeaderHash", + "description": "Get sortition information for a specific burn header hash.\nReturns a single-element array with the matching sortition.\n", + "parameters": [ + { + "name": "burn_header_hash", + "in": "path", + "required": true, + "description": "Hex-encoded burn header hash (64 characters)", + "schema": { + "type": "string", + "pattern": "^[0-9a-f]{64}$" + } + } + ], + "responses": { + "200": { + "description": "Sortition information for the burn header hash", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Sortitions" + }, + "examples": { + "sortition-by-burn-hash": { + "$ref": "#/components/examples/get-sortitions.example" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v3/sortitions/burn_height/{height}": { + "get": { + "summary": "Get sortition by burn block height", + "tags": [ + "Blocks" + ], + "security": [], + "operationId": "getSortitionByBurnBlockHeight", + "description": "Get sortition information for a specific burn block height.\nReturns a single-element array with the matching sortition.\n", + "parameters": [ + { + "name": "height", + "in": "path", + "required": true, + "description": "Burn block height (integer, max 4294967295)", + "schema": { + "type": "integer", + "minimum": 0, + "maximum": 4294967295 + } + } + ], + "responses": { + "200": { + "description": "Sortition information for the burn block height", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Sortitions" + }, + "examples": { + "sortition-by-height": { + "$ref": "#/components/examples/get-sortitions.example" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v3/signer/{signer_pubkey}/{cycle_number}": { + "get": { + "summary": "Get number of blocks signed by signer during a given reward cycle", + "tags": [ + "Blocks", + "Signers" + ], + "security": [], + "operationId": "getSignerBlocksSigned", + "description": "Get number of blocks signed by signer during a given reward cycle", + "parameters": [ + { + "name": "signer_pubkey", + "in": "path", + "required": true, + "description": "Hex-encoded compressed Secp256k1 public key of signer", + "schema": { + "type": "string", + "pattern": "^0[23][0-9a-f]{64}$" + } + }, + { + "name": "cycle_number", + "in": "path", + "required": true, + "description": "Reward cycle number", + "schema": { + "type": "integer", + "minimum": 0 + } + } + ], + "responses": { + "200": { + "description": "Number of blocks signed", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SignerBlocksSigned" + }, + "example": { + "blocks_signed": 7 + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v3/transaction/{txid}": { + "get": { + "summary": "Retrieve transaction details by TXID", + "tags": [ + "Transactions" + ], + "security": [], + "description": "Get a JSON with the transaction details including the `index_block_hash`,\nthe hex-encoded transaction body, and the `result`.\n", + "operationId": "getTransactionById", + "parameters": [ + { + "name": "txid", + "in": "path", + "required": true, + "description": "Transaction ID (64 hexadecimal characters)", + "schema": { + "type": "string", + "pattern": "^[0-9a-f]{64}$" + } + } + ], + "responses": { + "200": { + "description": "Transaction JSON with index_block_hash, transaction body and result", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TransactionInfo" + }, + "examples": { + "transaction-info": { + "$ref": "#/components/examples/get-transaction.example" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "501": { + "description": "Transaction indexing not enabled", + "content": { + "text/plain": { + "schema": { + "type": "string" + }, + "example": "Transaction indexing is not enabled" + } + } + } + } + } + }, + "/v3/health": { + "get": { + "summary": "Query the health of the node.", + "description": "Get node health information.\nA node is considered healthy if its Stacks tip height matches the maximum Stacks tip height observed among its connected peers.\nThis endpoint returns:\n- `difference_from_max_peer`: The difference in Stacks height between this node and its most advanced peer.\n- `max_stacks_height_of_neighbors`: The maximum Stacks height observed among the node\"s connected peers.\n- `node_stacks_tip_height`: The current Stacks tip height of this node.\n- `max_stacks_neighbor_address`: The address of the most advanced peer. Null if no peer data is available.\n", + "tags": [ + "Info" + ], + "security": [], + "operationId": "getNodeHealth", + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetHealth" + }, + "examples": { + "node-health": { + "$ref": "#/components/examples/node-health.example" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v2/attachments/{hash}": { + "get": { + "summary": "Get attachment by hash", + "tags": [ + "Atlas" + ], + "security": [], + "operationId": "getAttachment", + "description": "Get an attachment by its hash. Attachments are content stored in the Atlas network.\n\nThe attachment hash is a 40-character hex string (SHA-1 hash).\n", + "parameters": [ + { + "name": "hash", + "in": "path", + "required": true, + "description": "Hex-encoded SHA-1 hash of the attachment (40 characters)", + "schema": { + "type": "string", + "pattern": "^[0-9a-f]{40}$" + } + } + ], + "responses": { + "200": { + "description": "The attachment content", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AttachmentData" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + } + }, + "/v2/attachments/inv": { + "get": { + "summary": "Get attachment inventory", + "tags": [ + "Atlas" + ], + "security": [], + "operationId": "getAttachmentsInventory", + "description": "Get inventory of attachments for a given index block hash and page range.\nThis returns a bitfield indicating which attachments are available.\n", + "parameters": [ + { + "name": "index_block_hash", + "in": "query", + "required": true, + "description": "Hex-encoded index block hash (64 characters)", + "schema": { + "type": "string", + "pattern": "^[0-9a-f]{64}$" + } + }, + { + "name": "pages_indexes", + "in": "query", + "required": true, + "description": "Comma-separated list of page indexes to query.\n- Maximum 8 pages per request\n- Each index must be 0-4294967295 (u32 range)\n- Values outside u32 range return 400 Bad Request\n", + "schema": { + "type": "string", + "example": "1,2,3", + "pattern": "^[0-9]{1,10}(,[0-9]{1,10}){0,7}$" + } + } + ], + "responses": { + "200": { + "description": "Attachment inventory bitfield", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AttachmentInventory" + }, + "examples": { + "attachment-inventory": { + "summary": "Attachment inventory response", + "value": { + "block_id": "0123456789abcdef0123456789abcdef0123456789abcdef", + "pages": [ + { + "index": 1, + "inventory": [ + 255, + 0, + 255, + 0 + ] + }, + { + "index": 2, + "inventory": [ + 0, + 255, + 0, + 255 + ] + } + ] + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + } + }, + "/v2/microblocks/confirmed/{block_id}": { + "get": { + "summary": "Get stream of confirmed microblocks (Epoch 2.x)", + "tags": [ + "Blocks", + "Microblocks" + ], + "security": [], + "operationId": "getConfirmedMicroblocks", + "description": "Get microblocks that were confirmed by the given anchored block.\nThe microblocks are returned as a binary stream of concatenated microblock data.\n", + "parameters": [ + { + "name": "block_id", + "in": "path", + "required": true, + "description": "Hex-encoded Stacks block ID (64 characters)", + "schema": { + "type": "string", + "pattern": "^[0-9a-f]{64}$" + } + } + ], + "responses": { + "200": { + "description": "Stream of confirmed microblocks", + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v2/microblocks/{microblock_id}": { + "get": { + "summary": "Get a stream of microblocks beginning\nwith the given microblock (Epoch 2.x).\n", + "tags": [ + "Blocks", + "Microblocks" + ], + "security": [], + "operationId": "getMicroblockById", + "parameters": [ + { + "name": "microblock_id", + "in": "path", + "required": true, + "description": "Hex-encoded microblock hash (64 characters)", + "schema": { + "type": "string", + "pattern": "^[0-9a-f]{64}$" + } + } + ], + "responses": { + "200": { + "description": "The microblock data", + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v2/microblocks/unconfirmed/{block_id}/{seq}": { + "get": { + "summary": "Get stream of unconfirmed microblocks (Epoch 2.x)", + "tags": [ + "Blocks", + "Microblocks" + ], + "security": [], + "operationId": "getUnconfirmedMicroblocks", + "description": "Get unconfirmed microblocks starting from a specific sequence number.\nThe microblocks are returned as a binary stream.\n", + "parameters": [ + { + "name": "block_id", + "in": "path", + "required": true, + "description": "Hex-encoded parent block ID (64 characters)", + "schema": { + "type": "string", + "pattern": "^[0-9a-f]{64}$" + } + }, + { + "name": "seq", + "in": "path", + "required": true, + "description": "Starting sequence number (0-65535)", + "schema": { + "type": "integer", + "minimum": 0, + "maximum": 65535 + } + } + ], + "responses": { + "200": { + "description": "Stream of unconfirmed microblocks", + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v2/microblocks": { + "post": { + "summary": "Submit a microblock (Epoch 2.x)", + "tags": [ + "Blocks", + "Microblocks" + ], + "security": [], + "operationId": "postMicroblock", + "description": "Submit a microblock to the node for validation and relay.\nThe body **must** be the SIP-003 binary serialization of a `Microblock`\nand sent with `Content-Type: application/octet-stream`.\n", + "requestBody": { + "required": true, + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary", + "minLength": 1 + } + } + } + }, + "responses": { + "200": { + "description": "Index-block hash of the accepted microblock", + "content": { + "application/json": { + "schema": { + "type": "string", + "description": "32-byte block-header hash (hex)", + "pattern": "^[0-9a-f]{64}$" + }, + "example": "3e4f5d6b7c8a9e0ff1122303445566778899aabbccddeeff0011223344556677" + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v2/stackerdb/{principal}/{contract_name}/{slot_id}": { + "get": { + "summary": "Get StackerDB chunk (latest version)", + "tags": [ + "StackerDB" + ], + "security": [], + "operationId": "getStackerDbChunk", + "description": "Get the latest version of a chunk of data from a StackerDB instance.\n", + "parameters": [ + { + "$ref": "#/components/parameters/standard-principal" + }, + { + "$ref": "#/components/parameters/contract-name" + }, + { + "name": "slot_id", + "in": "path", + "required": true, + "description": "Slot ID (u32 range)", + "schema": { + "type": "integer", + "minimum": 0, + "maximum": 4294967295 + } + } + ], + "responses": { + "200": { + "description": "StackerDB chunk data", + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v2/stackerdb/{principal}/{contract_name}/{slot_id}/{slot_version}": { + "get": { + "summary": "Get StackerDB chunk (specific version)", + "tags": [ + "StackerDB" + ], + "security": [], + "operationId": "getStackerDbChunkVersioned", + "description": "Get a specific version of a chunk of data from a StackerDB instance.\n", + "parameters": [ + { + "$ref": "#/components/parameters/standard-principal" + }, + { + "$ref": "#/components/parameters/contract-name" + }, + { + "name": "slot_id", + "in": "path", + "required": true, + "description": "Slot ID (u32 range)", + "schema": { + "type": "integer", + "minimum": 0, + "maximum": 4294967295 + } + }, + { + "name": "slot_version", + "in": "path", + "required": true, + "description": "Specific slot version (u32 range)", + "schema": { + "type": "integer", + "minimum": 0, + "maximum": 4294967295 + } + } + ], + "responses": { + "200": { + "description": "StackerDB chunk data", + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v2/stackerdb/{principal}/{contract_name}": { + "get": { + "summary": "Get StackerDB metadata", + "tags": [ + "StackerDB" + ], + "security": [], + "operationId": "getStackerDbMetadata", + "description": "Get metadata about a StackerDB instance, including slot information.\n", + "parameters": [ + { + "$ref": "#/components/parameters/standard-principal" + }, + { + "$ref": "#/components/parameters/contract-name" + } + ], + "responses": { + "200": { + "description": "StackerDB metadata", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StackerDbMetadata" + }, + "examples": { + "stackerdb-metadata": { + "summary": "StackerDB metadata response", + "value": [ + { + "slot_id": 0, + "slot_version": 1, + "data_hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", + "signature": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" + } + ] + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v2/stackerdb/{principal}/{contract_name}/chunks": { + "post": { + "summary": "Write StackerDB chunk", + "tags": [ + "StackerDB" + ], + "security": [], + "operationId": "postStackerDbChunk", + "description": "Write a chunk of data to a StackerDB instance.\n\nThe request body should contain a JSON object with the chunk data including\nslot_id, slot_version, signature, and hex-encoded data.\n\nThe response indicates whether the chunk was accepted, and if not, provides\ndetailed error information. Note that failed writes return HTTP 200 with\naccepted: false, not HTTP error codes.\n", + "parameters": [ + { + "$ref": "#/components/parameters/standard-principal" + }, + { + "$ref": "#/components/parameters/contract-name" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StackerDbChunkData" + }, + "examples": { + "stackerdb-chunk-request": { + "summary": "StackerDB chunk data request", + "value": { + "slot_id": 1, + "slot_version": 2, + "sig": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef01", + "data": "deadbeefcafebabe" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Chunk submission result (both success and failure cases)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StackerDbChunkAckData" + }, + "examples": { + "success": { + "$ref": "#/components/examples/stackerdb-chunk-ack-success.example" + }, + "failure": { + "$ref": "#/components/examples/stackerdb-chunk-ack-failure.example" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v2/stackerdb/{principal}/{contract_name}/replicas": { + "get": { + "summary": "List StackerDB replicas", + "tags": [ + "StackerDB" + ], + "security": [], + "operationId": "listStackerDbReplicas", + "description": "Get a list of replicas for a StackerDB instance.\n", + "parameters": [ + { + "$ref": "#/components/parameters/standard-principal" + }, + { + "$ref": "#/components/parameters/contract-name" + } + ], + "responses": { + "200": { + "description": "List of StackerDB replicas", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StackerDbReplicas" + }, + "examples": { + "stackerdb-replicas": { + "summary": "List of StackerDB replicas", + "value": [ + { + "ip": "127.0.0.1", + "port": 20444, + "public_key_hash": "03abc123..." + } + ] + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v2/data_var/{principal}/{contract_name}/{var_name}": { + "get": { + "summary": "Get contract data variable", + "tags": [ + "Smart Contracts" + ], + "security": [], + "operationId": "getContractDataVariable", + "description": "Fetch a data variable from a smart contract.\nReturns the raw hex-encoded value of the variable.\n", + "parameters": [ + { + "$ref": "#/components/parameters/standard-principal" + }, + { + "$ref": "#/components/parameters/contract-name" + }, + { + "name": "var_name", + "in": "path", + "required": true, + "description": "Variable name (must be a valid Clarity name)", + "schema": { + "$ref": "#/components/schemas/ClarityName" + } + }, + { + "$ref": "#/components/parameters/proof" + }, + { + "$ref": "#/components/parameters/tip" + } + ], + "responses": { + "200": { + "description": "The data variable value", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClarityData" + }, + "examples": { + "clarity-data": { + "$ref": "#/components/examples/clarity-data.example" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + } + }, + "/v2/headers/{quantity}": { + "get": { + "summary": "Get recent 2.x block headers", + "tags": [ + "Blocks" + ], + "security": [], + "operationId": "getBlockHeaders", + "description": "**Deprecated**: This endpoint is deprecated since Nakamoto.**\nStream (as a JSON array) up to `quantity` most recent anchored Stacks block headers.\nThe result is ordered from the current tip backwards.\n", + "parameters": [ + { + "name": "quantity", + "in": "path", + "required": true, + "description": "Number of headers to return (max 256)", + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 256 + } + }, + { + "$ref": "#/components/parameters/tip" + } + ], + "responses": { + "200": { + "description": "Array of block headers", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BlockHeaders" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v2/blocks/{block_id}": { + "get": { + "summary": "Get Stacks 2.x block by ID", + "tags": [ + "Blocks" + ], + "security": [], + "operationId": "getLegacyBlockById", + "description": "Get a specific Stacks 2.x era block by its block ID. This endpoint streams the block data\nfrom the filesystem storage where traditional Stacks blocks are stored as individual files.\n\n**Compatibility**: Works with all Stacks 2.x blocks. For Nakamoto blocks (Stacks 3.x+), use `/v3/blocks/{block_id}`.\n", + "parameters": [ + { + "name": "block_id", + "in": "path", + "required": true, + "description": "Hex-encoded block ID (64 characters)", + "schema": { + "type": "string", + "pattern": "^[0-9a-f]{64}$" + } + } + ], + "responses": { + "200": { + "description": "The block data", + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v2/neighbors": { + "get": { + "summary": "Get neighbor peers", + "tags": [ + "Info" + ], + "security": [], + "operationId": "getNetworkPeers", + "description": "Get information about the node\"s neighbor peers in the network.\n", + "responses": { + "200": { + "description": "List of neighbor peers", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NetworkPeers" + }, + "examples": { + "network-peers": { + "$ref": "#/components/examples/network-peers.example" + } + } + } + } + } + } + } + }, + "/v3/tenures/fork_info/{start}/{stop}": { + "get": { + "summary": "Get tenure fork information", + "tags": [ + "Blocks" + ], + "security": [], + "operationId": "getTenureForkInfo", + "description": "Get information about tenure forking between two consensus hashes.\nThis is used to identify conflicting tenures in the Nakamoto consensus.\n", + "parameters": [ + { + "name": "start", + "in": "path", + "required": true, + "description": "Starting consensus hash (40 hexadecimal characters, without 0x prefix)", + "schema": { + "type": "string", + "pattern": "^[0-9a-f]{40}$" + } + }, + { + "name": "stop", + "in": "path", + "required": true, + "description": "Stopping consensus hash (40 hexadecimal characters, without 0x prefix)", + "schema": { + "type": "string", + "pattern": "^[0-9a-f]{40}$" + } + } + ], + "responses": { + "200": { + "description": "Ordered list of tenure fork events from `stop` back to (and including) `start`", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TenureForkInfo" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v3/tenures/tip/{consensus_hash}": { + "get": { + "summary": "Get tenure tip", + "tags": [ + "Blocks" + ], + "security": [], + "operationId": "getTenureTip", + "description": "Get the tip block of a tenure identified by consensus hash.\n", + "parameters": [ + { + "name": "consensus_hash", + "in": "path", + "required": true, + "description": "Consensus hash (40 characters)", + "schema": { + "type": "string", + "pattern": "^[0-9a-f]{40}$" + } + } + ], + "responses": { + "200": { + "description": "Tenure tip block information", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TenureTip" + }, + "examples": { + "tenure-tip": { + "$ref": "#/components/examples/get-tenure-tip.example" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v3/tenures/tip_metadata/{consensus_hash}": { + "get": { + "summary": "Get tenure tip with metadata", + "tags": [ + "Blocks" + ], + "security": [], + "operationId": "getTenureTipMetadata", + "description": "Get the tip block and associated metadata of a tenure identified by consensus hash.\n", + "parameters": [ + { + "name": "consensus_hash", + "in": "path", + "required": true, + "description": "Consensus hash (40 characters)", + "schema": { + "type": "string", + "pattern": "^[0-9a-f]{40}$" + } + } + ], + "responses": { + "200": { + "description": "Tenure tip block information", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TenureTipMetadata" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v2/transactions/unconfirmed/{txid}": { + "get": { + "summary": "Get unconfirmed transaction", + "tags": [ + "Transactions" + ], + "security": [], + "operationId": "getUnconfirmedTransactionById", + "description": "Get an unconfirmed transaction by its transaction ID.\nThis looks in both the mempool and unconfirmed microblock stream.\n", + "parameters": [ + { + "name": "txid", + "in": "path", + "required": true, + "description": "Transaction ID (64 hexadecimal characters)", + "schema": { + "type": "string", + "pattern": "^[0-9a-f]{64}$" + } + } + ], + "responses": { + "200": { + "description": "Unconfirmed transaction details", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnconfirmedTransaction" + }, + "examples": { + "unconfirmed-transaction": { + "summary": "Unconfirmed transaction in mempool", + "value": { + "tx": "800000000004...", + "status": "Mempool" + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v2/blocks/upload/{consensus_hash}": { + "post": { + "summary": "Upload a Stacks block", + "tags": [ + "Mining" + ], + "security": [], + "operationId": "uploadLegacyBlock", + "description": "Upload a Stacks block to the node for processing.\nThe block must be in binary format and associated with the given consensus hash.\n", + "parameters": [ + { + "name": "consensus_hash", + "in": "path", + "required": true, + "description": "Consensus hash (40 hex characters)", + "schema": { + "type": "string", + "pattern": "^[0-9a-f]{40}$" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary", + "minLength": 1, + "description": "Binary-encoded Stacks block" + } + } + } + }, + "responses": { + "200": { + "description": "Block upload result", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BlockUploadResponse" + }, + "examples": { + "block-upload-success": { + "summary": "Block upload accepted", + "value": { + "stacks_block_id": "abc123...", + "accepted": true + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v2/mempool/query": { + "post": { + "summary": "Query mempool for missing transactions", + "tags": [ + "Transactions" + ], + "security": [], + "operationId": "queryMempool", + "description": "Query the mempool for transactions that might be missing from the requesting node.\nThis endpoint supports pagination and streaming of transaction data.\n", + "parameters": [ + { + "name": "page_id", + "in": "query", + "description": "Transaction ID to start pagination from", + "schema": { + "type": "string", + "pattern": "^[0-9a-f]{64}$" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary", + "minLength": 1, + "description": "Binary SIP-003 encoding of `MemPoolSyncData`\n(`BloomFilter` or `TxTags` variants).\n" + } + } + } + }, + "responses": { + "200": { + "description": "Stream of missing transactions", + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary", + "description": "Binary stream of transactions and pagination data.\nThe stream contains serialized transactions followed by a page ID for continuation.\n" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v3/blocks/upload": { + "post": { + "summary": "Upload a Nakamoto block", + "tags": [ + "Blocks" + ], + "security": [ + { + "rpcAuth": [] + }, + {} + ], + "operationId": "uploadNakamotoBlock", + "description": "Upload a Nakamoto block to the node for processing.\n\n- **Body** - must be the binary (SIP-003) serialization of a `NakamotoBlock`.\n- **Authentication** - only required when the query parameter `broadcast=1` is supplied.\n In that case the caller **must** include an `Authorization` header.\n", + "parameters": [ + { + "name": "broadcast", + "in": "query", + "description": "If set to `\"1\"` the node will broadcast the uploaded block to peers.\nWhen present the request must include a valid `Authorization` header.\n", + "schema": { + "type": "string", + "enum": [ + "1" + ] + }, + "required": false + } + ], + "requestBody": { + "required": true, + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary", + "minLength": 1, + "description": "Binary SIP-003 encoding of a `NakamotoBlock`" + } + } + } + }, + "responses": { + "200": { + "description": "Block upload result.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BlockUploadResponse" + }, + "examples": { + "nakamoto-block-upload-success": { + "summary": "Nakamoto block upload accepted", + "value": { + "stacks_block_id": "abc123...", + "accepted": true + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v3/blocks/replay/{block_id}": { + "get": { + "summary": "Replay mining of a block and returns its content", + "tags": [ + "Blocks" + ], + "security": [ + { + "rpcAuth": [] + } + ], + "operationId": "blockReplay", + "description": "Replay the mining of a block (no data is written in the MARF) and returns its content.\n", + "parameters": [ + { + "name": "block_id", + "in": "path", + "description": "The block ID hash", + "required": true, + "schema": { + "type": "string", + "pattern": "^[0-9a-f]{64}$" + } + } + ], + "responses": { + "200": { + "description": "Content of the replayed block", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BlockReplay" + }, + "examples": { + "block-replay": { + "$ref": "#/components/examples/block-replay.example" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v3/blocks/simulate/{block_id}": { + "get": { + "summary": "Simulate mining of a block with the specified transactions and returns its content", + "tags": [ + "Blocks" + ], + "security": [ + { + "rpcAuth": [] + } + ], + "operationId": "blockSimulate", + "description": "Simulate the mining of a block (no data is written in the MARF) with specified transactions and returns its content.\n", + "parameters": [ + { + "name": "block_id", + "in": "path", + "description": "The block ID hash", + "required": true, + "schema": { + "type": "string", + "pattern": "^[0-9a-f]{64}$" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "transactions_hex": { + "type": "array", + "items": { + "type": "string", + "description": "SIP-003-encoded Transaction in hex format" + } + }, + "mint": { + "type": "array", + "items": { + "type": "object", + "properties": { + "principal": { + "type": "string", + "description": "Principal address receiving STX" + }, + "amount": { + "type": "integer", + "description": "amount of microSTX to mint for the block simulation" + } + } + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Content of the simulated block", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BlockReplay" + }, + "example": { + "summary": "Block replay response", + "value": { + "block_hash": "732f57eefc4dbfb015c9988d9943c47273d25fbe039220d53f311b307609c83f", + "block_id": "856f6b08f338164df7422f66337c8ce916b6b0301fcaa09de06c61cfb79e2a45", + "block_height": 123, + "consensus_hash": "33dffda027e2ca3aaf278855c59a8a0b2d2dd51f", + "fees": 1, + "miner_signature": "004b2878d7639060c4d183b1338447c06ceb0ad55424856c550a4c988401fdf8cf1fe6e8c05cc0e3ff8d4383590bf700cb5dd1a8bb3269f7125f6e0704b66eade8", + "parent_block_id": "3ac36fc1acfc86ba80ea27cd26017c675f75bc07fb042814b72e74cd7d331503", + "signer_signature": [ + "00d4e08331db614d18d7b5af53cf9bc03add9c7a2dcb6f0448721de7ea98f662cf7dc43ee73e14d18dfae3d3d349ff67e0fd773a446fb8c949c93ae4676f4d34bc", + "01619c6e69bad5b43e11bae3eb4d4626e5cf19d595923b0b5d2053e8883a266b41315fdaefd1eca03c5c0580b0f7fd28053c3f34eb0a12220b61392d342f5afb0d", + "0078fa352e0e4d2d94b25d4070ae24a819f268b2260a1e4d0d867415dbdc39e2cf75e57de69375794073e22a75873a5e1ca33ed96eadd8086415e934f697b78fdb", + "00b8d9b0d0cdfabe3c65237801e714185777f60507c773fcd2a72ed00b9d4c59cb5ab96e0e8d545bd562b5ca3de6db1d3b9fccd8f41c3bfa7de3528deb1acd30d6" + ], + "state_index_root": "839b826290027e5b92de415495be7bab2eab2ad4e2f8c371a1a773ae552fedba", + "timestamp": 1758284349, + "transactions": [ + { + "data": { + "anchor_mode": "OnChainOnly", + "auth": { + "Standard": { + "Singlesig": { + "hash_mode": "P2PKH", + "key_encoding": "Compressed", + "nonce": 99, + "signature": "01e29229b386e1f69ffd91e339c878246235ec1cd4771b42a7f45e1ed108643bc9417d43dd96a02c93314ef4cf5bcbcc5642df2e1f5a177333ff983c8719d80661", + "signer": "2965a4e6e4226868fa3ae88b2b9bb9e937d77fba", + "tx_fee": 1 + } + } + }, + "chain_id": 2147483648, + "payload": { + "TokenTransfer": [ + { + "Standard": [ + 26, + [ + 189, + 65, + 200, + 147, + 188, + 192, + 157, + 152, + 224, + 211, + 77, + 255, + 135, + 190, + 175, + 153, + 88, + 51, + 140, + 222 + ] + ] + }, + 1, + "00000000000000000000000000000000000000000000000000000000000000000000" + ] + }, + "post_condition_mode": "Deny", + "post_conditions": [], + "version": "Testnet" + }, + "events": [ + { + "committed": true, + "event_index": 0, + "stx_transfer_event": { + "amount": "1", + "memo": "00000000000000000000000000000000000000000000000000000000000000000000", + "recipient": "ST2YM3J4KQK09V670TD6ZZ1XYNYCNGCWCVTASN5VM", + "sender": "STMPB976WGH6GT7T7BM8PAWVQ7MKFNVZQAXS4BFS" + }, + "txid": "0xf14dd7dec56405fd7dac69c3080fb569fae4c49c591f9ad0e5cf5c797add9005", + "type": "stx_transfer_event" + } + ], + "execution_cost": { + "read_count": 0, + "read_length": 0, + "runtime": 0, + "write_count": 0, + "write_length": 0 + }, + "hex": "808000000004002965a4e6e4226868fa3ae88b2b9bb9e937d77fba000000000000006300000000000000010001e29229b386e1f69ffd91e339c878246235ec1cd4771b42a7f45e1ed108643bc9417d43dd96a02c93314ef4cf5bcbcc5642df2e1f5a177333ff983c8719d8066101020000000000051abd41c893bcc09d98e0d34dff87beaf9958338cde000000000000000100000000000000000000000000000000000000000000000000000000000000000000", + "result_hex": "0x0703", + "post_condition_aborted": false, + "stx_burned": 0, + "tx_index": 0, + "txid": "f14dd7dec56405fd7dac69c3080fb569fae4c49c591f9ad0e5cf5c797add9005", + "vm_error": null, + "profiler": null, + "execution_stats": { + "secs": 0, + "nanos": 123456 + } + } + ], + "tx_merkle_root": "a68e3c76471d9e66b71a14165c4c9a2b980c51efb5b313425cffcef7172d6080", + "valid_merkle_root": true + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/v3/transactions/simulate": { + "post": { + "summary": "Simulate a single transaction on top of a chain tip", + "tags": [ + "Transactions" + ], + "security": [ + { + "rpcAuth": [] + } + ], + "operationId": "transactionSimulate", + "parameters": [ + { + "$ref": "#/components/parameters/tip" + } + ], + "description": "Simulate a single transaction in an ephemeral block built on top of\nthe given chain tip, or the canonical chain tip if the `tip` query\nparameter is omitted (no data is written in the MARF), and return its\nresult, events, and execution cost. The simulation runs with the full\ntenure execution budget, independent of the cost already consumed in\nthe current tenure. The transaction must be fully signed and valid\n(correct nonce, sufficient balance for the fee). The simulation\nenforces the same per-transaction wall-clock and memory limits the\nsigners apply during block proposal validation (the\n`connection_options.block_proposal_max_tx_execution_time_secs`,\n`block_proposal_max_tx_analysis_time_secs`, and\n`block_proposal_max_tx_mem_bytes` options), so a transaction which\nexceeds them fails to simulate.\n\nA `tip` naming a block that does not exist returns 404. A `tip` naming\na block that exists but cannot be simulated by this endpoint (for\nexample an epoch-2.x block) returns 400.\n", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "transaction_hex" + ], + "properties": { + "transaction_hex": { + "type": "string", + "minLength": 2, + "pattern": "^([0-9a-fA-F]{2})+$", + "description": "SIP-005-encoded transaction in hex format" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Result of the simulated transaction", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "txid": { + "type": "string", + "description": "The transaction ID" + }, + "tip_block_id": { + "type": "string", + "description": "The block ID of the chain tip the transaction was simulated on top of" + }, + "consensus_hash": { + "type": "string", + "description": "Consensus hash of the tenure the simulated block would extend" + }, + "block_height": { + "type": "integer", + "description": "Height of the ephemeral block the transaction was simulated in" + }, + "result_hex": { + "type": "string", + "pattern": "^0x([0-9a-fA-F]{2})+$", + "description": "Clarity value returned by the transaction, encoded as a 0x-prefixed hex string" + }, + "stx_burned": { + "type": "integer", + "description": "Amount of microSTX burned" + }, + "execution_cost": { + "$ref": "#/components/schemas/ExecutionCost", + "description": "Execution cost consumed by the transaction" + }, + "execution_limit": { + "$ref": "#/components/schemas/ExecutionCost", + "description": "The execution limit the simulation ran under (the full tenure budget)" + }, + "events": { + "type": "array", + "items": { + "type": "object" + }, + "description": "Events generated by the transaction" + }, + "post_condition_aborted": { + "type": "boolean", + "description": "Whether the transaction was aborted by a post-condition" + }, + "vm_error": { + "type": [ + "string", + "null" + ], + "description": "VM error, if any" + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + } + }, + "components": { + "securitySchemes": { + "rpcAuth": { + "type": "apiKey", + "in": "header", + "name": "authorization", + "description": "Plain-text secret value that must exactly equal the node's\nconfigured password, which is set as `connection_options.auth_token`\nin the node's configuration file.\n" + } + }, + "responses": { + "Unauthorized": { + "description": "Unauthorized. Invalid or missing authentication token.", + "content": { + "text/plain": { + "schema": { + "type": "string" + }, + "example": "Unauthorized" + } + } + }, + "BadRequest": { + "description": "Bad request", + "content": { + "text/plain": { + "schema": { + "type": "string" + }, + "example": "Bad request" + } + } + }, + "NotFound": { + "description": "Not found", + "content": { + "text/plain": { + "schema": { + "type": "string" + }, + "example": "Not found" + } + } + }, + "InternalServerError": { + "description": "Internal Server Error", + "content": { + "text/plain": { + "schema": { + "type": "string" + }, + "example": "Internal Server Error" + } + } + }, + "MethodNotAllowed": { + "description": "Method Not Allowed", + "content": { + "text/plain": { + "schema": { + "type": "string" + }, + "example": "Method Not Allowed. Allowed: GET" + } + } + }, + "Timeout": { + "description": "Timeout", + "content": { + "text/plain": { + "schema": { + "type": "string" + }, + "example": "Timeout" + } + } + } + }, + "schemas": { + "NodeInfo": { + "description": "GET request for core node information", + "type": "object", + "required": [ + "peer_version", + "pox_consensus", + "burn_block_height", + "stable_pox_consensus", + "stable_burn_block_height", + "server_version", + "network_id", + "parent_network_id", + "stacks_tip_height", + "stacks_tip", + "stacks_tip_consensus_hash", + "genesis_chainstate_hash", + "tenure_height", + "is_fully_synced", + "unanchored_tip", + "unanchored_seq", + "exit_at_block_height" + ], + "properties": { + "peer_version": { + "type": "integer", + "description": "Identifies the version number for the networking communication. This\nshould not change while a node is running, and will only change if there's an\nupgrade.\n" + }, + "pox_consensus": { + "type": "string", + "description": "A hash used to identify the burnchain view for a node. It incorporates\nbitcoin chain information and PoX information. Nodes that disagree on this value\nwill appear to each other as forks. This value changes after every block.\n" + }, + "burn_block_height": { + "type": "integer", + "description": "Latest bitcoin chain height." + }, + "stable_pox_consensus": { + "type": "string", + "description": "Same as pox_consensus, but evaluated at stable_burn_block_height." + }, + "stable_burn_block_height": { + "type": "integer", + "description": "The bitcoin block height at which the last PoX anchor block was seen.\nLeftover from stacks 1.0, basically always burn_block_height - 1.\n" + }, + "server_version": { + "type": "string", + "description": "A version descriptor for the node." + }, + "network_id": { + "type": "integer", + "description": "Identifies the network (e.g., mainnet, testnet)." + }, + "parent_network_id": { + "type": "integer", + "description": "same as network_id, but for bitcoin" + }, + "stacks_tip_height": { + "type": "integer", + "description": "The latest Stacks chain height." + }, + "stacks_tip": { + "type": "string", + "description": "The best known block hash for the Stacks chain." + }, + "stacks_tip_consensus_hash": { + "type": "string", + "description": "The bitcoin consensus hash at the time that stacks_tip was mined." + }, + "genesis_chainstate_hash": { + "type": "string", + "description": "The SHA256 hash of the genesis chainstate." + }, + "unanchored_tip": { + "type": [ + "string", + "null" + ], + "description": "The latest microblock hash if any microblocks were processed. If no\nmicroblock has been processed for the current block, a 000.., hex array is\nreturned.\n" + }, + "unanchored_seq": { + "type": [ + "integer", + "null" + ], + "description": "The sequence number of the latest microblock if any microblocks were processed." + }, + "tenure_height": { + "type": "integer", + "description": "The latest Stacks tenure height." + }, + "exit_at_block_height": { + "type": [ + "integer", + "null" + ], + "description": "The block height at which a testnet network will be reset.\nNot applicable to mainnet.\n" + }, + "is_fully_synced": { + "type": "boolean", + "description": "Indicates whether the node has fully synchronized with the network." + }, + "node_public_key": { + "type": [ + "string", + "null" + ], + "description": "The node's public key." + }, + "node_public_key_hash": { + "type": [ + "string", + "null" + ], + "description": "The HASH160 of the node's public key." + }, + "last_pox_anchor": { + "type": [ + "object", + "null" + ], + "properties": { + "anchor_block_hash": { + "type": "string" + }, + "anchor_block_txid": { + "type": "string" + } + } + }, + "stackerdbs": { + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + } + } + } + }, + "PoxInfo": { + "description": "Get Proof of Transfer (PoX) information", + "type": "object", + "additionalProperties": false, + "required": [ + "contract_id", + "current_burnchain_block_height", + "first_burnchain_block_height", + "pox_activation_threshold_ustx", + "prepare_phase_block_length", + "reward_phase_block_length", + "reward_slots", + "total_liquid_supply_ustx", + "current_cycle", + "next_cycle", + "reward_cycle_length", + "contract_versions", + "epochs", + "current_epoch", + "pox_5_sbtc_contract", + "pox_5_sbtc_registry_contract" + ], + "properties": { + "contract_id": { + "type": "string", + "description": "The contract identifier for the PoX contract" + }, + "first_burnchain_block_height": { + "type": "integer", + "minimum": 0, + "description": "The first burn block evaluated in this Stacks chain" + }, + "current_burnchain_block_height": { + "type": "integer", + "minimum": 0, + "description": "The latest Bitcoin chain block height" + }, + "current_epoch": { + "type": "string", + "pattern": "^Epoch[0-9]+(_[0-9]+)?$", + "description": "The ID of the Stacks Epoch that the node is currently in." + }, + "pox_activation_threshold_ustx": { + "type": "integer", + "description": "The threshold of stacking participation that must be reached for PoX to activate in any cycle" + }, + "rejection_fraction": { + "type": [ + "integer", + "null" + ], + "description": "The fraction of liquid STX that must vote to reject PoX in order to prevent the next reward cycle from activating." + }, + "reward_phase_block_length": { + "type": "integer", + "minimum": 0, + "description": "The length in burn blocks of the reward phase" + }, + "prepare_phase_block_length": { + "type": "integer", + "minimum": 0, + "description": "The length in burn blocks of the prepare phase" + }, + "reward_slots": { + "type": "integer", + "minimum": 0, + "description": "The number of reward slots in a reward cycle" + }, + "total_liquid_supply_ustx": { + "type": "integer", + "minimum": 0, + "description": "The current total amount of liquid microstacks." + }, + "reward_cycle_length": { + "type": "integer", + "minimum": 0, + "description": "The length in burn blocks of a whole PoX cycle (reward phase and prepare phase)" + }, + "current_cycle": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "min_threshold_ustx", + "stacked_ustx", + "is_pox_active" + ], + "properties": { + "id": { + "type": "integer", + "minimum": 0, + "description": "The reward cycle number" + }, + "min_threshold_ustx": { + "type": "integer", + "minimum": 0, + "description": "The threshold amount for obtaining a slot in this reward cycle." + }, + "stacked_ustx": { + "type": "integer", + "minimum": 0, + "description": "The total amount of stacked microstacks in this reward cycle." + }, + "is_pox_active": { + "type": "boolean", + "description": "Whether or not PoX is active during this reward cycle." + } + } + }, + "next_cycle": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "min_threshold_ustx", + "min_increment_ustx", + "stacked_ustx", + "prepare_phase_start_block_height", + "blocks_until_prepare_phase", + "reward_phase_start_block_height", + "blocks_until_reward_phase" + ], + "properties": { + "id": { + "type": "integer", + "minimum": 0, + "description": "The reward cycle number" + }, + "min_threshold_ustx": { + "type": "integer", + "minimum": 0, + "description": "The threshold amount for obtaining a slot in this reward cycle." + }, + "stacked_ustx": { + "type": "integer", + "minimum": 0, + "description": "The total amount of stacked microstacks in this reward cycle." + }, + "min_increment_ustx": { + "type": "integer", + "minimum": 0, + "description": "The minimum amount that can be used to submit a `stack-stx` call." + }, + "prepare_phase_start_block_height": { + "type": "integer", + "minimum": 0, + "description": "The burn block height when the prepare phase for this cycle begins. Any eligible stacks must be stacked before this block." + }, + "blocks_until_prepare_phase": { + "type": "integer", + "description": "The number of burn blocks until the prepare phase for this cycle starts. If the prepare phase for this cycle already started, this value will be a negative number." + }, + "reward_phase_start_block_height": { + "type": "integer", + "minimum": 0, + "description": "The burn block height when the reward phase for this cycle begins. Any eligible stacks must be stacked before this block." + }, + "blocks_until_reward_phase": { + "type": "integer", + "minimum": 0, + "description": "The number of burn blocks until this reward phase starts." + }, + "ustx_until_pox_rejection": { + "type": [ + "integer", + "null" + ], + "minimum": 0, + "description": "The remaining amount of liquid STX that must vote to reject the next reward cycle to prevent the next reward cycle from activating." + } + } + }, + "reward_cycle_id": { + "type": "integer", + "minimum": 0, + "deprecated": true, + "description": "The active reward cycle number" + }, + "min_amount_ustx": { + "type": "integer", + "minimum": 0, + "deprecated": true + }, + "prepare_cycle_length": { + "type": "integer", + "minimum": 0, + "deprecated": true + }, + "rejection_votes_left_required": { + "type": [ + "integer", + "null" + ], + "deprecated": true + }, + "next_reward_cycle_in": { + "type": "integer", + "minimum": 0, + "description": "The number of blocks until the next reward cycle.", + "deprecated": true + }, + "contract_versions": { + "type": "array", + "description": "Versions of each PoX", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "contract_id", + "activation_burnchain_block_height", + "first_reward_cycle_id" + ], + "properties": { + "contract_id": { + "type": "string", + "description": "The contract identifier for the PoX contract" + }, + "activation_burnchain_block_height": { + "type": "integer", + "minimum": 0, + "description": "The burn block height at which this version of PoX is activated" + }, + "first_reward_cycle_id": { + "type": "integer", + "minimum": 0, + "description": "The first reward cycle number that uses this version of PoX" + } + } + } + }, + "pox_5_sbtc_contract": { + "type": "string", + "description": "The sBTC token contract used for PoX payments in epoch 4+. On mainnet this is the canonical sBTC token; on non-mainnet it reflects this node's configuration." + }, + "pox_5_sbtc_registry_contract": { + "type": "string", + "description": "The sBTC registry contract from which the node derives the per-cycle sBTC waterfall recipient (epoch 4+) via a call to `get-current-aggregate-pubkey`. On mainnet this is the canonical sBTC registry; on non-mainnet it reflects this node's configuration." + }, + "epochs": { + "type": "array", + "description": "Epochs", + "items": { + "type": "object", + "required": [ + "epoch_id", + "start_height", + "end_height", + "block_limit", + "network_epoch" + ], + "properties": { + "epoch_id": { + "type": "string", + "pattern": "^Epoch[0-9]+(_[0-9]+)?$" + }, + "start_height": { + "type": "integer", + "minimum": 0 + }, + "end_height": { + "type": "integer", + "minimum": 0 + }, + "block_limit": { + "$ref": "#/components/schemas/ExecutionCost" + }, + "network_epoch": { + "type": "integer", + "minimum": 0 + } + } + } + } + } + }, + "Sortitions": { + "description": "Array of sortition information objects from the burnchain", + "type": "array", + "items": { + "$ref": "#/components/schemas/Sortition" + } + }, + "Sortition": { + "type": "object", + "description": "Information about a burnchain sortition event", + "properties": { + "burn_block_hash": { + "type": "string", + "description": "The burnchain header hash of the block that triggered this event", + "pattern": "^0x[0-9a-f]{64}$" + }, + "burn_block_height": { + "type": "integer", + "description": "The burn height of the block that triggered this event", + "minimum": 0 + }, + "burn_header_timestamp": { + "type": "integer", + "description": "The burn block time of the sortition (Unix timestamp)", + "minimum": 0 + }, + "sortition_id": { + "type": "string", + "description": "This sortition ID of the block that triggered this event. This incorporates PoX forking information and the burn block hash to obtain an identifier that is unique across PoX forks and burnchain forks.", + "pattern": "^0x[0-9a-f]{64}$" + }, + "parent_sortition_id": { + "type": "string", + "description": "The parent of this burn block's Sortition ID", + "pattern": "^0x[0-9a-f]{64}$" + }, + "consensus_hash": { + "type": "string", + "description": "The consensus hash of the block that triggered this event. This incorporates PoX forking information and burn op information to obtain an identifier that is unique across PoX forks and burnchain forks.", + "pattern": "^0x[0-9a-f]{40}$" + }, + "was_sortition": { + "type": "boolean", + "description": "Boolean indicating whether or not there was a successful sortition (i.e. a winning block or miner was chosen)." + }, + "miner_pk_hash160": { + "type": [ + "string", + "null" + ], + "description": "If sortition occurred, and the miner's VRF key registration associated a nakamoto mining pubkey with their commit, this will contain the Hash160 of that mining key.", + "pattern": "^0x[0-9a-f]{40}$" + }, + "stacks_parent_ch": { + "type": [ + "string", + "null" + ], + "description": "If sortition occurred, this will be the consensus hash of the burn block corresponding to the winning block commit's parent block ptr. In 3.x, this is the consensus hash of the tenure that this new burn block's miner will be building off of.", + "pattern": "^0x[0-9a-f]{40}$" + }, + "last_sortition_ch": { + "type": [ + "string", + "null" + ], + "description": "If sortition occurred, this will be the consensus hash of the most recent sortition before this one.", + "pattern": "^0x[0-9a-f]{40}$" + }, + "committed_block_hash": { + "type": [ + "string", + "null" + ], + "description": "In Stacks 2.x, this is the winning block. In Stacks 3.x, this is the first block of the parent tenure.", + "pattern": "^0x[0-9a-f]{64}$" + }, + "vrf_seed": { + "type": [ + "string", + "null" + ], + "description": "This is the VRF seed generated by this sortition", + "pattern": "^0x[0-9a-f]{64}$" + } + }, + "required": [ + "burn_block_hash", + "burn_block_height", + "burn_header_timestamp", + "sortition_id", + "parent_sortition_id", + "consensus_hash", + "was_sortition" + ] + }, + "GetHealth": { + "type": "object", + "required": [ + "difference_from_max_peer", + "max_stacks_height_of_neighbors", + "node_stacks_tip_height" + ], + "properties": { + "difference_from_max_peer": { + "type": "integer", + "minimum": 0, + "description": "The difference in Stacks height between this node and its most advanced peer" + }, + "max_stacks_height_of_neighbors": { + "type": "integer", + "minimum": 0, + "description": "The maximum Stacks height observed among the node's connected peers" + }, + "node_stacks_tip_height": { + "type": "integer", + "minimum": 0, + "description": "The current Stacks tip height of this node" + }, + "max_stacks_neighbor_address": { + "type": [ + "string", + "null" + ], + "description": "The address of the most advanced peer" + } + }, + "description": "Health information about the node's synchronization status" + }, + "AccountData": { + "description": "GET request for account data", + "type": "object", + "additionalProperties": false, + "required": [ + "balance", + "locked", + "unlock_height", + "nonce" + ], + "properties": { + "balance": { + "type": "string", + "description": "Spendable balance in micro-STX, as a hex-encoded unsigned 128-bit integer (big-endian). Does not include `locked`." + }, + "locked": { + "type": "string", + "description": "Micro-STX locked by staking, as a hex-encoded unsigned 128-bit integer (big-endian). `0x00000000000000000000000000000000` once the burn block height of the queried tip reaches `unlock_height`." + }, + "unlock_height": { + "type": "integer", + "minimum": 0, + "description": "Bitcoin block height at which the locked amount becomes spendable (64-bit unsigned integer). `0` when nothing is locked." + }, + "nonce": { + "type": "integer", + "minimum": 0, + "description": "Account transaction nonce (64-bit unsigned integer)" + }, + "balance_proof": { + "type": "string", + "description": "Merkle proof for the balance value" + }, + "nonce_proof": { + "type": "string", + "description": "Merkle proof for the nonce value" + } + } + }, + "TransactionSubmissionError": { + "description": "Describes a transaction submission error response", + "type": "object", + "required": [ + "error", + "reason", + "txid" + ], + "properties": { + "error": { + "type": "string", + "description": "The error" + }, + "reason": { + "type": "string", + "description": "The reason for the error" + }, + "reason_data": { + "type": "object", + "description": "More details about the reason", + "properties": { + "actual": { + "type": "integer" + }, + "expected": { + "type": "integer" + }, + "is_origin": { + "type": "boolean" + }, + "principal": { + "type": "string" + } + } + }, + "txid": { + "type": "string", + "description": "The relevant transaction id" + } + } + }, + "FeeTransactionRequest": { + "description": "POST request for estimated fee", + "type": "object", + "additionalProperties": false, + "required": [ + "transaction_payload" + ], + "properties": { + "transaction_payload": { + "type": "string" + }, + "estimated_len": { + "type": "integer" + } + } + }, + "FeeTransactionResponse": { + "description": "POST response for estimated fee", + "type": "object", + "additionalProperties": false, + "required": [ + "estimated_cost", + "estimated_cost_scalar", + "cost_scalar_change_by_byte", + "estimations" + ], + "properties": { + "estimated_cost": { + "$ref": "#/components/schemas/ExecutionCost" + }, + "estimated_cost_scalar": { + "type": "integer", + "minimum": 0 + }, + "cost_scalar_change_by_byte": { + "type": "number", + "minimum": 0 + }, + "estimations": { + "type": "array", + "items": { + "type": "object", + "properties": { + "fee_rate": { + "type": "number", + "minimum": 0 + }, + "fee": { + "type": "integer", + "minimum": 0 + } + } + } + } + } + }, + "FeeTransactionError": { + "type": "object", + "description": "Returned when the node cannot calculate a fee estimate.\n", + "required": [ + "error", + "reason" + ], + "properties": { + "error": { + "type": "string", + "description": "Human-readable summary of the failure.", + "example": "Estimation could not be performed" + }, + "reason": { + "type": "string", + "description": "Machine-readable error code.", + "enum": [ + "DatabaseError", + "NoEstimateAvailable" + ] + }, + "reason_data": { + "type": [ + "object", + "null" + ], + "description": "Optional structured details specific to `reason`.\nFor the current implementation it contains a `message` field,\nbut additional fields may be added in future.\n", + "properties": { + "message": { + "type": "string", + "example": "SQLite error: table fees does not exist" + } + }, + "additionalProperties": true + } + } + }, + "ContractInterface": { + "description": "The interface of a Clarity smart contract.", + "type": "object", + "required": [ + "functions", + "variables", + "maps", + "fungible_tokens", + "non_fungible_tokens", + "epoch", + "clarity_version" + ], + "properties": { + "functions": { + "type": "array", + "description": "List of defined functions", + "items": { + "type": "object", + "required": [ + "name", + "access", + "args", + "outputs" + ], + "properties": { + "name": { + "type": "string" + }, + "access": { + "type": "string", + "description": "Whether the function was defined with `define-private`, `define-public` or `define-read-only`", + "enum": [ + "public", + "private", + "read_only" + ] + }, + "args": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "type" + ], + "properties": { + "name": { + "type": "string" + }, + "type": { + "$ref": "#/components/schemas/ClarityType" + } + } + } + }, + "outputs": { + "type": "object", + "required": [ + "type" + ], + "properties": { + "type": { + "$ref": "#/components/schemas/ClarityType" + } + } + } + } + } + }, + "variables": { + "type": "array", + "description": "List of defined constants and data variables", + "items": { + "type": "object", + "required": [ + "name", + "type", + "access" + ], + "properties": { + "name": { + "type": "string" + }, + "type": { + "$ref": "#/components/schemas/ClarityType" + }, + "access": { + "type": "string", + "description": "Whether the value was defined with `define-constant` or `define-data-var`", + "enum": [ + "constant", + "variable" + ] + } + } + } + }, + "maps": { + "type": "array", + "description": "List of defined data-maps", + "items": { + "type": "object", + "required": [ + "name", + "key", + "value" + ], + "properties": { + "name": { + "type": "string" + }, + "key": { + "$ref": "#/components/schemas/ClarityType" + }, + "value": { + "$ref": "#/components/schemas/ClarityType" + } + } + } + }, + "fungible_tokens": { + "type": "array", + "description": "List of fungible tokens in the contract", + "items": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string" + } + } + } + }, + "non_fungible_tokens": { + "type": "array", + "description": "List of non-fungible tokens in the contract", + "items": { + "type": "object", + "required": [ + "name", + "type" + ], + "properties": { + "name": { + "type": "string" + }, + "type": { + "$ref": "#/components/schemas/ClarityType" + } + } + } + }, + "epoch": { + "type": "string", + "description": "Stacks epoch in which the contract was deployed (e.g., \"Epoch30\")." + }, + "clarity_version": { + "type": "string", + "description": "Clarity language version used by this contract.", + "enum": [ + "Clarity1", + "Clarity2", + "Clarity3", + "Clarity4", + "Clarity5", + "Clarity6", + "Clarity7" + ] + } + } + }, + "ContractSource": { + "description": "GET request to get contract source", + "type": "object", + "additionalProperties": false, + "required": [ + "source", + "publish_height" + ], + "properties": { + "source": { + "type": "string" + }, + "publish_height": { + "type": "integer", + "minimum": 0, + "description": "Block height at which the contract was published (32-bit unsigned integer)" + }, + "proof": { + "type": "string", + "description": "Hex-encoded 0x prefixed string of the Merkle proof for the contract source", + "pattern": "^0x[0-9a-f]+$" + } + } + }, + "ReadOnlyFunctionArgs": { + "description": "Arguments for a simulated read-only Clarity function call, including the sender/sponsor principals and hex-encoded Clarity values.", + "type": "object", + "additionalProperties": false, + "required": [ + "sender", + "arguments" + ], + "properties": { + "sender": { + "description": "The simulated tx-sender (standard address or contract principal).", + "allOf": [ + { + "$ref": "#/components/schemas/Principal" + } + ] + }, + "sponsor": { + "description": "The simulated sponsor address.", + "allOf": [ + { + "$ref": "#/components/schemas/Principal" + } + ] + }, + "arguments": { + "type": "array", + "description": "An array of hex serialized Clarity values", + "items": { + "type": "string", + "pattern": "^(0x)?([0-9a-fA-F]{2})+$", + "description": "Hex-encoded Clarity value (optionally prefixed with 0x)" + } + } + } + }, + "ReadOnlyFunctionResult": { + "description": "The result of a read-only function call.", + "oneOf": [ + { + "type": "object", + "description": "Successful read-only function call result", + "required": [ + "okay", + "result" + ], + "properties": { + "okay": { + "type": "boolean", + "enum": [ + true + ] + }, + "result": { + "type": "string", + "description": "Hex-encoded Clarity value of the successful result." + } + } + }, + { + "type": "object", + "description": "Failed read-only function call result", + "required": [ + "okay", + "cause" + ], + "properties": { + "okay": { + "type": "boolean", + "enum": [ + false + ] + }, + "cause": { + "type": "string", + "description": "A string representing the cause of the error." + } + } + } + ] + }, + "ClarityName": { + "type": "string", + "description": "A valid Clarity name. Must either:\n- Start with a letter and contain only letters, numbers, and [-_!?+<>=/*]\n- Be exactly one of the special characters: - + = * /\n- Be a comparison operator: < > <= >=\n", + "pattern": "^[a-zA-Z]([a-zA-Z0-9]|[-_!?+<>=/*])*$|^[-+=/*]$|^[<>]=?$", + "minLength": 1, + "maxLength": 128 + }, + "ClarityMetadata": { + "description": "Response of get clarity metadata request", + "type": "object", + "required": [ + "data" + ], + "properties": { + "data": { + "type": "string", + "description": "Metadata value" + } + } + }, + "ConstantValue": { + "description": "Response of get constant val request", + "type": "object", + "required": [ + "data" + ], + "properties": { + "data": { + "type": "string", + "description": "Hex-encoded 0x prefixed string of clarity value.", + "pattern": "^0x[0-9a-f]+$" + } + } + }, + "IsTraitImplemented": { + "description": "GET request to get trait implementation information", + "type": "object", + "additionalProperties": false, + "required": [ + "is_implemented" + ], + "properties": { + "is_implemented": { + "type": "boolean" + } + } + }, + "BlockReplay": { + "type": "object", + "properties": { + "block_hash": { + "type": "string", + "description": "Hash of the block", + "pattern": "^[0-9a-f]{64}$" + }, + "block_id": { + "type": "string", + "description": "Block ID (index block hash)", + "pattern": "^[0-9a-f]{64}$" + }, + "block_height": { + "type": "integer", + "description": "Height of the Stacks block", + "format": "uint64" + }, + "consensus_hash": { + "type": "string", + "description": "Consensus hash of the tenure", + "pattern": "^[0-9a-f]{40}$" + }, + "fees": { + "type": "integer", + "description": "total fees for the block" + }, + "miner_signature": { + "type": "string", + "description": "Uncompressed signature of the miner", + "pattern": "^[0-9a-f]{130}$" + }, + "parent_block_id": { + "type": "string", + "description": "Parent Block ID (index block hash)", + "pattern": "^[0-9a-f]{64}$" + }, + "signer_signature": { + "type": "array", + "items": { + "type": "string", + "description": "Uncompressed signature of the signer", + "pattern": "^[0-9a-f]{130}$" + } + }, + "state_index_root": { + "type": "string", + "pattern": "^[0-9a-f]{64}$", + "description": "block state index root computed from the MARF (got from the original block)" + }, + "timestamp": { + "type": "integer" + }, + "tx_merkle_root": { + "type": "string", + "description": "merkle_root of the included transactions" + }, + "valid_merkle_root": { + "type": "boolean", + "description": "does the merkle_root matches the chain block and the simulated one?" + }, + "transactions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/BlockReplayTransaction" + } + } + }, + "required": [ + "block_hash", + "block_id", + "block_height", + "consensus_hash", + "fees", + "miner_signature", + "parent_block_id", + "signer_signature", + "state_index_root", + "timestamp", + "tx_merkle_root", + "valid_merkle_root", + "transactions" + ] + }, + "BlockReplayTransaction": { + "type": "object", + "properties": { + "data": { + "type": [ + "object", + "null" + ], + "description": "JSON representation of the transaction payload" + }, + "events": { + "type": "array", + "items": { + "description": "JSON representation of the transaction events", + "$ref": "#/components/schemas/BlockReplayTransactionEvent" + } + }, + "execution_cost": { + "$ref": "#/components/schemas/ExecutionCost" + }, + "hex": { + "type": "string", + "description": "hexadecimal representation of the transaction body" + }, + "result_hex": { + "type": "string", + "description": "The transaction's result, encoded as a Clarity hex string" + }, + "post_condition_aborted": { + "type": "boolean", + "description": "Whether the transaction was aborted by a post-condition" + }, + "stx_burned": { + "type": "integer", + "description": "number of burned stx" + }, + "tx_index": { + "type": "integer", + "description": "index of the transaction in the array of transactions" + }, + "txid": { + "type": "string", + "description": "transaction id" + }, + "vm_error": { + "type": [ + "string", + "null" + ], + "description": "optional vm error (for runtime failures)" + }, + "profiler": { + "type": [ + "object", + "null" + ], + "description": "hardware profiler metrics for the transaction execution context", + "properties": { + "cpu_instructions": { + "type": [ + "integer", + "null" + ], + "description": "number of instructions executed" + }, + "cpu_cycles": { + "type": [ + "integer", + "null" + ], + "description": "number of cycles executed" + }, + "cpu_ref_cycles": { + "type": [ + "integer", + "null" + ], + "description": "number of reference cycles executed" + } + }, + "required": [ + "cpu_instructions", + "cpu_cycles", + "cpu_ref_cycles" + ] + }, + "execution_stats": { + "type": "object", + "description": "metrics for the transaction execution context", + "properties": { + "secs": { + "type": "number", + "description": "execution time in seconds" + }, + "nanos": { + "type": "integer", + "description": "execution time in nanoseconds" + } + }, + "required": [ + "secs", + "nanos" + ] + } + }, + "required": [ + "data", + "events", + "execution_cost", + "hex", + "result_hex", + "post_condition_aborted", + "stx_burned", + "tx_index", + "txid", + "vm_error", + "profiler", + "execution_stats" + ] + }, + "BlockReplayTransactionEvent": { + "type": "object", + "oneOf": [ + { + "$ref": "#/components/schemas/BlockReplayTransactionStxTransferEvent" + }, + { + "$ref": "#/components/schemas/BlockReplayTransactionStxBurnEvent" + }, + { + "$ref": "#/components/schemas/BlockReplayTransactionStxLockEvent" + }, + { + "$ref": "#/components/schemas/BlockReplayTransactionStxMintEvent" + }, + { + "$ref": "#/components/schemas/BlockReplayTransactionFtMintEvent" + }, + { + "$ref": "#/components/schemas/BlockReplayTransactionFtTransferEvent" + }, + { + "$ref": "#/components/schemas/BlockReplayTransactionFtBurnEvent" + }, + { + "$ref": "#/components/schemas/BlockReplayTransactionNftMintEvent" + }, + { + "$ref": "#/components/schemas/BlockReplayTransactionNftTransferEvent" + }, + { + "$ref": "#/components/schemas/BlockReplayTransactionNftBurnEvent" + }, + { + "$ref": "#/components/schemas/BlockReplayTransactionContractEvent" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "stx_transfer_event": "#/components/schemas/BlockReplayTransactionStxTransferEvent", + "stx_burn_event": "#/components/schemas/BlockReplayTransactionStxBurnEvent", + "stx_lock_event": "#/components/schemas/BlockReplayTransactionStxLockEvent", + "stx_mint_event": "#/components/schemas/BlockReplayTransactionStxMintEvent", + "ft_mint_event": "#/components/schemas/BlockReplayTransactionFtMintEvent", + "ft_transfer_event": "#/components/schemas/BlockReplayTransactionFtTransferEvent", + "ft_burn_event": "#/components/schemas/BlockReplayTransactionFtBurnEvent", + "nft_mint_event": "#/components/schemas/BlockReplayTransactionNftMintEvent", + "nft_transfer_event": "#/components/schemas/BlockReplayTransactionNftTransferEvent", + "nft_burn_event": "#/components/schemas/BlockReplayTransactionNftBurnEvent", + "contract_event": "#/components/schemas/BlockReplayTransactionContractEvent" + } + } + }, + "BlockReplayTransactionStxTransferEvent": { + "type": "object", + "required": [ + "committed", + "event_index", + "stx_transfer_event", + "txid", + "type" + ], + "properties": { + "committed": { + "type": "boolean" + }, + "event_index": { + "type": "integer" + }, + "stx_transfer_event": { + "type": "object", + "required": [ + "amount", + "memo", + "recipient", + "sender" + ], + "properties": { + "amount": { + "type": "string" + }, + "memo": { + "type": "string" + }, + "recipient": { + "type": "string" + }, + "sender": { + "type": "string" + } + } + }, + "txid": { + "type": "string" + }, + "type": { + "type": "string", + "enum": [ + "stx_transfer_event" + ] + } + } + }, + "BlockReplayTransactionStxBurnEvent": { + "type": "object", + "required": [ + "committed", + "event_index", + "stx_burn_event", + "txid", + "type" + ], + "properties": { + "committed": { + "type": "boolean" + }, + "event_index": { + "type": "integer" + }, + "stx_burn_event": { + "type": "object", + "required": [ + "amount", + "sender" + ], + "properties": { + "amount": { + "type": "string" + }, + "sender": { + "type": "string" + } + } + }, + "txid": { + "type": "string" + }, + "type": { + "type": "string", + "enum": [ + "stx_burn_event" + ] + } + } + }, + "BlockReplayTransactionStxLockEvent": { + "type": "object", + "required": [ + "committed", + "event_index", + "stx_lock_event", + "txid", + "type" + ], + "properties": { + "committed": { + "type": "boolean" + }, + "event_index": { + "type": "integer" + }, + "stx_lock_event": { + "type": "object", + "required": [ + "contract_identifier", + "locked_address", + "locked_amount", + "unlock_height" + ], + "properties": { + "contract_identifier": { + "type": "string" + }, + "locked_address": { + "type": "string" + }, + "locked_amount": { + "type": "string" + }, + "unlock_height": { + "type": "string" + } + } + }, + "txid": { + "type": "string" + }, + "type": { + "type": "string", + "enum": [ + "stx_lock_event" + ] + } + } + }, + "BlockReplayTransactionStxMintEvent": { + "type": "object", + "required": [ + "committed", + "event_index", + "stx_mint_event", + "txid", + "type" + ], + "properties": { + "committed": { + "type": "boolean" + }, + "event_index": { + "type": "integer" + }, + "stx_mint_event": { + "type": "object", + "required": [ + "amount", + "recipient" + ], + "properties": { + "amount": { + "type": "string" + }, + "recipient": { + "type": "string" + } + } + }, + "txid": { + "type": "string" + }, + "type": { + "type": "string", + "enum": [ + "stx_mint_event" + ] + } + } + }, + "BlockReplayTransactionFtMintEvent": { + "type": "object", + "required": [ + "committed", + "event_index", + "ft_mint_event", + "txid", + "type" + ], + "properties": { + "committed": { + "type": "boolean" + }, + "event_index": { + "type": "integer" + }, + "ft_mint_event": { + "type": "object", + "required": [ + "amount", + "asset_identifier", + "recipient" + ], + "properties": { + "amount": { + "type": "string" + }, + "asset_identifier": { + "type": "string" + }, + "recipient": { + "type": "string" + } + } + }, + "txid": { + "type": "string" + }, + "type": { + "type": "string", + "enum": [ + "ft_mint_event" + ] + } + } + }, + "BlockReplayTransactionFtTransferEvent": { + "type": "object", + "required": [ + "committed", + "event_index", + "ft_transfer_event", + "txid", + "type" + ], + "properties": { + "committed": { + "type": "boolean" + }, + "event_index": { + "type": "integer" + }, + "ft_transfer_event": { + "type": "object", + "required": [ + "amount", + "asset_identifier", + "recipient", + "sender" + ], + "properties": { + "amount": { + "type": "string" + }, + "asset_identifier": { + "type": "string" + }, + "recipient": { + "type": "string" + }, + "sender": { + "type": "string" + } + } + }, + "txid": { + "type": "string" + }, + "type": { + "type": "string", + "enum": [ + "ft_transfer_event" + ] + } + } + }, + "BlockReplayTransactionFtBurnEvent": { + "type": "object", + "required": [ + "committed", + "event_index", + "ft_burn_event", + "txid", + "type" + ], + "properties": { + "committed": { + "type": "boolean" + }, + "event_index": { + "type": "integer" + }, + "ft_burn_event": { + "type": "object", + "required": [ + "amount", + "asset_identifier", + "sender" + ], + "properties": { + "amount": { + "type": "string" + }, + "asset_identifier": { + "type": "string" + }, + "sender": { + "type": "string" + } + } + }, + "txid": { + "type": "string" + }, + "type": { + "type": "string", + "enum": [ + "ft_burn_event" + ] + } + } + }, + "BlockReplayTransactionNftMintEvent": { + "type": "object", + "required": [ + "committed", + "event_index", + "nft_mint_event", + "txid", + "type" + ], + "properties": { + "committed": { + "type": "boolean" + }, + "event_index": { + "type": "integer" + }, + "nft_mint_event": { + "type": "object", + "required": [ + "asset_identifier", + "raw_value", + "recipient" + ], + "properties": { + "asset_identifier": { + "type": "string" + }, + "raw_value": { + "type": "string" + }, + "recipient": { + "type": "string" + } + } + }, + "txid": { + "type": "string" + }, + "type": { + "type": "string", + "enum": [ + "nft_mint_event" + ] + } + } + }, + "BlockReplayTransactionNftTransferEvent": { + "type": "object", + "required": [ + "committed", + "event_index", + "nft_transfer_event", + "txid", + "type" + ], + "properties": { + "committed": { + "type": "boolean" + }, + "event_index": { + "type": "integer" + }, + "nft_transfer_event": { + "type": "object", + "required": [ + "asset_identifier", + "raw_value", + "recipient", + "sender" + ], + "properties": { + "asset_identifier": { + "type": "string" + }, + "raw_value": { + "type": "string" + }, + "recipient": { + "type": "string" + }, + "sender": { + "type": "string" + } + } + }, + "txid": { + "type": "string" + }, + "type": { + "type": "string", + "enum": [ + "nft_transfer_event" + ] + } + } + }, + "BlockReplayTransactionNftBurnEvent": { + "type": "object", + "required": [ + "committed", + "event_index", + "nft_burn_event", + "txid", + "type" + ], + "properties": { + "committed": { + "type": "boolean" + }, + "event_index": { + "type": "integer" + }, + "nft_burn_event": { + "type": "object", + "required": [ + "asset_identifier", + "raw_value", + "sender" + ], + "properties": { + "asset_identifier": { + "type": "string" + }, + "raw_value": { + "type": "string" + }, + "sender": { + "type": "string" + } + } + }, + "txid": { + "type": "string" + }, + "type": { + "type": "string", + "enum": [ + "nft_burn_event" + ] + } + } + }, + "BlockReplayTransactionContractEvent": { + "type": "object", + "required": [ + "committed", + "contract_event", + "event_index", + "txid", + "type" + ], + "properties": { + "committed": { + "type": "boolean" + }, + "contract_event": { + "type": "object", + "required": [ + "contract_identifier", + "raw_value", + "topic" + ], + "properties": { + "contract_identifier": { + "type": "string" + }, + "raw_value": { + "type": "string" + }, + "topic": { + "type": "string" + } + } + }, + "event_index": { + "type": "integer" + }, + "txid": { + "type": "string" + }, + "type": { + "type": "string", + "enum": [ + "contract_event" + ] + } + } + }, + "ClarityType": { + "description": "Represents a Clarity type. It can be a simple string for primitive types or a nested object for complex types like lists and tuples.", + "oneOf": [ + { + "type": "string", + "description": "Simple primitive type", + "enum": [ + "none", + "int128", + "uint128", + "bool", + "principal", + "trait_reference" + ] + }, + { + "type": "object", + "description": "List type", + "required": [ + "list" + ], + "properties": { + "list": { + "type": "object", + "required": [ + "type", + "length" + ], + "properties": { + "type": { + "$ref": "#/components/schemas/ClarityType", + "description": "Type of list elements" + }, + "length": { + "type": "integer", + "description": "Maximum number of elements" + } + } + } + } + }, + { + "type": "object", + "description": "Tuple type", + "required": [ + "tuple" + ], + "properties": { + "tuple": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "type" + ], + "properties": { + "name": { + "type": "string", + "description": "Field name in the tuple" + }, + "type": { + "$ref": "#/components/schemas/ClarityType", + "description": "Type of the tuple field" + } + } + } + } + } + }, + { + "type": "object", + "description": "Response type", + "required": [ + "response" + ], + "properties": { + "response": { + "type": "object", + "required": [ + "ok", + "error" + ], + "properties": { + "ok": { + "$ref": "#/components/schemas/ClarityType", + "description": "Success type" + }, + "error": { + "$ref": "#/components/schemas/ClarityType", + "description": "Error type" + } + } + } + } + }, + { + "type": "object", + "description": "Optional type", + "required": [ + "optional" + ], + "properties": { + "optional": { + "$ref": "#/components/schemas/ClarityType", + "description": "Wrapped optional type" + } + } + }, + { + "type": "object", + "description": "Buffer type", + "required": [ + "buffer" + ], + "properties": { + "buffer": { + "type": "object", + "required": [ + "length" + ], + "properties": { + "length": { + "type": "integer", + "description": "Fixed length for buffer types" + } + } + } + } + }, + { + "type": "object", + "description": "ASCII string type with fixed maximum length", + "required": [ + "string-ascii" + ], + "properties": { + "string-ascii": { + "type": "object", + "required": [ + "length" + ], + "properties": { + "length": { + "type": "integer", + "description": "Maximum number of characters (ASCII)" + } + } + } + } + }, + { + "type": "object", + "description": "UTF-8 string type with fixed maximum length", + "required": [ + "string-utf8" + ], + "properties": { + "string-utf8": { + "type": "object", + "required": [ + "length" + ], + "properties": { + "length": { + "type": "integer", + "description": "Maximum number of code-points (UTF-8)" + } + } + } + } + } + ] + }, + "SignerBlocksSigned": { + "type": "object", + "properties": { + "blocks_signed": { + "type": "integer", + "description": "Number of blocks signed by this signer" + } + }, + "required": [ + "blocks_signed" + ] + }, + "UnconfirmedTransaction": { + "type": "object", + "properties": { + "tx": { + "type": "string", + "description": "Hex-encoded transaction data" + }, + "status": { + "oneOf": [ + { + "type": "object", + "properties": { + "Microblock": { + "type": "object", + "properties": { + "block_hash": { + "type": "string", + "description": "Block hash containing the microblock" + }, + "seq": { + "type": "integer", + "description": "Microblock sequence number" + } + } + } + } + }, + { + "type": "string", + "enum": [ + "Mempool" + ] + } + ] + } + } + }, + "BlockUploadResponse": { + "type": "object", + "properties": { + "stacks_block_id": { + "type": "string", + "description": "The ID of the uploaded block" + }, + "accepted": { + "type": "boolean", + "description": "Whether the block was accepted" + } + } + }, + "AttachmentInventory": { + "type": "object", + "properties": { + "block_id": { + "type": "string", + "description": "Index block hash" + }, + "pages": { + "type": "array", + "items": { + "type": "object", + "properties": { + "index": { + "type": "integer", + "description": "Page index" + }, + "inventory": { + "type": "array", + "description": "8-byte bitfield for the page (array of integers 0-255)", + "items": { + "type": "integer", + "minimum": 0, + "maximum": 255 + } + } + } + } + } + } + }, + "AttachmentData": { + "type": "object", + "properties": { + "attachment": { + "type": "string", + "format": "byte", + "description": "The attachment data, hex-encoded." + } + }, + "required": [ + "attachment" + ] + }, + "StackerDbMetadata": { + "type": "array", + "items": { + "type": "object", + "properties": { + "slot_id": { + "type": "integer", + "description": "Slot identifier (unique for each DB instance)" + }, + "slot_version": { + "type": "integer", + "description": "Slot version (a lamport clock)" + }, + "data_hash": { + "type": "string", + "description": "Data hash (hex, no 0x prefix)" + }, + "signature": { + "type": "string", + "description": "signature over the above (hex, no 0x prefix)" + } + } + } + }, + "StackerDbReplicas": { + "type": "array", + "items": { + "type": "object", + "properties": { + "ip": { + "type": "string" + }, + "port": { + "type": "integer" + }, + "public_key_hash": { + "type": "string", + "description": "20-byte public key hash" + } + } + } + }, + "StackerDbChunkData": { + "type": "object", + "required": [ + "slot_id", + "slot_version", + "sig", + "data" + ], + "properties": { + "slot_id": { + "type": "integer", + "minimum": 0, + "maximum": 4294967295, + "description": "Slot identifier (u32 range)" + }, + "slot_version": { + "type": "integer", + "minimum": 0, + "maximum": 4294967295, + "description": "Slot version (lamport clock, u32 range)" + }, + "sig": { + "type": "string", + "description": "Hex-encoded signature from the stacker", + "pattern": "^[0-9a-f]{130}$" + }, + "data": { + "type": "string", + "description": "Hex-encoded chunk data (must be even length)", + "pattern": "^([0-9a-f]{2})*$" + } + } + }, + "StackerDbChunkAckData": { + "type": "object", + "required": [ + "accepted" + ], + "properties": { + "accepted": { + "type": "boolean", + "description": "Whether the chunk was accepted" + }, + "reason": { + "type": [ + "string", + "null" + ], + "description": "JSON-encoded reason for rejection (only present when accepted is false)" + }, + "metadata": { + "type": [ + "object", + "null" + ], + "description": "Slot metadata (present on successful acceptance)", + "properties": { + "slot_id": { + "type": "integer", + "minimum": 0, + "description": "Slot identifier" + }, + "slot_version": { + "type": "integer", + "minimum": 0, + "description": "Slot version" + }, + "data_hash": { + "type": "string", + "description": "Hex-encoded SHA512/256 hash of the data", + "pattern": "^[0-9a-f]{64}$" + }, + "signature": { + "type": "string", + "description": "Hex-encoded signature", + "pattern": "^[0-9a-f]{130}$" + } + } + }, + "code": { + "type": [ + "integer", + "null" + ], + "description": "Error code (only present when accepted is false)" + } + } + }, + "ClarityData": { + "description": "Response to a GET request for Clarity Data/MARF/MapEntry value", + "type": "object", + "required": [ + "data" + ], + "properties": { + "data": { + "type": "string", + "description": "Hex-encoded 0x prefixed string of the MARF value", + "pattern": "^0x[0-9a-f]+$" + }, + "proof": { + "type": "string", + "description": "Hex-encoded 0x prefixed string of the Merkle proof for the data. Empty string if proof not requested.", + "pattern": "^(0x[0-9a-f]+)?$" + } + } + }, + "BlockHeaders": { + "type": "array", + "description": "JSON array returned by /v2/headers/{quantity}. Each entry is an ExtendedStacksHeader.", + "items": { + "type": "object", + "required": [ + "consensus_hash", + "header", + "parent_block_id" + ], + "properties": { + "consensus_hash": { + "type": "string", + "description": "20-byte burn-chain consensus hash (hex, no 0x prefix)", + "pattern": "^[0-9a-f]{40}$" + }, + "header": { + "type": "string", + "description": "Hex-encoded SIP-003 serialization of the Stacks block header", + "pattern": "^[0-9a-f]+$" + }, + "parent_block_id": { + "type": "string", + "description": "32-byte index-block ID of the parent Stacks block (hex)", + "pattern": "^[0-9a-f]{64}$" + } + }, + "additionalProperties": false + } + }, + "BlockProposalResponse": { + "description": "Get Response for Block Proposal", + "type": "object", + "additionalProperties": false, + "required": [ + "result", + "message" + ], + "properties": { + "result": { + "type": "string", + "enum": [ + "Error", + "Accepted" + ] + }, + "message": { + "type": "string", + "description": "A message describing the result or error message." + } + } + }, + "NetworkPeers": { + "description": "Information about the node's neighbor peers in the network.", + "type": "object", + "required": [ + "bootstrap", + "sample", + "inbound", + "outbound" + ], + "properties": { + "bootstrap": { + "type": "array", + "description": "List of bootstrap peers known to the node.", + "items": { + "$ref": "#/components/schemas/RPCNeighbor" + } + }, + "sample": { + "type": "array", + "description": "List of a sample of gossiped peers.", + "items": { + "$ref": "#/components/schemas/RPCNeighbor" + } + }, + "inbound": { + "type": "array", + "description": "List of inbound peer connections.", + "items": { + "$ref": "#/components/schemas/RPCNeighbor" + } + }, + "outbound": { + "type": "array", + "description": "List of outbound peer connections.", + "items": { + "$ref": "#/components/schemas/RPCNeighbor" + } + } + } + }, + "RPCNeighbor": { + "type": "object", + "description": "A peer in the network", + "required": [ + "network_id", + "peer_version", + "ip", + "port", + "public_key_hash", + "authenticated" + ], + "properties": { + "network_id": { + "type": "integer", + "description": "The network ID of the peer." + }, + "peer_version": { + "type": "integer", + "description": "The peer version." + }, + "ip": { + "type": "string", + "description": "The IP address of the peer.", + "format": "ip" + }, + "port": { + "type": "integer", + "description": "The port number of the peer." + }, + "public_key_hash": { + "type": "string", + "description": "The HASH160 of the peer's public key.", + "pattern": "^[0-9a-f]{40}$" + }, + "authenticated": { + "type": "boolean", + "description": "Whether the peer connection is authenticated." + }, + "stackerdbs": { + "type": [ + "array", + "null" + ], + "description": "List of StackerDBs the peer supports, represented as qualified contract identifiers.", + "items": { + "type": "string", + "example": "SP000000000000000000002Q6VF78.my-stacker-db" + } + }, + "age": { + "type": [ + "integer", + "null" + ], + "format": "int64", + "description": "The age of the peer connection in seconds." + } + } + }, + "TransactionInfo": { + "type": "object", + "required": [ + "index_block_hash", + "tx", + "result" + ], + "properties": { + "index_block_hash": { + "type": "string", + "description": "Block hash where the transaction was included", + "pattern": "^[0-9a-f]{64}$" + }, + "tx": { + "type": "string", + "description": "Hex-encoded transaction" + }, + "result": { + "type": "string", + "description": "Transaction execution result (Clarity value)" + }, + "block_height": { + "type": [ + "integer", + "null" + ], + "description": "Height of the block where the transaction was included" + }, + "is_canonical": { + "type": "boolean", + "description": "Whether the block where this transaction was included is in the canonical chain tip" + } + } + }, + "TenureForkInfo": { + "type": "object", + "description": "Information about a tenure used for fork-detection.", + "required": [ + "burn_block_hash", + "burn_block_height", + "sortition_id", + "parent_sortition_id", + "consensus_hash", + "was_sortition" + ], + "properties": { + "burn_block_hash": { + "type": "string", + "description": "0x-prefixed 32-byte Bitcoin block hash that triggered the tenure event", + "pattern": "^0x[0-9a-fA-F]{64}$" + }, + "burn_block_height": { + "type": "integer", + "format": "uint64" + }, + "sortition_id": { + "type": "string", + "description": "0x-prefixed 32-byte sortition ID (unique across PoX and Bitcoin forks)", + "pattern": "^0x[0-9a-fA-F]{64}$" + }, + "parent_sortition_id": { + "type": "string", + "description": "0x-prefixed sortition ID of the parent burn block", + "pattern": "^0x[0-9a-fA-F]{64}$" + }, + "consensus_hash": { + "type": "string", + "description": "0x-prefixed 20-byte consensus hash identifying the tenure", + "pattern": "^0x[0-9a-fA-F]{40}$" + }, + "was_sortition": { + "type": "boolean", + "description": "Whether a winning sortition occurred at this burn block" + }, + "first_block_mined": { + "type": [ + "string", + "null" + ], + "description": "0x-prefixed index-block ID of the first Stacks block in the tenure (if any)", + "pattern": "^0x[0-9a-fA-F]{64}$" + }, + "nakamoto_blocks": { + "type": "null", + "deprecated": true, + "description": "Deprecated and always null. Retained for compatibility with signers released before it stopped being populated, and will be removed in a future release." + } + }, + "additionalProperties": false + }, + "TenureInfo": { + "type": "object", + "properties": { + "consensus_hash": { + "type": "string", + "description": "Consensus hash of the tenure", + "pattern": "^[0-9a-f]{40}$" + }, + "tenure_start_block_id": { + "type": "string", + "description": "Block ID where the tenure started", + "pattern": "^[0-9a-f]{64}$" + }, + "parent_consensus_hash": { + "type": "string", + "description": "Parent consensus hash", + "pattern": "^[0-9a-f]{40}$" + }, + "parent_tenure_start_block_id": { + "type": "string", + "description": "Parent tenure start block ID", + "pattern": "^[0-9a-f]{64}$" + }, + "tip_block_id": { + "type": "string", + "description": "Current tip block ID", + "pattern": "^[0-9a-f]{64}$" + }, + "tip_height": { + "type": "integer", + "minimum": 0, + "description": "Current tip height" + }, + "reward_cycle": { + "type": "integer", + "minimum": 0, + "description": "Current reward cycle" + } + } + }, + "TenureTip": { + "description": "JSON encoding of `StacksBlockHeaderTypes` returned by /v3/tenures/tip.\nExactly one variant property will be present: either `Epoch2` or `Nakamoto`.\n", + "oneOf": [ + { + "title": "Epoch2HeaderVariant", + "type": "object", + "required": [ + "Epoch2" + ], + "additionalProperties": false, + "properties": { + "Epoch2": { + "type": "object", + "description": "Header structure for a Stacks 2.x anchored block.", + "required": [ + "version", + "total_work", + "proof", + "parent_block", + "parent_microblock", + "parent_microblock_sequence", + "tx_merkle_root", + "state_index_root", + "microblock_pubkey_hash" + ], + "properties": { + "version": { + "type": "integer", + "minimum": 0 + }, + "total_work": { + "type": "object", + "required": [ + "burn", + "work" + ], + "properties": { + "burn": { + "type": "integer", + "format": "uint64" + }, + "work": { + "type": "integer", + "format": "uint64" + } + } + }, + "proof": { + "type": "string", + "description": "Hex-encoded VRF proof" + }, + "parent_block": { + "type": "string", + "description": "32-byte hex of the parent block header hash" + }, + "parent_microblock": { + "type": "string", + "description": "32-byte hex of the parent microblock header hash" + }, + "parent_microblock_sequence": { + "type": "integer" + }, + "tx_merkle_root": { + "type": "string", + "description": "Hex-encoded merkle root of the transactions in the block" + }, + "state_index_root": { + "type": "string", + "description": "Hex-encoded MARF trie root after this block" + }, + "microblock_pubkey_hash": { + "type": "string", + "description": "Hash160 (20-byte hex) of the microblock public key" + } + }, + "additionalProperties": false + } + } + }, + { + "title": "NakamotoHeaderVariant", + "type": "object", + "required": [ + "Nakamoto" + ], + "additionalProperties": false, + "properties": { + "Nakamoto": { + "type": "object", + "description": "Header structure for a Nakamoto-epoch Stacks block.", + "required": [ + "version", + "chain_length", + "burn_spent", + "consensus_hash", + "parent_block_id", + "tx_merkle_root", + "state_index_root", + "timestamp", + "miner_signature", + "signer_signature", + "pox_treatment" + ], + "properties": { + "version": { + "type": "integer", + "minimum": 0 + }, + "chain_length": { + "type": "integer", + "format": "uint64", + "description": "Number of ancestor blocks including Stacks 2.x blocks" + }, + "burn_spent": { + "type": "integer", + "format": "uint64", + "description": "Total BTC spent by the sortition that elected this block" + }, + "consensus_hash": { + "type": "string", + "description": "20-byte hex consensus hash that identifies the tenure" + }, + "parent_block_id": { + "type": "string", + "description": "32-byte hex identifier of the parent block (hash+consensus)" + }, + "tx_merkle_root": { + "type": "string", + "description": "Hex-encoded merkle root of all transactions in the block" + }, + "state_index_root": { + "type": "string", + "description": "Hex-encoded MARF trie root after this block" + }, + "timestamp": { + "type": "integer", + "description": "Unix timestamp (seconds)" + }, + "miner_signature": { + "type": "string", + "description": "Recoverable ECDSA signature from the miner" + }, + "signer_signature": { + "type": "array", + "description": "Signer-set signatures over the block header", + "items": { + "type": "string" + } + }, + "pox_treatment": { + "type": "string", + "description": "Bit-vector, hex-encoded, indicating PoX reward treatment" + } + }, + "additionalProperties": false + } + } + } + ] + }, + "TenureTipMetadata": { + "description": "JSON encoding of `BlockHeaderWithMetadata` returned by /v3/tenures/tip_metadata.\nExactly one variant property will be present: either `Epoch2` or `Nakamoto`.\n", + "type": "object", + "required": [ + "anchored_header" + ], + "properties": { + "burn_view": { + "type": "string", + "description": "Hex-encoded bitcoin block hash" + }, + "anchored_header": { + "oneOf": [ + { + "title": "Epoch2HeaderVariant", + "type": "object", + "required": [ + "Epoch2" + ], + "additionalProperties": false, + "properties": { + "Epoch2": { + "type": "object", + "description": "Header structure for a Stacks 2.x anchored block.", + "required": [ + "version", + "total_work", + "proof", + "parent_block", + "parent_microblock", + "parent_microblock_sequence", + "tx_merkle_root", + "state_index_root", + "microblock_pubkey_hash" + ], + "properties": { + "version": { + "type": "integer", + "minimum": 0 + }, + "total_work": { + "type": "object", + "required": [ + "burn", + "work" + ], + "properties": { + "burn": { + "type": "integer", + "format": "uint64" + }, + "work": { + "type": "integer", + "format": "uint64" + } + } + }, + "proof": { + "type": "string", + "description": "Hex-encoded VRF proof" + }, + "parent_block": { + "type": "string", + "description": "32-byte hex of the parent block header hash" + }, + "parent_microblock": { + "type": "string", + "description": "32-byte hex of the parent microblock header hash" + }, + "parent_microblock_sequence": { + "type": "integer" + }, + "tx_merkle_root": { + "type": "string", + "description": "Hex-encoded merkle root of the transactions in the block" + }, + "state_index_root": { + "type": "string", + "description": "Hex-encoded MARF trie root after this block" + }, + "microblock_pubkey_hash": { + "type": "string", + "description": "Hash160 (20-byte hex) of the microblock public key" + } + }, + "additionalProperties": false + } + } + }, + { + "title": "NakamotoHeaderVariant", + "type": "object", + "required": [ + "Nakamoto" + ], + "additionalProperties": false, + "properties": { + "Nakamoto": { + "type": "object", + "description": "Header structure for a Nakamoto-epoch Stacks block.", + "required": [ + "version", + "chain_length", + "burn_spent", + "consensus_hash", + "parent_block_id", + "tx_merkle_root", + "state_index_root", + "timestamp", + "miner_signature", + "signer_signature", + "pox_treatment" + ], + "properties": { + "version": { + "type": "integer", + "minimum": 0 + }, + "chain_length": { + "type": "integer", + "format": "uint64", + "description": "Number of ancestor blocks including Stacks 2.x blocks" + }, + "burn_spent": { + "type": "integer", + "format": "uint64", + "description": "Total BTC spent by the sortition that elected this block" + }, + "consensus_hash": { + "type": "string", + "description": "20-byte hex consensus hash that identifies the tenure" + }, + "parent_block_id": { + "type": "string", + "description": "32-byte hex identifier of the parent block (hash+consensus)" + }, + "tx_merkle_root": { + "type": "string", + "description": "Hex-encoded merkle root of all transactions in the block" + }, + "state_index_root": { + "type": "string", + "description": "Hex-encoded MARF trie root after this block" + }, + "timestamp": { + "type": "integer", + "description": "Unix timestamp (seconds)" + }, + "miner_signature": { + "type": "string", + "description": "Recoverable ECDSA signature from the miner" + }, + "signer_signature": { + "type": "array", + "description": "Signer-set signatures over the block header", + "items": { + "type": "string" + } + }, + "pox_treatment": { + "type": "string", + "description": "Bit-vector, hex-encoded, indicating PoX reward treatment" + } + }, + "additionalProperties": false + } + } + } + ] + } + } + }, + "GetStackerSet": { + "type": "object", + "properties": { + "stacker_set": { + "description": "Reward set for the cycle. The shape depends on `reward_set_version`:\n`0` for PoX-4 cycles, `1` for PoX-5 cycles.\n", + "oneOf": [ + { + "$ref": "#/components/schemas/GetStackerSetPox4" + }, + { + "$ref": "#/components/schemas/GetStackerSetPox5" + } + ] + } + } + }, + "TenureBlocks": { + "type": "object", + "properties": { + "consensus_hash": { + "type": "string", + "description": "Consensus hash of the tenure", + "pattern": "^[0-9a-f]{40}$" + }, + "burn_block_height": { + "type": "integer", + "description": "Height of the Bitcoin block", + "format": "uint64" + }, + "burn_block_hash": { + "type": "string", + "description": "Hash of the Bitcoin block", + "pattern": "^[0-9a-f]{64}$" + }, + "stacks_blocks": { + "type": "array", + "items": { + "type": "object", + "properties": { + "block_id": { + "type": "string", + "description": "Block ID (index block hash)", + "pattern": "^[0-9a-f]{64}$" + }, + "block_hash": { + "type": "string", + "description": "Hash of the block", + "pattern": "^[0-9a-f]{64}$" + }, + "header_type": { + "type": "string", + "description": "Type of block (currently \"epoch2\" or \"nakamoto\")" + }, + "height": { + "type": "integer", + "description": "Height of the block", + "format": "uint64" + }, + "parent_block_id": { + "type": "string", + "description": "Block ID (index block hash) of the parent", + "pattern": "^[0-9a-f]{64}$" + } + } + } + } + } + }, + "ExecutionCost": { + "type": "object", + "additionalProperties": false, + "required": [ + "read_count", + "write_count", + "read_length", + "write_length", + "runtime" + ], + "properties": { + "read_count": { + "type": "integer", + "minimum": 0 + }, + "read_length": { + "type": "integer", + "minimum": 0 + }, + "runtime": { + "type": "integer", + "minimum": 0 + }, + "write_count": { + "type": "integer", + "minimum": 0 + }, + "write_length": { + "type": "integer", + "minimum": 0 + } + } + }, + "StandardPrincipal": { + "type": "string", + "pattern": "^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$", + "minLength": 28, + "maxLength": 41, + "examples": [ + "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0", + "ST000000000000000000002AMW42H", + "SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G", + "SN2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKP6D2ZK9" + ] + }, + "Principal": { + "type": "string", + "pattern": "^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}(\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})?$", + "minLength": 28, + "maxLength": 170, + "examples": [ + "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0", + "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info", + "ST000000000000000000002AMW42H", + "SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G", + "SN2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKP6D2ZK9" + ] + }, + "GetStackerSetPox4": { + "type": "object", + "description": "PoX-4 reward set (`reward_set_version` 0).", + "required": [ + "reward_set_version", + "rewarded_addresses", + "start_cycle_state" + ], + "properties": { + "reward_set_version": { + "type": "integer", + "enum": [ + 0 + ], + "description": "Reward set format version. `0` for PoX-4 cycles." + }, + "rewarded_addresses": { + "type": "array", + "description": "Reward addresses that will receive PoX rewards for the cycle.", + "items": { + "type": "object", + "description": "PoX address object with serialization details (see SIP-007).", + "properties": { + "Standard": { + "type": "array", + "description": "Standard address representation.", + "items": { + "oneOf": [ + { + "type": "object", + "properties": { + "bytes": { + "type": "string", + "description": "Hex-encoded 20-byte address payload" + }, + "version": { + "type": "integer", + "description": "Address version byte" + } + } + }, + { + "type": "string", + "description": "Serialization method (e.g., \"SerializeP2PKH\")" + } + ] + } + } + }, + "additionalProperties": true + } + }, + "signers": { + "type": "array", + "description": "Optional signer set for the reward cycle.", + "items": { + "type": "object", + "properties": { + "signing_key": { + "type": "string", + "description": "Hex-encoded compressed Secp256k1 public key (33 bytes)" + }, + "weight": { + "type": "integer", + "description": "Signer voting weight (number of slots)" + }, + "stacked_amt": { + "type": "integer", + "format": "int64", + "description": "Amount stacked by signer (in microSTX)" + } + } + } + }, + "start_cycle_state": { + "type": "object", + "properties": { + "missed_reward_slots": { + "type": "array", + "description": "Principals that missed reward slots at cycle start.", + "items": { + "type": "object" + } + } + } + }, + "pox_ustx_threshold": { + "type": "integer", + "format": "int64", + "description": "Minimum STX amount required to qualify for stacking (optional)" + } + } + }, + "GetStackerSetPox5": { + "type": "object", + "description": "PoX-5 reward set (`reward_set_version` 1). PoX-5 pays the cycle's rewards to\na single sBTC address, so there is no per-stacker `rewarded_addresses` list.\n", + "required": [ + "reward_set_version", + "sbtc_address", + "signers", + "pox_ustx_threshold" + ], + "properties": { + "reward_set_version": { + "type": "integer", + "enum": [ + 1 + ], + "description": "Reward set format version. `1` for PoX-5 cycles." + }, + "sbtc_address": { + "type": "object", + "description": "PoX address that receives the cycle's rewards. Serialized like the entries\nof `rewarded_addresses` in PoX-4 reward sets; on mainnet this is an\n`Addr32` taproot address.\n", + "properties": { + "Addr32": { + "type": "array", + "description": "32-byte witness address representation, a tuple of\n[mainnet flag, address type, 32-byte hash as a byte array].\n", + "items": { + "oneOf": [ + { + "type": "boolean", + "description": "Whether the address is a mainnet address" + }, + { + "type": "string", + "description": "Address type (\"P2WSH\" or \"P2TR\")" + }, + { + "type": "array", + "description": "32-byte hash as a byte array", + "items": { + "type": "integer" + } + } + ] + } + } + }, + "additionalProperties": true + }, + "signers": { + "type": "array", + "description": "Signer set for the reward cycle.", + "items": { + "type": "object", + "properties": { + "signing_key": { + "type": "string", + "description": "Hex-encoded compressed Secp256k1 public key (33 bytes)" + }, + "weight": { + "type": "integer", + "description": "Signer voting weight (number of slots)" + }, + "stacked_amt": { + "type": "integer", + "format": "int64", + "description": "Amount stacked by signer (in microSTX)" + } + } + } + }, + "pox_ustx_threshold": { + "type": "integer", + "format": "int64", + "description": "Minimum STX amount required to qualify for stacking" + } + } + } + }, + "examples": { + "transaction-submission-error.example": { + "summary": "Transaction submission error response", + "value": { + "error": "transaction rejected", + "reason": "BadNonce", + "reason_data": { + "actual": 4, + "expected": 0, + "is_origin": true, + "principal": "ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH" + }, + "txid": "caf6fd60ae05b0c2d19ef14ab6a7670b1095d117fa7c80224c74e76214d0a791" + } + }, + "contract-interface.example": { + "summary": "Contract interface details", + "value": { + "functions": [ + { + "name": "protocol-mint-many-iter", + "access": "private", + "args": [ + { + "name": "item", + "type": { + "tuple": [ + { + "name": "amount", + "type": "uint128" + }, + { + "name": "recipient", + "type": "principal" + } + ] + } + } + ], + "outputs": { + "type": { + "response": { + "ok": "bool", + "error": "uint128" + } + } + } + }, + { + "name": "transfer-many-iter", + "access": "private", + "args": [ + { + "name": "individual-transfer", + "type": { + "tuple": [ + { + "name": "amount", + "type": "uint128" + }, + { + "name": "memo", + "type": { + "optional": { + "buffer": { + "length": 34 + } + } + } + }, + { + "name": "sender", + "type": "principal" + }, + { + "name": "to", + "type": "principal" + } + ] + } + }, + { + "name": "result", + "type": { + "response": { + "ok": "uint128", + "error": "uint128" + } + } + } + ], + "outputs": { + "type": { + "response": { + "ok": "uint128", + "error": "uint128" + } + } + } + }, + { + "name": "protocol-burn", + "access": "public", + "args": [ + { + "name": "amount", + "type": "uint128" + }, + { + "name": "owner", + "type": "principal" + }, + { + "name": "contract-flag", + "type": { + "buffer": { + "length": 1 + } + } + } + ], + "outputs": { + "type": { + "response": { + "ok": "bool", + "error": "uint128" + } + } + } + }, + { + "name": "protocol-burn-locked", + "access": "public", + "args": [ + { + "name": "amount", + "type": "uint128" + }, + { + "name": "owner", + "type": "principal" + }, + { + "name": "contract-flag", + "type": { + "buffer": { + "length": 1 + } + } + } + ], + "outputs": { + "type": { + "response": { + "ok": "bool", + "error": "uint128" + } + } + } + }, + { + "name": "protocol-lock", + "access": "public", + "args": [ + { + "name": "amount", + "type": "uint128" + }, + { + "name": "owner", + "type": "principal" + }, + { + "name": "contract-flag", + "type": { + "buffer": { + "length": 1 + } + } + } + ], + "outputs": { + "type": { + "response": { + "ok": "bool", + "error": "uint128" + } + } + } + }, + { + "name": "protocol-mint", + "access": "public", + "args": [ + { + "name": "amount", + "type": "uint128" + }, + { + "name": "recipient", + "type": "principal" + }, + { + "name": "contract-flag", + "type": { + "buffer": { + "length": 1 + } + } + } + ], + "outputs": { + "type": { + "response": { + "ok": "bool", + "error": "uint128" + } + } + } + }, + { + "name": "protocol-mint-many", + "access": "public", + "args": [ + { + "name": "recipients", + "type": { + "list": { + "type": { + "tuple": [ + { + "name": "amount", + "type": "uint128" + }, + { + "name": "recipient", + "type": "principal" + } + ] + }, + "length": 200 + } + } + }, + { + "name": "contract-flag", + "type": { + "buffer": { + "length": 1 + } + } + } + ], + "outputs": { + "type": { + "response": { + "ok": { + "list": { + "type": { + "response": { + "ok": "bool", + "error": "uint128" + } + }, + "length": 200 + } + }, + "error": "uint128" + } + } + } + }, + { + "name": "protocol-set-name", + "access": "public", + "args": [ + { + "name": "new-name", + "type": { + "string-ascii": { + "length": 32 + } + } + }, + { + "name": "contract-flag", + "type": { + "buffer": { + "length": 1 + } + } + } + ], + "outputs": { + "type": { + "response": { + "ok": "bool", + "error": "uint128" + } + } + } + }, + { + "name": "protocol-set-symbol", + "access": "public", + "args": [ + { + "name": "new-symbol", + "type": { + "string-ascii": { + "length": 10 + } + } + }, + { + "name": "contract-flag", + "type": { + "buffer": { + "length": 1 + } + } + } + ], + "outputs": { + "type": { + "response": { + "ok": "bool", + "error": "uint128" + } + } + } + }, + { + "name": "protocol-set-token-uri", + "access": "public", + "args": [ + { + "name": "new-uri", + "type": { + "optional": { + "string-utf8": { + "length": 256 + } + } + } + }, + { + "name": "contract-flag", + "type": { + "buffer": { + "length": 1 + } + } + } + ], + "outputs": { + "type": { + "response": { + "ok": "bool", + "error": "uint128" + } + } + } + }, + { + "name": "protocol-unlock", + "access": "public", + "args": [ + { + "name": "amount", + "type": "uint128" + }, + { + "name": "owner", + "type": "principal" + }, + { + "name": "contract-flag", + "type": { + "buffer": { + "length": 1 + } + } + } + ], + "outputs": { + "type": { + "response": { + "ok": "bool", + "error": "uint128" + } + } + } + }, + { + "name": "transfer", + "access": "public", + "args": [ + { + "name": "amount", + "type": "uint128" + }, + { + "name": "sender", + "type": "principal" + }, + { + "name": "recipient", + "type": "principal" + }, + { + "name": "memo", + "type": { + "optional": { + "buffer": { + "length": 34 + } + } + } + } + ], + "outputs": { + "type": { + "response": { + "ok": "bool", + "error": "uint128" + } + } + } + }, + { + "name": "transfer-many", + "access": "public", + "args": [ + { + "name": "recipients", + "type": { + "list": { + "type": { + "tuple": [ + { + "name": "amount", + "type": "uint128" + }, + { + "name": "memo", + "type": { + "optional": { + "buffer": { + "length": 34 + } + } + } + }, + { + "name": "sender", + "type": "principal" + }, + { + "name": "to", + "type": "principal" + } + ] + }, + "length": 200 + } + } + } + ], + "outputs": { + "type": { + "response": { + "ok": "uint128", + "error": "uint128" + } + } + } + }, + { + "name": "get-balance", + "access": "read_only", + "args": [ + { + "name": "who", + "type": "principal" + } + ], + "outputs": { + "type": { + "response": { + "ok": "uint128", + "error": "none" + } + } + } + }, + { + "name": "get-balance-available", + "access": "read_only", + "args": [ + { + "name": "who", + "type": "principal" + } + ], + "outputs": { + "type": { + "response": { + "ok": "uint128", + "error": "none" + } + } + } + }, + { + "name": "get-balance-locked", + "access": "read_only", + "args": [ + { + "name": "who", + "type": "principal" + } + ], + "outputs": { + "type": { + "response": { + "ok": "uint128", + "error": "none" + } + } + } + }, + { + "name": "get-decimals", + "access": "read_only", + "args": [], + "outputs": { + "type": { + "response": { + "ok": "uint128", + "error": "none" + } + } + } + }, + { + "name": "get-name", + "access": "read_only", + "args": [], + "outputs": { + "type": { + "response": { + "ok": { + "string-ascii": { + "length": 32 + } + }, + "error": "none" + } + } + } + }, + { + "name": "get-symbol", + "access": "read_only", + "args": [], + "outputs": { + "type": { + "response": { + "ok": { + "string-ascii": { + "length": 10 + } + }, + "error": "none" + } + } + } + }, + { + "name": "get-token-uri", + "access": "read_only", + "args": [], + "outputs": { + "type": { + "response": { + "ok": { + "optional": { + "string-utf8": { + "length": 256 + } + } + }, + "error": "none" + } + } + } + }, + { + "name": "get-total-supply", + "access": "read_only", + "args": [], + "outputs": { + "type": { + "response": { + "ok": "uint128", + "error": "none" + } + } + } + } + ], + "variables": [ + { + "name": "ERR_NOT_OWNER", + "type": { + "response": { + "ok": "none", + "error": "uint128" + } + }, + "access": "constant" + }, + { + "name": "ERR_TRANSFER_INDEX_PREFIX", + "type": "uint128", + "access": "constant" + }, + { + "name": "token-decimals", + "type": "uint128", + "access": "constant" + }, + { + "name": "token-name", + "type": { + "string-ascii": { + "length": 32 + } + }, + "access": "variable" + }, + { + "name": "token-symbol", + "type": { + "string-ascii": { + "length": 10 + } + }, + "access": "variable" + }, + { + "name": "token-uri", + "type": { + "optional": { + "string-utf8": { + "length": 256 + } + } + }, + "access": "variable" + } + ], + "maps": [], + "fungible_tokens": [ + { + "name": "sbtc-token" + }, + { + "name": "sbtc-token-locked" + } + ], + "non_fungible_tokens": [], + "epoch": "Epoch30", + "clarity_version": "Clarity3" + } + }, + "clarity-data.example": { + "summary": "Clarity data map lookup result", + "value": { + "data": "0x0a0c000000010a6d6f6e737465722d69640100000000000000000000000000000001", + "proof": "0x123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" + } + }, + "contract-source.example": { + "summary": "Contract source code", + "value": { + "source": "(define-constant sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)\n(define-constant recipient 'SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G)\n\n(define-fungible-token novel-token-19)\n(begin (ft-mint? novel-token-19 u12 sender))\n(begin (ft-transfer? novel-token-19 u2 sender recipient))\n\n(define-non-fungible-token hello-nft uint)\n(begin (nft-mint? hello-nft u1 sender))\n(begin (nft-mint? hello-nft u2 sender))\n(begin (nft-transfer? hello-nft u1 sender recipient))\n\n(define-public (test-emit-event)\n (begin\n (print \"Event! Hello world\")\n (ok u1)))\n(begin (test-emit-event))\n\n(define-public (test-event-types)\n (begin\n (unwrap-panic (ft-mint? novel-token-19 u3 recipient))\n (unwrap-panic (nft-mint? hello-nft u2 recipient))\n (unwrap-panic (stx-transfer? u60 tx-sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR))\n (unwrap-panic (stx-burn? u20 tx-sender))\n (ok u1)))\n\n(define-map store ((key (buff 32))) ((value (buff 32))))\n(define-public (get-value (key (buff 32)))\n (begin\n (match (map-get? store ((key key)))\n entry (ok (get value entry))\n (err 0))))\n(define-public (set-value (key (buff 32)) (value (buff 32)))\n (begin\n (map-set store ((key key)) ((value value)))\n (ok u1)))", + "publish_height": 3196, + "proof": "0x000000110406000000123456789abcdef" + } + }, + "read-only-function-success.example": { + "summary": "Read-only function success response", + "value": { + "okay": true, + "result": "0x0100000000000000000000000000000001" + } + }, + "read-only-function-failure.example": { + "summary": "Read-only function failure response", + "value": { + "okay": false, + "cause": "NotReadOnly" + } + }, + "account-data.example": { + "summary": "Account data with balance and nonce", + "value": { + "balance": "0x0000000000000000000000000007a120", + "locked": "0x0000000000000000000000000007a120", + "unlock_height": 126, + "nonce": 2867, + "balance_proof": "0xabce", + "nonce_proof": "0xabcd" + } + }, + "fee-transaction-response.example": { + "summary": "Fee estimation response", + "value": { + "cost_scalar_change_by_byte": 0.00476837158203125, + "estimated_cost": { + "read_count": 19, + "read_length": 4814, + "runtime": 7175000, + "write_count": 2, + "write_length": 1020 + }, + "estimated_cost_scalar": 14, + "estimations": [ + { + "fee": 17, + "fee_rate": 1.2410714285714286 + }, + { + "fee": 125, + "fee_rate": 8.958333333333332 + }, + { + "fee": 140, + "fee_rate": 10 + } + ] + } + }, + "node-info.example": { + "summary": "Node information response", + "value": { + "peer_version": 385875968, + "pox_consensus": "17f76e597bab45646956f38dd39573085d72cbc0", + "burn_block_height": 16, + "stable_pox_consensus": "8e0561978fc5506b68a589c402dad97e862edb59", + "stable_burn_block_height": 15, + "server_version": "stacks-node 3.1.0.0.12 (release/3.1.0.0.12:ae969ca+, release build, linux [x86_64])", + "network_id": 1, + "parent_network_id": 3652501241, + "stacks_tip_height": 1832097, + "stacks_tip": "b1807a2d3f7f8c7922f7c1d60d7c34145ade05d789640dc7dc9ec1021e07bb54", + "stacks_tip_consensus_hash": "17f76e597bab45646956f38dd39573085d72cbc0", + "genesis_chainstate_hash": "74237aa39aa50a83de11a4f3e9a0b9c89a0b1a2f2a6a11b8a7e1e9a0b1c2d3e4f", + "unanchored_tip": "0000000000000000000000000000000000000000000000000000000000000000", + "tenure_height": 523, + "exit_at_block_height": null, + "is_fully_synced": false, + "node_public_key": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef01", + "node_public_key_hash": "1328af7c4f96eee8fdbb1e023e48ba11e255d1c8", + "last_pox_anchor": { + "anchor_block_hash": "47c20352492e1647127d6f6275fa5abfe90157f6a64e6a175ff45ed0c1fb3f4e", + "anchor_block_txid": "5b5d678c658525122fa73a8699b5810325ce9412bf0dc3762fb7518699be3d4d" + }, + "stackerdbs": [] + } + }, + "pox-info.example": { + "summary": "PoX information response", + "value": { + "contract_id": "SP000000000000000000002Q6VF78.pox-5", + "pox_activation_threshold_ustx": 93581153329244, + "first_burnchain_block_height": 666050, + "current_burnchain_block_height": 969845, + "prepare_phase_block_length": 100, + "reward_phase_block_length": 2000, + "reward_slots": 4000, + "rejection_fraction": null, + "total_liquid_supply_ustx": 1871623066584899, + "current_cycle": { + "id": 144, + "min_threshold_ustx": 50000000000, + "stacked_ustx": 448329575893867, + "is_pox_active": true + }, + "next_cycle": { + "id": 145, + "min_threshold_ustx": 50000000000, + "min_increment_ustx": 50000000000, + "stacked_ustx": 433669547352463, + "prepare_phase_start_block_height": 970450, + "blocks_until_prepare_phase": 605, + "reward_phase_start_block_height": 970550, + "blocks_until_reward_phase": 705, + "ustx_until_pox_rejection": null + }, + "epochs": [ + { + "epoch_id": "Epoch10", + "start_height": 0, + "end_height": 666050, + "block_limit": { + "write_length": 0, + "write_count": 0, + "read_length": 0, + "read_count": 0, + "runtime": 0 + }, + "network_epoch": 0 + }, + { + "epoch_id": "Epoch20", + "start_height": 666050, + "end_height": 713000, + "block_limit": { + "write_length": 15000000, + "write_count": 7750, + "read_length": 100000000, + "read_count": 7750, + "runtime": 5000000000 + }, + "network_epoch": 0 + }, + { + "epoch_id": "Epoch2_05", + "start_height": 713000, + "end_height": 781551, + "block_limit": { + "write_length": 15000000, + "write_count": 15000, + "read_length": 100000000, + "read_count": 15000, + "runtime": 5000000000 + }, + "network_epoch": 5 + }, + { + "epoch_id": "Epoch21", + "start_height": 781551, + "end_height": 787651, + "block_limit": { + "write_length": 15000000, + "write_count": 15000, + "read_length": 100000000, + "read_count": 15000, + "runtime": 5000000000 + }, + "network_epoch": 6 + }, + { + "epoch_id": "Epoch22", + "start_height": 787651, + "end_height": 788240, + "block_limit": { + "write_length": 15000000, + "write_count": 15000, + "read_length": 100000000, + "read_count": 15000, + "runtime": 5000000000 + }, + "network_epoch": 7 + }, + { + "epoch_id": "Epoch23", + "start_height": 788240, + "end_height": 791551, + "block_limit": { + "write_length": 15000000, + "write_count": 15000, + "read_length": 100000000, + "read_count": 15000, + "runtime": 5000000000 + }, + "network_epoch": 8 + }, + { + "epoch_id": "Epoch24", + "start_height": 791551, + "end_height": 840360, + "block_limit": { + "write_length": 15000000, + "write_count": 15000, + "read_length": 100000000, + "read_count": 15000, + "runtime": 5000000000 + }, + "network_epoch": 9 + }, + { + "epoch_id": "Epoch25", + "start_height": 840360, + "end_height": 867867, + "block_limit": { + "write_length": 15000000, + "write_count": 15000, + "read_length": 100000000, + "read_count": 15000, + "runtime": 5000000000 + }, + "network_epoch": 10 + }, + { + "epoch_id": "Epoch30", + "start_height": 867867, + "end_height": 875000, + "block_limit": { + "write_length": 15000000, + "write_count": 15000, + "read_length": 100000000, + "read_count": 15000, + "runtime": 5000000000 + }, + "network_epoch": 11 + }, + { + "epoch_id": "Epoch31", + "start_height": 875000, + "end_height": 907740, + "block_limit": { + "write_length": 15000000, + "write_count": 15000, + "read_length": 100000000, + "read_count": 15000, + "runtime": 5000000000 + }, + "network_epoch": 12 + }, + { + "epoch_id": "Epoch32", + "start_height": 907740, + "end_height": 923222, + "block_limit": { + "write_length": 15000000, + "write_count": 15000, + "read_length": 100000000, + "read_count": 15000, + "runtime": 5000000000 + }, + "network_epoch": 13 + }, + { + "epoch_id": "Epoch33", + "start_height": 923222, + "end_height": 943333, + "block_limit": { + "write_length": 15000000, + "write_count": 15000, + "read_length": 100000000, + "read_count": 15000, + "runtime": 5000000000 + }, + "network_epoch": 14 + }, + { + "epoch_id": "Epoch34", + "start_height": 943333, + "end_height": 960230, + "block_limit": { + "write_length": 15000000, + "write_count": 15000, + "read_length": 100000000, + "read_count": 15000, + "runtime": 5000000000 + }, + "network_epoch": 15 + }, + { + "epoch_id": "Epoch40", + "start_height": 960230, + "end_height": 9223372036854776000, + "block_limit": { + "write_length": 15000000, + "write_count": 15000, + "read_length": 200000000, + "read_count": 30000, + "runtime": 5000000000 + }, + "network_epoch": 16 + }, + { + "epoch_id": "Epoch41", + "start_height": 9223372036854776000, + "end_height": 9223372036854776000, + "block_limit": { + "write_length": 15000000, + "write_count": 15000, + "read_length": 200000000, + "read_count": 30000, + "runtime": 5000000000 + }, + "network_epoch": 17 + } + ], + "current_epoch": "Epoch40", + "min_amount_ustx": 50000000000, + "prepare_cycle_length": 100, + "reward_cycle_id": 144, + "reward_cycle_length": 2100, + "rejection_votes_left_required": null, + "next_reward_cycle_in": 705, + "contract_versions": [ + { + "contract_id": "SP000000000000000000002Q6VF78.pox", + "activation_burnchain_block_height": 666050, + "first_reward_cycle_id": 0 + }, + { + "contract_id": "SP000000000000000000002Q6VF78.pox-2", + "activation_burnchain_block_height": 781552, + "first_reward_cycle_id": 56 + }, + { + "contract_id": "SP000000000000000000002Q6VF78.pox-3", + "activation_burnchain_block_height": 791551, + "first_reward_cycle_id": 60 + }, + { + "contract_id": "SP000000000000000000002Q6VF78.pox-4", + "activation_burnchain_block_height": 840361, + "first_reward_cycle_id": 84 + }, + { + "contract_id": "SP000000000000000000002Q6VF78.pox-5", + "activation_burnchain_block_height": 960230, + "first_reward_cycle_id": 141 + } + ], + "pox_5_sbtc_contract": "SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token", + "pox_5_sbtc_registry_contract": "SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-registry" + } + }, + "is-trait-implemented.example": { + "summary": "Trait implementation check", + "value": { + "is_implemented": true + } + }, + "clarity-metadata.example": { + "summary": "Clarity contract metadata", + "value": { + "data": "'{\"contract_identifier\":{...}, \"private_function_types\":{...}'" + } + }, + "constant-value.example": { + "summary": "Constant value lookup result", + "value": { + "data": "0x01ce0123456789abcdef" + } + }, + "post-block-proposal-response.example": { + "summary": "Block proposal accepted response", + "value": { + "message": "Block proposal is processing, result will be returned via the event observer", + "result": "Accepted" + } + }, + "post-block-proposal-response.429.example": { + "summary": "Block proposal rate limit error", + "value": { + "message": "Could not process block proposal request: Proposal currently being evaluated", + "result": "Error" + } + }, + "get-stacker-set-pox4.example": { + "summary": "Stacker set response (PoX-4 cycle)", + "value": { + "stacker_set": { + "reward_set_version": 0, + "rewarded_addresses": [ + { + "Standard": [ + { + "bytes": "dc5f18421006ee2b98ab972edfa7268a981e3f00", + "version": 26 + }, + "SerializeP2PKH" + ] + } + ], + "signers": [ + { + "signing_key": "02d0a27e4f1bf186b4391eecfcc4d4a0d403684ad089b477b8548a69dd6378bf26", + "weight": 1, + "stacked_amt": 2143020000000000 + } + ], + "start_cycle_state": { + "missed_reward_slots": [] + }, + "pox_ustx_threshold": 110000000000 + } + } + }, + "get-stacker-set-pox5.example": { + "summary": "Stacker set response (PoX-5 cycle)", + "value": { + "stacker_set": { + "reward_set_version": 1, + "sbtc_address": { + "Addr32": [ + true, + "P2TR", + [ + 35, + 78, + 62, + 152, + 83, + 38, + 17, + 204, + 89, + 128, + 170, + 73, + 10, + 116, + 43, + 155, + 202, + 197, + 215, + 235, + 64, + 216, + 24, + 108, + 149, + 0, + 228, + 113, + 82, + 224, + 35, + 51 + ] + ] + }, + "signers": [ + { + "signing_key": "0209130bec93e83b23d3366adfcbe0a1641057b9c48102572d892fe8f78de2bee7", + "stacked_amt": 71276903000000, + "weight": 636 + }, + { + "signing_key": "0216436e7785e1dc55cf4350ac1f90e45daf0ec5b57bce13a32551a513446e71d1", + "stacked_amt": 1000001500110, + "weight": 9 + } + ], + "pox_ustx_threshold": 112082393974 + } + } + }, + "get-stacker-set-400.example": { + "summary": "Stacker set error response", + "value": { + "response": "error", + "err_type": "not_available_try_again", + "err_msg": "Could not read reward set. Prepare phase may not have started for this cycle yet. Cycle = 22, Err = PoXAnchorBlockRequired" + } + }, + "get-tenure-info.example": { + "summary": "Tenure information", + "value": { + "consensus_hash": "4c5a49be0e34dc603b66f090fd07d28a2f76a2ad", + "parent_consensus_hash": "fa8a04af41957499afdd4082b9b702ffca9a4370", + "parent_tenure_start_block_id": "0cfec8433849d353ad6b2fe1173da143e3d4a3ab452588a14eb074d0181ac202", + "reward_cycle": 8, + "tenure_start_block_id": "0425099d51547c714df6a7864c040c1a605b198ff07f71d19a823139c88a35f8", + "tip_block_id": "52d64f5e47abc7666c4fed3fe850f381f93f2d588ee2a92a4e07b44f14588d5e", + "tip_height": 416 + } + }, + "tenure-blocks.example": { + "summary": "List of blocks in a tenure", + "value": { + "burn_block_hash": "dff0aba3d65209225e365692ac46d26fa64ca9760bd7c244fc27e2022f7cb90d", + "burn_block_height": 51, + "consensus_hash": "90b360130732dd83a165a7fa34386ae547512300", + "stacks_blocks": [ + { + "block_hash": "a9f3d8bca7d766a2022528e27c52f39ba77192f0712ea5515cc9d06b97821a11", + "block_id": "67c795896b4c2940b3eb759871661a72e78458ba591dc63979d689d23695891f", + "header_type": "nakamoto", + "height": 116, + "parent_block_id": "fb7102c45bb2f07a6dd86b6672cb39133861fc7d38087e82cb04d4faccfcab82" + }, + { + "block_hash": "3e81505acaa3d386e15256921dd1193e479fd9d7f81d993b1c2b327b9bfb05cc", + "block_id": "fb7102c45bb2f07a6dd86b6672cb39133861fc7d38087e82cb04d4faccfcab82", + "header_type": "nakamoto", + "height": 115, + "parent_block_id": "5d51f815bc71508768b71258d8bc2adc68c129428101a418083f5b5ab30d525e" + }, + { + "block_hash": "c6f427503dcbe8bf187c7ce523c7a239328b2ab4ec87d6013895b2bd9ed23604", + "block_id": "5d51f815bc71508768b71258d8bc2adc68c129428101a418083f5b5ab30d525e", + "header_type": "nakamoto", + "height": 114, + "parent_block_id": "7d1c89f57a467f888fed171a5b3a2e51a7652f862189710df7db814ef84a29e2" + }, + { + "block_hash": "f0665d1dd419e949d68c4e85b7f79e078d6c36d929820b9cd9c794a60c0505b4", + "block_id": "7d1c89f57a467f888fed171a5b3a2e51a7652f862189710df7db814ef84a29e2", + "header_type": "nakamoto", + "height": 113, + "parent_block_id": "b65ab3b6d113285390c1d99c09a62d940f5b55c1cbc10bdc1b478c395fc435f9" + }, + { + "block_hash": "0486701e4eed06b74c3d93b82ffc0f3700b3cb2bea41aea1a30e00a5669ec0b7", + "block_id": "b65ab3b6d113285390c1d99c09a62d940f5b55c1cbc10bdc1b478c395fc435f9", + "header_type": "nakamoto", + "height": 112, + "parent_block_id": "c711415e6eedffcb6be16e33eb5c5cf62c3f51047f9528a51e21cbd83b25c185" + }, + { + "block_hash": "6724170340a2e507dbe7b21b691412e196c7c8900a597786aa991c1429ae6b58", + "block_id": "c711415e6eedffcb6be16e33eb5c5cf62c3f51047f9528a51e21cbd83b25c185", + "header_type": "nakamoto", + "height": 111, + "parent_block_id": "b11d631ef1b052942973cac88527a56f6e00c51fd57f9b7a710713f58ddc2393" + }, + { + "block_hash": "2114066e4446242e558847f552ca839f65ae769ab59000087677007e52b0dab7", + "block_id": "b11d631ef1b052942973cac88527a56f6e00c51fd57f9b7a710713f58ddc2393", + "header_type": "nakamoto", + "height": 110, + "parent_block_id": "2ef1973e95ba622479e59e87251d35c1eaaa9cb7f99f3dd3a8a79359624c38eb" + }, + { + "block_hash": "2345d34722cb07e908c5dab7f89ec0756f34d7fe34c86e40881c29c6aa202601", + "block_id": "2ef1973e95ba622479e59e87251d35c1eaaa9cb7f99f3dd3a8a79359624c38eb", + "header_type": "nakamoto", + "height": 109, + "parent_block_id": "9c1f844267819dc7349ff0aff6e6c6f60d8c41b531e304cd89df022ca4d147bf" + }, + { + "block_hash": "6b904297fdd045e2d18b93083f9d36592fa6915a53e8461fc3b4c59f6c91bc6d", + "block_id": "9c1f844267819dc7349ff0aff6e6c6f60d8c41b531e304cd89df022ca4d147bf", + "header_type": "nakamoto", + "height": 108, + "parent_block_id": "335596dd153bfc155863a2d439940816cd5095a3b36e2738fb89d715c28ac6c5" + }, + { + "block_hash": "cd748c67a9b7e685c52f388cc1d5e334b3dbe2509535caaf9f7ea7b6e5bbad77", + "block_id": "335596dd153bfc155863a2d439940816cd5095a3b36e2738fb89d715c28ac6c5", + "header_type": "nakamoto", + "height": 107, + "parent_block_id": "45cb658a80897117c2cfa6191a7623344ed1079117ad8bb30113019278bac028" + } + ] + } + }, + "get-sortitions.example": { + "summary": "Sortition information", + "value": [ + { + "burn_block_hash": "0x00000000000000000002173857dc821186d17c6aee85e545a74625b6bc9c3656", + "burn_block_height": 902499, + "burn_header_timestamp": 1750747303, + "sortition_id": "0x7ae9066d4c3cf4a5c5f5f89d30bd012317be1c10f520af6b8f35d169c3a424ba", + "parent_sortition_id": "0x04d40e2ee2a9ee79c59c2e85b2f742c57bdeed5a2c32bb3bf659a77e892d8234", + "consensus_hash": "0xe4a00a6c88722c7812ba0a2f780c42247c1d2d4c", + "was_sortition": true, + "miner_pk_hash160": "0x37e79a837b4071a1fc6c1b49208e7d2141a25905", + "stacks_parent_ch": "0x7d3094294fabc1948d15fca4566ee2175a1e9808", + "last_sortition_ch": "0x7d3094294fabc1948d15fca4566ee2175a1e9808", + "committed_block_hash": "0xdeb48fe0b0600092968fb7de1b6d586b111be7cd61bf52a666d14d41d6835ded", + "vrf_seed": "0x49b75b824fcf765264d6ec91889a146bf52d46e2688f1b7ae7f7e5187765e99d" + } + ] + }, + "get-sortitions-latest-and-prior.example": { + "summary": "Latest and prior sortitions", + "value": [ + { + "burn_block_hash": "0x046f54cd1924a5d80fc3b8186d0334b7521acae90f9e136e2bee680c720d0e83", + "burn_block_height": 231, + "burn_header_timestamp": 1726797570, + "sortition_id": "0x8a5116b7b4306dc4f6db290d1adfff9e1347f3e921bb793fc4c33e2ff05056e2", + "parent_sortition_id": "0xdaf479110cf859e58c56b6ae941f8a14e7c7992c57027183dfbda4a4b820897c", + "consensus_hash": "0x8d2c51db737597a93191f49bcdc9c7bb44b90892", + "was_sortition": true, + "miner_pk_hash160": "0x6bc51b33e9f3626944eb879147e18111581f8f9b", + "stacks_parent_ch": "0x697357c72da55b759b1d6b721676c92c69f0b490", + "last_sortition_ch": "0x697357c72da55b759b1d6b721676c92c69f0b490", + "committed_block_hash": "0xeea47d6d639c565027110e192e308fb11656183d5c077bcd718d830652800183" + }, + { + "burn_block_hash": "0x496ff02cb63a4850d0bdee5fab69284b6eb0392b4538e1c462f82362c5becfa4", + "burn_block_height": 230, + "burn_header_timestamp": 1726797570, + "sortition_id": "0xdaf479110cf859e58c56b6ae941f8a14e7c7992c57027183dfbda4a4b820897c", + "parent_sortition_id": "0xf9058692055cbd879d7f71e566e44b905a887b2b182407ed596b5d6499ceae2a", + "consensus_hash": "0x697357c72da55b759b1d6b721676c92c69f0b490", + "was_sortition": true, + "miner_pk_hash160": "0x6bc51b33e9f3626944eb879147e18111581f8f9b", + "stacks_parent_ch": "0xf7d1bd7d9d5c5a5c368402b6ef9510bd014d70f7", + "last_sortition_ch": "0xf7d1bd7d9d5c5a5c368402b6ef9510bd014d70f7", + "committed_block_hash": "0x36ee5f7f7271de1c1d4cd830e36320b51e01605547621267ae6e9b4e9b10f95e" + } + ] + }, + "get-transaction.example": { + "summary": "Transaction information", + "value": { + "index_block_hash": "e0b6c25b1dac0c0e1c75e41ab46bd6d70d9a2d02ffed8f2c0733b6e686289c38", + "result": "(ok true)", + "tx": "808000000004008bc5147525b8f477f0bc4522a88c8339b2494db5000000000000001a0000000000000000010123eab800bc9f639c5aa05d154148a981c89fd21064a6f8cafd8649800a56c9ea77e2e46bed8bd9ef0f173b19b20d6c43e2a9f37b078df5c74b9e6f9be75b650e01020000000007588687edeb02248d402c316ed33e22ea0e73af8703ce5011f3e25f5ce12f00f903ca504742117ee0588687edeb02248d402c316ed33e22ea0e73af87c54e0d94e4dd298cf19778352906a2fcf0af74582b07dfb57c710288874f71ca00000001006bc51b33e9f3626944eb879147e18111581f8f9b" + } + }, + "node-health.example": { + "summary": "Node health status", + "value": { + "difference_from_max_peer": 0, + "node_stacks_tip_height": 12345, + "max_stacks_height_of_neighbors": 12345, + "max_stacks_neighbor_address": "127.0.0.1:8080" + } + }, + "stackerdb-chunk-ack-success.example": { + "summary": "StackerDB chunk acknowledgment success", + "value": { + "accepted": true, + "reason": null, + "metadata": { + "slot_id": 1, + "slot_version": 2, + "data_hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", + "signature": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef01" + }, + "code": null + } + }, + "stackerdb-chunk-ack-failure.example": { + "summary": "StackerDB chunk acknowledgment failure", + "value": { + "accepted": false, + "reason": "{\"code\": 1, \"message\": \"NoSuchSlot\", \"reason\": \"No such StackerDB slot\"}", + "metadata": { + "slot_id": 1, + "slot_version": 1, + "data_hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", + "signature": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef01" + }, + "code": 1 + } + }, + "network-peers.example": { + "summary": "Network peer list", + "value": { + "bootstrap": [ + { + "network_id": 1, + "peer_version": 24000000, + "ip": "172.20.0.3", + "port": 20444, + "public_key_hash": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2", + "authenticated": true, + "stackerdbs": [ + "SP000000000000000000002Q6VF78.my-stacker-db-1" + ], + "age": null + } + ], + "sample": [ + { + "network_id": 1, + "peer_version": 24000000, + "ip": "88.99.100.123", + "port": 20444, + "public_key_hash": "b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3", + "authenticated": true, + "stackerdbs": [], + "age": null + } + ], + "inbound": [ + { + "network_id": 1, + "peer_version": 24000000, + "ip": "192.168.1.10", + "port": 54321, + "public_key_hash": "c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4", + "authenticated": true, + "stackerdbs": [], + "age": 3600 + } + ], + "outbound": [ + { + "network_id": 1, + "peer_version": 24000000, + "ip": "10.0.0.5", + "port": 20444, + "public_key_hash": "d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5", + "authenticated": true, + "stackerdbs": [ + "SP000000000000000000002Q6VF78.my-stacker-db-2" + ], + "age": 120 + } + ] + } + }, + "get-tenure-tip.example": { + "summary": "Tenure tip block header", + "value": { + "Nakamoto": { + "version": 0, + "chain_length": 1827432, + "burn_spent": 417647583456, + "consensus_hash": "16707a8b6d73e69605f37eab9917d83806035de1", + "parent_block_id": "28abb89ad887807b74b7b1493080450d3a2af8f4799422b9191c83b0da50d046", + "tx_merkle_root": "2661ea27ab74956a517f0239044511575c99230f635f19747671604db83fc4d7", + "state_index_root": "dcf3d34ff3e599088c28ae45b781efa00a79eeae49972b5a526b46502092ca91", + "timestamp": 1750774427, + "miner_signature": "01ee6027b7388d8e1d543f0df5ed97c8a84898867c1f77405979bfeb70e6ed4b7579e9f134d9b99eba65bf6099b7e6631296cb629ac5520d679f63336dcff4d105", + "signer_signature": [ + "00fb29e01245c97dad8d42b599437b68932b85279dd316a5a0616373e41293a9cf7fe48962252245cc3de8fa8772c2b0b13e014b3a49504eaba333c5577a1b61e6", + "01d5148eb9512e695c32ab9ad08e5057df87e050bcd1fa8c14adb9ae46510663c072c869671a946add8006948d058d8ce8e8405cbe0a615e322a3c5754df61fab5", + "006078e054d9b53a12ac729718be42b073674c07fbd000d557fced6e6a4030339f141c95761e9d15ab9781a85819bce21885fc712e82b771284f5c04fb47a42c36", + "0007432cee54e945eace6b34dc7d55d8fbbefd22f0fbb89e133ecd9005fddefaaf2a8ad6a56d3ff8cb8e1d7db6dbf33e096d4e3b8ed03c4811e264f4686619053f", + "00c207d4709ae3dbd56fdfbb6e719a32332d183fa5bd8cd3dd290e0333d3dffcf115f4b5ca5bad338557601c975ea82f31787351f9ad375058fe5d8232b8b41fd5", + "01daea2a0f838407b2120d6a96c58daa2dbf65af27d4b46e43f467183a4ed46d67387f66acb64c6e9cd41520f006bed6dbd333b5153f501affe7d77b4951029c95", + "003ac14920d3c37669ec185feb4c18789030de1fdcc1d7cec50c8c525120d1266a2928c0d9b820501b61540e349fece714d5fccddc73eab74243bbe0d3d7c70550", + "005a60b091799388a6af8a61d9322323979d296678603500e1113d9fd42379a3a9041ea1bc396fbe47635356dfccaf804b95c42e67db2bdfbc6395a0a9244bdd43", + "0148442563da3fbec0b40b631f6f421091afb03b628b089500e2f9d11d9d1689680d61687fa01f7cce286e55068f600311dea652040693985efeeb4bd4942a0106", + "00094f3caf8a332788dba5e586fc366e1622340e335565b15521d0d6819eca1ffe588caa77d57fdc92fae4eb4800244e723bb845d4eafbc58a35f7ce6e4fb83497", + "007647c92930d4a9517884e3c2a8060315e0e63d011bbcf87f03c47e7b384689a605b3e4a52052e3c34f37987631dcc7ef3ca935f17737e6c0dcee416f2da9c94f", + "016f1ff69b141a0d4aec4c437db2a683c99430594d61cdb3e69f846b8021850bf86906fed631fc0954418a26002dfda3263a4955d2f8ea093a6d6de0008b22e219", + "00a1694159603297b076c90050d784724373bf75bcfaa24d03b68587a98a4ab97267ec95f8ded366e63792880e8f45aeb5b9c752759e080248563e5a035488e188", + "00dbd71a18855f323e6a9dc7a558d2469ea53c0ec7cae20e6e9eccad97c4bd93083a04d4ca3888575f4818037876902fbe79adfecafdee2046d16936f8f3044777", + "008a797e8322470a68a74f4e3d4562d4c3b8c41ab9a50e7a13056e708935c2cf6c03c90a882ba4cb6b720eb41c1f7ced8400b44330dcf245ef44a48e66d7589207", + "007cc0376eceb67c305aa4ca3c1ce90d78462223dbf30b6e5152e44dc827604e480082057df1bac7e2f7b44c10d5d0d26d0b300498eb4d2bad1076b53a55399b33", + "0188d81d2dd3a071a9e4d802ddccdf5469892e69cfa3419acda8405eceaed6eb6d368b16f324ed252ad6364d8027f227fc5946fc498adde55c8f2753c597b6d85f", + "00eb8bbc18b9c07a9f48607b1b04d61673b5db1fad81ffcdc2049bd7f75217369a66d47f2366af006931d0800cf90a048f6722d726403bc876024ec64b4fa04f77", + "00ce98a988c8de55cda5a424cab99cd51a63b426e28f7fd7b6d0c0048bf0a16c7078ef30044e708da87e9a61105c1560aef6f4ed2678602abdf7671795c5812e2b", + "01fa10444944f58aa58fed5f023ae083254b13b579b25f5cbf2c79692bda52da7e4cce4c34bb1105a8cb79e437a35ed71588d0275bb45e541cc534b4102858ffbc", + "00d4bc9429e665b872ff973cbad786d4d5bbac9a68e8d6f4c010ab047c6e67ca3f7a59370b5e141c819235fcf2231ef6b20b3abd6a65e17b8771fafe7b485c3dd7", + "002262beb4bb0c7002f6d94ed4529a98ce186037a7466e8890e8bda6963b8859cd0ecb70a5f03f9fc5ba91d1cf661c1a588882c857dfa9d9334f1ca5979b1d3dd4", + "01bcd2139b34bebce77298c067941255fa433394660dc61f9a8d1cdca0787e8709191fe86e4224a03b2ce36f2b7e15b8ecf79edc9ef46dfac27b1c6bed550b0f47", + "0125f2fe864f413570a5b671b368b161f0ca645433ecc0666c46435a0a5f0ef4123ddad0b013f194b68cb685ac91f2e4fc76b39f09cd7f2af97fc4170fc319b20c", + "00c2460dbde6bd6ee5d02ab58b4180736ec307e1971d9cd98d72b5e5cdd88c654374f6f3939d07076b9d7c51b73c72e946fad918a0654a206bb1ee6fad7baffb99", + "01d4eef757e133bc7caebe505cbdd9443e55827ca9f46981fab6a2b504b33543801d62784103a8ec986fd74f5b486f01790d83eb8294ee972bf79ee8233cf94486", + "018b182276517c5c086ed2908baa5e914946d60124ea2787330dc271f7dd9769de7537f6d93910446b732085aac70c4f3c8b7de68498fe350f115d7ad079f08bef", + "019b5d53ad14817d2723bb263a1df4892e0a381b4673c9c33dffaf07855d3ee4ea540cc1d9ab7e990da5d35e8ab6dffcbac965f0b2b17ec96ea8bcbe7e467297f8", + "0136c976917663b492b0838fad3db0592de1a6237140e5b3e16800569dcb76a85707c32134bcea23ff5b9be6ee9cd2b359f07741d83ed59de3196f49c4b4af2c60", + "008f0d59da1833e60fb30984710882ac6159faf12773aa982bf3482f9519d9dd003d1d3e843e76d48cca90aece2bb44fb504d0bcc9aae0d8fd003aeed53dc4d52c", + "01d77eaf449638d33c92f346c0464aef2a678458f96cd1a4cc1e8b53155b8952b16ff72e1bc942c29deaee40900f8b00ab3c6ba7f0e91700881edbf53ef095ae6b" + ], + "pox_treatment": "0e7d000001d0ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff1f" + } + } + }, + "block-replay.example": { + "summary": "Block replay response", + "value": { + "block_hash": "732f57eefc4dbfb015c9988d9943c47273d25fbe039220d53f311b307609c83f", + "block_id": "856f6b08f338164df7422f66337c8ce916b6b0301fcaa09de06c61cfb79e2a45", + "block_height": 123, + "consensus_hash": "33dffda027e2ca3aaf278855c59a8a0b2d2dd51f", + "fees": 1, + "miner_signature": "004b2878d7639060c4d183b1338447c06ceb0ad55424856c550a4c988401fdf8cf1fe6e8c05cc0e3ff8d4383590bf700cb5dd1a8bb3269f7125f6e0704b66eade8", + "parent_block_id": "3ac36fc1acfc86ba80ea27cd26017c675f75bc07fb042814b72e74cd7d331503", + "signer_signature": [ + "00d4e08331db614d18d7b5af53cf9bc03add9c7a2dcb6f0448721de7ea98f662cf7dc43ee73e14d18dfae3d3d349ff67e0fd773a446fb8c949c93ae4676f4d34bc", + "01619c6e69bad5b43e11bae3eb4d4626e5cf19d595923b0b5d2053e8883a266b41315fdaefd1eca03c5c0580b0f7fd28053c3f34eb0a12220b61392d342f5afb0d", + "0078fa352e0e4d2d94b25d4070ae24a819f268b2260a1e4d0d867415dbdc39e2cf75e57de69375794073e22a75873a5e1ca33ed96eadd8086415e934f697b78fdb", + "00b8d9b0d0cdfabe3c65237801e714185777f60507c773fcd2a72ed00b9d4c59cb5ab96e0e8d545bd562b5ca3de6db1d3b9fccd8f41c3bfa7de3528deb1acd30d6" + ], + "state_index_root": "839b826290027e5b92de415495be7bab2eab2ad4e2f8c371a1a773ae552fedba", + "timestamp": 1758284349, + "transactions": [ + { + "data": { + "anchor_mode": "OnChainOnly", + "auth": { + "Standard": { + "Singlesig": { + "hash_mode": "P2PKH", + "key_encoding": "Compressed", + "nonce": 99, + "signature": "01e29229b386e1f69ffd91e339c878246235ec1cd4771b42a7f45e1ed108643bc9417d43dd96a02c93314ef4cf5bcbcc5642df2e1f5a177333ff983c8719d80661", + "signer": "2965a4e6e4226868fa3ae88b2b9bb9e937d77fba", + "tx_fee": 1 + } + } + }, + "chain_id": 2147483648, + "payload": { + "TokenTransfer": [ + { + "Standard": [ + 26, + [ + 189, + 65, + 200, + 147, + 188, + 192, + 157, + 152, + 224, + 211, + 77, + 255, + 135, + 190, + 175, + 153, + 88, + 51, + 140, + 222 + ] + ] + }, + 1, + "00000000000000000000000000000000000000000000000000000000000000000000" + ] + }, + "post_condition_mode": "Deny", + "post_conditions": [], + "version": "Testnet" + }, + "events": [ + { + "committed": true, + "event_index": 0, + "stx_transfer_event": { + "amount": "1", + "memo": "00000000000000000000000000000000000000000000000000000000000000000000", + "recipient": "ST2YM3J4KQK09V670TD6ZZ1XYNYCNGCWCVTASN5VM", + "sender": "STMPB976WGH6GT7T7BM8PAWVQ7MKFNVZQAXS4BFS" + }, + "txid": "0xf14dd7dec56405fd7dac69c3080fb569fae4c49c591f9ad0e5cf5c797add9005", + "type": "stx_transfer_event" + } + ], + "execution_cost": { + "read_count": 0, + "read_length": 0, + "runtime": 0, + "write_count": 0, + "write_length": 0 + }, + "hex": "808000000004002965a4e6e4226868fa3ae88b2b9bb9e937d77fba000000000000006300000000000000010001e29229b386e1f69ffd91e339c878246235ec1cd4771b42a7f45e1ed108643bc9417d43dd96a02c93314ef4cf5bcbcc5642df2e1f5a177333ff983c8719d8066101020000000000051abd41c893bcc09d98e0d34dff87beaf9958338cde000000000000000100000000000000000000000000000000000000000000000000000000000000000000", + "result_hex": "0x0703", + "post_condition_aborted": false, + "stx_burned": 0, + "tx_index": 0, + "txid": "f14dd7dec56405fd7dac69c3080fb569fae4c49c591f9ad0e5cf5c797add9005", + "vm_error": null, + "profiler": null, + "execution_stats": { + "secs": 0, + "nanos": 123456 + } + } + ], + "tx_merkle_root": "a68e3c76471d9e66b71a14165c4c9a2b980c51efb5b313425cffcef7172d6080", + "valid_merkle_root": true + } + } + }, + "parameters": { + "deployer-address": { + "name": "deployer_address", + "in": "path", + "required": true, + "description": "Standard Stacks address (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0`).\nMust be 28-41 characters long using Stacks c32check format.\n", + "schema": { + "$ref": "#/components/schemas/StandardPrincipal" + } + }, + "contract-name": { + "name": "contract_name", + "in": "path", + "required": true, + "description": "Contract name. Must start with a letter and can contain letters, numbers,\nhyphens, and underscores. Maximum length is 40 characters for new contracts.\nLegacy contracts may have names up to 128 characters.\n", + "schema": { + "type": "string", + "pattern": "^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$", + "minLength": 1, + "maxLength": 128, + "example": "get-info" + } + }, + "tip": { + "name": "tip", + "in": "query", + "schema": { + "type": "string", + "pattern": "^(latest|[0-9a-f]{64})?$", + "maxLength": 64, + "example": "latest" + }, + "description": "Stacks chain tip to query from. Options:\n- (empty/omitted): Use latest anchored tip (canonical confirmed state)\n- `latest`: Use latest known tip including unconfirmed microblocks.\n If no unconfirmed state is available, falls back to the confirmed canonical tip.\n If the unconfirmed state check fails with an error, returns 404.\n- `{block_id}`: Use specific block ID (64 lowercase hex characters)\n\n**Note:** If `tip` is present but contains an invalid or malformed value\n(i.e., not `latest` and not a valid 64-character hex block ID),\nthe node silently falls back to the latest anchored tip (same as omitting `tip`).\n" + }, + "proof": { + "name": "proof", + "in": "query", + "schema": { + "type": "integer", + "enum": [ + 0, + 1 + ], + "default": 1, + "example": 1 + }, + "description": "Controls MARF proof inclusion in response. Set to 1 (default) to include proof, 0 to exclude.\nInvalid values default to 0 (no proof).\n" + }, + "principal": { + "name": "principal", + "in": "path", + "required": true, + "description": "Stacks address (28-41 characters) or a Contract identifier in format `{address}.{contract_name}`\n(e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`).\nContract names have a maximum length of 40 characters for new contracts. Legacy contracts may have names up to 128 characters.\n", + "schema": { + "$ref": "#/components/schemas/Principal" + } + }, + "standard-principal": { + "name": "principal", + "in": "path", + "required": true, + "description": "Standard Stacks address (standard principal, not contract principal).\nMust be 28-41 characters long using Stacks c32check format.\n", + "schema": { + "$ref": "#/components/schemas/StandardPrincipal" + } + } + } + } +} \ No newline at end of file