From 8176355b6615b119cd068d67f6fe29732becc0c4 Mon Sep 17 00:00:00 2001 From: Ryan Waits Date: Wed, 2 Oct 2024 10:36:42 -0500 Subject: [PATCH 01/12] remove rpc endpoints from stacks api references --- content/docs/stacks/api/accounts/info.mdx | 146 -------------- content/docs/stacks/api/fees/estimate.mdx | 169 ---------------- .../stacks/api/fees/transfer-estimate.mdx | 104 ---------- content/docs/stacks/api/index.mdx | 18 +- content/docs/stacks/api/info/core-api.mdx | 171 ---------------- content/docs/stacks/api/info/pox-details.mdx | 124 ------------ content/docs/stacks/api/names/name-price.mdx | 119 ------------ .../docs/stacks/api/names/namespace-price.mdx | 119 ------------ .../stacks/api/smart-contracts/interface.mdx | 143 -------------- .../stacks/api/smart-contracts/map-entry.mdx | 170 ---------------- .../stacks/api/smart-contracts/read-only.mdx | 182 ------------------ .../stacks/api/smart-contracts/source.mdx | 112 ----------- .../transactions/broadcast-transaction.mdx | 162 ---------------- 13 files changed, 9 insertions(+), 1730 deletions(-) delete mode 100644 content/docs/stacks/api/accounts/info.mdx delete mode 100644 content/docs/stacks/api/fees/estimate.mdx delete mode 100644 content/docs/stacks/api/fees/transfer-estimate.mdx delete mode 100644 content/docs/stacks/api/info/core-api.mdx delete mode 100644 content/docs/stacks/api/info/pox-details.mdx delete mode 100644 content/docs/stacks/api/names/name-price.mdx delete mode 100644 content/docs/stacks/api/names/namespace-price.mdx delete mode 100644 content/docs/stacks/api/smart-contracts/interface.mdx delete mode 100644 content/docs/stacks/api/smart-contracts/map-entry.mdx delete mode 100644 content/docs/stacks/api/smart-contracts/read-only.mdx delete mode 100644 content/docs/stacks/api/smart-contracts/source.mdx delete mode 100644 content/docs/stacks/api/transactions/broadcast-transaction.mdx diff --git a/content/docs/stacks/api/accounts/info.mdx b/content/docs/stacks/api/accounts/info.mdx deleted file mode 100644 index 7ac57a06..00000000 --- a/content/docs/stacks/api/accounts/info.mdx +++ /dev/null @@ -1,146 +0,0 @@ ---- -title: Get account info -description: Retrieves the account data for a given account or contract identifier. -toc: false ---- - -import { - API, - APIExample, - APIInfo, - APIPlayground, - ExampleResponse, - Property, - Request, - Requests, - Response, - Responses, - ResponseTypes, - Root, - TypeScriptResponse -} from 'fumadocs-openapi/ui'; - - - - - - - -## Get account info - -Retrieves the account data for a given Account or a Contract Identifier - -Where balance is the hex encoding of a unsigned 128-bit integer (big-endian), nonce is an unsigned 64-bit integer, and the proofs are provided as hex strings. - -For non-existent accounts, this does not return a 404 error, rather it returns an object with balance and nonce of 0. - -### Path Parameters - - - -Stacks address or a Contract identifier - -Example: `"SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0"` - - - -### Query Parameters - - - -Returns object without the proof field if set to 0 - - - - - -The Stacks chain tip to query from - - - -| Status code | Description | -| :------ | :------ | -| `200` | Success | - - - - - - - - - - - - - -```bash -curl -X GET "https://api.hiro.so/v2/accounts/SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0?proof=0&tip=string" -``` - - - - - -```js -fetch("https://api.hiro.so/v2/accounts/SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0?proof=0&tip=string", { - method: "GET" -}); -``` - - - - - - - - - -GET request for account data - - - - - -```json -{ - "balance": "string", - "locked": "string", - "unlock_height": 0, - "nonce": 0, - "balance_proof": "string", - "nonce_proof": "string" -} -``` - - - - - -```ts -/** - * GET request for account data - */ -export interface AccountDataResponse { - balance: string; - locked: string; - unlock_height: number; - nonce: number; - balance_proof: string; - nonce_proof: string; -} -``` - - - - - - - - - - - - - - diff --git a/content/docs/stacks/api/fees/estimate.mdx b/content/docs/stacks/api/fees/estimate.mdx deleted file mode 100644 index e6a0cb39..00000000 --- a/content/docs/stacks/api/fees/estimate.mdx +++ /dev/null @@ -1,169 +0,0 @@ ---- -title: Get fee estimate -description: Retrieves an estimated fee rate for transactions. -toc: false ---- - -import { - API, - APIExample, - APIInfo, - APIPlayground, - ExampleResponse, - Property, - Request, - Requests, - Response, - Responses, - ResponseTypes, - Root, - TypeScriptResponse -} from 'fumadocs-openapi/ui'; - - - - - - - -## Get approximate fees for a given transaction - - -If the final transaction's byte size is larger than supplied to `estimated_len`, then applications should increase this fee amount: `fee_rate` x `cost_scalar_change_by_byte` x (`final_size` - `estimated_size`) - - -### Request Body (Optional) - - - -Hex-encoded serialization of the `TransactionPayload` for the transaction. - - - - - -Estimation of the final length (in bytes) of the transaction, including any post-conditions and signatures. - - - -| Status code | Description | -| :------ | :------ | -| `200` | Estimated fees for the transaction | - - - - - - - - - - - - - -```bash -curl -X POST "https://api.hiro.so/v2/fees/transaction" \ - -d '{ - "transaction_payload": "string", - "estimated_len": 0 -}' -``` - - - - - -```js -fetch("https://api.hiro.so/v2/fees/transaction", { - method: "POST" -}); -``` - - - - - - - - - -POST response for estimated fee - - - - - -```json -{ - "estimated_cost_scalar": 0, - "cost_scalar_change_by_byte": 0, - "estimated_cost": { - "read_count": 0, - "read_length": 0, - "runtime": 0, - "write_count": 0, - "write_length": 0 - }, - "estimations": [ - { - "fee_rate": 0, - "fee": 0 - } - ] -} -``` - - - - - -```ts -/** - * POST response for estimated fee - */ -export interface TransactionFeeEstimateResponse { - estimated_cost_scalar: number; - cost_scalar_change_by_byte?: number; - estimated_cost: { - read_count: number; - read_length: number; - runtime: number; - write_count: number; - write_length: number; - }; - estimations?: { - fee_rate?: number; - fee?: number; - }[]; -} -``` - - - - - - - - -The error response will be a JSON object containing a `reason` field. - - - - - `DatabaseError`: This Stacks node has had an internal database error while trying to estimate the costs of the supplied transaction. - - `NoEstimateAvailable`: This Stacks node has not seen this kind of contract-call before, and it cannot provide an estimate yet. - - `CostEstimationDisabled`: This Stacks node does not perform fee or cost estimation, and it cannot respond on this endpoint. - - If the node cannot provide an estimate for the transaction (e.g., if the node has never seen a contract-call for the given contract and function) or if estimation is not configured on this node, a `400` response is returned. - - - - - - - - - - - - diff --git a/content/docs/stacks/api/fees/transfer-estimate.mdx b/content/docs/stacks/api/fees/transfer-estimate.mdx deleted file mode 100644 index d16b0928..00000000 --- a/content/docs/stacks/api/fees/transfer-estimate.mdx +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: Get transfer fee estimate -description: Retrieves an estimated fee rate for STX transfer transactions. -toc: false ---- - -import { - API, - APIExample, - APIInfo, - APIPlayground, - ExampleResponse, - Property, - Request, - Requests, - Response, - Responses, - ResponseTypes, - Root, - TypeScriptResponse -} from 'fumadocs-openapi/ui'; - - - - - - - -## Get estimated fee - -Retrieves an estimated fee rate for STX transfer transactions. This a a fee rate / byte, and is returned as a JSON integer - -| Status code | Description | -| :------ | :------ | -| `200` | Success | - - - - - - - - - - - - - -```bash -curl -X GET "https://api.hiro.so/v2/fees/transfer" -``` - - - - - -```js -fetch("https://api.hiro.so/v2/fees/transfer", { - method: "GET" -}); -``` - - - - - - - - - -GET fee estimates - - - - - -```json -"string" -``` - - - - - -```ts -/** - * GET fee estimates - */ -export type CoreNodeFeeResponse = string; -``` - - - - - - - - - - - - - - diff --git a/content/docs/stacks/api/index.mdx b/content/docs/stacks/api/index.mdx index 8dedf3e5..36df06c1 100644 --- a/content/docs/stacks/api/index.mdx +++ b/content/docs/stacks/api/index.mdx @@ -1,6 +1,6 @@ --- title: Overview -description: Query the Stacks blockchain, interact with smart contracts, and broadcast transactions with the Stacks Blockchain API, all via a familiar REST interface. +description: Query the Stacks blockchain with the Stacks Blockchain API. toc: false --- @@ -11,7 +11,7 @@ The Stacks Blockchain API expands the intentionally minimal RPC endpoints availa ## Popular endpoints -Use our `/v2` route to access the Stacks API node endpoints. For more information, see the [Stacks Node RPC API](https://docs.stacks.co/reference/api#stacks-node-rpc-api-endpoints) documentation. +For more information on querying the Stacks core RPC endpoints, see the [Stacks Core RPC](/stacks/rpc-api) documentation. @@ -21,21 +21,21 @@ Use our `/v2` route to access the Stacks API node endpoints. For more informatio description="Retrieve data about transactions on Stacks." /> ## Related tools -- **[Hiro Archive](/stacks/archive)**: Bootstrap your own instance of the Stacks Blockchain API with the Hiro Archive and save days of setup time. +- **[Stacks Core RPC](/stacks/rpc-api)**: Fetch data and broadcast transactions from the Stacks core RPC API. - **[Token Metadata API](/stacks/token-metadata-api)**: Fetch fungible and non-fungible token data on the Stacks blockchain. - **[Stacks Explorer](https://explorer.hiro.so)**: Looking for a front end to verify activity on the Stacks blockchain? Try the Stacks Explorer. diff --git a/content/docs/stacks/api/info/core-api.mdx b/content/docs/stacks/api/info/core-api.mdx deleted file mode 100644 index 5cfb370d..00000000 --- a/content/docs/stacks/api/info/core-api.mdx +++ /dev/null @@ -1,171 +0,0 @@ ---- -title: Get core API info -description: Retrieves information about the Core API, including the server version. -toc: false ---- - -import { - API, - APIExample, - APIInfo, - APIPlayground, - ExampleResponse, - Property, - Request, - Requests, - Response, - Responses, - ResponseTypes, - Root, - TypeScriptResponse -} from 'fumadocs-openapi/ui'; - - - - - - - -## Get Core API info - -Retrieves information about the Core API including the server version - -| Status code | Description | -| :------ | :------ | -| `200` | Success | - - - - - - - - - - - - - -```bash -curl -X GET "https://api.hiro.so/v2/info" -``` - - - - - -```js -fetch("https://api.hiro.so/v2/info", { - method: "GET" -}); -``` - - - - - - - - - -GET request that core node information - - - - - -```json -{ - "peer_version": 402653194, - "pox_consensus": "string", - "burn_block_height": 863576, - "stable_pox_consensus": "string", - "stable_burn_block_height": 863569, - "server_version": "string", - "network_id": 1, - "parent_network_id": 3652501241, - "stacks_tip_height": 167976, - "stacks_tip": "string", - "stacks_tip_consensus_hash": "string", - "unanchored_tip": null, - "exit_at_block_height": null -} -``` - - - - - -```ts -/** - * GET request that core node information - */ -export interface CoreNodeInfoResponse { - /** - * 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 - */ - peer_version: number; - /** - * 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 - */ - pox_consensus: string; - /** - * latest bitcoin chain height - */ - burn_block_height: number; - /** - * same as burn_consensus, but evaluated at stable_burn_block_height - */ - stable_pox_consensus: string; - /** - * leftover from stacks 1.0, basically always burn_block_height - 1 - */ - stable_burn_block_height: number; - /** - * is a version descriptor - */ - server_version: string; - /** - * 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 - */ - network_id: number; - /** - * same as network_id, but for bitcoin - */ - parent_network_id: number; - /** - * 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_height: number; - /** - * the best known block hash for the Stack chain (not including any pending microblocks) - */ - stacks_tip: string; - /** - * the burn chain (i.e., bitcoin) consensus hash at the time that stacks_tip was mined - */ - stacks_tip_consensus_hash: string; - /** - * 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_tip: string; - /** - * the block height at which the testnet network will be reset. not applicable for mainnet - */ - exit_at_block_height: number; -} -``` - - - - - - - - - - - - - - diff --git a/content/docs/stacks/api/info/pox-details.mdx b/content/docs/stacks/api/info/pox-details.mdx deleted file mode 100644 index 12333291..00000000 --- a/content/docs/stacks/api/info/pox-details.mdx +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Get Proof-of-Transfer details -description: Retrieves Proof-of-Transfer (PoX) information. -toc: false ---- - -import { - API, - APIExample, - APIInfo, - APIPlayground, - ExampleResponse, - Property, - Request, - Requests, - Response, - Responses, - ResponseTypes, - Root, - TypeScriptResponse -} from 'fumadocs-openapi/ui'; - - - - - - - -## Get Proof-of-Transfer details - -Retrieves Proof-of-Transfer (PoX) information. Can be used for Stacking. - -| Status code | Description | -| :------ | :------ | -| `200` | Success | - - - - - - - - - - - - - -```bash -curl -X GET "https://api.hiro.so/v2/pox" -``` - - - - - -```js -fetch("https://api.hiro.so/v2/pox", { - method: "GET" -}); -``` - - - - - - - - - -Get Proof of Transfer (PoX) information - - - - - -```json -{ - "contract_id": "string", - "first_burnchain_block_height": 0, - "min_amount_ustx": 0, - "registration_window_length": 0, - "rejection_fraction": 0, - "reward_cycle_id": 0, - "reward_cycle_length": 0, - "rejection_votes_left_required": 0, - "total_liquid_supply_ustx": 0 -} -``` - - - - - -```ts -/** - * Get Proof of Transfer (PoX) information - */ -export interface CoreNodePoxResponse { - contract_id: string; - first_burnchain_block_height: number; - min_amount_ustx: number; - registration_window_length: number; - rejection_fraction: number; - reward_cycle_id: number; - reward_cycle_length: number; - rejection_votes_left_required: number; - total_liquid_supply_ustx: number; -} -``` - - - - - - - - - - - - - - diff --git a/content/docs/stacks/api/names/name-price.mdx b/content/docs/stacks/api/names/name-price.mdx deleted file mode 100644 index 8eba22e3..00000000 --- a/content/docs/stacks/api/names/name-price.mdx +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: Get name price -description: Retrieves the price of a name. -toc: false ---- - -import { - API, - APIExample, - APIInfo, - APIPlayground, - ExampleResponse, - Property, - Request, - Requests, - Response, - Responses, - ResponseTypes, - Root, - TypeScriptResponse -} from 'fumadocs-openapi/ui'; - - - - - - - -## Get name price - -Retrieves the price of a name. The `amount` given will be in the smallest possible units of the currency. -### Path Parameters - - - -the name to query price information for - -Example: `"muneeb.id"` - - - -| Status code | Description | -| :------ | :------ | -| `200` | Success | - - - - - - - - - - - - - -```bash -curl -X GET "https://api.hiro.so/v2/prices/names/muneeb.id" -``` - - - - - -```js -fetch("https://api.hiro.so/v2/prices/names/muneeb.id", { - method: "GET" -}); -``` - - - - - - - - - -Fetch price for name. - - - - - -```json -{ - "units": "string", - "amount": "string" -} -``` - - - - - -```ts -/** - * Fetch price for name. - */ -export interface BnsGetNamePriceResponse { - units: string; - amount: string; -} -``` - - - - - - - - - - - - - - diff --git a/content/docs/stacks/api/names/namespace-price.mdx b/content/docs/stacks/api/names/namespace-price.mdx deleted file mode 100644 index ca744cbb..00000000 --- a/content/docs/stacks/api/names/namespace-price.mdx +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: Get namespace price -description: Retrieves the price of a namespace. -toc: false ---- - -import { - API, - APIExample, - APIInfo, - APIPlayground, - ExampleResponse, - Property, - Request, - Requests, - Response, - Responses, - ResponseTypes, - Root, - TypeScriptResponse -} from 'fumadocs-openapi/ui'; - - - - - - - -## Get Namespace Price - -Retrieves the price of a namespace. The `amount` given will be in the smallest possible units of the currency. -### Path Parameters - - - -the namespace to fetch price for - -Example: `"id"` - - - -| Status code | Description | -| :------ | :------ | -| `200` | Success | - - - - - - - - - - - - - -```bash -curl -X GET "https://api.hiro.so/v2/prices/namespaces/id" -``` - - - - - -```js -fetch("https://api.hiro.so/v2/prices/namespaces/id", { - method: "GET" -}); -``` - - - - - - - - - -Fetch price for namespace. - - - - - -```json -{ - "units": "string", - "amount": "string" -} -``` - - - - - -```ts -/** - * Fetch price for namespace. - */ -export interface BnsGetNamespacePriceResponse { - units: string; - amount: string; -} -``` - - - - - - - - - - - - - - diff --git a/content/docs/stacks/api/smart-contracts/interface.mdx b/content/docs/stacks/api/smart-contracts/interface.mdx deleted file mode 100644 index d1aea4b1..00000000 --- a/content/docs/stacks/api/smart-contracts/interface.mdx +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: Get contract interface -description: Retrieves a list of functions, variables, maps, fungible tokens and non-fungible tokens for a given smart contract. -toc: false ---- - -import { - API, - APIExample, - APIInfo, - APIPlayground, - ExampleResponse, - Property, - Request, - Requests, - Response, - Responses, - ResponseTypes, - Root, - TypeScriptResponse -} from 'fumadocs-openapi/ui'; - - - - - - - -## Get contract interface - -Retrieves a contract interface with a given `contract_address` and `contract name` - -| Status code | Description | -| :------ | :------ | -| `200` | Contract interface | - - - - - - - - - - - - - -```bash -curl -X GET "https://api.hiro.so/v2/contracts/interface/%7Bcontract_address%7D/%7Bcontract_name%7D" -``` - - - - - -```js -fetch("https://api.hiro.so/v2/contracts/interface/%7Bcontract_address%7D/%7Bcontract_name%7D", { - method: "GET" -}); -``` - - - - - - - - - -GET request to get contract interface - - - - - -```json -{ - "functions": [ - {} - ], - "variables": [ - {} - ], - "maps": [ - {} - ], - "fungible_tokens": [ - {} - ], - "non_fungible_tokens": [ - {} - ], - "epoch": "string", - "clarity_version": "string" -} -``` - - - - - -```ts -/** - * GET request to get contract interface - */ -export interface ContractInterfaceResponse { - /** - * List of defined methods - */ - functions: {}[]; - /** - * List of defined variables - */ - variables: {}[]; - /** - * List of defined data-maps - */ - maps: {}[]; - /** - * List of fungible tokens in the contract - */ - fungible_tokens: {}[]; - /** - * List of non-fungible tokens in the contract - */ - non_fungible_tokens: {}[]; -} -``` - - - - - - - - - - - - - - diff --git a/content/docs/stacks/api/smart-contracts/map-entry.mdx b/content/docs/stacks/api/smart-contracts/map-entry.mdx deleted file mode 100644 index dc211d0d..00000000 --- a/content/docs/stacks/api/smart-contracts/map-entry.mdx +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: Get contract map entry -description: Retrieves a specific entry from a contract data map. -toc: false ---- - -import { - API, - APIExample, - APIInfo, - APIPlayground, - ExampleResponse, - Property, - Request, - Requests, - Response, - Responses, - ResponseTypes, - Root, - TypeScriptResponse -} from 'fumadocs-openapi/ui'; - - - - - - - -## Get specific data-map inside a contract - -Attempt to fetch data from a contract data map. The contract is identified with Stacks Address `contract_address` and Contract Name `contract_address` in the URL path. The map is identified with [Map Name]. - -The key to lookup in the map is supplied via the POST body. This should be supplied as the hex string serialization of the key (which should be a Clarity value). Note, this is a JSON string atom. - -In the response, `data` is the hex serialization of the map response. Note that map responses are Clarity option types, for non-existent values, this is a serialized none, and for all other responses, it is a serialized (some ...) object. - -### Request Body - -Hex string serialization of the lookup key (which should be a Clarity value) - - - - - -### Path Parameters - - - -Stacks address - -Example: `"SPSCWDV3RKV5ZRN1FQD84YE1NQFEDJ9R1F4DYQ11"` - - - - - -Contract name - -Example: `"newyorkcitycoin-core-v2"` - - - - - -Map name - -Example: `"approved-contracts"` - - - -### Query Parameters - - - -Returns object without the proof field when set to 0 - - - - - -The Stacks chain tip to query from - - - -| Status code | Description | -| :------ | :------ | -| `200` | Success | -| `400` | Failed loading data map | - - - - - - - - - - - - - -```bash -curl -X POST "https://api.hiro.so/v2/map_entry/SPSCWDV3RKV5ZRN1FQD84YE1NQFEDJ9R1F4DYQ11/newyorkcitycoin-core-v2/approved-contracts?proof=0&tip=string" \ - -d 'string' -``` - - - - - -```js -fetch("https://api.hiro.so/v2/map_entry/SPSCWDV3RKV5ZRN1FQD84YE1NQFEDJ9R1F4DYQ11/newyorkcitycoin-core-v2/approved-contracts?proof=0&tip=string", { - method: "POST" -}); -``` - - - - - - - - - -Response of get data map entry request - - - - - -```json -{ - "data": "string", - "proof": "string" -} -``` - - - - - -```ts -/** - * Response of get data map entry request - */ -export interface MapEntryResponse { - /** - * Hex-encoded string of clarity value. It is always an optional tuple. - */ - data: string; - /** - * Hex-encoded string of the MARF proof for the data - */ - proof?: string; -} -``` - - - - - - - - - - - - - - diff --git a/content/docs/stacks/api/smart-contracts/read-only.mdx b/content/docs/stacks/api/smart-contracts/read-only.mdx deleted file mode 100644 index 739acd28..00000000 --- a/content/docs/stacks/api/smart-contracts/read-only.mdx +++ /dev/null @@ -1,182 +0,0 @@ ---- -title: Call read-only function -description: Calls a read-only public function on a given smart contract. -toc: false ---- - -import { - API, - APIExample, - APIInfo, - APIPlayground, - ExampleResponse, - Property, - Request, - Requests, - Response, - Responses, - ResponseTypes, - Root, - TypeScriptResponse -} from 'fumadocs-openapi/ui'; - - - - - - - -## Call read-only function - -Call a read-only public function on a given smart contract. - -The smart contract and function are specified using the URL path. The arguments and the simulated tx-sender are supplied via the POST body in the following JSON format: - -### Request Body - -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. - - - -The simulated tx-sender - - - -"} required={true} deprecated={undefined}> - -An array of hex serialized Clarity values - - -### Path Parameters - - - -Stacks address - -Example: `"SP3D6PV2ACBPEKYJTCMH7HEN02KP87QSP8KTEH335"` - - - - - -Contract name - -Example: `"mega"` - - - - - -Function name - -Example: `"get-balance"` - - - -### Query Parameters - - - -The Stacks chain tip to query from - - - -| Status code | Description | -| :------ | :------ | -| `200` | Success | - - - - - - - - - - - - - -```bash -curl -X POST "https://api.hiro.so/v2/contracts/call-read/SP3D6PV2ACBPEKYJTCMH7HEN02KP87QSP8KTEH335/mega/get-balance" \ - -H "Content-Type: application/json" \ - -d '{ - "sender": "SP187Y7NRSG3T9Z9WTSWNEN3XRV1YSJWS81C7JKV7", - "arguments": [ - "0x0516da6b6c4a62ece9fa5a652278baa014ec83df3644" - ] - }' -``` - - - - - -```js -const body = JSON.stringify({ - sender: "SP187Y7NRSG3T9Z9WTSWNEN3XRV1YSJWS81C7JKV7", - arguments: ["0x0516da6b6c4a62ece9fa5a652278baa014ec83df3644"], -}); - -fetch( - "https://api.hiro.so/v2/contracts/call-read/SP3D6PV2ACBPEKYJTCMH7HEN02KP87QSP8KTEH335/mega/get-balance", - { - headers: { "Content-Type": "application/json" }, - method: "POST", - body, - } -); - -const responseBody = await response.json(); -``` - - - - - - - - - -GET request to get contract source - - - - - -```json -{ - "okay": true, - "result": "string", - "cause": "string" -} -``` - - - - - -```ts -/** - * GET request to get contract source - */ -export interface ReadOnlyFunctionSuccessResponse { - okay: boolean; - result?: string; - cause?: string; -} -``` - - - - - - - - - - - - - - diff --git a/content/docs/stacks/api/smart-contracts/source.mdx b/content/docs/stacks/api/smart-contracts/source.mdx deleted file mode 100644 index e6bc4894..00000000 --- a/content/docs/stacks/api/smart-contracts/source.mdx +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: Get contract source -description: Retrieves the Clarity source code of a given contract, along with the block height it was published in, and the MARF proof for the data. -toc: false ---- - -import { - API, - APIExample, - APIInfo, - APIPlayground, - ExampleResponse, - Property, - Request, - Requests, - Response, - Responses, - ResponseTypes, - Root, - TypeScriptResponse -} from 'fumadocs-openapi/ui'; - - - - - - - -## Get contract source - -Retrieves the Clarity source code of a given contract, along with the block height it was published in, and the MARF proof for the data - -| Status code | Description | -| :------ | :------ | -| `200` | Success | - - - - - - - - - - - - - -```bash -curl -X GET "https://api.hiro.so/v2/contracts/source/%7Bcontract_address%7D/%7Bcontract_name%7D" -``` - - - - - -```js -fetch("https://api.hiro.so/v2/contracts/source/%7Bcontract_address%7D/%7Bcontract_name%7D", { - method: "GET" -}); -``` - - - - - - - - - -GET request to get contract source - - - - - -```json -{ - "source": "string", - "publish_height": 0, - "proof": "string" -} -``` - - - - - -```ts -/** - * GET request to get contract source - */ -export interface ContractSourceResponse { - source: string; - publish_height: number; - proof: string; -} -``` - - - - - - - - - - - - - - diff --git a/content/docs/stacks/api/transactions/broadcast-transaction.mdx b/content/docs/stacks/api/transactions/broadcast-transaction.mdx deleted file mode 100644 index 7cb38056..00000000 --- a/content/docs/stacks/api/transactions/broadcast-transaction.mdx +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Broadcast transaction -description: Broadcasts raw transactions on the network. -toc: false ---- - -import { - API, - APIExample, - APIInfo, - APIPlayground, - ExampleResponse, - Property, - Request, - Requests, - Response, - Responses, - ResponseTypes, - Root, - TypeScriptResponse -} from 'fumadocs-openapi/ui'; - - - - - - - -## Broadcast raw transaction - -Broadcasts raw transactions on the network. You can use the [@stacks/transactions](https://github.com/blockstack/stacks.js) project to generate a raw transaction payload. - -### Request Body (Optional) - - - -Example: `"binary format of 00000000010400bed38c2aadffa348931bcb542880ff79d607afec000000000000000000000000000000c800012b0b1fff6cccd0974966dcd665835838f0985be508e1322e09fb3d751eca132c492bda720f9ef1768d14fdabed6127560ba52d5e3ac470dcb60b784e97dc88c9030200000000000516df0ba3e79792be7be5e50a370289accfc8c9e032000000000000303974657374206d656d6f00000000000000000000000000000000000000000000000000"` - -Format: `"binary"` - - - -| Status code | Description | -| :------ | :------ | -| `200` | Transaction id of successful post of a raw tx to the node's mempool | -| `400` | Rejections result in a 400 error | - - - - - - - - - - - - - -```bash -curl -X POST "https://api.hiro.so/v2/transactions" \ - -d 'binary format of 00000000010400bed38c2aadffa348931bcb542880ff79d607afec000000000000000000000000000000c800012b0b1fff6cccd0974966dcd665835838f0985be508e1322e09fb3d751eca132c492bda720f9ef1768d14fdabed6127560ba52d5e3ac470dcb60b784e97dc88c9030200000000000516df0ba3e79792be7be5e50a370289accfc8c9e032000000000000303974657374206d656d6f00000000000000000000000000000000000000000000000000' -``` - - - - - -```js -fetch("https://api.hiro.so/v2/transactions", { - method: "POST" -}); -``` - - - - - - - - - - - - - -```json -"e161978626f216b2141b156ade10501207ae535fa365a13ef5d7a7c9310a09f2" -``` - - - - - -```ts -export type Response = string; -``` - - - - - - - - - -GET request that returns transactions - - - - - -```json -{ - "error": "string", - "reason": "string", - "reason_data": {}, - "txid": "string" -} -``` - - - - - -```ts -/** - * GET request that returns transactions - */ -export interface PostCoreNodeTransactionsError { - /** - * The error - */ - error: string; - /** - * The reason for the error - */ - reason: string; - /** - * More details about the reason - */ - reason_data: {}; - /** - * The relevant transaction id - */ - txid: string; -} -``` - - - - - - - - - - - - - - From b3aa939f4ff1927e7de2538654315fd5c975519b Mon Sep 17 00:00:00 2001 From: Ryan Waits Date: Wed, 2 Oct 2024 10:36:50 -0500 Subject: [PATCH 02/12] add rpc endpoints --- app/(docs)/[...slug]/page.tsx | 1 + content/docs/stacks/meta.json | 1 + 2 files changed, 2 insertions(+) diff --git a/app/(docs)/[...slug]/page.tsx b/app/(docs)/[...slug]/page.tsx index 41700616..8b229e4f 100644 --- a/app/(docs)/[...slug]/page.tsx +++ b/app/(docs)/[...slug]/page.tsx @@ -29,6 +29,7 @@ export default function Page({ params }: { params: Param }): JSX.Element { hacks: "Hiro Hacks", "clarinet-js-sdk": "Clarinet JS SDK", "platform-api": "Platform API", + "rpc-api": "Stacks Core RPC", }; if (page.file?.name === "index" && page.slugs[1]) { diff --git a/content/docs/stacks/meta.json b/content/docs/stacks/meta.json index 93c608eb..e36457d2 100644 --- a/content/docs/stacks/meta.json +++ b/content/docs/stacks/meta.json @@ -15,6 +15,7 @@ "api", "token-metadata-api", "platform-api", + "rpc-api", "api-keys", "rate-limiting", "------", From c3e73f575fea85d67ba32b098451bf3a5f543438 Mon Sep 17 00:00:00 2001 From: Ryan Waits Date: Wed, 2 Oct 2024 10:37:03 -0500 Subject: [PATCH 03/12] add new rpc section --- content/docs/stacks/rpc-api/accounts/info.mdx | 146 ++++++++++++++ .../docs/stacks/rpc-api/accounts/meta.json | 16 ++ content/docs/stacks/rpc-api/fees/estimate.mdx | 169 ++++++++++++++++ content/docs/stacks/rpc-api/fees/index.mdx | 6 + content/docs/stacks/rpc-api/fees/meta.json | 5 + .../stacks/rpc-api/fees/transfer-estimate.mdx | 104 ++++++++++ content/docs/stacks/rpc-api/index.mdx | 44 +++++ content/docs/stacks/rpc-api/info/core-api.mdx | 171 ++++++++++++++++ content/docs/stacks/rpc-api/info/index.mdx | 6 + content/docs/stacks/rpc-api/info/meta.json | 15 ++ .../docs/stacks/rpc-api/info/pox-details.mdx | 124 ++++++++++++ content/docs/stacks/rpc-api/meta.json | 15 ++ content/docs/stacks/rpc-api/names/index.mdx | 6 + content/docs/stacks/rpc-api/names/meta.json | 16 ++ .../docs/stacks/rpc-api/names/name-price.mdx | 119 ++++++++++++ .../stacks/rpc-api/names/namespace-price.mdx | 119 ++++++++++++ .../stacks/rpc-api/smart-contracts/index.mdx | 6 + .../rpc-api/smart-contracts/interface.mdx | 143 ++++++++++++++ .../rpc-api/smart-contracts/map-entry.mdx | 170 ++++++++++++++++ .../stacks/rpc-api/smart-contracts/meta.json | 15 ++ .../rpc-api/smart-contracts/read-only.mdx | 182 ++++++++++++++++++ .../stacks/rpc-api/smart-contracts/source.mdx | 112 +++++++++++ .../transactions/broadcast-transaction.mdx | 162 ++++++++++++++++ .../stacks/rpc-api/transactions/index.mdx | 6 + .../stacks/rpc-api/transactions/meta.json | 20 ++ 25 files changed, 1897 insertions(+) create mode 100644 content/docs/stacks/rpc-api/accounts/info.mdx create mode 100644 content/docs/stacks/rpc-api/accounts/meta.json create mode 100644 content/docs/stacks/rpc-api/fees/estimate.mdx create mode 100644 content/docs/stacks/rpc-api/fees/index.mdx create mode 100644 content/docs/stacks/rpc-api/fees/meta.json create mode 100644 content/docs/stacks/rpc-api/fees/transfer-estimate.mdx create mode 100644 content/docs/stacks/rpc-api/index.mdx create mode 100644 content/docs/stacks/rpc-api/info/core-api.mdx create mode 100644 content/docs/stacks/rpc-api/info/index.mdx create mode 100644 content/docs/stacks/rpc-api/info/meta.json create mode 100644 content/docs/stacks/rpc-api/info/pox-details.mdx create mode 100644 content/docs/stacks/rpc-api/meta.json create mode 100644 content/docs/stacks/rpc-api/names/index.mdx create mode 100644 content/docs/stacks/rpc-api/names/meta.json create mode 100644 content/docs/stacks/rpc-api/names/name-price.mdx create mode 100644 content/docs/stacks/rpc-api/names/namespace-price.mdx create mode 100644 content/docs/stacks/rpc-api/smart-contracts/index.mdx create mode 100644 content/docs/stacks/rpc-api/smart-contracts/interface.mdx create mode 100644 content/docs/stacks/rpc-api/smart-contracts/map-entry.mdx create mode 100644 content/docs/stacks/rpc-api/smart-contracts/meta.json create mode 100644 content/docs/stacks/rpc-api/smart-contracts/read-only.mdx create mode 100644 content/docs/stacks/rpc-api/smart-contracts/source.mdx create mode 100644 content/docs/stacks/rpc-api/transactions/broadcast-transaction.mdx create mode 100644 content/docs/stacks/rpc-api/transactions/index.mdx create mode 100644 content/docs/stacks/rpc-api/transactions/meta.json diff --git a/content/docs/stacks/rpc-api/accounts/info.mdx b/content/docs/stacks/rpc-api/accounts/info.mdx new file mode 100644 index 00000000..7ac57a06 --- /dev/null +++ b/content/docs/stacks/rpc-api/accounts/info.mdx @@ -0,0 +1,146 @@ +--- +title: Get account info +description: Retrieves the account data for a given account or contract identifier. +toc: false +--- + +import { + API, + APIExample, + APIInfo, + APIPlayground, + ExampleResponse, + Property, + Request, + Requests, + Response, + Responses, + ResponseTypes, + Root, + TypeScriptResponse +} from 'fumadocs-openapi/ui'; + + + + + + + +## Get account info + +Retrieves the account data for a given Account or a Contract Identifier + +Where balance is the hex encoding of a unsigned 128-bit integer (big-endian), nonce is an unsigned 64-bit integer, and the proofs are provided as hex strings. + +For non-existent accounts, this does not return a 404 error, rather it returns an object with balance and nonce of 0. + +### Path Parameters + + + +Stacks address or a Contract identifier + +Example: `"SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0"` + + + +### Query Parameters + + + +Returns object without the proof field if set to 0 + + + + + +The Stacks chain tip to query from + + + +| Status code | Description | +| :------ | :------ | +| `200` | Success | + + + + + + + + + + + + + +```bash +curl -X GET "https://api.hiro.so/v2/accounts/SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0?proof=0&tip=string" +``` + + + + + +```js +fetch("https://api.hiro.so/v2/accounts/SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0?proof=0&tip=string", { + method: "GET" +}); +``` + + + + + + + + + +GET request for account data + + + + + +```json +{ + "balance": "string", + "locked": "string", + "unlock_height": 0, + "nonce": 0, + "balance_proof": "string", + "nonce_proof": "string" +} +``` + + + + + +```ts +/** + * GET request for account data + */ +export interface AccountDataResponse { + balance: string; + locked: string; + unlock_height: number; + nonce: number; + balance_proof: string; + nonce_proof: string; +} +``` + + + + + + + + + + + + + + diff --git a/content/docs/stacks/rpc-api/accounts/meta.json b/content/docs/stacks/rpc-api/accounts/meta.json new file mode 100644 index 00000000..c361f191 --- /dev/null +++ b/content/docs/stacks/rpc-api/accounts/meta.json @@ -0,0 +1,16 @@ +{ + "title": "Accounts", + "pages": [ + "info", + "assets", + "balances", + "stx-balances", + "inbound-stx-transfers", + "transactions", + "transactions-with-transfers", + "transaction-with-transfers", + "nft-events", + "latest-nonce" + ], + "defaultOpen": false +} \ No newline at end of file diff --git a/content/docs/stacks/rpc-api/fees/estimate.mdx b/content/docs/stacks/rpc-api/fees/estimate.mdx new file mode 100644 index 00000000..e6a0cb39 --- /dev/null +++ b/content/docs/stacks/rpc-api/fees/estimate.mdx @@ -0,0 +1,169 @@ +--- +title: Get fee estimate +description: Retrieves an estimated fee rate for transactions. +toc: false +--- + +import { + API, + APIExample, + APIInfo, + APIPlayground, + ExampleResponse, + Property, + Request, + Requests, + Response, + Responses, + ResponseTypes, + Root, + TypeScriptResponse +} from 'fumadocs-openapi/ui'; + + + + + + + +## Get approximate fees for a given transaction + + +If the final transaction's byte size is larger than supplied to `estimated_len`, then applications should increase this fee amount: `fee_rate` x `cost_scalar_change_by_byte` x (`final_size` - `estimated_size`) + + +### Request Body (Optional) + + + +Hex-encoded serialization of the `TransactionPayload` for the transaction. + + + + + +Estimation of the final length (in bytes) of the transaction, including any post-conditions and signatures. + + + +| Status code | Description | +| :------ | :------ | +| `200` | Estimated fees for the transaction | + + + + + + + + + + + + + +```bash +curl -X POST "https://api.hiro.so/v2/fees/transaction" \ + -d '{ + "transaction_payload": "string", + "estimated_len": 0 +}' +``` + + + + + +```js +fetch("https://api.hiro.so/v2/fees/transaction", { + method: "POST" +}); +``` + + + + + + + + + +POST response for estimated fee + + + + + +```json +{ + "estimated_cost_scalar": 0, + "cost_scalar_change_by_byte": 0, + "estimated_cost": { + "read_count": 0, + "read_length": 0, + "runtime": 0, + "write_count": 0, + "write_length": 0 + }, + "estimations": [ + { + "fee_rate": 0, + "fee": 0 + } + ] +} +``` + + + + + +```ts +/** + * POST response for estimated fee + */ +export interface TransactionFeeEstimateResponse { + estimated_cost_scalar: number; + cost_scalar_change_by_byte?: number; + estimated_cost: { + read_count: number; + read_length: number; + runtime: number; + write_count: number; + write_length: number; + }; + estimations?: { + fee_rate?: number; + fee?: number; + }[]; +} +``` + + + + + + + + +The error response will be a JSON object containing a `reason` field. + + + + - `DatabaseError`: This Stacks node has had an internal database error while trying to estimate the costs of the supplied transaction. + - `NoEstimateAvailable`: This Stacks node has not seen this kind of contract-call before, and it cannot provide an estimate yet. + - `CostEstimationDisabled`: This Stacks node does not perform fee or cost estimation, and it cannot respond on this endpoint. + + If the node cannot provide an estimate for the transaction (e.g., if the node has never seen a contract-call for the given contract and function) or if estimation is not configured on this node, a `400` response is returned. + + + + + + + + + + + + diff --git a/content/docs/stacks/rpc-api/fees/index.mdx b/content/docs/stacks/rpc-api/fees/index.mdx new file mode 100644 index 00000000..33c4d61f --- /dev/null +++ b/content/docs/stacks/rpc-api/fees/index.mdx @@ -0,0 +1,6 @@ +--- +title: Fees +index: true +toc: false +description: Provide estimates, rates, and approximate calculations for transaction costs. +--- \ No newline at end of file diff --git a/content/docs/stacks/rpc-api/fees/meta.json b/content/docs/stacks/rpc-api/fees/meta.json new file mode 100644 index 00000000..a4e2fce8 --- /dev/null +++ b/content/docs/stacks/rpc-api/fees/meta.json @@ -0,0 +1,5 @@ +{ + "title": "Fees", + "pages": ["..."], + "defaultOpen": false +} \ No newline at end of file diff --git a/content/docs/stacks/rpc-api/fees/transfer-estimate.mdx b/content/docs/stacks/rpc-api/fees/transfer-estimate.mdx new file mode 100644 index 00000000..d16b0928 --- /dev/null +++ b/content/docs/stacks/rpc-api/fees/transfer-estimate.mdx @@ -0,0 +1,104 @@ +--- +title: Get transfer fee estimate +description: Retrieves an estimated fee rate for STX transfer transactions. +toc: false +--- + +import { + API, + APIExample, + APIInfo, + APIPlayground, + ExampleResponse, + Property, + Request, + Requests, + Response, + Responses, + ResponseTypes, + Root, + TypeScriptResponse +} from 'fumadocs-openapi/ui'; + + + + + + + +## Get estimated fee + +Retrieves an estimated fee rate for STX transfer transactions. This a a fee rate / byte, and is returned as a JSON integer + +| Status code | Description | +| :------ | :------ | +| `200` | Success | + + + + + + + + + + + + + +```bash +curl -X GET "https://api.hiro.so/v2/fees/transfer" +``` + + + + + +```js +fetch("https://api.hiro.so/v2/fees/transfer", { + method: "GET" +}); +``` + + + + + + + + + +GET fee estimates + + + + + +```json +"string" +``` + + + + + +```ts +/** + * GET fee estimates + */ +export type CoreNodeFeeResponse = string; +``` + + + + + + + + + + + + + + diff --git a/content/docs/stacks/rpc-api/index.mdx b/content/docs/stacks/rpc-api/index.mdx new file mode 100644 index 00000000..8b8ab84a --- /dev/null +++ b/content/docs/stacks/rpc-api/index.mdx @@ -0,0 +1,44 @@ +--- +title: Overview +description: Query the Stacks core RPC API, interact with smart contracts, and broadcast transactions all via a familiar REST interface. +toc: false +--- + +import { SecondaryCard } from '@/components/card'; + +The Stacks Blockchain API expands the intentionally minimal RPC endpoints available in Stacks nodes and indexes, cleans, and enriches on-chain data to put everything you need at your fingertips. Who knew getting reliable blockchain data could be this easy? + +## Popular endpoints + + + + + + + + +## Related tools + +- **[Stacks Blockchain API](/stacks/api)**: Fetch data from the Stacks Blockchain API. +- **[Token Metadata API](/stacks/token-metadata-api)**: Fetch fungible and non-fungible token data on the Stacks blockchain. +- **[Stacks Explorer](https://explorer.hiro.so)**: Looking for a front end to verify activity on the Stacks blockchain? Try the Stacks Explorer. + +
+ + +Reach out to us on the #api channel on [Discord](https://stacks.chat/) under the Hiro Developer Tools section. There's also a [weekly office hours](https://events.stacks.co/event/HD16484710) on Discord every Thursday at 11am ET. + + + diff --git a/content/docs/stacks/rpc-api/info/core-api.mdx b/content/docs/stacks/rpc-api/info/core-api.mdx new file mode 100644 index 00000000..5cfb370d --- /dev/null +++ b/content/docs/stacks/rpc-api/info/core-api.mdx @@ -0,0 +1,171 @@ +--- +title: Get core API info +description: Retrieves information about the Core API, including the server version. +toc: false +--- + +import { + API, + APIExample, + APIInfo, + APIPlayground, + ExampleResponse, + Property, + Request, + Requests, + Response, + Responses, + ResponseTypes, + Root, + TypeScriptResponse +} from 'fumadocs-openapi/ui'; + + + + + + + +## Get Core API info + +Retrieves information about the Core API including the server version + +| Status code | Description | +| :------ | :------ | +| `200` | Success | + + + + + + + + + + + + + +```bash +curl -X GET "https://api.hiro.so/v2/info" +``` + + + + + +```js +fetch("https://api.hiro.so/v2/info", { + method: "GET" +}); +``` + + + + + + + + + +GET request that core node information + + + + + +```json +{ + "peer_version": 402653194, + "pox_consensus": "string", + "burn_block_height": 863576, + "stable_pox_consensus": "string", + "stable_burn_block_height": 863569, + "server_version": "string", + "network_id": 1, + "parent_network_id": 3652501241, + "stacks_tip_height": 167976, + "stacks_tip": "string", + "stacks_tip_consensus_hash": "string", + "unanchored_tip": null, + "exit_at_block_height": null +} +``` + + + + + +```ts +/** + * GET request that core node information + */ +export interface CoreNodeInfoResponse { + /** + * 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 + */ + peer_version: number; + /** + * 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 + */ + pox_consensus: string; + /** + * latest bitcoin chain height + */ + burn_block_height: number; + /** + * same as burn_consensus, but evaluated at stable_burn_block_height + */ + stable_pox_consensus: string; + /** + * leftover from stacks 1.0, basically always burn_block_height - 1 + */ + stable_burn_block_height: number; + /** + * is a version descriptor + */ + server_version: string; + /** + * 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 + */ + network_id: number; + /** + * same as network_id, but for bitcoin + */ + parent_network_id: number; + /** + * 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_height: number; + /** + * the best known block hash for the Stack chain (not including any pending microblocks) + */ + stacks_tip: string; + /** + * the burn chain (i.e., bitcoin) consensus hash at the time that stacks_tip was mined + */ + stacks_tip_consensus_hash: string; + /** + * 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_tip: string; + /** + * the block height at which the testnet network will be reset. not applicable for mainnet + */ + exit_at_block_height: number; +} +``` + + + + + + + + + + + + + + diff --git a/content/docs/stacks/rpc-api/info/index.mdx b/content/docs/stacks/rpc-api/info/index.mdx new file mode 100644 index 00000000..4106173a --- /dev/null +++ b/content/docs/stacks/rpc-api/info/index.mdx @@ -0,0 +1,6 @@ +--- +title: Info +index: true +toc: false +description: Retrieves information about the Core API and the Stacks network. +--- diff --git a/content/docs/stacks/rpc-api/info/meta.json b/content/docs/stacks/rpc-api/info/meta.json new file mode 100644 index 00000000..f553c6ac --- /dev/null +++ b/content/docs/stacks/rpc-api/info/meta.json @@ -0,0 +1,15 @@ +{ + "title": "Info", + "pages": [ + "status", + "core-api", + "network-block-time", + "network-given-block-time", + "total-and-unlocked-stx-supply", + "legacy-total-and-unlocked-stx-supply", + "total-stx-supply-in-plain-text", + "circulating-stx-supply-in-plain-text", + "pox-details" + ], + "defaultOpen": false +} \ No newline at end of file diff --git a/content/docs/stacks/rpc-api/info/pox-details.mdx b/content/docs/stacks/rpc-api/info/pox-details.mdx new file mode 100644 index 00000000..12333291 --- /dev/null +++ b/content/docs/stacks/rpc-api/info/pox-details.mdx @@ -0,0 +1,124 @@ +--- +title: Get Proof-of-Transfer details +description: Retrieves Proof-of-Transfer (PoX) information. +toc: false +--- + +import { + API, + APIExample, + APIInfo, + APIPlayground, + ExampleResponse, + Property, + Request, + Requests, + Response, + Responses, + ResponseTypes, + Root, + TypeScriptResponse +} from 'fumadocs-openapi/ui'; + + + + + + + +## Get Proof-of-Transfer details + +Retrieves Proof-of-Transfer (PoX) information. Can be used for Stacking. + +| Status code | Description | +| :------ | :------ | +| `200` | Success | + + + + + + + + + + + + + +```bash +curl -X GET "https://api.hiro.so/v2/pox" +``` + + + + + +```js +fetch("https://api.hiro.so/v2/pox", { + method: "GET" +}); +``` + + + + + + + + + +Get Proof of Transfer (PoX) information + + + + + +```json +{ + "contract_id": "string", + "first_burnchain_block_height": 0, + "min_amount_ustx": 0, + "registration_window_length": 0, + "rejection_fraction": 0, + "reward_cycle_id": 0, + "reward_cycle_length": 0, + "rejection_votes_left_required": 0, + "total_liquid_supply_ustx": 0 +} +``` + + + + + +```ts +/** + * Get Proof of Transfer (PoX) information + */ +export interface CoreNodePoxResponse { + contract_id: string; + first_burnchain_block_height: number; + min_amount_ustx: number; + registration_window_length: number; + rejection_fraction: number; + reward_cycle_id: number; + reward_cycle_length: number; + rejection_votes_left_required: number; + total_liquid_supply_ustx: number; +} +``` + + + + + + + + + + + + + + diff --git a/content/docs/stacks/rpc-api/meta.json b/content/docs/stacks/rpc-api/meta.json new file mode 100644 index 00000000..b17def52 --- /dev/null +++ b/content/docs/stacks/rpc-api/meta.json @@ -0,0 +1,15 @@ +{ + "title": "Stacks Core RPC", + "root": true, + "pages": [ + "---Stacks Core RPC---", + "index", + "---API Reference---", + "accounts", + "transactions", + "fees", + "smart-contracts", + "names", + "info" + ] +} diff --git a/content/docs/stacks/rpc-api/names/index.mdx b/content/docs/stacks/rpc-api/names/index.mdx new file mode 100644 index 00000000..b1e2ce35 --- /dev/null +++ b/content/docs/stacks/rpc-api/names/index.mdx @@ -0,0 +1,6 @@ +--- +title: Names +index: true +toc: false +description: Manages and retrieve information on blockchain namespaces, names, and related details. +--- \ No newline at end of file diff --git a/content/docs/stacks/rpc-api/names/meta.json b/content/docs/stacks/rpc-api/names/meta.json new file mode 100644 index 00000000..8c03640e --- /dev/null +++ b/content/docs/stacks/rpc-api/names/meta.json @@ -0,0 +1,16 @@ +{ + "title": "Names", + "pages": [ + "namespaces", + "names", + "namespace-names", + "namespace-price", + "name-price", + "name-details", + "name-subdomains", + "name-zonefile", + "historical-zonefile", + "owned-by-address" + ], + "defaultOpen": false +} diff --git a/content/docs/stacks/rpc-api/names/name-price.mdx b/content/docs/stacks/rpc-api/names/name-price.mdx new file mode 100644 index 00000000..8eba22e3 --- /dev/null +++ b/content/docs/stacks/rpc-api/names/name-price.mdx @@ -0,0 +1,119 @@ +--- +title: Get name price +description: Retrieves the price of a name. +toc: false +--- + +import { + API, + APIExample, + APIInfo, + APIPlayground, + ExampleResponse, + Property, + Request, + Requests, + Response, + Responses, + ResponseTypes, + Root, + TypeScriptResponse +} from 'fumadocs-openapi/ui'; + + + + + + + +## Get name price + +Retrieves the price of a name. The `amount` given will be in the smallest possible units of the currency. +### Path Parameters + + + +the name to query price information for + +Example: `"muneeb.id"` + + + +| Status code | Description | +| :------ | :------ | +| `200` | Success | + + + + + + + + + + + + + +```bash +curl -X GET "https://api.hiro.so/v2/prices/names/muneeb.id" +``` + + + + + +```js +fetch("https://api.hiro.so/v2/prices/names/muneeb.id", { + method: "GET" +}); +``` + + + + + + + + + +Fetch price for name. + + + + + +```json +{ + "units": "string", + "amount": "string" +} +``` + + + + + +```ts +/** + * Fetch price for name. + */ +export interface BnsGetNamePriceResponse { + units: string; + amount: string; +} +``` + + + + + + + + + + + + + + diff --git a/content/docs/stacks/rpc-api/names/namespace-price.mdx b/content/docs/stacks/rpc-api/names/namespace-price.mdx new file mode 100644 index 00000000..ca744cbb --- /dev/null +++ b/content/docs/stacks/rpc-api/names/namespace-price.mdx @@ -0,0 +1,119 @@ +--- +title: Get namespace price +description: Retrieves the price of a namespace. +toc: false +--- + +import { + API, + APIExample, + APIInfo, + APIPlayground, + ExampleResponse, + Property, + Request, + Requests, + Response, + Responses, + ResponseTypes, + Root, + TypeScriptResponse +} from 'fumadocs-openapi/ui'; + + + + + + + +## Get Namespace Price + +Retrieves the price of a namespace. The `amount` given will be in the smallest possible units of the currency. +### Path Parameters + + + +the namespace to fetch price for + +Example: `"id"` + + + +| Status code | Description | +| :------ | :------ | +| `200` | Success | + + + + + + + + + + + + + +```bash +curl -X GET "https://api.hiro.so/v2/prices/namespaces/id" +``` + + + + + +```js +fetch("https://api.hiro.so/v2/prices/namespaces/id", { + method: "GET" +}); +``` + + + + + + + + + +Fetch price for namespace. + + + + + +```json +{ + "units": "string", + "amount": "string" +} +``` + + + + + +```ts +/** + * Fetch price for namespace. + */ +export interface BnsGetNamespacePriceResponse { + units: string; + amount: string; +} +``` + + + + + + + + + + + + + + diff --git a/content/docs/stacks/rpc-api/smart-contracts/index.mdx b/content/docs/stacks/rpc-api/smart-contracts/index.mdx new file mode 100644 index 00000000..32e39b1a --- /dev/null +++ b/content/docs/stacks/rpc-api/smart-contracts/index.mdx @@ -0,0 +1,6 @@ +--- +title: Smart contracts +index: true +toc: false +description: Provide information and facilitate interactions with smart contracts. +--- diff --git a/content/docs/stacks/rpc-api/smart-contracts/interface.mdx b/content/docs/stacks/rpc-api/smart-contracts/interface.mdx new file mode 100644 index 00000000..d1aea4b1 --- /dev/null +++ b/content/docs/stacks/rpc-api/smart-contracts/interface.mdx @@ -0,0 +1,143 @@ +--- +title: Get contract interface +description: Retrieves a list of functions, variables, maps, fungible tokens and non-fungible tokens for a given smart contract. +toc: false +--- + +import { + API, + APIExample, + APIInfo, + APIPlayground, + ExampleResponse, + Property, + Request, + Requests, + Response, + Responses, + ResponseTypes, + Root, + TypeScriptResponse +} from 'fumadocs-openapi/ui'; + + + + + + + +## Get contract interface + +Retrieves a contract interface with a given `contract_address` and `contract name` + +| Status code | Description | +| :------ | :------ | +| `200` | Contract interface | + + + + + + + + + + + + + +```bash +curl -X GET "https://api.hiro.so/v2/contracts/interface/%7Bcontract_address%7D/%7Bcontract_name%7D" +``` + + + + + +```js +fetch("https://api.hiro.so/v2/contracts/interface/%7Bcontract_address%7D/%7Bcontract_name%7D", { + method: "GET" +}); +``` + + + + + + + + + +GET request to get contract interface + + + + + +```json +{ + "functions": [ + {} + ], + "variables": [ + {} + ], + "maps": [ + {} + ], + "fungible_tokens": [ + {} + ], + "non_fungible_tokens": [ + {} + ], + "epoch": "string", + "clarity_version": "string" +} +``` + + + + + +```ts +/** + * GET request to get contract interface + */ +export interface ContractInterfaceResponse { + /** + * List of defined methods + */ + functions: {}[]; + /** + * List of defined variables + */ + variables: {}[]; + /** + * List of defined data-maps + */ + maps: {}[]; + /** + * List of fungible tokens in the contract + */ + fungible_tokens: {}[]; + /** + * List of non-fungible tokens in the contract + */ + non_fungible_tokens: {}[]; +} +``` + + + + + + + + + + + + + + diff --git a/content/docs/stacks/rpc-api/smart-contracts/map-entry.mdx b/content/docs/stacks/rpc-api/smart-contracts/map-entry.mdx new file mode 100644 index 00000000..dc211d0d --- /dev/null +++ b/content/docs/stacks/rpc-api/smart-contracts/map-entry.mdx @@ -0,0 +1,170 @@ +--- +title: Get contract map entry +description: Retrieves a specific entry from a contract data map. +toc: false +--- + +import { + API, + APIExample, + APIInfo, + APIPlayground, + ExampleResponse, + Property, + Request, + Requests, + Response, + Responses, + ResponseTypes, + Root, + TypeScriptResponse +} from 'fumadocs-openapi/ui'; + + + + + + + +## Get specific data-map inside a contract + +Attempt to fetch data from a contract data map. The contract is identified with Stacks Address `contract_address` and Contract Name `contract_address` in the URL path. The map is identified with [Map Name]. + +The key to lookup in the map is supplied via the POST body. This should be supplied as the hex string serialization of the key (which should be a Clarity value). Note, this is a JSON string atom. + +In the response, `data` is the hex serialization of the map response. Note that map responses are Clarity option types, for non-existent values, this is a serialized none, and for all other responses, it is a serialized (some ...) object. + +### Request Body + +Hex string serialization of the lookup key (which should be a Clarity value) + + + + + +### Path Parameters + + + +Stacks address + +Example: `"SPSCWDV3RKV5ZRN1FQD84YE1NQFEDJ9R1F4DYQ11"` + + + + + +Contract name + +Example: `"newyorkcitycoin-core-v2"` + + + + + +Map name + +Example: `"approved-contracts"` + + + +### Query Parameters + + + +Returns object without the proof field when set to 0 + + + + + +The Stacks chain tip to query from + + + +| Status code | Description | +| :------ | :------ | +| `200` | Success | +| `400` | Failed loading data map | + + + + + + + + + + + + + +```bash +curl -X POST "https://api.hiro.so/v2/map_entry/SPSCWDV3RKV5ZRN1FQD84YE1NQFEDJ9R1F4DYQ11/newyorkcitycoin-core-v2/approved-contracts?proof=0&tip=string" \ + -d 'string' +``` + + + + + +```js +fetch("https://api.hiro.so/v2/map_entry/SPSCWDV3RKV5ZRN1FQD84YE1NQFEDJ9R1F4DYQ11/newyorkcitycoin-core-v2/approved-contracts?proof=0&tip=string", { + method: "POST" +}); +``` + + + + + + + + + +Response of get data map entry request + + + + + +```json +{ + "data": "string", + "proof": "string" +} +``` + + + + + +```ts +/** + * Response of get data map entry request + */ +export interface MapEntryResponse { + /** + * Hex-encoded string of clarity value. It is always an optional tuple. + */ + data: string; + /** + * Hex-encoded string of the MARF proof for the data + */ + proof?: string; +} +``` + + + + + + + + + + + + + + diff --git a/content/docs/stacks/rpc-api/smart-contracts/meta.json b/content/docs/stacks/rpc-api/smart-contracts/meta.json new file mode 100644 index 00000000..a0aff84c --- /dev/null +++ b/content/docs/stacks/rpc-api/smart-contracts/meta.json @@ -0,0 +1,15 @@ +{ + "title": "Smart Contracts", + "pages": [ + "status", + "info", + "source", + "by-trait", + "interface", + "map-entry", + "read-only", + "events" + ], + "defaultOpen": false +} + diff --git a/content/docs/stacks/rpc-api/smart-contracts/read-only.mdx b/content/docs/stacks/rpc-api/smart-contracts/read-only.mdx new file mode 100644 index 00000000..739acd28 --- /dev/null +++ b/content/docs/stacks/rpc-api/smart-contracts/read-only.mdx @@ -0,0 +1,182 @@ +--- +title: Call read-only function +description: Calls a read-only public function on a given smart contract. +toc: false +--- + +import { + API, + APIExample, + APIInfo, + APIPlayground, + ExampleResponse, + Property, + Request, + Requests, + Response, + Responses, + ResponseTypes, + Root, + TypeScriptResponse +} from 'fumadocs-openapi/ui'; + + + + + + + +## Call read-only function + +Call a read-only public function on a given smart contract. + +The smart contract and function are specified using the URL path. The arguments and the simulated tx-sender are supplied via the POST body in the following JSON format: + +### Request Body + +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. + + + +The simulated tx-sender + + + +"} required={true} deprecated={undefined}> + +An array of hex serialized Clarity values + + +### Path Parameters + + + +Stacks address + +Example: `"SP3D6PV2ACBPEKYJTCMH7HEN02KP87QSP8KTEH335"` + + + + + +Contract name + +Example: `"mega"` + + + + + +Function name + +Example: `"get-balance"` + + + +### Query Parameters + + + +The Stacks chain tip to query from + + + +| Status code | Description | +| :------ | :------ | +| `200` | Success | + + + + + + + + + + + + + +```bash +curl -X POST "https://api.hiro.so/v2/contracts/call-read/SP3D6PV2ACBPEKYJTCMH7HEN02KP87QSP8KTEH335/mega/get-balance" \ + -H "Content-Type: application/json" \ + -d '{ + "sender": "SP187Y7NRSG3T9Z9WTSWNEN3XRV1YSJWS81C7JKV7", + "arguments": [ + "0x0516da6b6c4a62ece9fa5a652278baa014ec83df3644" + ] + }' +``` + + + + + +```js +const body = JSON.stringify({ + sender: "SP187Y7NRSG3T9Z9WTSWNEN3XRV1YSJWS81C7JKV7", + arguments: ["0x0516da6b6c4a62ece9fa5a652278baa014ec83df3644"], +}); + +fetch( + "https://api.hiro.so/v2/contracts/call-read/SP3D6PV2ACBPEKYJTCMH7HEN02KP87QSP8KTEH335/mega/get-balance", + { + headers: { "Content-Type": "application/json" }, + method: "POST", + body, + } +); + +const responseBody = await response.json(); +``` + + + + + + + + + +GET request to get contract source + + + + + +```json +{ + "okay": true, + "result": "string", + "cause": "string" +} +``` + + + + + +```ts +/** + * GET request to get contract source + */ +export interface ReadOnlyFunctionSuccessResponse { + okay: boolean; + result?: string; + cause?: string; +} +``` + + + + + + + + + + + + + + diff --git a/content/docs/stacks/rpc-api/smart-contracts/source.mdx b/content/docs/stacks/rpc-api/smart-contracts/source.mdx new file mode 100644 index 00000000..e6bc4894 --- /dev/null +++ b/content/docs/stacks/rpc-api/smart-contracts/source.mdx @@ -0,0 +1,112 @@ +--- +title: Get contract source +description: Retrieves the Clarity source code of a given contract, along with the block height it was published in, and the MARF proof for the data. +toc: false +--- + +import { + API, + APIExample, + APIInfo, + APIPlayground, + ExampleResponse, + Property, + Request, + Requests, + Response, + Responses, + ResponseTypes, + Root, + TypeScriptResponse +} from 'fumadocs-openapi/ui'; + + + + + + + +## Get contract source + +Retrieves the Clarity source code of a given contract, along with the block height it was published in, and the MARF proof for the data + +| Status code | Description | +| :------ | :------ | +| `200` | Success | + + + + + + + + + + + + + +```bash +curl -X GET "https://api.hiro.so/v2/contracts/source/%7Bcontract_address%7D/%7Bcontract_name%7D" +``` + + + + + +```js +fetch("https://api.hiro.so/v2/contracts/source/%7Bcontract_address%7D/%7Bcontract_name%7D", { + method: "GET" +}); +``` + + + + + + + + + +GET request to get contract source + + + + + +```json +{ + "source": "string", + "publish_height": 0, + "proof": "string" +} +``` + + + + + +```ts +/** + * GET request to get contract source + */ +export interface ContractSourceResponse { + source: string; + publish_height: number; + proof: string; +} +``` + + + + + + + + + + + + + + diff --git a/content/docs/stacks/rpc-api/transactions/broadcast-transaction.mdx b/content/docs/stacks/rpc-api/transactions/broadcast-transaction.mdx new file mode 100644 index 00000000..7cb38056 --- /dev/null +++ b/content/docs/stacks/rpc-api/transactions/broadcast-transaction.mdx @@ -0,0 +1,162 @@ +--- +title: Broadcast transaction +description: Broadcasts raw transactions on the network. +toc: false +--- + +import { + API, + APIExample, + APIInfo, + APIPlayground, + ExampleResponse, + Property, + Request, + Requests, + Response, + Responses, + ResponseTypes, + Root, + TypeScriptResponse +} from 'fumadocs-openapi/ui'; + + + + + + + +## Broadcast raw transaction + +Broadcasts raw transactions on the network. You can use the [@stacks/transactions](https://github.com/blockstack/stacks.js) project to generate a raw transaction payload. + +### Request Body (Optional) + + + +Example: `"binary format of 00000000010400bed38c2aadffa348931bcb542880ff79d607afec000000000000000000000000000000c800012b0b1fff6cccd0974966dcd665835838f0985be508e1322e09fb3d751eca132c492bda720f9ef1768d14fdabed6127560ba52d5e3ac470dcb60b784e97dc88c9030200000000000516df0ba3e79792be7be5e50a370289accfc8c9e032000000000000303974657374206d656d6f00000000000000000000000000000000000000000000000000"` + +Format: `"binary"` + + + +| Status code | Description | +| :------ | :------ | +| `200` | Transaction id of successful post of a raw tx to the node's mempool | +| `400` | Rejections result in a 400 error | + + + + + + + + + + + + + +```bash +curl -X POST "https://api.hiro.so/v2/transactions" \ + -d 'binary format of 00000000010400bed38c2aadffa348931bcb542880ff79d607afec000000000000000000000000000000c800012b0b1fff6cccd0974966dcd665835838f0985be508e1322e09fb3d751eca132c492bda720f9ef1768d14fdabed6127560ba52d5e3ac470dcb60b784e97dc88c9030200000000000516df0ba3e79792be7be5e50a370289accfc8c9e032000000000000303974657374206d656d6f00000000000000000000000000000000000000000000000000' +``` + + + + + +```js +fetch("https://api.hiro.so/v2/transactions", { + method: "POST" +}); +``` + + + + + + + + + + + + + +```json +"e161978626f216b2141b156ade10501207ae535fa365a13ef5d7a7c9310a09f2" +``` + + + + + +```ts +export type Response = string; +``` + + + + + + + + + +GET request that returns transactions + + + + + +```json +{ + "error": "string", + "reason": "string", + "reason_data": {}, + "txid": "string" +} +``` + + + + + +```ts +/** + * GET request that returns transactions + */ +export interface PostCoreNodeTransactionsError { + /** + * The error + */ + error: string; + /** + * The reason for the error + */ + reason: string; + /** + * More details about the reason + */ + reason_data: {}; + /** + * The relevant transaction id + */ + txid: string; +} +``` + + + + + + + + + + + + + + diff --git a/content/docs/stacks/rpc-api/transactions/index.mdx b/content/docs/stacks/rpc-api/transactions/index.mdx new file mode 100644 index 00000000..c6098a6e --- /dev/null +++ b/content/docs/stacks/rpc-api/transactions/index.mdx @@ -0,0 +1,6 @@ +--- +title: Transactions +index: true +toc: false +description: Manage, retrieve, and broadcast transaction data on the blockchain. +--- \ No newline at end of file diff --git a/content/docs/stacks/rpc-api/transactions/meta.json b/content/docs/stacks/rpc-api/transactions/meta.json new file mode 100644 index 00000000..a8d56253 --- /dev/null +++ b/content/docs/stacks/rpc-api/transactions/meta.json @@ -0,0 +1,20 @@ +{ + "title": "Transactions", + "pages": [ + "recent-transactions", + "get-transaction", + "get-raw-transaction", + "address-transactions", + "transactions-by-block", + "events-for-an-address-transaction", + "transaction-events", + "transaction-fee-priorities", + "mempool-transactions", + "dropped-mempool-transactions", + "statistics-for-mempool-transactions", + "details-for-transactions", + "broadcast-transaction" + ], + "defaultOpen": false +} + From 26ed0875a2b37a919a445c7cbb5eb22cec9d2db2 Mon Sep 17 00:00:00 2001 From: max-crawford <102705427+max-crawford@users.noreply.github.com> Date: Wed, 2 Oct 2024 19:08:05 -0700 Subject: [PATCH 04/12] Update index.mdx There was copy/pasta from Hiro's Stacks API overview page. I replaced the description with something specific to the RPC. I'm not sure if this is accurate / how we should position this against Hiro's API, so take a look and let me know what you think. --- content/docs/stacks/rpc-api/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/stacks/rpc-api/index.mdx b/content/docs/stacks/rpc-api/index.mdx index 8b8ab84a..0373ec32 100644 --- a/content/docs/stacks/rpc-api/index.mdx +++ b/content/docs/stacks/rpc-api/index.mdx @@ -6,7 +6,7 @@ toc: false import { SecondaryCard } from '@/components/card'; -The Stacks Blockchain API expands the intentionally minimal RPC endpoints available in Stacks nodes and indexes, cleans, and enriches on-chain data to put everything you need at your fingertips. Who knew getting reliable blockchain data could be this easy? +The Stacks Core RPC API allows you to query the Stacks blockchain and interact with smart contracts. Note: this is not a Hiro-maintained service. This RPC API is generated by every Stacks node and allows you to self-host your own node and API. This is a minimalist configuration. For a richer data set and an API that is easier to use, try [Hiro's Stacks Blockchain API](/stacks/api). ## Popular endpoints From b3340f6b74bfa924074103c266a227c3d541717c Mon Sep 17 00:00:00 2001 From: Ryan Waits Date: Wed, 2 Oct 2024 15:03:49 -0500 Subject: [PATCH 05/12] add openapi spec for rpc --- scripts/generate-docs.mjs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/generate-docs.mjs b/scripts/generate-docs.mjs index a787b5fb..2ff5fed0 100644 --- a/scripts/generate-docs.mjs +++ b/scripts/generate-docs.mjs @@ -1,6 +1,6 @@ import { generateFiles } from "fumadocs-openapi" void generateFiles({ - input: ["./openapi/stacks-api.json", "./openapi/token-metadata-api.json", "./openapi/ordinals-api.json", "./openapi/runes-api.json", "./openapi/platform-api.json"], + input: ["./openapi/stacks-api.json", "./openapi/stacks-rpc-api.json", "./openapi/token-metadata-api.json", "./openapi/ordinals-api.json", "./openapi/runes-api.json", "./openapi/platform-api.json"], output: "./openapi/spec" }) From 3e55a79a82335e5a40635ed2ea78316207485c6f Mon Sep 17 00:00:00 2001 From: Ryan Waits Date: Wed, 9 Oct 2024 13:36:48 -0500 Subject: [PATCH 06/12] add rpc endpoints; --- .../docs/stacks/rpc-api/accounts/index.mdx | 6 + content/docs/stacks/rpc-api/accounts/info.mdx | 23 +- .../docs/stacks/rpc-api/accounts/meta.json | 11 +- .../stacks/rpc-api/blocks/block-proposal.mdx | 154 ++++++++++ content/docs/stacks/rpc-api/blocks/index.mdx | 6 + content/docs/stacks/rpc-api/blocks/meta.json | 7 + .../rpc-api/burn-ops/get-burn-operations.mdx | 85 ++++++ .../docs/stacks/rpc-api/burn-ops/index.mdx | 6 + .../docs/stacks/rpc-api/burn-ops/meta.json | 8 + content/docs/stacks/rpc-api/fees/estimate.mdx | 104 +++++-- content/docs/stacks/rpc-api/fees/meta.json | 5 +- .../stacks/rpc-api/fees/transfer-estimate.mdx | 10 +- content/docs/stacks/rpc-api/info/core-api.mdx | 26 +- content/docs/stacks/rpc-api/info/meta.json | 10 +- .../docs/stacks/rpc-api/info/pox-details.mdx | 124 -------- content/docs/stacks/rpc-api/meta.json | 3 + content/docs/stacks/rpc-api/names/meta.json | 10 +- content/docs/stacks/rpc-api/pox/index.mdx | 6 + content/docs/stacks/rpc-api/pox/meta.json | 8 + .../docs/stacks/rpc-api/pox/pox-details.mdx | 282 ++++++++++++++++++ .../docs/stacks/rpc-api/pox/stacker-set.mdx | 83 ++++++ .../rpc-api/smart-contracts/constants.mdx | 142 +++++++++ .../rpc-api/smart-contracts/interface.mdx | 14 +- .../rpc-api/smart-contracts/map-entry.mdx | 21 +- .../stacks/rpc-api/smart-contracts/meta.json | 11 +- .../rpc-api/smart-contracts/read-only.mdx | 48 +-- .../stacks/rpc-api/smart-contracts/source.mdx | 10 +- .../stacks/rpc-api/smart-contracts/traits.mdx | 108 +++++++ .../rpc-api/smart-contracts/variables.mdx | 145 +++++++++ .../transactions/broadcast-transaction.mdx | 18 +- .../stacks/rpc-api/transactions/meta.json | 12 - content/docs/stacks/rpc-api/v3/index.mdx | 6 + content/docs/stacks/rpc-api/v3/meta.json | 9 + .../docs/stacks/rpc-api/v3/nakamoto-block.mdx | 108 +++++++ .../docs/stacks/rpc-api/v3/tenure-blocks.mdx | 99 ++++++ .../stacks/rpc-api/v3/tenure-metadata.mdx | 71 +++++ 36 files changed, 1496 insertions(+), 303 deletions(-) create mode 100644 content/docs/stacks/rpc-api/accounts/index.mdx create mode 100644 content/docs/stacks/rpc-api/blocks/block-proposal.mdx create mode 100644 content/docs/stacks/rpc-api/blocks/index.mdx create mode 100644 content/docs/stacks/rpc-api/blocks/meta.json create mode 100644 content/docs/stacks/rpc-api/burn-ops/get-burn-operations.mdx create mode 100644 content/docs/stacks/rpc-api/burn-ops/index.mdx create mode 100644 content/docs/stacks/rpc-api/burn-ops/meta.json delete mode 100644 content/docs/stacks/rpc-api/info/pox-details.mdx create mode 100644 content/docs/stacks/rpc-api/pox/index.mdx create mode 100644 content/docs/stacks/rpc-api/pox/meta.json create mode 100644 content/docs/stacks/rpc-api/pox/pox-details.mdx create mode 100644 content/docs/stacks/rpc-api/pox/stacker-set.mdx create mode 100644 content/docs/stacks/rpc-api/smart-contracts/constants.mdx create mode 100644 content/docs/stacks/rpc-api/smart-contracts/traits.mdx create mode 100644 content/docs/stacks/rpc-api/smart-contracts/variables.mdx create mode 100644 content/docs/stacks/rpc-api/v3/index.mdx create mode 100644 content/docs/stacks/rpc-api/v3/meta.json create mode 100644 content/docs/stacks/rpc-api/v3/nakamoto-block.mdx create mode 100644 content/docs/stacks/rpc-api/v3/tenure-blocks.mdx create mode 100644 content/docs/stacks/rpc-api/v3/tenure-metadata.mdx diff --git a/content/docs/stacks/rpc-api/accounts/index.mdx b/content/docs/stacks/rpc-api/accounts/index.mdx new file mode 100644 index 00000000..bfd9e48f --- /dev/null +++ b/content/docs/stacks/rpc-api/accounts/index.mdx @@ -0,0 +1,6 @@ +--- +title: Accounts +index: true +toc: false +description: Get account information. +--- \ No newline at end of file diff --git a/content/docs/stacks/rpc-api/accounts/info.mdx b/content/docs/stacks/rpc-api/accounts/info.mdx index 7ac57a06..3202d059 100644 --- a/content/docs/stacks/rpc-api/accounts/info.mdx +++ b/content/docs/stacks/rpc-api/accounts/info.mdx @@ -20,7 +20,7 @@ import { TypeScriptResponse } from 'fumadocs-openapi/ui'; - + @@ -28,19 +28,18 @@ import { ## Get account info -Retrieves the account data for a given Account or a Contract Identifier +Get the account data for the provided principal -Where balance is the hex encoding of a unsigned 128-bit integer (big-endian), nonce is an unsigned 64-bit integer, and the proofs are provided as hex strings. +Where balance is the hex encoding of a unsigned 128-bit integer (big-endian), nonce is a unsigned 64-bit integer, and the proofs are provided as hex strings. + +For non-existent accounts, this does not 404, rather it returns an object with balance and nonce of 0. -For non-existent accounts, this does not return a 404 error, rather it returns an object with balance and nonce of 0. ### Path Parameters -Stacks address or a Contract identifier - -Example: `"SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0"` +Stacks address or a Contract identifier (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`) @@ -54,15 +53,15 @@ Returns object without the proof field if set to 0 -The Stacks chain tip to query from +The Stacks chain tip to query from. If tip == latest, the query will be run from the latest known tip (includes unconfirmed state). | Status code | Description | -| :------ | :------ | +| ----------- | ----------- | | `200` | Success | - + @@ -75,7 +74,7 @@ The Stacks chain tip to query from ```bash -curl -X GET "https://api.hiro.so/v2/accounts/SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0?proof=0&tip=string" +curl -X GET "http://localhost:20443/v2/accounts/string?proof=0&tip=string" ``` @@ -83,7 +82,7 @@ curl -X GET "https://api.hiro.so/v2/accounts/SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW ```js -fetch("https://api.hiro.so/v2/accounts/SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0?proof=0&tip=string", { +fetch("http://localhost:20443/v2/accounts/string?proof=0&tip=string", { method: "GET" }); ``` diff --git a/content/docs/stacks/rpc-api/accounts/meta.json b/content/docs/stacks/rpc-api/accounts/meta.json index c361f191..d2bf1632 100644 --- a/content/docs/stacks/rpc-api/accounts/meta.json +++ b/content/docs/stacks/rpc-api/accounts/meta.json @@ -1,16 +1,7 @@ { "title": "Accounts", "pages": [ - "info", - "assets", - "balances", - "stx-balances", - "inbound-stx-transfers", - "transactions", - "transactions-with-transfers", - "transaction-with-transfers", - "nft-events", - "latest-nonce" + "info" ], "defaultOpen": false } \ No newline at end of file diff --git a/content/docs/stacks/rpc-api/blocks/block-proposal.mdx b/content/docs/stacks/rpc-api/blocks/block-proposal.mdx new file mode 100644 index 00000000..d4df5a00 --- /dev/null +++ b/content/docs/stacks/rpc-api/blocks/block-proposal.mdx @@ -0,0 +1,154 @@ +--- +title: Validate proposed block +description: Validate a proposed Stacks block. +toc: false +--- + +import { + API, + APIExample, + APIInfo, + APIPlayground, + ExampleResponse, + Property, + Request, + Requests, + Response, + Responses, + ResponseTypes, + Root, + TypeScriptResponse +} from 'fumadocs-openapi/ui'; + + + + + + + +## Validate a proposed Stacks block + +Used by stackers to validate a proposed Stacks block from a miner. + +**This API endpoint requires a basic Authorization header.** + + +### Request Body (Optional) + + + + + + + + + +| Status code | Description | +| ----------- | ----------- | +| `202` | Block proposal has been accepted for processing. The result will be returned via the event observer. | +| `403` | Request not over loopback interface | +| `429` | There is an ongoing proposal validation being processed, the new request cannot be accepted until the prior request has been processed. | + + + + + + + + + + + + + +```bash +curl -X POST "http://localhost:20443/v2/block_proposal" \ + -d '{ + "block": "string", + "chain_id": 0 +}' +``` + + + + + +```js +fetch("http://localhost:20443/v2/block_proposal", { + method: "POST" +}); +``` + + + + + + + + + + + + + +```json +{ + "message": "string", + "result": "string" +} +``` + + + + + +```ts +export interface Response { + message?: string; + result?: string; +} +``` + + + + + + + + + + + + + +```json +{ + "message": "string", + "result": "string" +} +``` + + + + + +```ts +export interface Response { + message?: string; + result?: string; +} +``` + + + + + + + + + + + + + + diff --git a/content/docs/stacks/rpc-api/blocks/index.mdx b/content/docs/stacks/rpc-api/blocks/index.mdx new file mode 100644 index 00000000..12bb3f08 --- /dev/null +++ b/content/docs/stacks/rpc-api/blocks/index.mdx @@ -0,0 +1,6 @@ +--- +title: Blocks +index: true +toc: false +description: Get block proposal information. +--- \ No newline at end of file diff --git a/content/docs/stacks/rpc-api/blocks/meta.json b/content/docs/stacks/rpc-api/blocks/meta.json new file mode 100644 index 00000000..aa59a6d3 --- /dev/null +++ b/content/docs/stacks/rpc-api/blocks/meta.json @@ -0,0 +1,7 @@ +{ + "title": "Blocks", + "pages": [ + "block-proposal" + ], + "defaultOpen": false +} \ No newline at end of file diff --git a/content/docs/stacks/rpc-api/burn-ops/get-burn-operations.mdx b/content/docs/stacks/rpc-api/burn-ops/get-burn-operations.mdx new file mode 100644 index 00000000..df9f9969 --- /dev/null +++ b/content/docs/stacks/rpc-api/burn-ops/get-burn-operations.mdx @@ -0,0 +1,85 @@ +--- +title: Get burn operations +description: Get all burn operations of type `op_type` successfully read at `burn_height`. +toc: false +--- + +import { + API, + APIExample, + APIInfo, + APIPlayground, + ExampleResponse, + Property, + Request, + Requests, + Response, + Responses, + ResponseTypes, + Root, + TypeScriptResponse +} from 'fumadocs-openapi/ui'; + + + + + + + +## Get burn operations + +Get all burn operations of type `op_type` successfully read at `burn_height`. Valid `op_type`s are `peg_in`, `peg_out_request` and `peg_out_fulfill`. + +### Path Parameters + + + +height of the burnchain (Bitcoin) + + + + + +name of the burnchain operation type + + + +| Status code | Description | +| ----------- | ----------- | +| `200` | Burn operations list | + + + + + + + + + + + + + +```bash +curl -X GET "http://localhost:20443/v2/burn_ops/0/string" +``` + + + + + +```js +fetch("http://localhost:20443/v2/burn_ops/0/string", { + method: "GET" +}); +``` + + + + + + + + + + \ No newline at end of file diff --git a/content/docs/stacks/rpc-api/burn-ops/index.mdx b/content/docs/stacks/rpc-api/burn-ops/index.mdx new file mode 100644 index 00000000..5ec824da --- /dev/null +++ b/content/docs/stacks/rpc-api/burn-ops/index.mdx @@ -0,0 +1,6 @@ +--- +title: Burn operations +index: true +toc: false +description: Get burn operations of type `op_type` successfully read at `burn_height`. +--- \ No newline at end of file diff --git a/content/docs/stacks/rpc-api/burn-ops/meta.json b/content/docs/stacks/rpc-api/burn-ops/meta.json new file mode 100644 index 00000000..57bb4343 --- /dev/null +++ b/content/docs/stacks/rpc-api/burn-ops/meta.json @@ -0,0 +1,8 @@ +{ + "title": "Burn operations", + "pages": [ + "get-burn-operations" + ], + "defaultOpen": false +} + diff --git a/content/docs/stacks/rpc-api/fees/estimate.mdx b/content/docs/stacks/rpc-api/fees/estimate.mdx index e6a0cb39..09423419 100644 --- a/content/docs/stacks/rpc-api/fees/estimate.mdx +++ b/content/docs/stacks/rpc-api/fees/estimate.mdx @@ -1,6 +1,6 @@ --- -title: Get fee estimate -description: Retrieves an estimated fee rate for transactions. +title: Get approximate fees for the given transaction +description: Get an estimated fee for the supplied transaction. toc: false --- @@ -20,34 +20,93 @@ import { TypeScriptResponse } from 'fumadocs-openapi/ui'; - + -## Get approximate fees for a given transaction +## Get approximate fees for the given transaction + +Get an estimated fee for the supplied transaction. This +estimates the execution cost of the transaction, the current +fee rate of the network, and returns estimates for fee +amounts. + +* `transaction_payload` is a hex-encoded serialization of + the TransactionPayload for the transaction. +* `estimated_len` is an optional argument that provides the + endpoint with an estimation of the final length (in bytes) + of the transaction, including any post-conditions and + signatures + +If the node cannot provide an estimate for the transaction +(e.g., if the node has never seen a contract-call for the +given contract and function) or if estimation is not +configured on this node, a 400 response is returned. +The 400 response will be a JSON error containing a `reason` +field which can be one of the following: + +* `DatabaseError` - this Stacks node has had an internal + database error while trying to estimate the costs of the + supplied transaction. +* `NoEstimateAvailable` - this Stacks node has not seen this + kind of contract-call before, and it cannot provide an + estimate yet. +* `CostEstimationDisabled` - this Stacks node does not perform + fee or cost estimation, and it cannot respond on this + endpoint. + +The 200 response contains the following data: + +* `estimated_cost` - the estimated multi-dimensional cost of + executing the Clarity VM on the provided transaction. +* `estimated_cost_scalar` - a unitless integer that the Stacks + node uses to compare how much of the block limit is consumed + by different transactions. This value incorporates the + estimated length of the transaction and the estimated + execution cost of the transaction. The range of this integer + may vary between different Stacks nodes. In order to compute + an estimate of total fee amount for the transaction, this + value is multiplied by the same Stacks node's estimated fee + rate. +* `cost_scalar_change_by_byte` - a float value that indicates how + much the `estimated_cost_scalar` value would increase for every + additional byte in the final transaction. +* `estimations` - an array of estimated fee rates and total fees to + pay in microSTX for the transaction. This array provides a range of + estimates (default: 3) that may be used. Each element of the array + contains the following fields: + * `fee_rate` - the estimated value for the current fee + rates in the network + * `fee` - the estimated value for the total fee in + microSTX that the given transaction should pay. These + values are the result of computing: + `fee_rate` x `estimated_cost_scalar`. + If the estimated fees are less than the minimum relay + fee `(1 ustx x estimated_len)`, then that minimum relay + fee will be returned here instead. + + +Note: If the final transaction's byte size is larger than +supplied to `estimated_len`, then applications should increase +this fee amount by: + + `fee_rate` x `cost_scalar_change_by_byte` x (`final_size` - `estimated_size`) - -If the final transaction's byte size is larger than supplied to `estimated_len`, then applications should increase this fee amount: `fee_rate` x `cost_scalar_change_by_byte` x (`final_size` - `estimated_size`) - ### Request Body (Optional) -Hex-encoded serialization of the `TransactionPayload` for the transaction. - -Estimation of the final length (in bytes) of the transaction, including any post-conditions and signatures. - | Status code | Description | -| :------ | :------ | +| ----------- | ----------- | | `200` | Estimated fees for the transaction | @@ -63,7 +122,7 @@ Estimation of the final length (in bytes) of the transaction, including any post ```bash -curl -X POST "https://api.hiro.so/v2/fees/transaction" \ +curl -X POST "http://localhost:20443/v2/fees/transaction" \ -d '{ "transaction_payload": "string", "estimated_len": 0 @@ -75,7 +134,7 @@ curl -X POST "https://api.hiro.so/v2/fees/transaction" \ ```js -fetch("https://api.hiro.so/v2/fees/transaction", { +fetch("http://localhost:20443/v2/fees/transaction", { method: "POST" }); ``` @@ -84,7 +143,7 @@ fetch("https://api.hiro.so/v2/fees/transaction", { - + @@ -145,21 +204,6 @@ export interface TransactionFeeEstimateResponse { - -The error response will be a JSON object containing a `reason` field. - - - - - `DatabaseError`: This Stacks node has had an internal database error while trying to estimate the costs of the supplied transaction. - - `NoEstimateAvailable`: This Stacks node has not seen this kind of contract-call before, and it cannot provide an estimate yet. - - `CostEstimationDisabled`: This Stacks node does not perform fee or cost estimation, and it cannot respond on this endpoint. - - If the node cannot provide an estimate for the transaction (e.g., if the node has never seen a contract-call for the given contract and function) or if estimation is not configured on this node, a `400` response is returned. - - - - - diff --git a/content/docs/stacks/rpc-api/fees/meta.json b/content/docs/stacks/rpc-api/fees/meta.json index a4e2fce8..8553c9cf 100644 --- a/content/docs/stacks/rpc-api/fees/meta.json +++ b/content/docs/stacks/rpc-api/fees/meta.json @@ -1,5 +1,8 @@ { "title": "Fees", - "pages": ["..."], + "pages": [ + "estimate", + "transfer-estimate" + ], "defaultOpen": false } \ No newline at end of file diff --git a/content/docs/stacks/rpc-api/fees/transfer-estimate.mdx b/content/docs/stacks/rpc-api/fees/transfer-estimate.mdx index d16b0928..8704f065 100644 --- a/content/docs/stacks/rpc-api/fees/transfer-estimate.mdx +++ b/content/docs/stacks/rpc-api/fees/transfer-estimate.mdx @@ -20,7 +20,7 @@ import { TypeScriptResponse } from 'fumadocs-openapi/ui'; - + @@ -28,10 +28,10 @@ import { ## Get estimated fee -Retrieves an estimated fee rate for STX transfer transactions. This a a fee rate / byte, and is returned as a JSON integer +Get an estimated fee rate for STX transfer transactions. This a a fee rate / byte, and is returned as a JSON integer | Status code | Description | -| :------ | :------ | +| ----------- | ----------- | | `200` | Success | @@ -47,7 +47,7 @@ Retrieves an estimated fee rate for STX transfer transactions. This a a fee rate ```bash -curl -X GET "https://api.hiro.so/v2/fees/transfer" +curl -X GET "http://localhost:20443/v2/fees/transfer" ``` @@ -55,7 +55,7 @@ curl -X GET "https://api.hiro.so/v2/fees/transfer" ```js -fetch("https://api.hiro.so/v2/fees/transfer", { +fetch("http://localhost:20443/v2/fees/transfer", { method: "GET" }); ``` diff --git a/content/docs/stacks/rpc-api/info/core-api.mdx b/content/docs/stacks/rpc-api/info/core-api.mdx index 5cfb370d..48e12047 100644 --- a/content/docs/stacks/rpc-api/info/core-api.mdx +++ b/content/docs/stacks/rpc-api/info/core-api.mdx @@ -20,7 +20,7 @@ import { TypeScriptResponse } from 'fumadocs-openapi/ui'; - + @@ -28,10 +28,10 @@ import { ## Get Core API info -Retrieves information about the Core API including the server version +Get Core API information | Status code | Description | -| :------ | :------ | +| ----------- | ----------- | | `200` | Success | @@ -47,7 +47,7 @@ Retrieves information about the Core API including the server version ```bash -curl -X GET "https://api.hiro.so/v2/info" +curl -X GET "http://localhost:20443/v2/info" ``` @@ -55,7 +55,7 @@ curl -X GET "https://api.hiro.so/v2/info" ```js -fetch("https://api.hiro.so/v2/info", { +fetch("http://localhost:20443/v2/info", { method: "GET" }); ``` @@ -76,19 +76,19 @@ GET request that core node information ```json { - "peer_version": 402653194, + "peer_version": 0, "pox_consensus": "string", - "burn_block_height": 863576, + "burn_block_height": 0, "stable_pox_consensus": "string", - "stable_burn_block_height": 863569, + "stable_burn_block_height": 0, "server_version": "string", - "network_id": 1, - "parent_network_id": 3652501241, - "stacks_tip_height": 167976, + "network_id": 0, + "parent_network_id": 0, + "stacks_tip_height": 0, "stacks_tip": "string", "stacks_tip_consensus_hash": "string", - "unanchored_tip": null, - "exit_at_block_height": null + "unanchored_tip": "string", + "exit_at_block_height": 0 } ``` diff --git a/content/docs/stacks/rpc-api/info/meta.json b/content/docs/stacks/rpc-api/info/meta.json index f553c6ac..d99dd0e1 100644 --- a/content/docs/stacks/rpc-api/info/meta.json +++ b/content/docs/stacks/rpc-api/info/meta.json @@ -1,15 +1,7 @@ { "title": "Info", "pages": [ - "status", - "core-api", - "network-block-time", - "network-given-block-time", - "total-and-unlocked-stx-supply", - "legacy-total-and-unlocked-stx-supply", - "total-stx-supply-in-plain-text", - "circulating-stx-supply-in-plain-text", - "pox-details" + "core-api" ], "defaultOpen": false } \ No newline at end of file diff --git a/content/docs/stacks/rpc-api/info/pox-details.mdx b/content/docs/stacks/rpc-api/info/pox-details.mdx deleted file mode 100644 index 12333291..00000000 --- a/content/docs/stacks/rpc-api/info/pox-details.mdx +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Get Proof-of-Transfer details -description: Retrieves Proof-of-Transfer (PoX) information. -toc: false ---- - -import { - API, - APIExample, - APIInfo, - APIPlayground, - ExampleResponse, - Property, - Request, - Requests, - Response, - Responses, - ResponseTypes, - Root, - TypeScriptResponse -} from 'fumadocs-openapi/ui'; - - - - - - - -## Get Proof-of-Transfer details - -Retrieves Proof-of-Transfer (PoX) information. Can be used for Stacking. - -| Status code | Description | -| :------ | :------ | -| `200` | Success | - - - - - - - - - - - - - -```bash -curl -X GET "https://api.hiro.so/v2/pox" -``` - - - - - -```js -fetch("https://api.hiro.so/v2/pox", { - method: "GET" -}); -``` - - - - - - - - - -Get Proof of Transfer (PoX) information - - - - - -```json -{ - "contract_id": "string", - "first_burnchain_block_height": 0, - "min_amount_ustx": 0, - "registration_window_length": 0, - "rejection_fraction": 0, - "reward_cycle_id": 0, - "reward_cycle_length": 0, - "rejection_votes_left_required": 0, - "total_liquid_supply_ustx": 0 -} -``` - - - - - -```ts -/** - * Get Proof of Transfer (PoX) information - */ -export interface CoreNodePoxResponse { - contract_id: string; - first_burnchain_block_height: number; - min_amount_ustx: number; - registration_window_length: number; - rejection_fraction: number; - reward_cycle_id: number; - reward_cycle_length: number; - rejection_votes_left_required: number; - total_liquid_supply_ustx: number; -} -``` - - - - - - - - - - - - - - diff --git a/content/docs/stacks/rpc-api/meta.json b/content/docs/stacks/rpc-api/meta.json index b17def52..fb31d535 100644 --- a/content/docs/stacks/rpc-api/meta.json +++ b/content/docs/stacks/rpc-api/meta.json @@ -7,9 +7,12 @@ "---API Reference---", "accounts", "transactions", + "blocks", "fees", + "burn-ops", "smart-contracts", "names", + "v3", "info" ] } diff --git a/content/docs/stacks/rpc-api/names/meta.json b/content/docs/stacks/rpc-api/names/meta.json index 8c03640e..7bed3ab7 100644 --- a/content/docs/stacks/rpc-api/names/meta.json +++ b/content/docs/stacks/rpc-api/names/meta.json @@ -1,16 +1,8 @@ { "title": "Names", "pages": [ - "namespaces", - "names", - "namespace-names", "namespace-price", - "name-price", - "name-details", - "name-subdomains", - "name-zonefile", - "historical-zonefile", - "owned-by-address" + "name-price" ], "defaultOpen": false } diff --git a/content/docs/stacks/rpc-api/pox/index.mdx b/content/docs/stacks/rpc-api/pox/index.mdx new file mode 100644 index 00000000..58aff34b --- /dev/null +++ b/content/docs/stacks/rpc-api/pox/index.mdx @@ -0,0 +1,6 @@ +--- +title: Proof of Transfer +index: true +toc: false +description: Retrieves Proof-of-Transfer (PoX) information. +--- diff --git a/content/docs/stacks/rpc-api/pox/meta.json b/content/docs/stacks/rpc-api/pox/meta.json new file mode 100644 index 00000000..7e834a56 --- /dev/null +++ b/content/docs/stacks/rpc-api/pox/meta.json @@ -0,0 +1,8 @@ +{ + "title": "Accounts", + "pages": [ + "pox-details", + "stacker-set" + ], + "defaultOpen": false +} \ No newline at end of file diff --git a/content/docs/stacks/rpc-api/pox/pox-details.mdx b/content/docs/stacks/rpc-api/pox/pox-details.mdx new file mode 100644 index 00000000..5082390a --- /dev/null +++ b/content/docs/stacks/rpc-api/pox/pox-details.mdx @@ -0,0 +1,282 @@ +--- +title: Get Proof-of-Transfer details +description: Retrieves Proof-of-Transfer (PoX) information. +toc: false +--- + +import { + API, + APIExample, + APIInfo, + APIPlayground, + ExampleResponse, + Property, + Request, + Requests, + Response, + Responses, + ResponseTypes, + Root, + TypeScriptResponse +} from 'fumadocs-openapi/ui'; + + + + + + + +## Get PoX details + +Get Proof of Transfer (PoX) information. Can be used for Stacking. + +### Query Parameters + + + +The Stacks chain tip to query from. If tip == latest, the query will be run from the latest known tip (includes unconfirmed state). + + + +| Status code | Description | +| ----------- | ----------- | +| `200` | Success | + + + + + + + + + + + + + +```bash +curl -X GET "http://localhost:20443/v2/pox?tip=string" +``` + + + + + +```js +fetch("http://localhost:20443/v2/pox?tip=string", { + method: "GET" +}); +``` + + + + + + + + + +Get Proof of Transfer (PoX) information + + + + + +```json +{ + "contract_id": "string", + "first_burnchain_block_height": 0, + "current_burnchain_block_height": 0, + "pox_activation_threshold_ustx": 0, + "rejection_fraction": 0, + "reward_phase_block_length": 0, + "prepare_phase_block_length": 0, + "reward_slots": 0, + "total_liquid_supply_ustx": 0, + "reward_cycle_length": 0, + "current_cycle": { + "id": 0, + "min_threshold_ustx": 0, + "stacked_ustx": 0, + "is_pox_active": true + }, + "next_cycle": { + "id": 0, + "min_threshold_ustx": 0, + "stacked_ustx": 0, + "min_increment_ustx": 0, + "prepare_phase_start_block_height": 0, + "blocks_until_prepare_phase": 0, + "reward_phase_start_block_height": 0, + "blocks_until_reward_phase": 0, + "ustx_until_pox_rejection": 0 + }, + "reward_cycle_id": 0, + "min_amount_ustx": 0, + "prepare_cycle_length": 0, + "rejection_votes_left_required": 0, + "contract_versions": [ + { + "contract_id": "string", + "activation_burnchain_block_height": 0, + "first_reward_cycle_id": 0 + } + ] +} +``` + + + + + +```ts +/** + * Get Proof of Transfer (PoX) information + */ +export interface CoreNodePoxResponse { + /** + * The contract identifier for the PoX contract + */ + contract_id: string; + /** + * The first burn block evaluated in this Stacks chain + */ + first_burnchain_block_height: number; + /** + * The latest Bitcoin chain block height + */ + current_burnchain_block_height: number; + /** + * The threshold of stacking participation that must be reached for PoX to activate in any cycle + */ + pox_activation_threshold_ustx: number; + /** + * The fraction of liquid STX that must vote to reject PoX in order to prevent the next reward cycle from activating. + */ + rejection_fraction: number; + /** + * The length in burn blocks of the reward phase + */ + reward_phase_block_length: number; + /** + * The length in burn blocks of the prepare phase + */ + prepare_phase_block_length: number; + /** + * The number of reward slots in a reward cycle + */ + reward_slots: number; + /** + * The current total amount of liquid microstacks. + */ + total_liquid_supply_ustx: number; + /** + * The length in burn blocks of a whole PoX cycle (reward phase and prepare phase) + */ + reward_cycle_length: number; + current_cycle: { + /** + * The reward cycle number + */ + id: number; + /** + * The threshold amount for obtaining a slot in this reward cycle. + */ + min_threshold_ustx: number; + /** + * The total amount of stacked microstacks in this reward cycle. + */ + stacked_ustx: number; + /** + * Whether or not PoX is active during this reward cycle. + */ + is_pox_active: boolean; + }; + next_cycle: { + /** + * The reward cycle number + */ + id: number; + /** + * The threshold amount for obtaining a slot in this reward cycle. + */ + min_threshold_ustx: number; + /** + * The total amount of stacked microstacks in this reward cycle. + */ + stacked_ustx: number; + /** + * The minimum amount that can be used to submit a `stack-stx` call. + */ + min_increment_ustx: number; + /** + * The burn block height when the prepare phase for this cycle begins. Any eligible stacks must be stacked before this block. + */ + prepare_phase_start_block_height: number; + /** + * 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. + */ + blocks_until_prepare_phase: number; + /** + * The burn block height when the reward phase for this cycle begins. Any eligible stacks must be stacked before this block. + */ + reward_phase_start_block_height: number; + /** + * The number of burn blocks until this reward phase starts. + */ + blocks_until_reward_phase: number; + /** + * The remaining amount of liquid STX that must vote to reject the next reward cycle to prevent the next reward cycle from activating. + */ + ustx_until_pox_rejection: number; + }; + /** + * @deprecated + * The active reward cycle number + */ + reward_cycle_id: number; + /** + * @deprecated + */ + min_amount_ustx: number; + /** + * @deprecated + */ + prepare_cycle_length: number; + /** + * @deprecated + */ + rejection_votes_left_required: number; + /** + * Versions of each PoX + */ + contract_versions: { + /** + * The contract identifier for the PoX contract + */ + contract_id: string; + /** + * The burn block height at which this version of PoX is activated + */ + activation_burnchain_block_height: number; + /** + * The first reward cycle number that uses this version of PoX + */ + first_reward_cycle_id: number; + }[]; +} +``` + + + + + + + + + + + + + + diff --git a/content/docs/stacks/rpc-api/pox/stacker-set.mdx b/content/docs/stacks/rpc-api/pox/stacker-set.mdx new file mode 100644 index 00000000..5ebcf6aa --- /dev/null +++ b/content/docs/stacks/rpc-api/pox/stacker-set.mdx @@ -0,0 +1,83 @@ +--- +title: Get stacker and signer set information +description: Retrieves stacker and signer set information for a given cycle. +toc: false +--- + +import { + API, + APIExample, + APIInfo, + APIPlayground, + ExampleResponse, + Property, + Request, + Requests, + Response, + Responses, + ResponseTypes, + Root, + TypeScriptResponse +} from 'fumadocs-openapi/ui'; + + + + + + + +## Fetch the stacker and signer set information for a given cycle. + +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. + + +### Path Parameters + + + +reward cycle number + + + +| Status code | Description | +| ----------- | ----------- | +| `200` | Information for the given reward cycle | +| `400` | Could not fetch the given reward set | + + + + + + + + + + + + + +```bash +curl -X GET "http://localhost:20443/v2/stacker_set/0" +``` + + + + + +```js +fetch("http://localhost:20443/v2/stacker_set/0", { + method: "GET" +}); +``` + + + + + + + + + + \ No newline at end of file diff --git a/content/docs/stacks/rpc-api/smart-contracts/constants.mdx b/content/docs/stacks/rpc-api/smart-contracts/constants.mdx new file mode 100644 index 00000000..6dcf64e1 --- /dev/null +++ b/content/docs/stacks/rpc-api/smart-contracts/constants.mdx @@ -0,0 +1,142 @@ +--- +title: Get constant value +description: Get the value of a constant inside a contract. +toc: false +--- + +import { + API, + APIExample, + APIInfo, + APIPlayground, + ExampleResponse, + Property, + Request, + Requests, + Response, + Responses, + ResponseTypes, + Root, + TypeScriptResponse +} from 'fumadocs-openapi/ui'; + + + + + + + +## Get the value of a constant inside a contract + +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. + +### Path Parameters + + + +Stacks address + + + + + +Contract name + + + + + +Constant name + + + +### Query Parameters + + + +The Stacks chain tip to query from. If tip == latest, the query will be run from the latest known tip (includes unconfirmed state). + + + +| Status code | Description | +| ----------- | ----------- | +| `200` | Success | +| `400` | Failed to retrieve constant value from contract | + + + + + + + + + + + + + +```bash +curl -X POST "http://localhost:20443/v2/constant_val/string/string/string?tip=string" +``` + + + + + +```js +fetch("http://localhost:20443/v2/constant_val/string/string/string?tip=string", { + method: "POST" +}); +``` + + + + + + + + + +Response of get constant val request + + + + + +```json +{ + "data": "string" +} +``` + + + + + +```ts +/** + * Response of get constant val request + */ +export interface ConstantValResponse { + /** + * Hex-encoded string of clarity value. + */ + data: string; +} +``` + + + + + + + + + + + + + + diff --git a/content/docs/stacks/rpc-api/smart-contracts/interface.mdx b/content/docs/stacks/rpc-api/smart-contracts/interface.mdx index d1aea4b1..c03193b6 100644 --- a/content/docs/stacks/rpc-api/smart-contracts/interface.mdx +++ b/content/docs/stacks/rpc-api/smart-contracts/interface.mdx @@ -20,7 +20,7 @@ import { TypeScriptResponse } from 'fumadocs-openapi/ui'; - + @@ -28,10 +28,10 @@ import { ## Get contract interface -Retrieves a contract interface with a given `contract_address` and `contract name` +Get contract interface using a `contract_address` and `contract name` | Status code | Description | -| :------ | :------ | +| ----------- | ----------- | | `200` | Contract interface | @@ -47,7 +47,7 @@ Retrieves a contract interface with a given `contract_address` and `contract nam ```bash -curl -X GET "https://api.hiro.so/v2/contracts/interface/%7Bcontract_address%7D/%7Bcontract_name%7D" +curl -X GET "http://localhost:20443/v2/contracts/interface/%7Bcontract_address%7D/%7Bcontract_name%7D" ``` @@ -55,7 +55,7 @@ curl -X GET "https://api.hiro.so/v2/contracts/interface/%7Bcontract_address%7D/% ```js -fetch("https://api.hiro.so/v2/contracts/interface/%7Bcontract_address%7D/%7Bcontract_name%7D", { +fetch("http://localhost:20443/v2/contracts/interface/%7Bcontract_address%7D/%7Bcontract_name%7D", { method: "GET" }); ``` @@ -90,9 +90,7 @@ GET request to get contract interface ], "non_fungible_tokens": [ {} - ], - "epoch": "string", - "clarity_version": "string" + ] } ``` diff --git a/content/docs/stacks/rpc-api/smart-contracts/map-entry.mdx b/content/docs/stacks/rpc-api/smart-contracts/map-entry.mdx index dc211d0d..f841e2d8 100644 --- a/content/docs/stacks/rpc-api/smart-contracts/map-entry.mdx +++ b/content/docs/stacks/rpc-api/smart-contracts/map-entry.mdx @@ -20,7 +20,7 @@ import { TypeScriptResponse } from 'fumadocs-openapi/ui'; - + @@ -28,12 +28,13 @@ import { ## Get specific data-map inside a contract -Attempt to fetch data from a contract data map. The contract is identified with Stacks Address `contract_address` and Contract Name `contract_address` 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. 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. + ### Request Body Hex string serialization of the lookup key (which should be a Clarity value) @@ -48,24 +49,18 @@ Hex string serialization of the lookup key (which should be a Clarity value) Stacks address -Example: `"SPSCWDV3RKV5ZRN1FQD84YE1NQFEDJ9R1F4DYQ11"` - Contract name -Example: `"newyorkcitycoin-core-v2"` - Map name -Example: `"approved-contracts"` - ### Query Parameters @@ -78,16 +73,16 @@ Returns object without the proof field when set to 0 -The Stacks chain tip to query from +The Stacks chain tip to query from. If tip == latest, the query will be run from the latest known tip (includes unconfirmed state). | Status code | Description | -| :------ | :------ | +| ----------- | ----------- | | `200` | Success | | `400` | Failed loading data map | - + @@ -100,7 +95,7 @@ The Stacks chain tip to query from ```bash -curl -X POST "https://api.hiro.so/v2/map_entry/SPSCWDV3RKV5ZRN1FQD84YE1NQFEDJ9R1F4DYQ11/newyorkcitycoin-core-v2/approved-contracts?proof=0&tip=string" \ +curl -X POST "http://localhost:20443/v2/map_entry/string/string/string?proof=0&tip=string" \ -d 'string' ``` @@ -109,7 +104,7 @@ curl -X POST "https://api.hiro.so/v2/map_entry/SPSCWDV3RKV5ZRN1FQD84YE1NQFEDJ9R1 ```js -fetch("https://api.hiro.so/v2/map_entry/SPSCWDV3RKV5ZRN1FQD84YE1NQFEDJ9R1F4DYQ11/newyorkcitycoin-core-v2/approved-contracts?proof=0&tip=string", { +fetch("http://localhost:20443/v2/map_entry/string/string/string?proof=0&tip=string", { method: "POST" }); ``` diff --git a/content/docs/stacks/rpc-api/smart-contracts/meta.json b/content/docs/stacks/rpc-api/smart-contracts/meta.json index a0aff84c..9e0e7f93 100644 --- a/content/docs/stacks/rpc-api/smart-contracts/meta.json +++ b/content/docs/stacks/rpc-api/smart-contracts/meta.json @@ -1,15 +1,6 @@ { "title": "Smart Contracts", - "pages": [ - "status", - "info", - "source", - "by-trait", - "interface", - "map-entry", - "read-only", - "events" - ], + "pages": ["..."], "defaultOpen": false } diff --git a/content/docs/stacks/rpc-api/smart-contracts/read-only.mdx b/content/docs/stacks/rpc-api/smart-contracts/read-only.mdx index 739acd28..3545a797 100644 --- a/content/docs/stacks/rpc-api/smart-contracts/read-only.mdx +++ b/content/docs/stacks/rpc-api/smart-contracts/read-only.mdx @@ -20,7 +20,7 @@ import { TypeScriptResponse } from 'fumadocs-openapi/ui'; - + @@ -32,6 +32,7 @@ Call a read-only public function on a given smart contract. The smart contract and function are specified using the URL path. The arguments and the simulated tx-sender are supplied via the POST body in the following JSON format: + ### Request Body 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. @@ -47,45 +48,40 @@ The simulated tx-sender An array of hex serialized Clarity values + ### Path Parameters Stacks address -Example: `"SP3D6PV2ACBPEKYJTCMH7HEN02KP87QSP8KTEH335"` - Contract name -Example: `"mega"` - Function name -Example: `"get-balance"` - ### Query Parameters -The Stacks chain tip to query from +The Stacks chain tip to query from. If tip == latest, the query will be run from the latest known tip (includes unconfirmed state). | Status code | Description | -| :------ | :------ | +| ----------- | ----------- | | `200` | Success | - + @@ -98,36 +94,24 @@ The Stacks chain tip to query from ```bash -curl -X POST "https://api.hiro.so/v2/contracts/call-read/SP3D6PV2ACBPEKYJTCMH7HEN02KP87QSP8KTEH335/mega/get-balance" \ - -H "Content-Type: application/json" \ +curl -X POST "http://localhost:20443/v2/contracts/call-read/string/string/string?tip=string" \ -d '{ - "sender": "SP187Y7NRSG3T9Z9WTSWNEN3XRV1YSJWS81C7JKV7", - "arguments": [ - "0x0516da6b6c4a62ece9fa5a652278baa014ec83df3644" - ] - }' -``` + "sender": "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info", + "arguments": [ + "0x0011...", + "0x00231..." + ] +}' +``` ```js -const body = JSON.stringify({ - sender: "SP187Y7NRSG3T9Z9WTSWNEN3XRV1YSJWS81C7JKV7", - arguments: ["0x0516da6b6c4a62ece9fa5a652278baa014ec83df3644"], +fetch("http://localhost:20443/v2/contracts/call-read/string/string/string?tip=string", { + method: "POST" }); - -fetch( - "https://api.hiro.so/v2/contracts/call-read/SP3D6PV2ACBPEKYJTCMH7HEN02KP87QSP8KTEH335/mega/get-balance", - { - headers: { "Content-Type": "application/json" }, - method: "POST", - body, - } -); - -const responseBody = await response.json(); ``` diff --git a/content/docs/stacks/rpc-api/smart-contracts/source.mdx b/content/docs/stacks/rpc-api/smart-contracts/source.mdx index e6bc4894..1c134a97 100644 --- a/content/docs/stacks/rpc-api/smart-contracts/source.mdx +++ b/content/docs/stacks/rpc-api/smart-contracts/source.mdx @@ -20,7 +20,7 @@ import { TypeScriptResponse } from 'fumadocs-openapi/ui'; - + @@ -28,10 +28,10 @@ import { ## Get contract source -Retrieves the Clarity source code of a given contract, along with the block height it was published in, and the MARF proof for the data +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 | Status code | Description | -| :------ | :------ | +| ----------- | ----------- | | `200` | Success | @@ -47,7 +47,7 @@ Retrieves the Clarity source code of a given contract, along with the block heig ```bash -curl -X GET "https://api.hiro.so/v2/contracts/source/%7Bcontract_address%7D/%7Bcontract_name%7D" +curl -X GET "http://localhost:20443/v2/contracts/source/%7Bcontract_address%7D/%7Bcontract_name%7D" ``` @@ -55,7 +55,7 @@ curl -X GET "https://api.hiro.so/v2/contracts/source/%7Bcontract_address%7D/%7Bc ```js -fetch("https://api.hiro.so/v2/contracts/source/%7Bcontract_address%7D/%7Bcontract_name%7D", { +fetch("http://localhost:20443/v2/contracts/source/%7Bcontract_address%7D/%7Bcontract_name%7D", { method: "GET" }); ``` diff --git a/content/docs/stacks/rpc-api/smart-contracts/traits.mdx b/content/docs/stacks/rpc-api/smart-contracts/traits.mdx new file mode 100644 index 00000000..9c8d170b --- /dev/null +++ b/content/docs/stacks/rpc-api/smart-contracts/traits.mdx @@ -0,0 +1,108 @@ +--- +title: Get trait implementation details +description: Determine whether or not a specified trait is implemented (either explicitly or implicitly) within a given contract. +toc: false +--- + +import { + API, + APIExample, + APIInfo, + APIPlayground, + ExampleResponse, + Property, + Request, + Requests, + Response, + Responses, + ResponseTypes, + Root, + TypeScriptResponse +} from 'fumadocs-openapi/ui'; + + + + + + + +## Get trait implementation details + +Determine whether or not a specified trait is implemented (either explicitly or implicitly) within a given contract. + +| Status code | Description | +| ----------- | ----------- | +| `200` | Success | + + + + + + + + + + + + + +```bash +curl -X GET "http://localhost:20443/v2/traits/%7Bcontract_address%7D/%7Bcontract_name%7D/%7Btrait_contract_address%7D/%7Btrait_contract_name%7D/%7Btrait_name%7D" +``` + + + + + +```js +fetch("http://localhost:20443/v2/traits/%7Bcontract_address%7D/%7Bcontract_name%7D/%7Btrait_contract_address%7D/%7Btrait_contract_name%7D/%7Btrait_name%7D", { + method: "GET" +}); +``` + + + + + + + + + +GET request to get trait implementation information + + + + + +```json +{ + "is_implemented": true +} +``` + + + + + +```ts +/** + * GET request to get trait implementation information + */ +export interface IsTraitImplementedSuccessResponse { + is_implemented: boolean; +} +``` + + + + + + + + + + + + + + \ No newline at end of file diff --git a/content/docs/stacks/rpc-api/smart-contracts/variables.mdx b/content/docs/stacks/rpc-api/smart-contracts/variables.mdx new file mode 100644 index 00000000..bbd30e6b --- /dev/null +++ b/content/docs/stacks/rpc-api/smart-contracts/variables.mdx @@ -0,0 +1,145 @@ +--- +title: Get data variable value +description: Get the value of a data variable inside a contract. +toc: false +--- + +import { + API, + APIExample, + APIInfo, + APIPlayground, + ExampleResponse, + Property, + Request, + Requests, + Response, + Responses, + ResponseTypes, + Root, + TypeScriptResponse +} from 'fumadocs-openapi/ui'; + + + + + + + +## Get the value of a data variable inside a contract + +Attempt to vetch a data var from a contract. The contract is identified with [Stacks Address] and +[Contract Name] in the URL path. The variable is identified with [Var Name]. + +In the response, `data` is the hex serialization of the data variable value. + +### Path Parameters + + + +Stacks address + + + + + +Contract name + + + + + +Data variable name + + + +### Query Parameters + + + +When supplied `0`, will return the JSON object _without_ the `proof` field. + + + +| Status code | Description | +| ----------- | ----------- | +| `200` | Success | +| `400` | Failed to retrieve data variable value from contract | + + + + + + + + + + + + + +```bash +curl -X GET "http://localhost:20443/v2/data_var/string/string/string" +``` + + + + + +```js +fetch("http://localhost:20443/v2/constant_val/string/string/string", { + method: "POST" +}); +``` + + + + + + + + + +Response of get constant val request + + + + + +```json +{ + "data": "string", + "proof": "string", +} +``` + + + + + +```ts +/** + * Response of get constant val request + */ +export interface ConstantValResponse { + /** + * Hex-encoded string of clarity value. + */ + data: string; + proof: string; +} +``` + + + + + + + + + + + + + + diff --git a/content/docs/stacks/rpc-api/transactions/broadcast-transaction.mdx b/content/docs/stacks/rpc-api/transactions/broadcast-transaction.mdx index 7cb38056..b4111726 100644 --- a/content/docs/stacks/rpc-api/transactions/broadcast-transaction.mdx +++ b/content/docs/stacks/rpc-api/transactions/broadcast-transaction.mdx @@ -20,7 +20,7 @@ import { TypeScriptResponse } from 'fumadocs-openapi/ui'; - + @@ -28,24 +28,22 @@ import { ## Broadcast raw transaction -Broadcasts raw transactions on the network. You can use the [@stacks/transactions](https://github.com/blockstack/stacks.js) project to generate a raw transaction payload. +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. ### Request Body (Optional) -Example: `"binary format of 00000000010400bed38c2aadffa348931bcb542880ff79d607afec000000000000000000000000000000c800012b0b1fff6cccd0974966dcd665835838f0985be508e1322e09fb3d751eca132c492bda720f9ef1768d14fdabed6127560ba52d5e3ac470dcb60b784e97dc88c9030200000000000516df0ba3e79792be7be5e50a370289accfc8c9e032000000000000303974657374206d656d6f00000000000000000000000000000000000000000000000000"` - Format: `"binary"` | Status code | Description | -| :------ | :------ | +| ----------- | ----------- | | `200` | Transaction id of successful post of a raw tx to the node's mempool | | `400` | Rejections result in a 400 error | - + @@ -58,8 +56,8 @@ Broadcasts raw transactions on the network. You can use the [@stacks/transaction ```bash -curl -X POST "https://api.hiro.so/v2/transactions" \ - -d 'binary format of 00000000010400bed38c2aadffa348931bcb542880ff79d607afec000000000000000000000000000000c800012b0b1fff6cccd0974966dcd665835838f0985be508e1322e09fb3d751eca132c492bda720f9ef1768d14fdabed6127560ba52d5e3ac470dcb60b784e97dc88c9030200000000000516df0ba3e79792be7be5e50a370289accfc8c9e032000000000000303974657374206d656d6f00000000000000000000000000000000000000000000000000' +curl -X POST "http://localhost:20443/v2/transactions" \ + -d 'string' ``` @@ -67,7 +65,7 @@ curl -X POST "https://api.hiro.so/v2/transactions" \ ```js -fetch("https://api.hiro.so/v2/transactions", { +fetch("http://localhost:20443/v2/transactions", { method: "POST" }); ``` @@ -159,4 +157,4 @@ export interface PostCoreNodeTransactionsError { - + \ No newline at end of file diff --git a/content/docs/stacks/rpc-api/transactions/meta.json b/content/docs/stacks/rpc-api/transactions/meta.json index a8d56253..c927411b 100644 --- a/content/docs/stacks/rpc-api/transactions/meta.json +++ b/content/docs/stacks/rpc-api/transactions/meta.json @@ -1,18 +1,6 @@ { "title": "Transactions", "pages": [ - "recent-transactions", - "get-transaction", - "get-raw-transaction", - "address-transactions", - "transactions-by-block", - "events-for-an-address-transaction", - "transaction-events", - "transaction-fee-priorities", - "mempool-transactions", - "dropped-mempool-transactions", - "statistics-for-mempool-transactions", - "details-for-transactions", "broadcast-transaction" ], "defaultOpen": false diff --git a/content/docs/stacks/rpc-api/v3/index.mdx b/content/docs/stacks/rpc-api/v3/index.mdx new file mode 100644 index 00000000..f6c28b33 --- /dev/null +++ b/content/docs/stacks/rpc-api/v3/index.mdx @@ -0,0 +1,6 @@ +--- +title: v3 +index: true +toc: false +description: Version 3 of the RPC API. +--- \ No newline at end of file diff --git a/content/docs/stacks/rpc-api/v3/meta.json b/content/docs/stacks/rpc-api/v3/meta.json new file mode 100644 index 00000000..22b93adc --- /dev/null +++ b/content/docs/stacks/rpc-api/v3/meta.json @@ -0,0 +1,9 @@ +{ + "title": "v3", + "pages": [ + "nakamoto-block", + "tenure-metadata", + "tenure-blocks" + ], + "defaultOpen": false +} \ No newline at end of file diff --git a/content/docs/stacks/rpc-api/v3/nakamoto-block.mdx b/content/docs/stacks/rpc-api/v3/nakamoto-block.mdx new file mode 100644 index 00000000..b7568fdf --- /dev/null +++ b/content/docs/stacks/rpc-api/v3/nakamoto-block.mdx @@ -0,0 +1,108 @@ +--- +title: Get Nakamoto block +description: Fetch a Nakamoto block by its index block hash. +toc: false +--- + +import { + API, + APIExample, + APIInfo, + APIPlayground, + ExampleResponse, + Property, + Request, + Requests, + Response, + Responses, + ResponseTypes, + Root, + TypeScriptResponse +} from 'fumadocs-openapi/ui'; + + + + + + + +## Fetch a Nakamoto block + +Fetch a Nakamoto block by its index block hash. + +### Path Parameters + + + +The block's ID hash + + + +| Status code | Description | +| ----------- | ----------- | +| `200` | The raw SIP-003-encoded block will be returned. | +| `404` | The block could not be found | + + + + + + + + + + + + + +```bash +curl -X GET "http://localhost:20443/v3/blocks/string" +``` + + + + + +```js +fetch("http://localhost:20443/v3/blocks/string", { + method: "GET" +}); +``` + + + + + + + + + + + + + +```json +"string" +``` + + + + + +```ts +export type Response = string; +``` + + + + + + + + + + + + + + diff --git a/content/docs/stacks/rpc-api/v3/tenure-blocks.mdx b/content/docs/stacks/rpc-api/v3/tenure-blocks.mdx new file mode 100644 index 00000000..841e0c56 --- /dev/null +++ b/content/docs/stacks/rpc-api/v3/tenure-blocks.mdx @@ -0,0 +1,99 @@ +--- +title: Get Nakamoto tenure blocks +description: Fetch a sequence of Nakamoto blocks in a tenure. +toc: false +--- + +import { + API, + APIExample, + APIInfo, + APIPlayground, + ExampleResponse, + Property, + Request, + Requests, + Response, + Responses, + ResponseTypes, + Root, + TypeScriptResponse +} from 'fumadocs-openapi/ui'; + + + + + + + +## Fetch a sequence of Nakamoto blocks in a tenure + +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. + +| Status code | Description | +| ----------- | ----------- | +| `200` | SIP-003-encoded Nakamoto blocks, concatenated together | + + + + + + + + + + + + + +```bash +curl -X GET "http://localhost:20443/v3/tenures/%7Bblock_id%7D" +``` + + + + + +```js +fetch("http://localhost:20443/v3/tenures/%7Bblock_id%7D", { + method: "GET" +}); +``` + + + + + + + + + + + + + +```json +"string" +``` + + + + + +```ts +export type Response = string; +``` + + + + + + + + + + + + + + diff --git a/content/docs/stacks/rpc-api/v3/tenure-metadata.mdx b/content/docs/stacks/rpc-api/v3/tenure-metadata.mdx new file mode 100644 index 00000000..ca187ff4 --- /dev/null +++ b/content/docs/stacks/rpc-api/v3/tenure-metadata.mdx @@ -0,0 +1,71 @@ +--- +title: Get Nakamoto tenure metadata +description: Fetch metadata about the ongoing Nakamoto tenure. +toc: false +--- + +import { + API, + APIExample, + APIInfo, + APIPlayground, + ExampleResponse, + Property, + Request, + Requests, + Response, + Responses, + ResponseTypes, + Root, + TypeScriptResponse +} from 'fumadocs-openapi/ui'; + + + + + + + +## Fetch metadata about the ongoing Nakamoto tenure + +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. + +| Status code | Description | +| ----------- | ----------- | +| `200` | Metadata about the ongoing tenure | + + + + + + + + + + + + + +```bash +curl -X GET "http://localhost:20443/v3/tenures/info" +``` + + + + + +```js +fetch("http://localhost:20443/v3/tenures/info", { + method: "GET" +}); +``` + + + + + + + + + + From f09448bb30f3702b6fe2a94dd51f6fe22187402e Mon Sep 17 00:00:00 2001 From: Ryan Waits Date: Thu, 10 Oct 2024 12:32:14 -0500 Subject: [PATCH 07/12] fix duplicate title --- app/(docs)/[...slug]/page.tsx | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/app/(docs)/[...slug]/page.tsx b/app/(docs)/[...slug]/page.tsx index 8b229e4f..ab3a446c 100644 --- a/app/(docs)/[...slug]/page.tsx +++ b/app/(docs)/[...slug]/page.tsx @@ -52,11 +52,16 @@ export default function Page({ params }: { params: Param }): JSX.Element { prefix = "Token Metadata API"; } + if (page.slugs[1].toLowerCase() === "rpc-api") { + prefix = "Stacks Core RPC"; + } + return prefix; } else if (["overview", "index"].includes(page.file?.name)) { const pathSegments = page.file.dirname.split("/"); if (pathSegments.length >= 2) { const relevantSegments = pathSegments.slice(-2); // Get the last two segments + return relevantSegments .map( (segment: string) => From 6665a1690a270795d92cd6142cc2617bd17cff83 Mon Sep 17 00:00:00 2001 From: Ryan Waits Date: Thu, 10 Oct 2024 12:32:41 -0500 Subject: [PATCH 08/12] add pox folder to sidebar --- content/docs/stacks/rpc-api/pox/meta.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/stacks/rpc-api/pox/meta.json b/content/docs/stacks/rpc-api/pox/meta.json index 7e834a56..c0d853cd 100644 --- a/content/docs/stacks/rpc-api/pox/meta.json +++ b/content/docs/stacks/rpc-api/pox/meta.json @@ -1,5 +1,5 @@ { - "title": "Accounts", + "title": "Proof of Transfer", "pages": [ "pox-details", "stacker-set" From 2ce5ba69b5b11f9f064f0fbc92842f680328bdcb Mon Sep 17 00:00:00 2001 From: Ryan Waits Date: Thu, 10 Oct 2024 12:32:59 -0500 Subject: [PATCH 09/12] update sidebar and copy --- content/docs/stacks/api/index.mdx | 2 +- content/docs/stacks/rpc-api/index.mdx | 8 ++++---- content/docs/stacks/rpc-api/meta.json | 1 + 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/content/docs/stacks/api/index.mdx b/content/docs/stacks/api/index.mdx index 36df06c1..df521ffe 100644 --- a/content/docs/stacks/api/index.mdx +++ b/content/docs/stacks/api/index.mdx @@ -11,7 +11,7 @@ The Stacks Blockchain API expands the intentionally minimal RPC endpoints availa ## Popular endpoints -For more information on querying the Stacks core RPC endpoints, see the [Stacks Core RPC](/stacks/rpc-api) documentation. +If you're looking for direct access to the Stacks node, including the ability to broadcast transactions and interact with smart contracts, check out our [Stacks Core RPC](/stacks/rpc-api) documentation. diff --git a/content/docs/stacks/rpc-api/index.mdx b/content/docs/stacks/rpc-api/index.mdx index 0373ec32..b54af6e8 100644 --- a/content/docs/stacks/rpc-api/index.mdx +++ b/content/docs/stacks/rpc-api/index.mdx @@ -21,10 +21,10 @@ The Stacks Core RPC API allows you to query the Stacks blockchain and interact w title="Call smart contracts" description="Call a read-only public function on a smart contract." /> - diff --git a/content/docs/stacks/rpc-api/meta.json b/content/docs/stacks/rpc-api/meta.json index fb31d535..43f140e5 100644 --- a/content/docs/stacks/rpc-api/meta.json +++ b/content/docs/stacks/rpc-api/meta.json @@ -8,6 +8,7 @@ "accounts", "transactions", "blocks", + "pox", "fees", "burn-ops", "smart-contracts", From 192bd9f78d87f5b7d50eb6347cfa1158e0d9eddb Mon Sep 17 00:00:00 2001 From: max-crawford <102705427+max-crawford@users.noreply.github.com> Date: Thu, 10 Oct 2024 15:03:44 -0700 Subject: [PATCH 10/12] Update index.mdx Swapped the name of the "Stacks Core RPC API" to "Stacks Node RPC API" Also updated some copy. --- content/docs/stacks/rpc-api/index.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/docs/stacks/rpc-api/index.mdx b/content/docs/stacks/rpc-api/index.mdx index b54af6e8..3e41f696 100644 --- a/content/docs/stacks/rpc-api/index.mdx +++ b/content/docs/stacks/rpc-api/index.mdx @@ -1,12 +1,12 @@ --- title: Overview -description: Query the Stacks core RPC API, interact with smart contracts, and broadcast transactions all via a familiar REST interface. +description: Query the Stacks Node RPC API, interact with smart contracts, and broadcast transactions all via a familiar REST interface. toc: false --- import { SecondaryCard } from '@/components/card'; -The Stacks Core RPC API allows you to query the Stacks blockchain and interact with smart contracts. Note: this is not a Hiro-maintained service. This RPC API is generated by every Stacks node and allows you to self-host your own node and API. This is a minimalist configuration. For a richer data set and an API that is easier to use, try [Hiro's Stacks Blockchain API](/stacks/api). +The Stacks Node RPC API allows you to query the Stacks blockchain and interact with smart contracts. Note: this is not a Hiro-maintained service. This RPC API is generated by every Stacks node and allows you to self-host your own node and API. This is a minimalist configuration. For a richer data set and an API that is easier to use, try [Hiro's Stacks Blockchain API](/stacks/api). ## Popular endpoints @@ -31,13 +31,13 @@ The Stacks Core RPC API allows you to query the Stacks blockchain and interact w ## Related tools -- **[Stacks Blockchain API](/stacks/api)**: Fetch data from the Stacks Blockchain API. +- **[Stacks Blockchain API](/stacks/api)**: Fetch richer data from Hiro's Stacks Blockchain API. - **[Token Metadata API](/stacks/token-metadata-api)**: Fetch fungible and non-fungible token data on the Stacks blockchain. -- **[Stacks Explorer](https://explorer.hiro.so)**: Looking for a front end to verify activity on the Stacks blockchain? Try the Stacks Explorer. +- **[Stacks Explorer](https://explorer.hiro.so)**: Verify activity on the Stacks blockchain with an easy-to-use front end.
- + Reach out to us on the #api channel on [Discord](https://stacks.chat/) under the Hiro Developer Tools section. There's also a [weekly office hours](https://events.stacks.co/event/HD16484710) on Discord every Thursday at 11am ET. From d8f39ae9e98fb0305114192ade6a7cce3fa965dd Mon Sep 17 00:00:00 2001 From: Ryan Waits Date: Thu, 10 Oct 2024 18:07:45 -0500 Subject: [PATCH 11/12] rename to Stacks Node RPC --- app/(docs)/[...slug]/page.tsx | 4 ++-- content/docs/stacks/api/index.mdx | 4 ++-- content/docs/stacks/rpc-api/meta.json | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/app/(docs)/[...slug]/page.tsx b/app/(docs)/[...slug]/page.tsx index ab3a446c..07d29cd1 100644 --- a/app/(docs)/[...slug]/page.tsx +++ b/app/(docs)/[...slug]/page.tsx @@ -29,7 +29,7 @@ export default function Page({ params }: { params: Param }): JSX.Element { hacks: "Hiro Hacks", "clarinet-js-sdk": "Clarinet JS SDK", "platform-api": "Platform API", - "rpc-api": "Stacks Core RPC", + "rpc-api": "Stacks Node RPC", }; if (page.file?.name === "index" && page.slugs[1]) { @@ -53,7 +53,7 @@ export default function Page({ params }: { params: Param }): JSX.Element { } if (page.slugs[1].toLowerCase() === "rpc-api") { - prefix = "Stacks Core RPC"; + prefix = "Stacks Node RPC"; } return prefix; diff --git a/content/docs/stacks/api/index.mdx b/content/docs/stacks/api/index.mdx index df521ffe..e968703a 100644 --- a/content/docs/stacks/api/index.mdx +++ b/content/docs/stacks/api/index.mdx @@ -11,7 +11,7 @@ The Stacks Blockchain API expands the intentionally minimal RPC endpoints availa ## Popular endpoints -If you're looking for direct access to the Stacks node, including the ability to broadcast transactions and interact with smart contracts, check out our [Stacks Core RPC](/stacks/rpc-api) documentation. +If you're looking for direct access to the Stacks node, including the ability to broadcast transactions and interact with smart contracts, check out our [Stacks Node RPC](/stacks/rpc-api) documentation. @@ -35,7 +35,7 @@ If you're looking for direct access to the Stacks node, including the ability to ## Related tools -- **[Stacks Core RPC](/stacks/rpc-api)**: Fetch data and broadcast transactions from the Stacks core RPC API. +- **[Stacks Node RPC](/stacks/rpc-api)**: Fetch data and broadcast transactions from the Stacks Node RPC API. - **[Token Metadata API](/stacks/token-metadata-api)**: Fetch fungible and non-fungible token data on the Stacks blockchain. - **[Stacks Explorer](https://explorer.hiro.so)**: Looking for a front end to verify activity on the Stacks blockchain? Try the Stacks Explorer. diff --git a/content/docs/stacks/rpc-api/meta.json b/content/docs/stacks/rpc-api/meta.json index 43f140e5..6f86ddc0 100644 --- a/content/docs/stacks/rpc-api/meta.json +++ b/content/docs/stacks/rpc-api/meta.json @@ -1,8 +1,8 @@ { - "title": "Stacks Core RPC", + "title": "Stacks Node RPC", "root": true, "pages": [ - "---Stacks Core RPC---", + "---Stacks Node RPC---", "index", "---API Reference---", "accounts", From cbbf5335fb652b7a04f268f425f3876774158de9 Mon Sep 17 00:00:00 2001 From: Ryan Waits Date: Thu, 10 Oct 2024 19:46:30 -0500 Subject: [PATCH 12/12] update title page --- app/(docs)/[...slug]/page.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/(docs)/[...slug]/page.tsx b/app/(docs)/[...slug]/page.tsx index 07d29cd1..75b037af 100644 --- a/app/(docs)/[...slug]/page.tsx +++ b/app/(docs)/[...slug]/page.tsx @@ -53,7 +53,7 @@ export default function Page({ params }: { params: Param }): JSX.Element { } if (page.slugs[1].toLowerCase() === "rpc-api") { - prefix = "Stacks Node RPC"; + prefix = "Stacks Node RPC API"; } return prefix;