diff --git a/.github/workflows/stacks-core-tests.yml b/.github/workflows/stacks-core-tests.yml index 05b9f09f62..10dfc7bc60 100644 --- a/.github/workflows/stacks-core-tests.yml +++ b/.github/workflows/stacks-core-tests.yml @@ -61,12 +61,15 @@ jobs: name: OpenAPI Validation runs-on: ubuntu-latest steps: - - name: OpenAPI + - name: Generate OpenAPI documentation id: openapi uses: stacks-network/actions/openapi@main with: - input: ./docs/rpc/openapi.yaml - output: ./open-api-docs.html + input: "./docs/rpc/openapi.yaml" + output: "./openapi-docs.html" + config: "./docs/rpc/redocly.yaml" + validate: "true" + redocly-version: "1.34" ## Disabled ## - this test can take several hours to run diff --git a/docs/rpc/api/contract/post-call-read-only-fn-fail.example.json b/docs/rpc/api/contract/post-call-read-only-fn-fail.example.json deleted file mode 100644 index 9017085887..0000000000 --- a/docs/rpc/api/contract/post-call-read-only-fn-fail.example.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "value": { - "okay": false, - "cause": "Unchecked(PublicFunctionNotReadOnly(..." - } -} diff --git a/docs/rpc/api/contract/post-call-read-only-fn-success.example.json b/docs/rpc/api/contract/post-call-read-only-fn-success.example.json deleted file mode 100644 index c2f5d845f1..0000000000 --- a/docs/rpc/api/contract/post-call-read-only-fn-success.example.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "value": { - "okay": true, - "result": "0x111..." - } -} diff --git a/docs/rpc/api/contract/post-call-read-only-fn.schema.json b/docs/rpc/api/contract/post-call-read-only-fn.schema.json deleted file mode 100644 index 6528681687..0000000000 --- a/docs/rpc/api/contract/post-call-read-only-fn.schema.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "description": "GET request to get contract source", - "title": "ReadOnlyFunctionSuccessResponse", - "type": "object", - "additionalProperties": false, - "required": ["okay"], - "properties": { - "okay": { - "type": "boolean" - }, - "result": { - "type": "string" - }, - "cause": { - "type": "string" - } - } -} diff --git a/docs/rpc/api/core-node/get-account-data.schema.json b/docs/rpc/api/core-node/get-account-data.schema.json deleted file mode 100644 index adddb540cc..0000000000 --- a/docs/rpc/api/core-node/get-account-data.schema.json +++ /dev/null @@ -1,28 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "description": "GET request for account data", - "title": "AccountDataResponse", - "type": "object", - "additionalProperties": false, - "required": ["balance", "locked", "unlock_height", "nonce", "balance_proof", "nonce_proof"], - "properties": { - "balance": { - "type": "string" - }, - "locked": { - "type": "string" - }, - "unlock_height": { - "type": "integer" - }, - "nonce": { - "type": "integer" - }, - "balance_proof": { - "type": "string" - }, - "nonce_proof": { - "type": "string" - } - } -} diff --git a/docs/rpc/api/core-node/get-clarity-marf-value.schema.json b/docs/rpc/api/core-node/get-clarity-marf-value.schema.json deleted file mode 100644 index ea7e7894fb..0000000000 --- a/docs/rpc/api/core-node/get-clarity-marf-value.schema.json +++ /dev/null @@ -1,17 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "description": "Response of get Clarity MARF value request", - "title": "ClarityMARFValueResponse", - "type": "object", - "required": ["data"], - "properties": { - "data": { - "type": "string", - "description": "Hex-encoded string" - }, - "proof": { - "type": "string", - "description": "Hex-encoded string of the MARF proof for the data" - } - } -} diff --git a/docs/rpc/api/core-node/get-clarity-metadata.schema.json b/docs/rpc/api/core-node/get-clarity-metadata.schema.json deleted file mode 100644 index 3c0104fa41..0000000000 --- a/docs/rpc/api/core-node/get-clarity-metadata.schema.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "description": "Response of get clarity metadata request", - "title": "ClarityMetadataResponse", - "type": "object", - "required": ["data"], - "properties": { - "data": { - "type": "string", - "description": "Metadata value formatted as a JSON string" - } - } -} diff --git a/docs/rpc/api/core-node/get-constant-val.example.json b/docs/rpc/api/core-node/get-constant-val.example.json deleted file mode 100644 index aaf12d6246..0000000000 --- a/docs/rpc/api/core-node/get-constant-val.example.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "data": "0x01ce..." -} \ No newline at end of file diff --git a/docs/rpc/api/core-node/get-constant-val.schema.json b/docs/rpc/api/core-node/get-constant-val.schema.json deleted file mode 100644 index 877f1216b2..0000000000 --- a/docs/rpc/api/core-node/get-constant-val.schema.json +++ /dev/null @@ -1,15 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "description": "Response of get constant val request", - "title": "ConstantValResponse", - "type": "object", - "required": [ - "data" - ], - "properties": { - "data": { - "type": "string", - "description": "Hex-encoded string of clarity value." - } - } -} \ No newline at end of file diff --git a/docs/rpc/api/core-node/get-contract-data-map-entry.example.json b/docs/rpc/api/core-node/get-contract-data-map-entry.example.json deleted file mode 100644 index d0e233416f..0000000000 --- a/docs/rpc/api/core-node/get-contract-data-map-entry.example.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "data": "0x0a0c000000010a6d6f6e737465722d69640100000000000000000000000000000001", - "proof": "0x123..." -} diff --git a/docs/rpc/api/core-node/get-contract-data-map-entry.schema.json b/docs/rpc/api/core-node/get-contract-data-map-entry.schema.json deleted file mode 100644 index 04c945eb4f..0000000000 --- a/docs/rpc/api/core-node/get-contract-data-map-entry.schema.json +++ /dev/null @@ -1,17 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "description": "Response of get data map entry request", - "title": "MapEntryResponse", - "type": "object", - "required": ["data"], - "properties": { - "data": { - "type": "string", - "description": "Hex-encoded string of clarity value. It is always an optional tuple." - }, - "proof": { - "type": "string", - "description": "Hex-encoded string of the MARF proof for the data" - } - } -} diff --git a/docs/rpc/api/core-node/get-contract-interface.example.json b/docs/rpc/api/core-node/get-contract-interface.example.json deleted file mode 100644 index 0e7c12bb79..0000000000 --- a/docs/rpc/api/core-node/get-contract-interface.example.json +++ /dev/null @@ -1,134 +0,0 @@ -{ - "functions": [ - { - "name": "get-value", - "access": "public", - "args": [ - { - "name": "key", - "type": { - "buffer": { - "length": 32 - } - } - } - ], - "outputs": { - "type": { - "response": { - "ok": { - "buffer": { - "length": 32 - } - }, - "error": "int128" - } - } - } - }, - { - "name": "set-value", - "access": "public", - "args": [ - { - "name": "key", - "type": { - "buffer": { - "length": 32 - } - } - }, - { - "name": "value", - "type": { - "buffer": { - "length": 32 - } - } - } - ], - "outputs": { - "type": { - "response": { - "ok": "uint128", - "error": "none" - } - } - } - }, - { - "name": "test-emit-event", - "access": "public", - "args": [], - "outputs": { - "type": { - "response": { - "ok": "uint128", - "error": "none" - } - } - } - }, - { - "name": "test-event-types", - "access": "public", - "args": [], - "outputs": { - "type": { - "response": { - "ok": "uint128", - "error": "none" - } - } - } - } - ], - "variables": [ - { - "name": "recipient", - "type": "principal", - "access": "constant" - }, - { - "name": "sender", - "type": "principal", - "access": "constant" - } - ], - "maps": [ - { - "name": "store", - "key": [ - { - "name": "key", - "type": { - "buffer": { - "length": 32 - } - } - } - ], - "value": [ - { - "name": "value", - "type": { - "buffer": { - "length": 32 - } - } - } - ] - } - ], - "fungible_tokens": [ - { - "name": "novel-token-19" - } - ], - "non_fungible_tokens": [ - { - "name": "hello-nft", - "type": "uint128" - } - ] -} diff --git a/docs/rpc/api/core-node/get-contract-interface.schema.json b/docs/rpc/api/core-node/get-contract-interface.schema.json deleted file mode 100644 index b2c580f651..0000000000 --- a/docs/rpc/api/core-node/get-contract-interface.schema.json +++ /dev/null @@ -1,44 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "description": "GET request to get contract interface", - "title": "ContractInterfaceResponse", - "type": "object", - "required": ["functions", "variables", "maps", "fungible_tokens", "non_fungible_tokens"], - "properties": { - "functions": { - "type": "array", - "items": { - "type": "object" - }, - "description": "List of defined methods" - }, - "variables": { - "type": "array", - "items": { - "type": "object" - }, - "description": "List of defined variables" - }, - "maps": { - "type": "array", - "items": { - "type": "object" - }, - "description": "List of defined data-maps" - }, - "fungible_tokens": { - "type": "array", - "items": { - "type": "object" - }, - "description": "List of fungible tokens in the contract" - }, - "non_fungible_tokens": { - "type": "array", - "items": { - "type": "object" - }, - "description": "List of non-fungible tokens in the contract" - } - } -} diff --git a/docs/rpc/api/core-node/get-contract-source.schema.json b/docs/rpc/api/core-node/get-contract-source.schema.json deleted file mode 100644 index fe09af4bf8..0000000000 --- a/docs/rpc/api/core-node/get-contract-source.schema.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "description": "GET request to get contract source", - "title": "ContractSourceResponse", - "type": "object", - "additionalProperties": false, - "required": ["source", "publish_height", "proof"], - "properties": { - "source": { - "type": "string" - }, - "publish_height": { - "type": "integer" - }, - "proof": { - "type": "string" - } - } -} diff --git a/docs/rpc/api/core-node/get-fee-transfer.example.json b/docs/rpc/api/core-node/get-fee-transfer.example.json deleted file mode 100644 index d00491fd7e..0000000000 --- a/docs/rpc/api/core-node/get-fee-transfer.example.json +++ /dev/null @@ -1 +0,0 @@ -1 diff --git a/docs/rpc/api/core-node/get-fee-transfer.schema.json b/docs/rpc/api/core-node/get-fee-transfer.schema.json deleted file mode 100644 index 24d9b98768..0000000000 --- a/docs/rpc/api/core-node/get-fee-transfer.schema.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "description": "GET fee estimates", - "title": "CoreNodeFeeResponse", - "type": "string", - "additionalProperties": false -} diff --git a/docs/rpc/api/core-node/get-health-error.example.json b/docs/rpc/api/core-node/get-health-error.example.json deleted file mode 100644 index 00b510d909..0000000000 --- a/docs/rpc/api/core-node/get-health-error.example.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "error": "No viable bootstrap peers found, unable to determine health" -} \ No newline at end of file diff --git a/docs/rpc/api/core-node/get-health-error.schema.json b/docs/rpc/api/core-node/get-health-error.schema.json deleted file mode 100644 index e8b4437af0..0000000000 --- a/docs/rpc/api/core-node/get-health-error.schema.json +++ /dev/null @@ -1,15 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "description": "Error response when GET request to query node health fails", - "title": "ServerError", - "type": "object", - "additionalProperties": false, - "required": [ - "error" - ], - "properties": { - "error": { - "type": "string" - } - } -} \ No newline at end of file diff --git a/docs/rpc/api/core-node/get-health.schema.json b/docs/rpc/api/core-node/get-health.schema.json deleted file mode 100644 index 3fc62a4429..0000000000 --- a/docs/rpc/api/core-node/get-health.schema.json +++ /dev/null @@ -1,26 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "description": "GET request to query node health", - "title": "GetHealthResponse", - "type": "object", - "additionalProperties": false, - "required": [ - "difference_from_max_peer", - "max_stacks_height_of_neighbors", - "node_stacks_tip_height" - ], - "properties": { - "difference_from_max_peer": { - "type": "integer", - "description": "The difference in height between the node and its most advanced neighbor." - }, - "max_stacks_height_of_neighbors": { - "type": "integer", - "description": "The max Stacks height of the node's most advanced neighbor." - }, - "node_stacks_tip_height": { - "type": "integer", - "description": "The Stacks height of this node." - } - } -} \ No newline at end of file diff --git a/docs/rpc/api/core-node/get-info.example.json b/docs/rpc/api/core-node/get-info.example.json deleted file mode 100644 index 77ece128c3..0000000000 --- a/docs/rpc/api/core-node/get-info.example.json +++ /dev/null @@ -1,17 +0,0 @@ -{ - "peer_version": 385875968, - "pox_consensus": "17f76e597bab45646956f38dd39573085d72cbc0", - "burn_block_height": 16, - "stable_pox_consensus": "8e0561978fc5506b68a589c402dad97e862edb59", - "stable_burn_block_height": 15, - "server_version": "blockstack-core 0.0.1 => 23.0.0.0 (, release build, linux [x86_64])", - "network_id": 2147483648, - "parent_network_id": 3669344250, - "stacks_tip_height": 15, - "stacks_tip": "b1807a2d3f7f8c7922f7c1d60d7c34145ade05d789640dc7dc9ec1021e07bb54", - "stacks_tip_consensus_hash": "17f76e597bab45646956f38dd39573085d72cbc0", - "unanchored_tip": "0000000000000000000000000000000000000000000000000000000000000000", - "tenure_height": 523, - "exit_at_block_height": null, - "is_fully_synced": false -} diff --git a/docs/rpc/api/core-node/get-info.schema.json b/docs/rpc/api/core-node/get-info.schema.json deleted file mode 100644 index e997a2d19c..0000000000 --- a/docs/rpc/api/core-node/get-info.schema.json +++ /dev/null @@ -1,86 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "description": "GET request that core node information", - "title": "CoreNodeInfoResponse", - "type": "object", - "additionalProperties": false, - "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", - "unanchored_tip", - "tenure_height", - "exit_at_block_height", - "is_fully_synced" - ], - "properties": { - "peer_version": { - "type": "integer", - "description": "identifies the version number for the networking communication, this should not change while a node is running, and will only change if there's an upgrade" - }, - "pox_consensus": { - "type": "string", - "description": "is a hash used to identify the burnchain view for a node. it incorporates bitcoin chain information and PoX information. nodes that disagree on this value will appear to each other as forks. this value will change after every block" - }, - "burn_block_height": { - "type": "integer", - "description": "latest bitcoin chain height" - }, - "stable_pox_consensus": { - "type": "string", - "description": "same as burn_consensus, but evaluated at stable_burn_block_height" - }, - "stable_burn_block_height": { - "type": "integer", - "description": "leftover from stacks 1.0, basically always burn_block_height - 1" - }, - "server_version": { - "type": "string", - "description": "is a version descriptor" - }, - "network_id": { - "type": "integer", - "description": "is similar to peer_version and will be used to differentiate between different testnets. this value will be different between mainnet and testnet. once launched, this value will not change" - }, - "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 forks can occur independent of the Bitcoin chain, that height doesn't increase 1-to-1 with the Bitcoin height" - }, - "stacks_tip": { - "type": "string", - "description": "the best known block hash for the Stack chain (not including any pending microblocks)" - }, - "stacks_tip_consensus_hash": { - "type": "string", - "description": "the burn chain (i.e., bitcoin) consensus hash at the time that stacks_tip was mined" - }, - "unanchored_tip": { - "type": "string", - "description": "the latest microblock hash if any microblocks were processed. if no microblock has been processed for the current block, a 000.., hex array is returned" - }, - "tenure_height": { - "type": "integer", - "description": "the latest Stacks tenure height" - }, - "exit_at_block_height": { - "type": "integer", - "description": "the block height at which the testnet network will be reset. not applicable for mainnet" - }, - "is_fully_synced": { - "type": "boolean", - "description": "indicates whether the node has fully synchronized with the network" - } - } -} diff --git a/docs/rpc/api/core-node/get-pox.schema.json b/docs/rpc/api/core-node/get-pox.schema.json deleted file mode 100644 index b0fffacb9d..0000000000 --- a/docs/rpc/api/core-node/get-pox.schema.json +++ /dev/null @@ -1,193 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "description": "Get Proof of Transfer (PoX) information", - "title": "CoreNodePoxResponse", - "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", - "rejection_fraction", - "total_liquid_supply_ustx", - "current_cycle", - "next_cycle", - "reward_cycle_length", - "min_amount_ustx", - "reward_cycle_id", - "prepare_cycle_length", - "rejection_votes_left_required", - "contract_versions" - ], - "properties": { - "contract_id": { - "type": "string", - "description": "The contract identifier for the PoX contract" - }, - "first_burnchain_block_height": { - "type": "integer", - "description": "The first burn block evaluated in this Stacks chain" - }, - "current_burnchain_block_height": { - "type": "integer", - "description": "The latest Bitcoin chain block height" - }, - "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", - "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", - "description": "The length in burn blocks of the reward phase" - }, - "prepare_phase_block_length": { - "type": "integer", - "description": "The length in burn blocks of the prepare phase" - }, - "reward_slots": { - "type": "integer", - "description": "The number of reward slots in a reward cycle" - }, - "total_liquid_supply_ustx": { - "type": "integer", - "description": "The current total amount of liquid microstacks." - }, - "reward_cycle_length": { - "type": "integer", - "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", - "description": "The reward cycle number" - }, - "min_threshold_ustx": { - "type": "integer", - "description": "The threshold amount for obtaining a slot in this reward cycle." - }, - "stacked_ustx": { - "type": "integer", - "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", - "stacked_ustx", - "min_increment_ustx", - "prepare_phase_start_block_height", - "blocks_until_prepare_phase", - "reward_phase_start_block_height", - "blocks_until_reward_phase", - "ustx_until_pox_rejection" - ], - "properties": { - "id": { - "type": "integer", - "description": "The reward cycle number" - }, - "min_threshold_ustx": { - "type": "integer", - "description": "The threshold amount for obtaining a slot in this reward cycle." - }, - "stacked_ustx": { - "type": "integer", - "description": "The total amount of stacked microstacks in this reward cycle." - }, - "min_increment_ustx": { - "type": "integer", - "description": "The minimum amount that can be used to submit a `stack-stx` call." - }, - "prepare_phase_start_block_height": { - "type": "integer", - "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 negative." - }, - "reward_phase_start_block_height": { - "type": "integer", - "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", - "description": "The number of burn blocks until this reward phase starts." - }, - "ustx_until_pox_rejection": { - "type": "integer", - "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", - "deprecated": true, - "description": "The active reward cycle number" - }, - "min_amount_ustx": { - "type": "integer", - "deprecated": true - }, - "prepare_cycle_length": { - "type": "integer", - "deprecated": true - }, - "rejection_votes_left_required": { - "type": "integer", - "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", - "description": "The burn block height at which this version of PoX is activated" - }, - "first_reward_cycle_id": { - "type": "integer", - "description": "The first reward cycle number that uses this version of PoX" - } - } - } - } - } -} diff --git a/docs/rpc/api/core-node/get_sortitions.example.json b/docs/rpc/api/core-node/get_sortitions.example.json deleted file mode 100644 index 571a51beb6..0000000000 --- a/docs/rpc/api/core-node/get_sortitions.example.json +++ /dev/null @@ -1,16 +0,0 @@ -[ - { - "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", - "vrf_seed": "0x48b754acc291a5bfad1354ee19bbc471f14af2b21dc7eccc0f929bd16798defe" - } -] diff --git a/docs/rpc/api/core-node/post-fee-transaction-response.schema.json b/docs/rpc/api/core-node/post-fee-transaction-response.schema.json deleted file mode 100644 index af84276b0b..0000000000 --- a/docs/rpc/api/core-node/post-fee-transaction-response.schema.json +++ /dev/null @@ -1,47 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "description": "POST response for estimated fee", - "title": "TransactionFeeEstimateResponse", - "type": "object", - "additionalProperties": false, - "required": [ - "estimated_cost", - "estimated_cost_scalar", - "cost_scalar_change_by_byte", - "estimations" - ], - "properties": { - "estimated_cost_scalar": { - "type": "integer" - }, - "cost_scalar_change_by_byte": { - "type": "number" - }, - "estimated_cost": { - "type": "object", - "additionalProperties": false, - "required": ["read_count", "write_count", "read_length", "write_length", "runtime"], - "properties": { - "read_count": { "type": "integer" }, - "read_length": { "type": "integer" }, - "runtime": { "type": "integer" }, - "write_count": { "type": "integer" }, - "write_length": { "type": "integer" } - } - }, - "estimations": { - "type": "array", - "items": { - "type": "object", - "properties": { - "fee_rate": { - "type": "number" - }, - "fee": { - "type": "number" - } - } - } - } - } -} diff --git a/docs/rpc/api/core-node/post-fee-transaction.schema.json b/docs/rpc/api/core-node/post-fee-transaction.schema.json deleted file mode 100644 index ce7e47198d..0000000000 --- a/docs/rpc/api/core-node/post-fee-transaction.schema.json +++ /dev/null @@ -1,16 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "description": "POST request for estimated fee", - "title": "TransactionFeeEstimateRequest", - "type": "object", - "additionalProperties": false, - "required": ["transaction_payload"], - "properties": { - "transaction_payload": { - "type": "string" - }, - "estimated_len": { - "type": "integer" - } - } -} diff --git a/docs/rpc/api/trait/get-is-trait-implemented.schema.json b/docs/rpc/api/trait/get-is-trait-implemented.schema.json deleted file mode 100644 index 30cb3fa486..0000000000 --- a/docs/rpc/api/trait/get-is-trait-implemented.schema.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "description": "GET request to get trait implementation information", - "title": "IsTraitImplementedSuccessResponse", - "type": "object", - "additionalProperties": false, - "required": ["is_implemented"], - "properties": { - "is_implemented": { - "type": "boolean" - } - } -} diff --git a/docs/rpc/api/transaction/post-core-node-transactions-error.schema.json b/docs/rpc/api/transaction/post-core-node-transactions-error.schema.json deleted file mode 100644 index ca36fd40ac..0000000000 --- a/docs/rpc/api/transaction/post-core-node-transactions-error.schema.json +++ /dev/null @@ -1,25 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "description": "GET request that returns transactions", - "title": "PostCoreNodeTransactionsError", - "type": "object", - "required": ["error", "reason", "reason_data", "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" - }, - "txid": { - "type": "string", - "description": "The relevant transaction id" - } - } -} diff --git a/docs/rpc/api/core-node/get-account-data.example.json b/docs/rpc/components/examples/account-data.example.json similarity index 100% rename from docs/rpc/api/core-node/get-account-data.example.json rename to docs/rpc/components/examples/account-data.example.json diff --git a/docs/rpc/api/core-node/get-clarity-marf-value.example.json b/docs/rpc/components/examples/clarity-data.example.json similarity index 52% rename from docs/rpc/api/core-node/get-clarity-marf-value.example.json rename to docs/rpc/components/examples/clarity-data.example.json index d0e233416f..cf54898ab0 100644 --- a/docs/rpc/api/core-node/get-clarity-marf-value.example.json +++ b/docs/rpc/components/examples/clarity-data.example.json @@ -1,4 +1,4 @@ { "data": "0x0a0c000000010a6d6f6e737465722d69640100000000000000000000000000000001", - "proof": "0x123..." + "proof": "0x123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" } diff --git a/docs/rpc/api/core-node/get-clarity-metadata.example.json b/docs/rpc/components/examples/clarity-metadata.example.json similarity index 100% rename from docs/rpc/api/core-node/get-clarity-metadata.example.json rename to docs/rpc/components/examples/clarity-metadata.example.json diff --git a/docs/rpc/components/examples/constant-value.example.json b/docs/rpc/components/examples/constant-value.example.json new file mode 100644 index 0000000000..4c188b2a15 --- /dev/null +++ b/docs/rpc/components/examples/constant-value.example.json @@ -0,0 +1,3 @@ +{ + "data": "0x01ce0123456789abcdef" +} diff --git a/docs/rpc/components/examples/contract-interface.example.json b/docs/rpc/components/examples/contract-interface.example.json new file mode 100644 index 0000000000..729f1e6335 --- /dev/null +++ b/docs/rpc/components/examples/contract-interface.example.json @@ -0,0 +1,659 @@ +{ + "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" +} diff --git a/docs/rpc/api/core-node/get-contract-source.example.json b/docs/rpc/components/examples/contract-source.example.json similarity index 96% rename from docs/rpc/api/core-node/get-contract-source.example.json rename to docs/rpc/components/examples/contract-source.example.json index b770b5005d..97a3f819b9 100644 --- a/docs/rpc/api/core-node/get-contract-source.example.json +++ b/docs/rpc/components/examples/contract-source.example.json @@ -1,5 +1,5 @@ { "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": "0000001104060000001ec4e..." + "proof": "0x000000110406000000123456789abcdef" } diff --git a/docs/rpc/api/core-node/post-fee-transaction.example.json b/docs/rpc/components/examples/fee-transaction-request.example.json similarity index 100% rename from docs/rpc/api/core-node/post-fee-transaction.example.json rename to docs/rpc/components/examples/fee-transaction-request.example.json diff --git a/docs/rpc/api/core-node/post-fee-transaction-response.example.json b/docs/rpc/components/examples/fee-transaction-response.example.json similarity index 100% rename from docs/rpc/api/core-node/post-fee-transaction-response.example.json rename to docs/rpc/components/examples/fee-transaction-response.example.json diff --git a/docs/rpc/api/core-node/get_sortitions_latest_and_prior.example.json b/docs/rpc/components/examples/get-sortitions-latest-and-prior.example.json similarity index 100% rename from docs/rpc/api/core-node/get_sortitions_latest_and_prior.example.json rename to docs/rpc/components/examples/get-sortitions-latest-and-prior.example.json diff --git a/docs/rpc/components/examples/get-sortitions.example.json b/docs/rpc/components/examples/get-sortitions.example.json new file mode 100644 index 0000000000..7fcc0cff7b --- /dev/null +++ b/docs/rpc/components/examples/get-sortitions.example.json @@ -0,0 +1,16 @@ +[ + { + "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" + } +] diff --git a/docs/rpc/api/core-node/get_stacker_set.400.example.json b/docs/rpc/components/examples/get-stacker-set-400.example.json similarity index 80% rename from docs/rpc/api/core-node/get_stacker_set.400.example.json rename to docs/rpc/components/examples/get-stacker-set-400.example.json index 263129a1c6..6650f7b771 100644 --- a/docs/rpc/api/core-node/get_stacker_set.400.example.json +++ b/docs/rpc/components/examples/get-stacker-set-400.example.json @@ -1,4 +1,5 @@ { "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" } diff --git a/docs/rpc/api/core-node/get_stacker_set.example.json b/docs/rpc/components/examples/get-stacker-set.example.json similarity index 87% rename from docs/rpc/api/core-node/get_stacker_set.example.json rename to docs/rpc/components/examples/get-stacker-set.example.json index 1bcd3fad59..322fa4225f 100644 --- a/docs/rpc/api/core-node/get_stacker_set.example.json +++ b/docs/rpc/components/examples/get-stacker-set.example.json @@ -14,12 +14,13 @@ "signers": [ { "signing_key": "02d0a27e4f1bf186b4391eecfcc4d4a0d403684ad089b477b8548a69dd6378bf26", - "slots": 1, + "weight": 1, "stacked_amt": 2143020000000000 } ], "start_cycle_state": { "missed_reward_slots": [] - } + }, + "pox_ustx_threshold": 110000000000 } } diff --git a/docs/rpc/api/core-node/get_tenure_info.json b/docs/rpc/components/examples/get-tenure-info.example.json similarity index 100% rename from docs/rpc/api/core-node/get_tenure_info.json rename to docs/rpc/components/examples/get-tenure-info.example.json diff --git a/docs/rpc/components/examples/get-tenure-tip.example.json b/docs/rpc/components/examples/get-tenure-tip.example.json new file mode 100644 index 0000000000..453de45409 --- /dev/null +++ b/docs/rpc/components/examples/get-tenure-tip.example.json @@ -0,0 +1,47 @@ +{ + "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" + } +} diff --git a/docs/rpc/api/core-node/get_transaction.json b/docs/rpc/components/examples/get-transaction.example.json similarity index 99% rename from docs/rpc/api/core-node/get_transaction.json rename to docs/rpc/components/examples/get-transaction.example.json index e5add75b23..7520a8f9a7 100644 --- a/docs/rpc/api/core-node/get_transaction.json +++ b/docs/rpc/components/examples/get-transaction.example.json @@ -2,4 +2,4 @@ "index_block_hash": "e0b6c25b1dac0c0e1c75e41ab46bd6d70d9a2d02ffed8f2c0733b6e686289c38", "result": "(ok true)", "tx": "808000000004008bc5147525b8f477f0bc4522a88c8339b2494db5000000000000001a0000000000000000010123eab800bc9f639c5aa05d154148a981c89fd21064a6f8cafd8649800a56c9ea77e2e46bed8bd9ef0f173b19b20d6c43e2a9f37b078df5c74b9e6f9be75b650e01020000000007588687edeb02248d402c316ed33e22ea0e73af8703ce5011f3e25f5ce12f00f903ca504742117ee0588687edeb02248d402c316ed33e22ea0e73af87c54e0d94e4dd298cf19778352906a2fcf0af74582b07dfb57c710288874f71ca00000001006bc51b33e9f3626944eb879147e18111581f8f9b" -} \ No newline at end of file +} diff --git a/docs/rpc/api/trait/get-is-trait-implemented.example.json b/docs/rpc/components/examples/is-trait-implemented.example.json similarity index 100% rename from docs/rpc/api/trait/get-is-trait-implemented.example.json rename to docs/rpc/components/examples/is-trait-implemented.example.json diff --git a/docs/rpc/components/examples/network-peers.example.json b/docs/rpc/components/examples/network-peers.example.json new file mode 100644 index 0000000000..b258fdf48f --- /dev/null +++ b/docs/rpc/components/examples/network-peers.example.json @@ -0,0 +1,54 @@ +{ + "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 + } + ] +} diff --git a/docs/rpc/api/core-node/get-health.example.json b/docs/rpc/components/examples/node-health.example.json similarity index 98% rename from docs/rpc/api/core-node/get-health.example.json rename to docs/rpc/components/examples/node-health.example.json index 86e85d1a06..472b1e383c 100644 --- a/docs/rpc/api/core-node/get-health.example.json +++ b/docs/rpc/components/examples/node-health.example.json @@ -2,4 +2,4 @@ "difference_from_max_peer": 0, "max_stacks_height_of_neighbors": 12345, "node_stacks_tip_height": 12345 -} \ No newline at end of file +} diff --git a/docs/rpc/components/examples/node-info.example.json b/docs/rpc/components/examples/node-info.example.json new file mode 100644 index 0000000000..9cb48475b9 --- /dev/null +++ b/docs/rpc/components/examples/node-info.example.json @@ -0,0 +1,31 @@ +{ + "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", + "affirmations": { + "heaviest": "", + "stacks_tip": "", + "sortition_tip": "", + "tentative_best": "" + }, + "last_pox_anchor": { + "anchor_block_hash": "47c20352492e1647127d6f6275fa5abfe90157f6a64e6a175ff45ed0c1fb3f4e", + "anchor_block_txid": "5b5d678c658525122fa73a8699b5810325ce9412bf0dc3762fb7518699be3d4d" + }, + "stackerdbs": [] +} diff --git a/docs/rpc/api/core-node/post-block-proposal-req.example.json b/docs/rpc/components/examples/post-block-proposal-request.example.json similarity index 100% rename from docs/rpc/api/core-node/post-block-proposal-req.example.json rename to docs/rpc/components/examples/post-block-proposal-request.example.json diff --git a/docs/rpc/api/core-node/post-block-proposal-response.429.json b/docs/rpc/components/examples/post-block-proposal-response.429.example.json similarity index 100% rename from docs/rpc/api/core-node/post-block-proposal-response.429.json rename to docs/rpc/components/examples/post-block-proposal-response.429.example.json diff --git a/docs/rpc/api/core-node/post-block-proposal-response.example.json b/docs/rpc/components/examples/post-block-proposal-response.example.json similarity index 97% rename from docs/rpc/api/core-node/post-block-proposal-response.example.json rename to docs/rpc/components/examples/post-block-proposal-response.example.json index b2f9c8e518..d74c45eb51 100644 --- a/docs/rpc/api/core-node/post-block-proposal-response.example.json +++ b/docs/rpc/components/examples/post-block-proposal-response.example.json @@ -1,4 +1,4 @@ { "message": "Block proposal is processing, result will be returned via the event observer", "result": "Accepted" -} +} diff --git a/docs/rpc/api/core-node/get-pox.example.json b/docs/rpc/components/examples/pox-info.example.json similarity index 68% rename from docs/rpc/api/core-node/get-pox.example.json rename to docs/rpc/components/examples/pox-info.example.json index 2f88154816..1659052c82 100644 --- a/docs/rpc/api/core-node/get-pox.example.json +++ b/docs/rpc/components/examples/pox-info.example.json @@ -42,5 +42,33 @@ "activation_burnchain_block_height": 712345, "first_reward_cycle_id": 123 } - ] + ], + "epochs": [ + { + "epoch_id": "Epoch0", + "start_height": 0, + "end_height": 200000, + "block_limit": { + "read_count": 15000, + "read_length": 100000000, + "write_count": 15000, + "write_length": 15000000, + "runtime": 5000000000 + }, + "network_epoch": 0 + }, + { + "epoch_id": "Epoch1", + "start_height": 200000, + "end_height": 300000, + "block_limit": { + "read_count": 15000, + "read_length": 100000000, + "write_count": 15000, + "write_length": 15000000, + "runtime": 5000000000 + }, + "network_epoch": 1 + } + ] } diff --git a/docs/rpc/components/examples/read-only-function-failure.example.json b/docs/rpc/components/examples/read-only-function-failure.example.json new file mode 100644 index 0000000000..43f998d0af --- /dev/null +++ b/docs/rpc/components/examples/read-only-function-failure.example.json @@ -0,0 +1,4 @@ +{ + "okay": false, + "cause": "NotReadOnly" +} diff --git a/docs/rpc/components/examples/read-only-function-success.example.json b/docs/rpc/components/examples/read-only-function-success.example.json new file mode 100644 index 0000000000..0aef730e37 --- /dev/null +++ b/docs/rpc/components/examples/read-only-function-success.example.json @@ -0,0 +1,4 @@ +{ + "okay": true, + "result": "0x0100000000000000000000000000000001" +} diff --git a/docs/rpc/components/examples/stackerdb-chunk-ack-failure.example.json b/docs/rpc/components/examples/stackerdb-chunk-ack-failure.example.json new file mode 100644 index 0000000000..5d6e97ed30 --- /dev/null +++ b/docs/rpc/components/examples/stackerdb-chunk-ack-failure.example.json @@ -0,0 +1,11 @@ +{ + "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 +} diff --git a/docs/rpc/components/examples/stackerdb-chunk-ack-success.example.json b/docs/rpc/components/examples/stackerdb-chunk-ack-success.example.json new file mode 100644 index 0000000000..b63934f64b --- /dev/null +++ b/docs/rpc/components/examples/stackerdb-chunk-ack-success.example.json @@ -0,0 +1,11 @@ +{ + "accepted": true, + "reason": null, + "metadata": { + "slot_id": 1, + "slot_version": 2, + "data_hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", + "signature": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef01" + }, + "code": null +} diff --git a/docs/rpc/components/examples/stackerdb-chunk-data-request.example.json b/docs/rpc/components/examples/stackerdb-chunk-data-request.example.json new file mode 100644 index 0000000000..b5de8f43b1 --- /dev/null +++ b/docs/rpc/components/examples/stackerdb-chunk-data-request.example.json @@ -0,0 +1,6 @@ +{ + "slot_id": 1, + "slot_version": 2, + "sig": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef01", + "data": "deadbeefcafebabe" +} diff --git a/docs/rpc/api/transaction/post-core-node-transactions-error.example.json b/docs/rpc/components/examples/transaction-submission-error.example.json similarity index 100% rename from docs/rpc/api/transaction/post-core-node-transactions-error.example.json rename to docs/rpc/components/examples/transaction-submission-error.example.json diff --git a/docs/rpc/components/parameters/contract-address.yaml b/docs/rpc/components/parameters/contract-address.yaml new file mode 100644 index 0000000000..abe6462fe8 --- /dev/null +++ b/docs/rpc/components/parameters/contract-address.yaml @@ -0,0 +1,12 @@ +name: contract_address +in: path +required: true +description: | + Standard Stacks address (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0`). + Must be 28-41 characters long using Stacks base58check format. +schema: + type: string + pattern: "^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$" + minLength: 28 + maxLength: 41 + example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0 diff --git a/docs/rpc/components/parameters/contract-name.yaml b/docs/rpc/components/parameters/contract-name.yaml new file mode 100644 index 0000000000..58353c1a6e --- /dev/null +++ b/docs/rpc/components/parameters/contract-name.yaml @@ -0,0 +1,13 @@ +name: contract_name +in: path +required: true +description: | + Contract name. Must start with a letter and can contain letters, numbers, + hyphens, and underscores. Maximum length is 40 characters for new contracts. + Legacy contracts may have names up to 128 characters. +schema: + type: string + pattern: "^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$" + minLength: 1 + maxLength: 128 + example: get-info diff --git a/docs/rpc/components/parameters/principal.yaml b/docs/rpc/components/parameters/principal.yaml new file mode 100644 index 0000000000..fa0e4d7592 --- /dev/null +++ b/docs/rpc/components/parameters/principal.yaml @@ -0,0 +1,13 @@ +name: principal +in: path +required: true +description: | + Stacks address (28-41 characters) or a Contract identifier in format `{address}.{contract_name}` + (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`). + Contract names have a maximum length of 40 characters for new contracts. Legacy contracts may have names up to 128 characters. +schema: + type: string + pattern: "^([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41})|([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})$" + minLength: 28 + maxLength: 170 + example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info diff --git a/docs/rpc/components/parameters/proof.yaml b/docs/rpc/components/parameters/proof.yaml new file mode 100644 index 0000000000..59e66f7e8f --- /dev/null +++ b/docs/rpc/components/parameters/proof.yaml @@ -0,0 +1,12 @@ +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. + Invalid values default to 0 (no proof). diff --git a/docs/rpc/components/parameters/tip.yaml b/docs/rpc/components/parameters/tip.yaml new file mode 100644 index 0000000000..d6a53a0613 --- /dev/null +++ b/docs/rpc/components/parameters/tip.yaml @@ -0,0 +1,12 @@ +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: + - (empty/omitted): Use latest anchored tip (canonical confirmed state) + - `latest`: Use latest known tip including unconfirmed microblocks + - `{block_id}`: Use specific block ID (64 hex characters) diff --git a/docs/rpc/components/schemas/account-data.schema.yaml b/docs/rpc/components/schemas/account-data.schema.yaml new file mode 100644 index 0000000000..adb1cc67c6 --- /dev/null +++ b/docs/rpc/components/schemas/account-data.schema.yaml @@ -0,0 +1,27 @@ +description: GET request for account data +type: object +additionalProperties: false +required: + - balance + - locked + - unlock_height + - nonce +properties: + balance: + type: string + locked: + type: string + unlock_height: + type: integer + minimum: 0 + description: Block height when locked balance unlocks (64-bit unsigned integer) + 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 diff --git a/docs/rpc/components/schemas/attachment-data.schema.yaml b/docs/rpc/components/schemas/attachment-data.schema.yaml new file mode 100644 index 0000000000..b3a4c91187 --- /dev/null +++ b/docs/rpc/components/schemas/attachment-data.schema.yaml @@ -0,0 +1,8 @@ +type: object +properties: + attachment: + type: string + format: byte + description: The attachment data, hex-encoded. +required: + - attachment diff --git a/docs/rpc/components/schemas/attachment-inventory.schema.yaml b/docs/rpc/components/schemas/attachment-inventory.schema.yaml new file mode 100644 index 0000000000..55ef0a31dd --- /dev/null +++ b/docs/rpc/components/schemas/attachment-inventory.schema.yaml @@ -0,0 +1,20 @@ +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 diff --git a/docs/rpc/components/schemas/block-headers.schema.yaml b/docs/rpc/components/schemas/block-headers.schema.yaml new file mode 100644 index 0000000000..da22869fbc --- /dev/null +++ b/docs/rpc/components/schemas/block-headers.schema.yaml @@ -0,0 +1,22 @@ +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 diff --git a/docs/rpc/components/schemas/block-proposal.schema.yaml b/docs/rpc/components/schemas/block-proposal.schema.yaml new file mode 100644 index 0000000000..8700663832 --- /dev/null +++ b/docs/rpc/components/schemas/block-proposal.schema.yaml @@ -0,0 +1,13 @@ +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. diff --git a/docs/rpc/components/schemas/block-upload-response.schema.yaml b/docs/rpc/components/schemas/block-upload-response.schema.yaml new file mode 100644 index 0000000000..d4529ce936 --- /dev/null +++ b/docs/rpc/components/schemas/block-upload-response.schema.yaml @@ -0,0 +1,8 @@ +type: object +properties: + stacks_block_id: + type: string + description: The ID of the uploaded block + accepted: + type: boolean + description: Whether the block was accepted diff --git a/docs/rpc/components/schemas/clarity-data.schema.yaml b/docs/rpc/components/schemas/clarity-data.schema.yaml new file mode 100644 index 0000000000..53082adfb0 --- /dev/null +++ b/docs/rpc/components/schemas/clarity-data.schema.yaml @@ -0,0 +1,13 @@ +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 + pattern: "^0x[0-9a-f]+$" diff --git a/docs/rpc/components/schemas/clarity-metadata.schema.yaml b/docs/rpc/components/schemas/clarity-metadata.schema.yaml new file mode 100644 index 0000000000..bff2b29f88 --- /dev/null +++ b/docs/rpc/components/schemas/clarity-metadata.schema.yaml @@ -0,0 +1,8 @@ +description: Response of get clarity metadata request +type: object +required: + - data +properties: + data: + type: string + description: Metadata value diff --git a/docs/rpc/components/schemas/clarity-name.schema.yaml b/docs/rpc/components/schemas/clarity-name.schema.yaml new file mode 100644 index 0000000000..e4dc469e40 --- /dev/null +++ b/docs/rpc/components/schemas/clarity-name.schema.yaml @@ -0,0 +1,4 @@ +type: string +pattern: "^([a-zA-Z0-9_]|[-!?+<>=/*]){1,128}$" +minLength: 1 +maxLength: 128 diff --git a/docs/rpc/components/schemas/constant-value.schema.yaml b/docs/rpc/components/schemas/constant-value.schema.yaml new file mode 100644 index 0000000000..1f80cfa092 --- /dev/null +++ b/docs/rpc/components/schemas/constant-value.schema.yaml @@ -0,0 +1,9 @@ +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]+$" diff --git a/docs/rpc/components/schemas/contract-interface.schema.yaml b/docs/rpc/components/schemas/contract-interface.schema.yaml new file mode 100644 index 0000000000..a3179f8323 --- /dev/null +++ b/docs/rpc/components/schemas/contract-interface.schema.yaml @@ -0,0 +1,200 @@ +description: The interface of a Clarity smart contract. +type: object +required: + - functions + - variables + - maps + - fungible_tokens + - non_fungible_tokens + - epoch + - clarity_version + +$defs: + 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 (e.g., 'int', 'uint', 'bool', 'principal')" + - type: object + description: "List type" + required: + - list + properties: + list: + type: object + required: + - type + properties: + type: + $ref: "#/$defs/ClarityType" + description: "Type of list elements" + length: + type: integer + description: "Fixed length for list types" + - 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: "#/$defs/ClarityType" + description: "Type of the tuple field" + - type: object + description: "Response type" + required: + - response + properties: + response: + type: object + required: + - ok + - error + properties: + ok: + $ref: "#/$defs/ClarityType" + description: "Success type" + error: + $ref: "#/$defs/ClarityType" + description: "Error type" + - type: object + description: "Optional type" + required: + - optional + properties: + optional: + $ref: "#/$defs/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)" + +properties: + functions: + type: array + description: List of defined methods + items: + type: object + required: [name, access, args, outputs] + properties: + name: + type: string + access: + type: string + enum: [public, private, read_only] + args: + type: array + items: + type: object + required: [name, type] + properties: + name: + type: string + type: + $ref: "#/$defs/ClarityType" + outputs: + type: object + required: [type] + properties: + type: + $ref: "#/$defs/ClarityType" + variables: + type: array + description: List of defined constants + items: + type: object + required: [name, type, access] + properties: + name: + type: string + type: + $ref: "#/$defs/ClarityType" + access: + type: string + 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: "#/$defs/ClarityType" + value: + $ref: "#/$defs/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: "#/$defs/ClarityType" + epoch: + type: string + description: Stacks epoch identifier (e.g., "Epoch30"). + clarity_version: + type: string + description: Clarity language version used by this contract. + enum: [Clarity1, Clarity2, Clarity3] diff --git a/docs/rpc/components/schemas/contract-source.schema.yaml b/docs/rpc/components/schemas/contract-source.schema.yaml new file mode 100644 index 0000000000..499db0a124 --- /dev/null +++ b/docs/rpc/components/schemas/contract-source.schema.yaml @@ -0,0 +1,17 @@ +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]+$" diff --git a/docs/rpc/components/schemas/fee-transaction-error.schema.yaml b/docs/rpc/components/schemas/fee-transaction-error.schema.yaml new file mode 100644 index 0000000000..3a77f6077f --- /dev/null +++ b/docs/rpc/components/schemas/fee-transaction-error.schema.yaml @@ -0,0 +1,28 @@ +type: object +description: | + Returned when the node cannot calculate a fee estimate. +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`. + For the current implementation it contains a `message` field, + but additional fields may be added in future. + properties: + message: + type: string + example: "SQLite error: table fees does not exist" + additionalProperties: true diff --git a/docs/rpc/components/schemas/fee-transaction-request.schema.yaml b/docs/rpc/components/schemas/fee-transaction-request.schema.yaml new file mode 100644 index 0000000000..7c60f3f14b --- /dev/null +++ b/docs/rpc/components/schemas/fee-transaction-request.schema.yaml @@ -0,0 +1,10 @@ +description: POST request for estimated fee +type: object +additionalProperties: false +required: +- transaction_payload +properties: + transaction_payload: + type: string + estimated_len: + type: integer diff --git a/docs/rpc/components/schemas/fee-transaction-response.schema.yaml b/docs/rpc/components/schemas/fee-transaction-response.schema.yaml new file mode 100644 index 0000000000..f0693c60d9 --- /dev/null +++ b/docs/rpc/components/schemas/fee-transaction-response.schema.yaml @@ -0,0 +1,51 @@ +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: + 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 + 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 diff --git a/docs/rpc/components/schemas/get-health.schema.yaml b/docs/rpc/components/schemas/get-health.schema.yaml new file mode 100644 index 0000000000..259a2cc280 --- /dev/null +++ b/docs/rpc/components/schemas/get-health.schema.yaml @@ -0,0 +1,19 @@ +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 +description: Health information about the node's synchronization status diff --git a/docs/rpc/components/schemas/get-stacker-set.schema.yaml b/docs/rpc/components/schemas/get-stacker-set.schema.yaml new file mode 100644 index 0000000000..0da8c182de --- /dev/null +++ b/docs/rpc/components/schemas/get-stacker-set.schema.yaml @@ -0,0 +1,59 @@ +type: object +properties: + stacker_set: + type: object + required: + - rewarded_addresses + - start_cycle_state + properties: + 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 PoX-4 reward cycles. + 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) diff --git a/docs/rpc/components/schemas/get-transaction.schema.yaml b/docs/rpc/components/schemas/get-transaction.schema.yaml new file mode 100644 index 0000000000..3e30e6a24e --- /dev/null +++ b/docs/rpc/components/schemas/get-transaction.schema.yaml @@ -0,0 +1,16 @@ +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) diff --git a/docs/rpc/components/schemas/is-trait-implemented.schema.yaml b/docs/rpc/components/schemas/is-trait-implemented.schema.yaml new file mode 100644 index 0000000000..5faaed009a --- /dev/null +++ b/docs/rpc/components/schemas/is-trait-implemented.schema.yaml @@ -0,0 +1,8 @@ +description: GET request to get trait implementation information +type: object +additionalProperties: false +required: +- is_implemented +properties: + is_implemented: + type: boolean diff --git a/docs/rpc/components/schemas/network-peers.schema.yaml b/docs/rpc/components/schemas/network-peers.schema.yaml new file mode 100644 index 0000000000..e5dd78c52d --- /dev/null +++ b/docs/rpc/components/schemas/network-peers.schema.yaml @@ -0,0 +1,71 @@ +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: '#/$defs/RPCNeighbor' + sample: + type: array + description: List of a sample of gossiped peers. + items: + $ref: '#/$defs/RPCNeighbor' + inbound: + type: array + description: List of inbound peer connections. + items: + $ref: '#/$defs/RPCNeighbor' + outbound: + type: array + description: List of outbound peer connections. + items: + $ref: '#/$defs/RPCNeighbor' + +$defs: + 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. diff --git a/docs/rpc/components/schemas/node-info.schema.yaml b/docs/rpc/components/schemas/node-info.schema.yaml new file mode 100644 index 0000000000..1abd48d3de --- /dev/null +++ b/docs/rpc/components/schemas/node-info.schema.yaml @@ -0,0 +1,116 @@ +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 +properties: + peer_version: + type: integer + description: | + Identifies the version number for the networking communication. This + should not change while a node is running, and will only change if there's an + upgrade. + pox_consensus: + type: string + description: | + A hash used to identify the burnchain view for a node. It incorporates + bitcoin chain information and PoX information. Nodes that disagree on this value + will appear to each other as forks. This value changes after every block. + 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. + Leftover from stacks 1.0, basically always burn_block_height - 1. + 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 + microblock has been processed for the current block, a 000.., hex array is + returned. + 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. + Not applicable to mainnet. + 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. + affirmations: + type: [object, "null"] + properties: + heaviest: + type: string + description: Encoded affirmation map string. + stacks_tip: + type: string + description: Encoded affirmation map string. + sortition_tip: + type: string + description: Encoded affirmation map string. + tentative_best: + type: string + description: Encoded affirmation map string. + last_pox_anchor: + type: [object, "null"] + properties: + anchor_block_hash: + type: string + anchor_block_txid: + type: string + stackerdbs: + type: [array, "null"] + items: + type: string diff --git a/docs/rpc/components/schemas/pox-info.schema.yaml b/docs/rpc/components/schemas/pox-info.schema.yaml new file mode 100644 index 0000000000..0d72158f82 --- /dev/null +++ b/docs/rpc/components/schemas/pox-info.schema.yaml @@ -0,0 +1,234 @@ +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 +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 + 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 + minimum: 0 + 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 + 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: + type: object + required: + - read_count + - read_length + - write_count + - write_length + - runtime + properties: + read_count: + type: integer + minimum: 0 + read_length: + type: integer + minimum: 0 + write_count: + type: integer + minimum: 0 + write_length: + type: integer + minimum: 0 + runtime: + type: integer + minimum: 0 + network_epoch: + type: integer + minimum: 0 diff --git a/docs/rpc/components/schemas/read-only-function-args.schema.yaml b/docs/rpc/components/schemas/read-only-function-args.schema.yaml new file mode 100644 index 0000000000..d72cdea84b --- /dev/null +++ b/docs/rpc/components/schemas/read-only-function-args.schema.yaml @@ -0,0 +1,17 @@ +description: Describes representation of a Type-0 Stacks 2.0 transaction. https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#type-0-transferring-an-asset +type: object +required: + - sender + - arguments +properties: + sender: + type: string + description: The simulated tx-sender + sponsor: + type: string + description: The simulated sponsor address + arguments: + type: array + description: An array of hex serialized Clarity values + items: + type: string diff --git a/docs/rpc/components/schemas/read-only-function-result.schema.yaml b/docs/rpc/components/schemas/read-only-function-result.schema.yaml new file mode 100644 index 0000000000..890a90e305 --- /dev/null +++ b/docs/rpc/components/schemas/read-only-function-result.schema.yaml @@ -0,0 +1,26 @@ +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. diff --git a/docs/rpc/components/schemas/signer-blocks-signed.schema.yaml b/docs/rpc/components/schemas/signer-blocks-signed.schema.yaml new file mode 100644 index 0000000000..7c444d860d --- /dev/null +++ b/docs/rpc/components/schemas/signer-blocks-signed.schema.yaml @@ -0,0 +1,7 @@ +type: object +properties: + blocks_signed: + type: integer + description: Number of blocks signed by this signer +required: + - blocks_signed diff --git a/docs/rpc/components/schemas/sortitions.schema.yaml b/docs/rpc/components/schemas/sortitions.schema.yaml new file mode 100644 index 0000000000..4f7cbe8a55 --- /dev/null +++ b/docs/rpc/components/schemas/sortitions.schema.yaml @@ -0,0 +1,79 @@ +description: Array of sortition information objects from the burnchain +type: array + +$defs: + 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). This will also be true if this + sortition corresponds to a shadow block. + 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 + +items: + $ref: '#/$defs/Sortition' diff --git a/docs/rpc/components/schemas/stackerdb-chunk-ack-data.schema.yaml b/docs/rpc/components/schemas/stackerdb-chunk-ack-data.schema.yaml new file mode 100644 index 0000000000..c990b50141 --- /dev/null +++ b/docs/rpc/components/schemas/stackerdb-chunk-ack-data.schema.yaml @@ -0,0 +1,33 @@ +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) diff --git a/docs/rpc/components/schemas/stackerdb-chunk-data.schema.yaml b/docs/rpc/components/schemas/stackerdb-chunk-data.schema.yaml new file mode 100644 index 0000000000..f31cafbb7e --- /dev/null +++ b/docs/rpc/components/schemas/stackerdb-chunk-data.schema.yaml @@ -0,0 +1,23 @@ +type: object +required: + - slot_id + - slot_version + - sig + - data +properties: + slot_id: + type: integer + minimum: 0 + description: Slot identifier + slot_version: + type: integer + minimum: 0 + description: Slot version (lamport clock) + sig: + type: string + description: Hex-encoded signature from the stacker + pattern: "^[0-9a-f]{130}$" + data: + type: string + description: Hex-encoded chunk data + pattern: "^[0-9a-f]*$" diff --git a/docs/rpc/components/schemas/stackerdb-metadata.schema.yaml b/docs/rpc/components/schemas/stackerdb-metadata.schema.yaml new file mode 100644 index 0000000000..530ae3c22c --- /dev/null +++ b/docs/rpc/components/schemas/stackerdb-metadata.schema.yaml @@ -0,0 +1,16 @@ +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) diff --git a/docs/rpc/components/schemas/stackerdb-replicas.schema.yaml b/docs/rpc/components/schemas/stackerdb-replicas.schema.yaml new file mode 100644 index 0000000000..5dd37d9d42 --- /dev/null +++ b/docs/rpc/components/schemas/stackerdb-replicas.schema.yaml @@ -0,0 +1,11 @@ +type: array +items: + type: object + properties: + ip: + type: string + port: + type: integer + public_key_hash: + type: string + description: 20-byte public key hash diff --git a/docs/rpc/components/schemas/tenure-fork-info.schema.yaml b/docs/rpc/components/schemas/tenure-fork-info.schema.yaml new file mode 100644 index 0000000000..5ea9113470 --- /dev/null +++ b/docs/rpc/components/schemas/tenure-fork-info.schema.yaml @@ -0,0 +1,40 @@ +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: [string, "null"] + description: 0x-prefixed SIP-003 binary encoding of all Nakamoto blocks mined in this tenure +additionalProperties: false diff --git a/docs/rpc/components/schemas/tenure-info.schema.yaml b/docs/rpc/components/schemas/tenure-info.schema.yaml new file mode 100644 index 0000000000..bfd6855920 --- /dev/null +++ b/docs/rpc/components/schemas/tenure-info.schema.yaml @@ -0,0 +1,30 @@ +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 diff --git a/docs/rpc/components/schemas/tenure-tip.schema.yaml b/docs/rpc/components/schemas/tenure-tip.schema.yaml new file mode 100644 index 0000000000..d738477e45 --- /dev/null +++ b/docs/rpc/components/schemas/tenure-tip.schema.yaml @@ -0,0 +1,116 @@ +description: | + JSON encoding of `StacksBlockHeaderTypes` returned by /v3/tenures/tip. + Exactly one variant property will be present: either `Epoch2` or `Nakamoto`. +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 diff --git a/docs/rpc/components/schemas/transaction-submission-error.schema.yaml b/docs/rpc/components/schemas/transaction-submission-error.schema.yaml new file mode 100644 index 0000000000..f78efc464c --- /dev/null +++ b/docs/rpc/components/schemas/transaction-submission-error.schema.yaml @@ -0,0 +1,29 @@ +description: Describes a transaction submission error response +type: object +required: + - error + - reason + - reason_data + - 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 diff --git a/docs/rpc/components/schemas/unconfirmed-transaction.schema.yaml b/docs/rpc/components/schemas/unconfirmed-transaction.schema.yaml new file mode 100644 index 0000000000..c9ba49c27c --- /dev/null +++ b/docs/rpc/components/schemas/unconfirmed-transaction.schema.yaml @@ -0,0 +1,20 @@ +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"] diff --git a/docs/rpc/entities/contracts/read-only-function-args.schema.json b/docs/rpc/entities/contracts/read-only-function-args.schema.json deleted file mode 100644 index 7d49733756..0000000000 --- a/docs/rpc/entities/contracts/read-only-function-args.schema.json +++ /dev/null @@ -1,20 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "title": "ReadOnlyFunctionArgs", - "description": "Describes representation of a Type-0 Stacks 2.0 transaction. https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#type-0-transferring-an-asset", - "type": "object", - "required": ["sender", "arguments"], - "properties": { - "sender": { - "type": "string", - "description": "The simulated tx-sender" - }, - "arguments": { - "type": "array", - "description": "An array of hex serialized Clarity values", - "items": { - "type": "string" - } - } - } -} diff --git a/docs/rpc/openapi.yaml b/docs/rpc/openapi.yaml index 5fe375cc05..63f3e8fbbf 100644 --- a/docs/rpc/openapi.yaml +++ b/docs/rpc/openapi.yaml @@ -1,14 +1,162 @@ openapi: 3.1.0 servers: - url: http://localhost:20443 - description: Local + description: Local Stacks Node info: title: Stacks 3.0+ RPC API - version: '1.0.0' + version: "1.0.0" description: | This is the documentation for the `stacks-node` RPC interface. license: name: CC-0 + url: https://creativecommons.org/publicdomain/zero/1.0/ + +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. + +components: + securitySchemes: + rpcAuth: + type: apiKey + in: header + name: authorization + description: | + Plain-text secret value that must exactly equal the node's + configured password. + 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" + Timeout: + description: Timeout + content: + text/plain: + schema: + type: string + example: "Timeout" + schemas: + NodeInfo: + $ref: ./components/schemas/node-info.schema.yaml + PoxInfo: + $ref: ./components/schemas/pox-info.schema.yaml + Sortitions: + $ref: ./components/schemas/sortitions.schema.yaml + GetHealth: + $ref: ./components/schemas/get-health.schema.yaml + AccountData: + $ref: ./components/schemas/account-data.schema.yaml + + # Transaction Schemas + TransactionSubmissionError: + $ref: ./components/schemas/transaction-submission-error.schema.yaml + FeeTransactionRequest: + $ref: ./components/schemas/fee-transaction-request.schema.yaml + FeeTransactionResponse: + $ref: ./components/schemas/fee-transaction-response.schema.yaml + FeeTransactionError: + $ref: ./components/schemas/fee-transaction-error.schema.yaml + + # Contract & Clarity Schemas + ContractInterface: + $ref: ./components/schemas/contract-interface.schema.yaml + ContractSource: + $ref: ./components/schemas/contract-source.schema.yaml + ReadOnlyFunctionArgs: + $ref: ./components/schemas/read-only-function-args.schema.yaml + ReadOnlyFunctionResult: + $ref: ./components/schemas/read-only-function-result.schema.yaml + ClarityName: + $ref: ./components/schemas/clarity-name.schema.yaml + ClarityMetadata: + $ref: ./components/schemas/clarity-metadata.schema.yaml + ConstantValue: + $ref: ./components/schemas/constant-value.schema.yaml + IsTraitImplemented: + $ref: ./components/schemas/is-trait-implemented.schema.yaml + + # Other Schemas + SignerBlocksSigned: + $ref: ./components/schemas/signer-blocks-signed.schema.yaml + UnconfirmedTransaction: + $ref: ./components/schemas/unconfirmed-transaction.schema.yaml + BlockUploadResponse: + $ref: ./components/schemas/block-upload-response.schema.yaml + AttachmentInventory: + $ref: ./components/schemas/attachment-inventory.schema.yaml + AttachmentData: + $ref: ./components/schemas/attachment-data.schema.yaml + StackerDbMetadata: + $ref: ./components/schemas/stackerdb-metadata.schema.yaml + StackerDbReplicas: + $ref: ./components/schemas/stackerdb-replicas.schema.yaml + StackerDbChunkData: + $ref: ./components/schemas/stackerdb-chunk-data.schema.yaml + StackerDbChunkAckData: + $ref: ./components/schemas/stackerdb-chunk-ack-data.schema.yaml + ClarityData: + $ref: ./components/schemas/clarity-data.schema.yaml + BlockHeaders: + $ref: ./components/schemas/block-headers.schema.yaml + BlockProposalResponse: + $ref: ./components/schemas/block-proposal.schema.yaml + NetworkPeers: + $ref: ./components/schemas/network-peers.schema.yaml + TransactionInfo: + $ref: ./components/schemas/get-transaction.schema.yaml + TenureForkInfo: + $ref: ./components/schemas/tenure-fork-info.schema.yaml + TenureInfo: + $ref: ./components/schemas/tenure-info.schema.yaml + TenureTip: + $ref: ./components/schemas/tenure-tip.schema.yaml + GetStackerSet: + $ref: ./components/schemas/get-stacker-set.schema.yaml paths: /v2/transactions: @@ -16,8 +164,18 @@ paths: summary: Broadcast raw transaction tags: - Transactions - description: Broadcast raw transactions on the network. You can use the [@stacks/transactions](https://github.com/blockstack/stacks.js) project to generate a raw transaction payload. - operationId: post_core_node_transactions + security: [] + description: | + Broadcast raw transactions on the network. You can use the [@stacks/transactions](https://github.com/blockstack/stacks.js) + project to generate a raw transaction payload. + + The node performs static validation checks on transactions before accepting them into the mempool, including: + - Transaction format validation + - Signature verification + - Nonce checking + - Fee validation + - Size limits + operationId: broadcastTransaction requestBody: content: application/octet-stream: @@ -25,22 +183,41 @@ paths: type: string format: binary 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 + description: Transaction ID of successful post of a raw tx to the node's mempool. content: - text/plain: + application/json: schema: type: string - example: '"e161978626f216b2141b156ade10501207ae535fa365a13ef5d7a7c9310a09f2"' + pattern: "^[0-9a-f]{64}$" + example: "e161978626f216b2141b156ade10501207ae535fa365a13ef5d7a7c9310a09f2" "400": - description: Rejections result in a 400 error + description: Bad request content: application/json: schema: - $ref: ./api/transaction/post-core-node-transactions-error.schema.json + $ref: "#/components/schemas/TransactionSubmissionError" example: - $ref: ./api/transaction/post-core-node-transactions-error.example.json + $ref: "./components/examples/transaction-submission-error.example.json" + "500": + $ref: "#/components/responses/InternalServerError" /v2/contracts/interface/{contract_address}/{contract_name}: get: @@ -48,88 +225,61 @@ paths: description: Get contract interface using a `contract_address` and `contract name` tags: - Smart Contracts - operationId: get_contract_interface + security: [] + operationId: getContractInterface + parameters: + - $ref: ./components/parameters/contract-address.yaml + - $ref: ./components/parameters/contract-name.yaml + - $ref: ./components/parameters/tip.yaml responses: "200": description: Contract interface content: application/json: schema: - $ref: ./api/core-node/get-contract-interface.schema.json + $ref: "#/components/schemas/ContractInterface" example: - $ref: ./api/core-node/get-contract-interface.example.json - parameters: - - name: contract_address - in: path - required: true - description: Stacks address - schema: - type: string - - name: contract_name - in: path - required: true - description: Contract name - schema: - type: string - - name: tip - in: query - schema: - type: string - description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest - known tip (includes unconfirmed state). + $ref: "./components/examples/contract-interface.example.json" + "400": + $ref: "#/components/responses/BadRequest" + "404": + $ref: "#/components/responses/NotFound" + "500": + $ref: "#/components/responses/InternalServerError" + /v2/map_entry/{contract_address}/{contract_name}/{map_name}: post: summary: Get specific data-map inside a contract tags: - Smart Contracts - operationId: get_contract_data_map_entry + security: [] + operationId: getContractDataMapEntry description: | - Attempt to fetch data from a contract data map. The contract is identified with [Stacks Address] and [Contract Name] in the URL path. The map is identified with [Map Name]. + Attempt to fetch data from a contract data map. The contract is + identified with [Stacks Address] and [Contract Name] in the URL path. + The map is identified with [Map Name]. - The key to lookup in the map is supplied via the POST body. This should be supplied as the hex string serialization of the key (which should be a Clarity value). Note, this is a JSON string atom. + The key to lookup in the map is supplied via the POST body. This should + be supplied as the hex string serialization of the key (which should be + a Clarity value). Note, this is a JSON string. + + The response is a JSON object with the following properties: + - `data`: The hex serialization of the map response. Note that map + responses are Clarity option types, for non-existent values, this is + a serialized none, and for all other responses, it is a serialized + (some ...) object. + - `proof`: The hex serialization of the Merkle proof for the data. - In the response, `data` is the hex serialization of the map response. Note that map responses are Clarity option types, for non-existent values, this is a serialized none, and for all other responses, it is a serialized (some ...) object. - responses: - "200": - description: Success - content: - application/json: - schema: - $ref: ./api/core-node/get-contract-data-map-entry.schema.json - example: - $ref: ./api/core-node/get-contract-data-map-entry.example.json - "400": - description: Failed loading data map parameters: - - name: contract_address - in: path - required: true - description: Stacks address - schema: - type: string - - name: contract_name - in: path - required: true - description: Contract name - schema: - type: string + - $ref: ./components/parameters/contract-address.yaml + - $ref: ./components/parameters/contract-name.yaml - name: map_name in: path required: true - description: Map name - schema: - type: string - - name: proof - in: query - description: Returns object without the proof field when set to 0 - schema: - type: integer - - name: tip - in: query schema: - type: string - description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest - known tip (includes unconfirmed state). + $ref: "#/components/schemas/ClarityName" + - $ref: ./components/parameters/proof.yaml + - $ref: ./components/parameters/tip.yaml x-codegen-request-body-name: key requestBody: description: Hex string serialization of the lookup key (which should be a Clarity value) @@ -138,116 +288,177 @@ paths: application/json: schema: type: string + responses: + "200": + description: Success + content: + application/json: + schema: + $ref: "#/components/schemas/ClarityData" + example: + $ref: "./components/examples/clarity-data.example.json" + "400": + $ref: "#/components/responses/BadRequest" + "404": + $ref: "#/components/responses/NotFound" + "500": + $ref: "#/components/responses/InternalServerError" /v2/contracts/source/{contract_address}/{contract_name}: get: summary: Get contract source tags: - Smart Contracts - operationId: get_contract_source - description: Returns the Clarity source code of a given contract, along with the block height it was published in, and the MARF proof for the data + security: [] + operationId: getContractSource + description: | + Returns the Clarity source code of a given contract, along with the + block height it was published in, and the MARF proof for the data. + parameters: + - $ref: ./components/parameters/contract-address.yaml + - $ref: ./components/parameters/contract-name.yaml + - $ref: ./components/parameters/proof.yaml + - $ref: ./components/parameters/tip.yaml responses: "200": description: Success content: application/json: schema: - $ref: ./api/core-node/get-contract-source.schema.json + $ref: "#/components/schemas/ContractSource" example: - $ref: ./api/core-node/get-contract-source.example.json - parameters: - - name: contract_address - in: path - required: true - description: Stacks address - schema: - type: string - - name: contract_name - in: path - required: true - description: Contract name - schema: - type: string - - name: proof - in: query - description: Returns object without the proof field if set to 0 - schema: - type: integer - - name: tip - in: query - schema: - type: string - description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest - known tip (includes unconfirmed state). - required: false + $ref: "./components/examples/contract-source.example.json" + "400": + $ref: "#/components/responses/BadRequest" + "404": + $ref: "#/components/responses/NotFound" + "500": + $ref: "#/components/responses/InternalServerError" /v2/contracts/call-read/{contract_address}/{contract_name}/{function_name}: post: summary: Call read-only function - tags: - - Smart Contracts - operationId: call_read_only_function description: | - Call a read-only public function on a given smart contract. + Call a read-only public function on a given contract. - The smart contract and function are specified using the URL path. The arguments and the simulated tx-sender are supplied via the POST body in the following JSON format: + The contract is identified with [Stacks Address] and [Contract Name] in the URL path. + The function is identified with [Function Name]. + + The arguments to the function are supplied via the POST body. + This should be a JSON object with two main properties: + - `sender` which should be a standard Stacks address + - `arguments` which should be an array of hex-encoded Clarity values. + tags: + - Smart Contracts + security: [] + operationId: callReadOnlyFunction + parameters: + - $ref: ./components/parameters/contract-address.yaml + - $ref: ./components/parameters/contract-name.yaml + - name: function_name + in: path + required: true + schema: + $ref: "#/components/schemas/ClarityName" + - $ref: ./components/parameters/tip.yaml + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ReadOnlyFunctionArgs" responses: "200": - description: Success + description: Function executed successfully content: application/json: schema: - $ref: ./api/contract/post-call-read-only-fn.schema.json + $ref: "#/components/schemas/ReadOnlyFunctionResult" examples: success: - $ref: ./api/contract/post-call-read-only-fn-success.example.json - fail: - $ref: ./api/contract/post-call-read-only-fn-fail.example.json + summary: Successful function call + externalValue: "./components/examples/read-only-function-success.example.json" + failure: + summary: Failed function call + externalValue: "./components/examples/read-only-function-failure.example.json" + "400": + $ref: "#/components/responses/BadRequest" + "404": + $ref: "#/components/responses/NotFound" + "500": + $ref: "#/components/responses/InternalServerError" + + /v3/contracts/fast-call-read/{contract_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. + + The contract is identified with [Stacks Address] and [Contract Name] in the URL path. + The function is identified with [Function Name]. + + The arguments to the function are supplied via the POST body. + This should be a JSON object with two main properties: + - `sender` which should be a standard Stacks address + - `arguments` which should be an array of hex-encoded Clarity values. + + **This API endpoint requires a basic Authorization header.** + tags: + - Smart Contracts + security: + - rpcAuth: [] + operationId: fastCallReadOnlyFunction parameters: - - name: contract_address - in: path - required: true - description: Stacks address - schema: - type: string - - name: contract_name - in: path - required: true - description: Contract name - schema: - type: string + - $ref: ./components/parameters/contract-address.yaml + - $ref: ./components/parameters/contract-name.yaml - name: function_name in: path required: true - description: Function name - schema: - type: string - - name: tip - in: query schema: - type: string - description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest - known tip (includes unconfirmed state). - required: false + $ref: "#/components/schemas/ClarityName" + - $ref: ./components/parameters/tip.yaml requestBody: description: map of arguments and the simulated tx-sender where sender is either a Contract identifier or a normal Stacks address, and arguments is an array of hex serialized Clarity values. required: true content: application/json: schema: - $ref: './entities/contracts/read-only-function-args.schema.json' + $ref: "#/components/schemas/ReadOnlyFunctionArgs" example: - sender: 'SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info' + sender: "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info" arguments: - - '0x0011...' - - '0x00231...' + - "0x0011..." + - "0x00231..." + responses: + "200": + description: Function executed successfully + content: + application/json: + schema: + $ref: "#/components/schemas/ReadOnlyFunctionResult" + examples: + success: + summary: Successful function call + externalValue: "./components/examples/read-only-function-success.example.json" + failure: + summary: Failed function call + externalValue: "./components/examples/read-only-function-failure.example.json" + "400": + $ref: "#/components/responses/BadRequest" + "404": + $ref: "#/components/responses/NotFound" + "408": + $ref: "#/components/responses/Timeout" + "500": + $ref: "#/components/responses/InternalServerError" /v2/accounts/{principal}: get: summary: Get account info tags: - Accounts - operationId: get_account_info + security: [] + operationId: getAccountInfo description: | Get the account data for the provided principal @@ -255,38 +466,31 @@ paths: For non-existent accounts, this does not 404, rather it returns an object with balance and nonce of 0. parameters: - - name: principal - in: path - description: Stacks address or a Contract identifier (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`) - required: true - schema: - type: string - - name: proof - in: query - description: Returns object without the proof field if set to 0 - schema: - type: integer - - name: tip - in: query - schema: - type: string - description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest - known tip (includes unconfirmed state). + - $ref: ./components/parameters/principal.yaml + - $ref: ./components/parameters/proof.yaml + - $ref: ./components/parameters/tip.yaml responses: "200": description: Success content: application/json: schema: - $ref: ./api/core-node/get-account-data.schema.json + $ref: "#/components/schemas/AccountData" example: - $ref: ./api/core-node/get-account-data.example.json + $ref: "./components/examples/account-data.example.json" + "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 estimates the execution cost of the transaction, the current @@ -328,7 +532,7 @@ paths: execution cost of the transaction. The range of this integer may vary between different Stacks nodes. In order to compute an estimate of total fee amount for the transaction, this - value is multiplied by the same Stacks node's estimated fee + value is multiplied by the same Stacks node"s estimated fee rate. * `cost_scalar_change_by_byte` - a float value that indicates how much the `estimated_cost_scalar` value would increase for every @@ -348,46 +552,60 @@ paths: fee will be returned here instead. - Note: If the final transaction's byte size is larger than + Note: If the final transaction"s byte size is larger than supplied to `estimated_len`, then applications should increase this fee amount by: `fee_rate` x `cost_scalar_change_by_byte` x (`final_size` - `estimated_size`) - operationId: post_fee_transaction + operationId: getFeeTransaction requestBody: content: application/json: schema: - $ref: ./api/core-node/post-fee-transaction.schema.json + $ref: "#/components/schemas/FeeTransactionRequest" example: - $ref: ./api/core-node/post-fee-transaction.example.json + $ref: "./components/examples/fee-transaction-request.example.json" responses: "200": description: Estimated fees for the transaction content: application/json: schema: - $ref: ./api/core-node/post-fee-transaction-response.schema.json + $ref: "#/components/schemas/FeeTransactionResponse" example: - $ref: ./api/core-node/post-fee-transaction-response.example.json + $ref: "./components/examples/fee-transaction-response.example.json" + "400": + description: Fee estimation error + content: + application/json: + schema: + $ref: "#/components/schemas/FeeTransactionError" + "500": + $ref: "#/components/responses/InternalServerError" /v2/fees/transfer: get: summary: Get estimated fee tags: - Fees - operationId: get_fee_transfer - description: Get an estimated fee rate for STX transfer transactions. This a a fee rate / byte, and is returned as a JSON integer + security: [] + operationId: getFeeTransfer + description: | + Get an estimated fee rate for STX transfer transactions. This is a fee + rate per byte, returned as a JSON integer (microSTX per byte). responses: "200": - description: Success + description: Fee rate in microSTX per byte content: application/json: schema: - $ref: ./api/core-node/get-fee-transfer.schema.json - example: - $ref: ./api/core-node/get-fee-transfer.example.json + type: integer + minimum: 1 + description: Fee rate in microSTX per byte + example: 3 + "500": + $ref: "#/components/responses/InternalServerError" /v2/info: get: @@ -395,16 +613,19 @@ paths: description: Get Core API information tags: - Info - operationId: get_core_api_info + security: [] + operationId: getNodeInfo responses: "200": description: Success content: application/json: schema: - $ref: ./api/core-node/get-info.schema.json + $ref: "#/components/schemas/NodeInfo" example: - $ref: ./api/core-node/get-info.example.json + $ref: "./components/examples/node-info.example.json" + "500": + $ref: "#/components/responses/InternalServerError" /v2/pox: get: @@ -412,175 +633,161 @@ paths: description: Get Proof of Transfer (PoX) information. Can be used for Stacking. tags: - Info - operationId: get_pox_info + security: [] + operationId: getPoxInfo responses: "200": description: Success content: application/json: schema: - $ref: ./api/core-node/get-pox.schema.json + $ref: "#/components/schemas/PoxInfo" example: - $ref: ./api/core-node/get-pox.example.json + $ref: "./components/examples/pox-info.example.json" parameters: - - name: tip - in: query - schema: - type: string - description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest - known tip (includes unconfirmed state). + - $ref: ./components/parameters/tip.yaml /v2/traits/{contract_address}/{contract_name}/{trait_contract_address}/{trait_contract_name}/{trait_name}: get: summary: Get trait implementation details - description: Determine whether or not a specified trait is implemented (either explicitly or implicitly) within a given contract. + description: | + Determine whether or not a specified trait is implemented (either + explicitly or implicitly) within a given contract. tags: - Smart Contracts - operationId: get_is_trait_implemented + security: [] + operationId: checkTraitImplementation + parameters: + - $ref: ./components/parameters/contract-address.yaml + - $ref: ./components/parameters/contract-name.yaml + - name: trait_contract_address + in: path + required: true + description: | + Stacks address of the trait-defining contract. + schema: + type: string + pattern: "^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$" + minLength: 28 + maxLength: 41 + example: "SP2Z1K16238380NBP4T38A4G10A90Q03JJ2C2003" + - 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.yaml responses: "200": description: Success content: application/json: schema: - $ref: ./api/trait/get-is-trait-implemented.schema.json + $ref: "#/components/schemas/IsTraitImplemented" example: - $ref: ./api/trait/get-is-trait-implemented.example.json - parameters: - - name: contract_address - in: path - required: true - description: Stacks address - schema: - type: string - - name: contract_name - in: path - required: true - description: Contract name - schema: - type: string - - name: trait_contract_address - in: path - required: true - description: Trait Stacks address - schema: - type: string - - name: trait_contract_name - in: path - required: true - description: Trait contract name - schema: - type: string - - name: trait_name - in: path - required: true - description: Trait name - schema: - type: string - - name: tip - in: query - schema: - type: string - description: | - The Stacks chain tip to query from. - If tip == "latest", the query will be run from the latest known tip (includes unconfirmed state). - If the tip is left unspecified, the stacks chain tip will be selected (only includes confirmed state). - - /v2/clarity/marf/{clarity_marf_key}: - post: + $ref: "./components/examples/is-trait-implemented.example.json" + "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 - operationId: get_clarity_marf_value + security: [] + operationId: getClarityMarfValue description: | - Attempt to fetch the value of a MARF key. - - In the response, `data` is the hex serialization of the value. + Attempt to fetch the value of a MARF key. The key is a 64-character + hex string representing the MARF node hash. responses: - 200: + "200": description: Success content: application/json: schema: - $ref: ./api/core-node/get-clarity-marf-value.schema.json + $ref: "#/components/schemas/ClarityData" example: - $ref: ./api/core-node/get-clarity-marf-value.example.json - 400: - description: Failed to retrieve MARF key + $ref: "./components/examples/clarity-data.example.json" + "400": + $ref: "#/components/responses/BadRequest" + "404": + $ref: "#/components/responses/NotFound" parameters: - - name: clarity_marf_key + - name: marf_key_hash in: path required: true - description: MARF key - schema: - type: string - - name: proof - in: query - description: Returns object without the proof field when set to 0 - schema: - type: integer - - name: tip - in: query + description: The 64-character hex-encoded hash of the MARF key. schema: type: string - description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest - known tip (includes unconfirmed state). + pattern: "^[0-9a-f]{64}$" + minLength: 64 + maxLength: 64 + - $ref: ./components/parameters/proof.yaml + - $ref: ./components/parameters/tip.yaml /v2/clarity/metadata/{contract_address}/{contract_name}/{clarity_metadata_key}: - post: + get: summary: Get the contract metadata for the metadata key tags: - Smart Contracts - operationId: get_clarity_metadata_key + security: [] + operationId: getClarityMetadata description: | - Attempt to fetch the metadata of a contract. The contract is identified with [Contract Address] and [Contract Name] in the URL path. The metadata key is identified with [Clarity Metadata Key]. + Attempt to fetch the metadata of a contract. The contract is identified + with [Contract Address] and [Contract Name] in the URL path. The metadata + key is identified with [Clarity Metadata Key]. In the response, `data` is formatted as JSON. responses: - 200: + "200": description: Success content: application/json: schema: - $ref: ./api/core-node/get-clarity-metadata.schema.json + $ref: "#/components/schemas/ClarityMetadata" example: - $ref: ./api/core-node/get-clarity-metadata.example.json - 400: - description: Failed to retrieve constant value from contract + $ref: "./components/examples/clarity-metadata.example.json" + "400": + $ref: "#/components/responses/BadRequest" + "404": + $ref: "#/components/responses/NotFound" + "500": + $ref: "#/components/responses/InternalServerError" parameters: - - name: contract_address - in: path - required: true - description: Stacks address - schema: - type: string - - name: contract_name - in: path - required: true - description: Contract name - schema: - type: string + - $ref: ./components/parameters/contract-address.yaml + - $ref: ./components/parameters/contract-name.yaml - name: clarity_metadata_key in: path required: true description: Metadata key schema: type: string - - name: tip - in: query - schema: - type: string - description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest - known tip (includes unconfirmed state). + - $ref: ./components/parameters/tip.yaml /v2/constant_val/{contract_address}/{contract_name}/{constant_name}: - post: + get: summary: Get the value of a constant inside a contract tags: - Smart Contracts - operationId: get_constant_val + security: [] + operationId: getConstantValue description: | - Attempt to fetch the value of a constant inside a contract. The contract is identified with [Stacks Address] and [Contract Name] in the URL path. The constant is identified with [Constant Name]. + Attempt to fetch the value of a constant inside a contract. The contract + is identified with [Stacks Address] and [Contract Name] in the URL path. + The constant is identified with [Constant Name]. In the response, `data` is the hex serialization of the constant value. responses: @@ -589,82 +796,103 @@ paths: content: application/json: schema: - $ref: ./api/core-node/get-constant-val.schema.json + $ref: "#/components/schemas/ConstantValue" example: - $ref: ./api/core-node/get-constant-val.example.json + $ref: "./components/examples/constant-value.example.json" "400": - description: Failed to retrieve constant value from contract + $ref: "#/components/responses/BadRequest" + "404": + $ref: "#/components/responses/NotFound" + "500": + $ref: "#/components/responses/InternalServerError" parameters: - - name: contract_address - in: path - required: true - description: Stacks address - schema: - type: string - - name: contract_name - in: path - required: true - description: Contract name - schema: - type: string + - $ref: ./components/parameters/contract-address.yaml + - $ref: ./components/parameters/contract-name.yaml - name: constant_name in: path required: true - description: Constant name - schema: - type: string - - name: tip - in: query schema: - type: string - description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest - known tip (includes unconfirmed state). + $ref: "#/components/schemas/ClarityName" + - $ref: ./components/parameters/tip.yaml /v3/block_proposal: post: summary: Validate a proposed Stacks block tags: - Mining - operationId: post_block_proposal + operationId: postBlockProposal description: | Used by stackers to validate a proposed Stacks block from a miner. - **This API endpoint requires a basic Authorization header.** + security: + - rpcAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: ["block", "chain_id"] + properties: + block: + type: string + description: Hex-encoded block data + chain_id: + type: integer + description: Chain ID for the block + example: + $ref: "./components/examples/post-block-proposal-request.example.json" responses: "202": - description: Block proposal has been accepted for processing. + description: | + Block proposal has been accepted for processing. The result will be returned via the event observer. content: application/json: + schema: + $ref: "#/components/schemas/BlockProposalResponse" example: - $ref: ./api/core-node/post-block-proposal-response.example.json + $ref: "./components/examples/post-block-proposal-response.example.json" "400": - description: Endpoint not enabled. + 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": - description: Unauthorized. + $ref: "#/components/responses/Unauthorized" "429": - description: There is an ongoing proposal validation being processed, - the new request cannot be accepted until the prior request has been processed. + description: | + There is an ongoing proposal validation being processed, the new + request cannot be accepted until the prior request has been processed. content: application/json: + schema: + $ref: "#/components/schemas/BlockProposalResponse" example: - $ref: ./api/core-node/post-block-proposal-response.429.json - requestBody: - content: - application/json: - example: - $ref: ./api/core-node/post-block-proposal-req.example.json + $ref: "./components/examples/post-block-proposal-response.429.example.json" + "500": + $ref: "#/components/responses/InternalServerError" /v3/stacker_set/{cycle_number}: get: summary: Fetch the stacker and signer set information for a given cycle. tags: - - Mining - operationId: get_stacker_set + - Signers + security: [] + operationId: getStackerSet description: | Used to get stacker and signer set information for a given cycle. - This will only return information for cycles started in Epoch-2.5 where PoX-4 was active and subsequent cycles. + This will only return information for cycles started in Epoch-2.5 + where PoX-4 was active and subsequent cycles. parameters: - name: cycle_number in: path @@ -672,32 +900,56 @@ paths: description: reward cycle number schema: type: integer + - $ref: ./components/parameters/tip.yaml responses: "200": description: Information for the given reward cycle content: application/json: + schema: + $ref: "#/components/schemas/GetStackerSet" example: - $ref: ./api/core-node/get_stacker_set.example.json + $ref: "./components/examples/get-stacker-set.example.json" "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 example: - $ref: ./api/core-node/get_stacker_set.400.example.json + $ref: "./components/examples/get-stacker-set-400.example.json" /v3/blocks/{block_id}: get: - summary: Fetch a Nakamoto block + summary: Get Nakamoto block by ID tags: - Blocks - operationId: get_block_v3 - description: - Fetch a Nakamoto block by its index block hash. + security: [] + operationId: getNakamotoBlockById + description: | + Get a specific Nakamoto block (Stacks 3.x+) by its index block hash. This endpoint streams + the block data from the Nakamoto staging blocks database where Nakamoto blocks are stored + with additional metadata including tenure information. + + **Compatibility**: Works with Nakamoto blocks only. For Stacks 2.x blocks, use `/v2/blocks/{block_id}`. parameters: - name: block_id in: path - description: The block's ID hash + description: The block"s ID hash required: true schema: type: string @@ -709,19 +961,21 @@ paths: schema: type: string format: binary + "400": + $ref: "#/components/responses/BadRequest" "404": - description: The block could not be found - content: - application/text-plain: {} + $ref: "#/components/responses/NotFound" + "500": + $ref: "#/components/responses/InternalServerError" /v3/blocks/height/{block_height}: get: summary: Fetch a Nakamoto block by its height and optional tip tags: - Blocks - operationId: get_block_v3_by_height - description: - Fetch a Nakamoto block by its height and optional tip. + security: [] + operationId: getNakamotoBlockByHeight + description: Fetch a Nakamoto block by its height and optional tip. parameters: - name: block_height in: path @@ -729,12 +983,7 @@ paths: required: true schema: type: integer - - name: tip - in: query - schema: - type: string - description: The Stacks chain tip to query from. If tip == latest or empty, the query will be run - from the latest known tip. + - $ref: ./components/parameters/tip.yaml responses: "200": description: The raw SIP-003-encoded block will be returned. @@ -743,158 +992,298 @@ paths: schema: type: string format: binary + "400": + $ref: "#/components/responses/BadRequest" "404": - description: The block could not be found - content: - application/text-plain: {} + $ref: "#/components/responses/NotFound" + "500": + $ref: "#/components/responses/InternalServerError" /v3/tenures/info: get: summary: Fetch metadata about the ongoing Nakamoto tenure tags: - Blocks - operationId: get_tenure_info - description: - Fetch metadata about the ongoing Nakamoto tenure. This information is sufficient to obtain and authenticate the highest complete tenure, as well as obtain new tenure blocks. + security: [] + operationId: getTenureInfo + description: | + Fetch metadata about the ongoing Nakamoto tenure. This information is + sufficient to obtain and authenticate the highest complete tenure, as + well as obtain new tenure blocks. responses: "200": description: Metadata about the ongoing tenure content: application/json: + schema: + $ref: "#/components/schemas/TenureInfo" example: - $ref: ./api/core-node/get_tenure_info.json + $ref: "./components/examples/get-tenure-info.example.json" /v3/tenures/{block_id}: get: summary: Fetch a sequence of Nakamoto blocks in a tenure tags: - Blocks - operationId: get_tenures - description: - Fetch a sequence of Nakamoto blocks in a tenure. The blocks will be served in order from highest to lowest. The blocks will be encoded in their SIP-003 wire format, and concatenated together. - responses: - "200": - description: SIP-003-encoded Nakamoto blocks, concatenated together - content: - application/octet-stream: - schema: - type: string - format: binary - parameters: - - name: block_id - in: path - description: - The tenure-start block ID of the tenure to query - required: true - schema: - type: string - - name: stop - in: query - description: - The block ID hash of the highest block in this tenure that is already known to the caller. Neither the corresponding block nor any of its ancestors will be served. This is used to fetch tenure blocks that the caller does not have. - required: false - schema: - type: string - - /v3/sortitions/{lookup_kind}/{lookup}: + security: [] + operationId: getTenures + description: | + Fetch a sequence of Nakamoto blocks in a tenure. The blocks will be + served in order from highest to lowest. The blocks will be encoded in + their SIP-003 wire format, and concatenated together. + parameters: + - name: block_id + in: path + description: The tenure-start block ID of the tenure to query + required: true + schema: + type: string + - name: stop + in: query + description: | + The block ID hash of the highest block in this tenure that is already + known to the caller. Neither the corresponding block nor any of its + ancestors will be served. This is used to fetch tenure blocks that the + caller does not have. + required: false + schema: + type: string + responses: + "200": + description: SIP-003-encoded Nakamoto blocks, concatenated together + content: + application/octet-stream: + schema: + type: string + format: binary + + /v3/sortitions: get: - summary: Fetch information about evaluated burnchain blocks (i.e., sortitions). + summary: Get latest sortition information tags: - Blocks - operationId: get_sortitions - description: - Fetch sortition information about a burnchain block. If the `lookup_kind` and `lookup` parameters are empty, it will return information about the latest burn block. + security: [] + operationId: getLatestSortitions + description: | + Get sortition information about the latest burnchain block processed by this node. + Returns a single-element array with the latest sortition. responses: "200": - description: Information for the burn block or in the case of `latest_and_last`, multiple burn blocks + description: Latest sortition information content: application/json: - examples: - Latest: - description: A single element list is returned when just one sortition is requested - value: - $ref: ./api/core-node/get_sortitions.example.json - LatestAndLast: - description: Sortition information about the latest burn block with a winning miner, and the previous such burn block. - value: - $ref: ./api/core-node/get_sortitions_latest_and_prior.example.json - parameters: - - name: lookup_kind - in: path - description: |- - The style of lookup that should be performed. If not given, the most recent burn block processed will be returned. - Otherwise, the `lookup_kind` should be one of the following strings: - * `consensus` - find the burn block using the consensus hash supplied in the `lookup` field. - * `burn_height` - find the burn block using the burn block height supplied in the `lookup` field. - * `burn` - find the burn block using the burn block hash supplied in the `lookup` field. - * `latest_and_last` - return information about the latest burn block with a winning miner *and* the previous such burn block - required: false - schema: - type: string - - name: lookup - in: path - description: The value to use for the lookup if `lookup_kind` is `consensus`, `burn_height`, or `burn` - required: false - schema: - type: string - /v3/signer/{signer}/{cycle_number}: + schema: + $ref: "#/components/schemas/Sortitions" + example: + $ref: "./components/examples/get-sortitions.example.json" + "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 + AND the previous such burn block. Returns an array with two sortition objects. + responses: + "200": + description: Latest and last sortition information + content: + application/json: + schema: + $ref: "#/components/schemas/Sortitions" + example: + $ref: "./components/examples/get-sortitions-latest-and-prior.example.json" + "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. + Returns a single-element array with the matching sortition. + parameters: + - name: consensus_hash + in: path + required: true + description: Hex-encoded consensus hash (40 characters) + schema: + type: string + pattern: "^(0x)?[0-9a-f]{40}$" + responses: + "200": + description: Sortition information for the consensus hash + content: + application/json: + schema: + $ref: "#/components/schemas/Sortitions" + example: + $ref: "./components/examples/get-sortitions.example.json" + "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. + Returns a single-element array with the matching sortition. + parameters: + - name: burn_header_hash + in: path + required: true + description: Hex-encoded burn header hash (64 characters) + schema: + type: string + pattern: "^(0x)?[0-9a-f]{64}$" + responses: + "200": + description: Sortition information for the burn header hash + content: + application/json: + schema: + $ref: "#/components/schemas/Sortitions" + example: + $ref: "./components/examples/get-sortitions.example.json" + "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. + Returns a single-element array with the matching sortition. + parameters: + - name: height + in: path + required: true + description: Burn block height (integer) + schema: + type: integer + minimum: 0 + responses: + "200": + description: Sortition information for the burn block height + content: + application/json: + schema: + $ref: "#/components/schemas/Sortitions" + example: + $ref: "./components/examples/get-sortitions.example.json" + "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 - operationId: get_signer + security: [] + operationId: getSignerBlocksSigned description: Get number of blocks signed by signer during a given reward cycle parameters: - - name: signer + - 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 + - $ref: ./components/parameters/tip.yaml responses: - 200: + "200": description: Number of blocks signed content: - text/plain: + application/json: schema: - type: integer - example: 7 + $ref: "#/components/schemas/SignerBlocksSigned" + example: + blocks_signed: 7 + /v3/transaction/{txid}: - post: + get: summary: Retrieve transaction details by TXID tags: - Transactions - description: Get a JSON with the transaction details including the `index_block_hash`, the hex-encoded transaction body, and the `result`. - operationId: get_transaction + security: [] + description: | + Get a JSON with the transaction details including the `index_block_hash`, + the hex-encoded transaction body, and the `result`. + operationId: getTransactionById parameters: - - name: txid - in: path - required: true - description: Transaction ID - schema: - type: string + - 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" example: - $ref: ./api/core-node/get_transaction.json + $ref: "./components/examples/get-transaction.example.json" "404": - description: Transaction not found - content: - application/text-plain: {} + $ref: "#/components/responses/NotFound" + "500": + $ref: "#/components/responses/InternalServerError" "501": description: Transaction indexing not enabled content: - application/text-plain: {} + text/plain: + schema: + type: string + example: "Transaction indexing is not enabled" /v3/health: get: @@ -904,17 +1293,19 @@ paths: A node is considered healthy if its Stacks tip height matches the maximum Stacks tip height observed among its connected peers. This endpoint returns: - `difference_from_max_peer`: The difference in Stacks height between this node and its most advanced peer. - - `max_stacks_height_of_neighbors`: The maximum Stacks height observed among the node's connected peers. + - `max_stacks_height_of_neighbors`: The maximum Stacks height observed among the node"s connected peers. - `node_stacks_tip_height`: The current Stacks tip height of this node. tags: - Info - operationId: get_health + security: [] + operationId: getNodeHealth parameters: - in: query name: neighbors - description: "Specifies the set of peers to use for health checks. + description: | + Specifies the set of peers to use for health checks. - `initial` (default): Use only the initial bootstrap peers. - - `all`: Use all connected peers." + - `all`: Use all connected peers. required: false schema: type: string @@ -923,97 +1314,799 @@ paths: - all default: initial responses: - 200: + "200": description: Success content: application/json: schema: - $ref: ./api/core-node/get-health.schema.json + $ref: "#/components/schemas/GetHealth" example: - $ref: ./api/core-node/get-health.example.json - 400: + $ref: "./components/examples/node-health.example.json" + "400": description: Bad request, such as an invalid `neighbors` query parameter. + $ref: "#/components/responses/BadRequest" + "500": + description: | + Failed to query for health (e.g., no data or no valid peers to query from). + $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. + + The attachment hash is a 40-character hex string (SHA-1 hash). + 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. + This returns a bitfield indicating which attachments are available. + 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 + schema: + type: string + example: "1,2,3" + pattern: "^[0-9]+(,[0-9]+){0,7}$" + description: max 8 pages per request + responses: + "200": + description: Attachment inventory bitfield + content: + application/json: + schema: + $ref: "#/components/schemas/AttachmentInventory" + example: + 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. + The microblocks are returned as a binary stream of concatenated microblock data. + parameters: + - name: block_id + in: path + required: true + description: Hex-encoded Stacks block ID (64 characters) + schema: + type: string + pattern: "^[0-9a-f]{64}$" + - $ref: ./components/parameters/tip.yaml + responses: + "200": + description: Stream of confirmed microblocks + content: + application/octet-stream: schema: type: string - example: "Invalid `neighbors` query parameter: allowed values are `initial` or `all`" - 500: - description: | - Failed to query for health (e.g., no data or no valid peers to query from). - Only the `error` field will be set in this case, providing a message about the failure. + format: binary + "404": + $ref: "#/components/responses/NotFound" + "500": + $ref: "#/components/responses/InternalServerError" + + /v2/microblocks/{microblock_id}: + get: + summary: | + Get a stream of microblocks beginning + with the given microblock (Epoch 2.x). + 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. + The microblocks are returned as a binary stream. + 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. + The body **must** be the SIP-003 binary serialization of a `Microblock` + and sent with `Content-Type: application/octet-stream`. + requestBody: + required: true + content: + application/octet-stream: + schema: + type: string + format: binary + responses: + "200": + description: Index-block hash of the accepted microblock content: application/json: schema: - $ref: ./api/core-node/get-health-error.schema.json - example: - $ref: ./api/core-node/get-health-error.example.json + 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" - /v3/contracts/fast-call-read/{contract_address}/{contract_name}/{function_name}: + /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. + parameters: + - $ref: ./components/parameters/principal.yaml + - $ref: ./components/parameters/contract-name.yaml + - name: slot_id + in: path + required: true + description: Slot ID + schema: + type: integer + minimum: 0 + responses: + "200": + description: StackerDB chunk data + content: + application/octet-stream: + schema: + type: string + format: binary + "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. + parameters: + - $ref: ./components/parameters/principal.yaml + - $ref: ./components/parameters/contract-name.yaml + - name: slot_id + in: path + required: true + description: Slot ID + schema: + type: integer + minimum: 0 + - name: slot_version + in: path + required: true + description: Specific slot version + schema: + type: integer + minimum: 0 + 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. + parameters: + - $ref: ./components/parameters/principal.yaml + - $ref: ./components/parameters/contract-name.yaml + responses: + "200": + description: StackerDB metadata + content: + application/json: + schema: + $ref: "#/components/schemas/StackerDbMetadata" + example: + - 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: Call read-only function in fast mode (no cost and memory tracking) + summary: Write StackerDB chunk tags: - - Smart Contracts - operationId: fast_call_read_only_function + - StackerDB + security: [] + operationId: postStackerDbChunk description: | - Call a read-only public function on a given smart contract without cost tracking. + Write a chunk of data to a StackerDB instance. - **This API endpoint requires a basic Authorization header.** + The request body should contain a JSON object with the chunk data including + slot_id, slot_version, signature, and hex-encoded data. - The smart contract and function are specified using the URL path. The arguments and the simulated tx-sender are supplied via the POST body in the following JSON format: + The response indicates whether the chunk was accepted, and if not, provides + detailed error information. Note that failed writes return HTTP 200 with + accepted: false, not HTTP error codes. + parameters: + - $ref: ./components/parameters/principal.yaml + - $ref: ./components/parameters/contract-name.yaml + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/StackerDbChunkData" + example: + $ref: "./components/examples/stackerdb-chunk-data-request.example.json" responses: "200": - description: Success + description: Chunk submission result (both success and failure cases) content: application/json: schema: - $ref: ./api/contract/post-call-read-only-fn.schema.json + $ref: "#/components/schemas/StackerDbChunkAckData" examples: success: - $ref: ./api/contract/post-call-read-only-fn-success.example.json - fail: - $ref: ./api/contract/post-call-read-only-fn-fail.example.json + summary: Successful chunk write + externalValue: "./components/examples/stackerdb-chunk-ack-success.example.json" + failure: + summary: Failed chunk write + externalValue: "./components/examples/stackerdb-chunk-ack-failure.example.json" "400": - description: Endpoint not enabled. - "401": - description: Unauthorized. - "408": - description: ExecutionTime expired. + $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. parameters: - - name: contract_address + - $ref: ./components/parameters/principal.yaml + - $ref: ./components/parameters/contract-name.yaml + responses: + "200": + description: List of StackerDB replicas + content: + application/json: + schema: + $ref: "#/components/schemas/StackerDbReplicas" + example: + - 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. + Returns the raw hex-encoded value of the variable. + parameters: + - $ref: ./components/parameters/principal.yaml + - $ref: ./components/parameters/contract-name.yaml + - name: var_name in: path required: true - description: Stacks address + description: Variable name schema: type: string - - name: contract_name + - $ref: ./components/parameters/proof.yaml + - $ref: ./components/parameters/tip.yaml + responses: + "200": + description: The data variable value + content: + application/json: + schema: + $ref: "#/components/schemas/ClarityData" + example: + $ref: "./components/examples/clarity-data.example.json" + "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.** + Stream (as a JSON array) up to `quantity` most recent anchored Stacks block headers. + The result is ordered from the current tip backwards. + parameters: + - name: quantity in: path required: true - description: Contract name + description: Number of headers to return (max 256) + schema: + type: integer + minimum: 1 + maximum: 256 + - $ref: ./components/parameters/tip.yaml + 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 + from the filesystem storage where traditional Stacks blocks are stored as individual files. + + **Compatibility**: Works with all Stacks 2.x blocks. For Nakamoto blocks (Stacks 3.x+), use `/v3/blocks/{block_id}`. + parameters: + - name: block_id + in: path + required: true + description: Hex-encoded block ID (64 characters) schema: type: string - - name: function_name + 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. + responses: + "200": + description: List of neighbor peers + content: + application/json: + schema: + $ref: "#/components/schemas/NetworkPeers" + example: + $ref: ./components/examples/network-peers.example.json + + /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. + This is used to identify conflicting tenures in the Nakamoto consensus. + 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. + 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" + example: + $ref: "./components/examples/get-tenure-tip.example.json" + "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. + This looks in both the mempool and unconfirmed microblock stream. + parameters: + - name: txid in: path required: true - description: Function name + description: Transaction ID (64 hexadecimal characters) schema: type: string - - name: tip + pattern: "^[0-9a-f]{64}$" + responses: + "200": + description: Unconfirmed transaction details + content: + application/json: + schema: + $ref: "#/components/schemas/UnconfirmedTransaction" + example: + 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. + The block must be in binary format and associated with the given consensus hash. + 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 + description: Binary-encoded Stacks block + responses: + "200": + description: Block upload result + content: + application/json: + schema: + $ref: "#/components/schemas/BlockUploadResponse" + example: + 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. + This endpoint supports pagination and streaming of transaction data. + parameters: + - name: page_id in: query + description: Transaction ID to start pagination from schema: type: string - description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest - known tip (includes unconfirmed state). + pattern: "^[0-9a-f]{64}$" + requestBody: + required: true + content: + application/octet-stream: + schema: + type: string + format: binary + description: | + Binary SIP-003 encoding of `MemPoolSyncData` + (`BloomFilter` or `TxTags` variants). + properties: + transactions: + type: array + items: + type: string + description: Transaction IDs + responses: + "200": + description: Stream of missing transactions + content: + application/octet-stream: + schema: + type: string + format: binary + description: | + Binary stream of transactions and pagination data. + The stream contains serialized transactions followed by a page ID for continuation. + "400": + $ref: "#/components/responses/BadRequest" + "500": + $ref: "#/components/responses/InternalServerError" + + /v3/blocks/upload: + post: + summary: Upload a Nakamoto block + tags: + - Blocks + # Two alternative security requirements: + # - With `rpcAuth` when broadcast=1 + # - No auth when broadcast is absent + security: + - rpcAuth: [] + - {} + operationId: uploadNakamotoBlock + description: | + Upload a Nakamoto block to the node for processing. + + - **Body** - must be the binary (SIP-003) serialization of a `NakamotoBlock`. + - **Authentication** - only required when the query parameter `broadcast=1` is supplied. + In that case the caller **must** include an `Authorization` header. + parameters: + - name: broadcast + in: query + description: | + If set to `"1"` the node will broadcast the uploaded block to peers. + When present the request must include a valid `Authorization` header. + schema: + type: string + enum: ["1"] required: false requestBody: - description: map of arguments and the simulated tx-sender where sender is either a Contract identifier or a normal Stacks address, and arguments is an array of hex serialized Clarity values. required: true content: - application/json: + application/octet-stream: schema: - $ref: './entities/contracts/read-only-function-args.schema.json' - example: - sender: 'SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info' - arguments: - - '0x0011...' - - '0x00231...' + type: string + format: binary + description: Binary SIP-003 encoding of a `NakamotoBlock` + responses: + "200": + description: Block upload result. + content: + application/json: + schema: + $ref: "#/components/schemas/BlockUploadResponse" + example: + stacks_block_id: "abc123..." + accepted: true + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "500": + $ref: "#/components/responses/InternalServerError" diff --git a/docs/rpc/redocly.yaml b/docs/rpc/redocly.yaml new file mode 100644 index 0000000000..2e1fb27bd9 --- /dev/null +++ b/docs/rpc/redocly.yaml @@ -0,0 +1,12 @@ +apis: + main: + root: ./openapi.yaml + +rules: + # Don't force 4xx responses for all endpoints + operation-4xx-response: off + # Turn off the localhost server warning since it's appropriate for RPC APIs + no-server-example.com: off + +extends: + - recommended