mirror of
https://github.com/alexgo-io/stacks-puppet-node.git
synced 2026-06-18 03:38:57 +08:00
346 lines
9.2 KiB
Markdown
346 lines
9.2 KiB
Markdown
# RPC Endpoints
|
|
|
|
### POST /v2/transactions
|
|
|
|
This endpoint is for posting _raw_ transaction data to the node's mempool.
|
|
|
|
Rejections result in a 400 error, with JSON data in the form:
|
|
|
|
```
|
|
{
|
|
"error": "transaction rejected",
|
|
"reason": "BadNonce",
|
|
"reason_data": {
|
|
"actual": 3,
|
|
"expected": 0,
|
|
"is_origin": true,
|
|
"principal": "ST2MVNFYF6H9DCMAV3HVNHTJVVE3CFWT1JYMH1EZB"
|
|
},
|
|
"txid": "0x4068179cb9169b969c80518d83890f8b808a70ab998dd227149221be9480a616"
|
|
}
|
|
```
|
|
|
|
Possible values for the "reason" field and "reason_data" field are:
|
|
|
|
* `Serialization`
|
|
* The `reason_data` field will be an object containing a `message`
|
|
string detailing the serialization error
|
|
* `Deserialization`
|
|
* The `reason_data` field will be an object containing a `message`
|
|
string detailing the deserialization error
|
|
* `SignatureValidation`
|
|
* The `reason_data` field will be an object containing a `message`
|
|
string detailing the signature validation error
|
|
* `BadNonce`
|
|
* The `reason_data` field will be an object containing:
|
|
* `expected` - a number representing the expected nonce,
|
|
* `actual` - a number representing the actual nonce,
|
|
* `is_origin` - a boolean representing whether the nonce error
|
|
occurred on the 'origin' or 'sponsor' of the transaction,
|
|
* `principal` - a string representing the principal address
|
|
that had the bad nonce
|
|
* `FeeTooLow`
|
|
* The `reason_data` field will be an object containing:
|
|
* `expected` - a number representing the minimum expected fee,
|
|
* `actual` - a number representing the supplied fee
|
|
* `NotEnoughFunds`
|
|
* The `reason_data` field will be an object containing:
|
|
* `expected` - a hex string representing the expected
|
|
number of microstacks
|
|
* `actual` - a hex string representing the actual
|
|
number of microstacks the account possesses
|
|
* `NoSuchContract`
|
|
* `NoSuchPublicFunction`
|
|
* `BadFunctionArgument`
|
|
* The `reason_data` field will be an object containing a `message`
|
|
string detailing why the supplied argument was bad.
|
|
* `ContractAlreadyExists`
|
|
* The `reason_data` field will be an object containing a `contract_identifier`
|
|
string representing the contract identifier that would be duplicated.
|
|
* `PoisonMicroblocksDoNotConflict`
|
|
* `PoisonMicroblockHasUnknownPubKeyHash`
|
|
* `PoisonMicroblockIsInvalid`
|
|
* `BadAddressVersionByte`
|
|
* `NoCoinbaseViaMempool`
|
|
* `ServerFailureNoSuchChainTip`
|
|
* `ServerFailureDatabase`
|
|
* The `reason_data` field will be an object containing a `message`
|
|
string detailing why the server had a database error
|
|
* `ServerFailureOther`
|
|
* The `reason_data` field will be an object containing a `message`
|
|
string providing more detail on the server failure
|
|
|
|
Reason types without additional information will not have a
|
|
`reason_data` field.
|
|
|
|
### GET /v2/pox
|
|
|
|
Get current PoX-relevant information. See OpenAPI [spec](./rpc/openapi.yaml) for details.
|
|
|
|
### GET /v2/accounts/[Principal]
|
|
|
|
Get the account data for the provided principal.
|
|
The principal string is either a Stacks address or a Contract identifier (e.g.,
|
|
`SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`
|
|
|
|
Returns JSON data in the form:
|
|
|
|
```
|
|
{
|
|
"balance": "0x100..",
|
|
"nonce": 1,
|
|
"balance_proof": "0x01fa...",
|
|
"nonce_proof": "0x01ab...",
|
|
}
|
|
```
|
|
|
|
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.
|
|
|
|
This endpoint also accepts a querystring parameter `?proof=` which when supplied `0`, will return the
|
|
JSON object _without_ the `balance_proof` or `nonce_proof` fields.
|
|
|
|
### POST /v2/map_entry/[Stacks Address]/[Contract Name]/[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.
|
|
|
|
Returns JSON data in the form:
|
|
|
|
```
|
|
{
|
|
"data": "0x01ce...",
|
|
"proof": "0x01ab...",
|
|
}
|
|
```
|
|
|
|
Where 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.
|
|
|
|
This endpoint also accepts a querystring parameter `?proof=` which when supplied `0`, will return the
|
|
JSON object _without_ the `proof` field.
|
|
|
|
### GET /v2/fees/transfer
|
|
|
|
Get an estimated fee rate for STX transfer transactions. This a a fee rate / byte, and is returned as a JSON integer.
|
|
|
|
### GET /v2/contracts/interface/[Stacks Address]/[Contract Name]
|
|
|
|
Fetch the contract interface for a given contract, identified by [Stacks Address] and [Contract Name].
|
|
|
|
This returns a JSON object of the form:
|
|
|
|
```
|
|
{
|
|
"functions": [
|
|
{
|
|
"name": "exotic-block-height",
|
|
"access": "private",
|
|
"args": [
|
|
{
|
|
"name": "height",
|
|
"type": "uint128"
|
|
}
|
|
],
|
|
"outputs": {
|
|
"type": "bool"
|
|
}
|
|
},
|
|
{
|
|
"name": "update-info",
|
|
"access": "public",
|
|
"args": [],
|
|
"outputs": {
|
|
"type": {
|
|
"response": {
|
|
"ok": "bool",
|
|
"error": "none"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"name": "get-exotic-data-info",
|
|
"access": "read_only",
|
|
"args": [
|
|
{
|
|
"name": "height",
|
|
"type": "uint128"
|
|
}
|
|
],
|
|
"outputs": {
|
|
"type": {
|
|
"tuple": [
|
|
{
|
|
"name": "btc-hash",
|
|
"type": {
|
|
"buffer": {
|
|
"length": 32
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"name": "burn-block-time",
|
|
"type": "uint128"
|
|
},
|
|
{
|
|
"name": "id-hash",
|
|
"type": {
|
|
"buffer": {
|
|
"length": 32
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"name": "stacks-hash",
|
|
"type": {
|
|
"buffer": {
|
|
"length": 32
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"name": "stacks-miner",
|
|
"type": "principal"
|
|
},
|
|
{
|
|
"name": "vrf-seed",
|
|
"type": {
|
|
"buffer": {
|
|
"length": 32
|
|
}
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
],
|
|
"variables": [],
|
|
"maps": [
|
|
{
|
|
"name": "block-data",
|
|
"key": [
|
|
{
|
|
"name": "height",
|
|
"type": "uint128"
|
|
}
|
|
],
|
|
"value": [
|
|
{
|
|
"name": "btc-hash",
|
|
"type": {
|
|
"buffer": {
|
|
"length": 32
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"name": "burn-block-time",
|
|
"type": "uint128"
|
|
},
|
|
{
|
|
"name": "id-hash",
|
|
"type": {
|
|
"buffer": {
|
|
"length": 32
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"name": "stacks-hash",
|
|
"type": {
|
|
"buffer": {
|
|
"length": 32
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"name": "stacks-miner",
|
|
"type": "principal"
|
|
},
|
|
{
|
|
"name": "vrf-seed",
|
|
"type": {
|
|
"buffer": {
|
|
"length": 32
|
|
}
|
|
}
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"fungible_tokens": [],
|
|
"non_fungible_tokens": []
|
|
}
|
|
```
|
|
|
|
### GET /v2/contracts/source/[Stacks Address]/[Contract Name]
|
|
|
|
Fetch the source for a smart contract, along with the block height it was
|
|
published in, and the MARF proof for the data.
|
|
|
|
```
|
|
{
|
|
"source": "(define-private ...",
|
|
"publish_height": 1,
|
|
"proof": "0x00213..."
|
|
}
|
|
```
|
|
|
|
This endpoint also accepts a querystring parameter `?proof=` which
|
|
when supplied `0`, will return the JSON object _without_ the `proof`
|
|
field.
|
|
|
|
### POST /v2/contracts/call-read/[Stacks Address]/[Contract Name]/[Function Name]
|
|
|
|
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:
|
|
|
|
```
|
|
{
|
|
"sender": "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info",
|
|
"arguments": [ "0x0011...", "0x00231..." ]
|
|
}
|
|
```
|
|
|
|
Where sender is either a Contract identifier or a normal Stacks address, and arguments
|
|
is an array of hex serialized Clarity values.
|
|
|
|
This endpoint returns a JSON object of the following form:
|
|
|
|
```
|
|
{
|
|
"okay": true,
|
|
"result": "0x0011..."
|
|
}
|
|
```
|
|
|
|
Where `"okay"` is `true` if the function executed successfully, and result contains the
|
|
hex serialization of the Clarity return value.
|
|
|
|
If an error occurs in processing the function call, this endpoint returns a 200 response with a JSON
|
|
object of the following form:
|
|
|
|
```
|
|
{
|
|
"okay": false,
|
|
"cause": "Unchecked(PublicFunctionNotReadOnly(..."
|
|
}
|
|
```
|
|
|
|
### GET /v2/traits/[Stacks Address]/[Contract Name]/[Trait Stacks Address]/[Trait Contract Name]/[Trait Name]
|
|
|
|
Determine whether a given trait is implemented within the specified contract (either explicitly or implicitly).
|
|
|
|
See OpenAPI [spec](./rpc/openapi.yaml) for details. |