kylefang/stacks-puppet-node
1
0
Fork 0
mirror of https://github.com/alexgo-io/stacks-puppet-node.git synced 2026-06-17 02:24:48 +08:00
Code Issues Packages Projects Releases Wiki Activity

add OpenAPI docs for RPC endpoints, update /v2/pox return based on PR feedback

Browse Source
This commit is contained in:
Aaron Blankstein
2021-02-23 11:31:10 -06:00
parent 345bd0d49f
commit 8650dff243
26 changed files with 1102 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/rpc/api/contract/post-call-read-only-fn-fail.example.json Normal file
View File

@@ -0,0 +1,4 @@
{
"okay": false,
"cause": "Unchecked(PublicFunctionNotReadOnly(..."
}

4
docs/rpc/api/contract/post-call-read-only-fn-success.example.json Normal file
View File

@@ -0,0 +1,4 @@
{
"okay": true,
"result": "0x111..."
}

19
docs/rpc/api/contract/post-call-read-only-fn.schema.json Normal file
View File

@@ -0,0 +1,19 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "GET request to get contract source",
"title": "ReadOnlyFunctionSuccessResponse",
"type": "object",
"additionalProperties": false,
"required": ["okay"],
"properties": {
"okay": {
"type": "boolean"
},
"result": {
"type": "string"
},
"cause": {
"type": "string"
}
}
}

8
docs/rpc/api/core-node/get-account-data.example.json Normal file
View File

@@ -0,0 +1,8 @@
{
"balance": "0x0000000000000000000000000007a120",
"locked": "0x0000000000000000000000000007a120",
"unlock_height": 126,
"nonce": 2867,
"balance_proof": "0xabce",
"nonce_proof": "0xabcd"
}

28
docs/rpc/api/core-node/get-account-data.schema.json Normal file
View File

@@ -0,0 +1,28 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "GET request for account data",
"title": "AccountDataResponse",
"type": "object",
"additionalProperties": false,
"required": ["balance", "locked", "unlock_height", "nonce", "balance_proof", "nonce_proof"],
"properties": {
"balance": {
"type": "string"
},
"locked": {
"type": "string"
},
"unlock_height": {
"type": "integer"
},
"nonce": {
"type": "integer"
},
"balance_proof": {
"type": "string"
},
"nonce_proof": {
"type": "string"
}
}
}

4
docs/rpc/api/core-node/get-contract-data-map-entry.example.json Normal file
View File

@@ -0,0 +1,4 @@
{
"data": "0x0a0c000000010a6d6f6e737465722d69640100000000000000000000000000000001",
"proof": "0x123..."
}

17
docs/rpc/api/core-node/get-contract-data-map-entry.schema.json Normal file
View File

@@ -0,0 +1,17 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Response of get data map entry request",
"title": "MapEntryResponse",
"type": "object",
"required": ["data"],
"properties": {
"data": {
"type": "string",
"description": "Hex-encoded string of clarity value. It is always an optional tuple."
},
"proof": {
"type": "string",
"description": "Hex-encoded string of the MARF proof for the data"
}
}
}

134
docs/rpc/api/core-node/get-contract-interface.example.json Normal file
View File

@@ -0,0 +1,134 @@
{
"functions": [
{
"name": "get-value",
"access": "public",
"args": [
{
"name": "key",
"type": {
"buffer": {
"length": 32
}
}
}
],
"outputs": {
"type": {
"response": {
"ok": {
"buffer": {
"length": 32
}
},
"error": "int128"
}
}
}
},
{
"name": "set-value",
"access": "public",
"args": [
{
"name": "key",
"type": {
"buffer": {
"length": 32
}
}
},
{
"name": "value",
"type": {
"buffer": {
"length": 32
}
}
}
],
"outputs": {
"type": {
"response": {
"ok": "uint128",
"error": "none"
}
}
}
},
{
"name": "test-emit-event",
"access": "public",
"args": [],
"outputs": {
"type": {
"response": {
"ok": "uint128",
"error": "none"
}
}
}
},
{
"name": "test-event-types",
"access": "public",
"args": [],
"outputs": {
"type": {
"response": {
"ok": "uint128",
"error": "none"
}
}
}
}
],
"variables": [
{
"name": "recipient",
"type": "principal",
"access": "constant"
},
{
"name": "sender",
"type": "principal",
"access": "constant"
}
],
"maps": [
{
"name": "store",
"key": [
{
"name": "key",
"type": {
"buffer": {
"length": 32
}
}
}
],
"value": [
{
"name": "value",
"type": {
"buffer": {
"length": 32
}
}
}
]
}
],
"fungible_tokens": [
{
"name": "novel-token-19"
}
],
"non_fungible_tokens": [
{
"name": "hello-nft",
"type": "uint128"
}
]
}

44
docs/rpc/api/core-node/get-contract-interface.schema.json Normal file
View File

@@ -0,0 +1,44 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "GET request to get contract interface",
"title": "ContractInterfaceResponse",
"type": "object",
"required": ["functions", "variables", "maps", "fungible_tokens", "non_fungible_tokens"],
"properties": {
"functions": {
"type": "array",
"items": {
"type": "object"
},
"description": "List of defined methods"
},
"variables": {
"type": "array",
"items": {
"type": "object"
},
"description": "List of defined variables"
},
"maps": {
"type": "array",
"items": {
"type": "object"
},
"description": "List of defined data-maps"
},
"fungible_tokens": {
"type": "array",
"items": {
"type": "object"
},
"description": "List of fungible tokens in the contract"
},
"non_fungible_tokens": {
"type": "array",
"items": {
"type": "object"
},
"description": "List of non-fungible tokens in the contract"
}
}
}

5
docs/rpc/api/core-node/get-contract-source.example.json Normal file
View File

@@ -0,0 +1,5 @@
{
"source": "(define-constant sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)\n(define-constant recipient 'SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G)\n\n(define-fungible-token novel-token-19)\n(begin (ft-mint? novel-token-19 u12 sender))\n(begin (ft-transfer? novel-token-19 u2 sender recipient))\n\n(define-non-fungible-token hello-nft uint)\n(begin (nft-mint? hello-nft u1 sender))\n(begin (nft-mint? hello-nft u2 sender))\n(begin (nft-transfer? hello-nft u1 sender recipient))\n\n(define-public (test-emit-event)\n (begin\n (print \"Event! Hello world\")\n (ok u1)))\n(begin (test-emit-event))\n\n(define-public (test-event-types)\n (begin\n (unwrap-panic (ft-mint? novel-token-19 u3 recipient))\n (unwrap-panic (nft-mint? hello-nft u2 recipient))\n (unwrap-panic (stx-transfer? u60 tx-sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR))\n (unwrap-panic (stx-burn? u20 tx-sender))\n (ok u1)))\n\n(define-map store ((key (buff 32))) ((value (buff 32))))\n(define-public (get-value (key (buff 32)))\n (begin\n (match (map-get? store ((key key)))\n entry (ok (get value entry))\n (err 0))))\n(define-public (set-value (key (buff 32)) (value (buff 32)))\n (begin\n (map-set store ((key key)) ((value value)))\n (ok u1)))",
"publish_height": 3196,
"proof": "0000001104060000001ec4e..."
}

19
docs/rpc/api/core-node/get-contract-source.schema.json Normal file
View File

@@ -0,0 +1,19 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "GET request to get contract source",
"title": "ContractSourceResponse",
"type": "object",
"additionalProperties": false,
"required": ["source", "publish_height", "proof"],
"properties": {
"source": {
"type": "string"
},
"publish_height": {
"type": "integer"
},
"proof": {
"type": "string"
}
}
}

1
docs/rpc/api/core-node/get-fee-transfer.example.json Normal file
View File

@@ -0,0 +1 @@
1

7
docs/rpc/api/core-node/get-fee-transfer.schema.json Normal file
View File

@@ -0,0 +1,7 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "GET fee estimates",
"title": "CoreNodeFeeResponse",
"type": "string",
"additionalProperties": false
}

15
docs/rpc/api/core-node/get-info.example.json Normal file
View File

@@ -0,0 +1,15 @@
{
"peer_version": 385875968,
"pox_consensus": "17f76e597bab45646956f38dd39573085d72cbc0",
"burn_block_height": 16,
"stable_pox_consensus": "8e0561978fc5506b68a589c402dad97e862edb59",
"stable_burn_block_height": 15,
"server_version": "blockstack-core 0.0.1 => 23.0.0.0 (, release build, linux [x86_64])",
"network_id": 2147483648,
"parent_network_id": 3669344250,
"stacks_tip_height": 15,
"stacks_tip": "b1807a2d3f7f8c7922f7c1d60d7c34145ade05d789640dc7dc9ec1021e07bb54",
"stacks_tip_consensus_hash": "17f76e597bab45646956f38dd39573085d72cbc0",
"unanchored_tip": "0000000000000000000000000000000000000000000000000000000000000000",
"exit_at_block_height": null
}

76
docs/rpc/api/core-node/get-info.schema.json Normal file
View File

@@ -0,0 +1,76 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "GET request that core node information",
"title": "CoreNodeInfoResponse",
"type": "object",
"additionalProperties": false,
"required": [
"peer_version",
"pox_consensus",
"burn_block_height",
"stable_pox_consensus",
"stable_burn_block_height",
"server_version",
"network_id",
"parent_network_id",
"stacks_tip_height",
"stacks_tip",
"stacks_tip_consensus_hash",
"unanchored_tip",
"exit_at_block_height"
],
"properties": {
"peer_version": {
"type": "integer",
"description": "identifies the version number for the networking communication, this should not change while a node is running, and will only change if there's an upgrade"
},
"pox_consensus": {
"type": "string",
"description": "is a hash used to identify the burnchain view for a node. it incorporates bitcoin chain information and PoX information. nodes that disagree on this value will appear to each other as forks. this value will change after every block"
},
"burn_block_height": {
"type": "integer",
"description": "latest bitcoin chain height"
},
"stable_pox_consensus": {
"type": "string",
"description": "same as burn_consensus, but evaluated at stable_burn_block_height"
},
"stable_burn_block_height": {
"type": "integer",
"description": "leftover from stacks 1.0, basically always burn_block_height - 1"
},
"server_version": {
"type": "string",
"description": "is a version descriptor"
},
"network_id": {
"type": "integer",
"description": "is similar to peer_version and will be used to differentiate between different testnets. this value will be different between mainnet and testnet. once launched, this value will not change"
},
"parent_network_id": {
"type": "integer",
"description": "same as network_id, but for bitcoin"
},
"stacks_tip_height": {
"type": "integer",
"description": "the latest Stacks chain height. Stacks forks can occur independent of the Bitcoin chain, that height doesn't increase 1-to-1 with the Bitcoin height"
},
"stacks_tip": {
"type": "string",
"description": "the best known block hash for the Stack chain (not including any pending microblocks)"
},
"stacks_tip_consensus_hash": {
"type": "string",
"description": "the burn chain (i.e., bitcoin) consensus hash at the time that stacks_tip was mined"
},
"unanchored_tip": {
"type": "string",
"description": "the latest microblock hash if any microblocks were processed. if no microblock has been processed for the current block, a 000.., hex array is returned"
},
"exit_at_block_height": {
"type": "integer",
"description": "the block height at which the testnet network will be reset. not applicable for mainnet"
}
}
}

33
docs/rpc/api/core-node/get-pox.example.json Normal file
View File

@@ -0,0 +1,33 @@
{
"contract_id": "SP000000000000000000002Q6VF78.pox",
"pox_activation_threshold_ustx": 52329761604388,
"first_burnchain_block_height": 666050,
"prepare_phase_block_length": 100,
"reward_phase_block_length": 2000,
"reward_slots": 4000,
"rejection_fraction": 25,
"total_liquid_supply_ustx": 1046595232087772,
"current_cycle": {
"id": 2,
"min_threshold_ustx": 70000000000,
"stacked_ustx": 202157971547640,
"is_pox_active": true
},
"next_cycle": {
"id": 3,
"min_threshold_ustx": 70000000000,
"min_increment_ustx": 52329761604,
"stacked_ustx": 162057034977640,
"prepare_phase_start_block_height": 672250,
"blocks_until_prepare_phase": 407,
"reward_phase_start_block_height": 672350,
"blocks_until_reward_phase": 507,
"ustx_until_pox_rejection": 261648808021925
},
"min_amount_ustx": 70000000000,
"prepare_cycle_length": 100,
"reward_cycle_id": 2,
"reward_cycle_length": 2100,
"rejection_votes_left_required": 261648808021925,
"next_reward_cycle_in": 507
}

160
docs/rpc/api/core-node/get-pox.schema.json Normal file
View File

@@ -0,0 +1,160 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Get Proof of Transfer (PoX) information",
"title": "CoreNodePoxResponse",
"type": "object",
"additionalProperties": false,
"required": [
"contract_id",
"first_burnchain_block_height",
"pox_activation_threshold_ustx",
"prepare_phase_block_length",
"reward_phase_block_length",
"reward_slots",
"rejection_fraction",
"total_liquid_supply_ustx",
"current_cycle",
"next_cycle",
"reward_cycle_length",
"min_amount_ustx",
"reward_cycle_id",
"prepare_cycle_length",
"rejection_votes_left_required"
],
"properties": {
"contract_id": {
"type": "string",
"description": "The contract identifier for the PoX contract"
},
"first_burnchain_block_height": {
"type": "integer",
"description": "The first burn block evaluated in this Stacks chain"
},
"pox_activation_threshold_ustx": {
"type": "integer",
"description": "The threshold of stacking participation that must be reached for PoX to activate in any cycle"
},
"rejection_fraction": {
"type": "integer",
"description": "The fraction of liquid STX that must vote to reject PoX in order to prevent the next reward cycle from activating."
},
"reward_phase_block_length": {
"type": "integer",
"description": "The length in burn blocks of the reward phase"
},
"prepare_phase_block_length": {
"type": "integer",
"description": "The length in burn blocks of the prepare phase"
},
"reward_slots": {
"type": "integer",
"description": "The number of reward slots in a reward cycle"
},
"total_liquid_supply_ustx": {
"type": "integer",
"description": "The current total amount of liquid microstacks."
},
"reward_cycle_length": {
"type": "integer",
"description": "The length in burn blocks of a whole PoX cycle (reward phase and prepare phase)"
},
"current_cycle": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"min_threshold_ustx",
"stacked_ustx",
"is_pox_active"
],
"properties": {
"id": {
"type": "integer",
"description": "The reward cycle number"
},
"min_threshold_ustx": {
"type": "integer",
"description": "The threshold amount for obtaining a slot in this reward cycle."
},
"stacked_ustx": {
"type": "integer",
"description": "The total amount of stacked microstacks in this reward cycle."
},
"is_pox_active": {
"type": "boolean",
"description": "Whether or not PoX is active during this reward cycle."
},
}
},
"next_cycle": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"min_threshold_ustx",
"stacked_ustx",
"min_increment_ustx",
"prepare_phase_start_block_height",
"blocks_until_prepare_phase",
"reward_phase_start_block_height",
"blocks_until_reward_phase",
"ustx_until_pox_rejection"
],
"properties": {
"id": {
"type": "integer",
"description": "The reward cycle number"
},
"min_threshold_ustx": {
"type": "integer",
"description": "The threshold amount for obtaining a slot in this reward cycle."
},
"stacked_ustx": {
"type": "integer",
"description": "The total amount of stacked microstacks in this reward cycle."
},
"min_increment_ustx": {
"type": "integer",
"description": "The minimum amount that can be used to submit a `stack-stx` call."
},
"prepare_phase_start_block_height": {
"type": "integer",
"description": "The burn block height when the prepare phase for this cycle begins. Any eligible stacks must be stacked before this block."
},
"blocks_until_prepare_phase": {
"type": "integer",
"description": "The number of burn blocks until the prepare phase for this cycle starts. If the prepare phase for this cycle already started, this value will be negative."
},
"reward_phase_start_block_height": {
"type": "integer",
"description": "The burn block height when the reward phase for this cycle begins. Any eligible stacks must be stacked before this block."
},
"blocks_until_reward_phase": {
"type": "integer",
"description": "The number of burn blocks until this reward phase starts."
},
"ustx_until_pox_rejection": {
"type": "integer",
"description": "The remaining amount of liquid STX that must vote to reject the next reward cycle to prevent the next reward cycle from activating."
}
}
},
"reward_cycle_id": {
"type": "integer",
"deprecated": true,
"description": "The active reward cycle number"
},
"min_amount_ustx": {
"type": "integer",
"deprecated": true,
},
"prepare_cycle_length": {
"type": "integer",
"deprecated": true,
},
"rejection_votes_left_required": {
"type": "integer",
"deprecated": true,
}
}
}

11
docs/rpc/api/transaction/post-core-node-transactions-error.example.json Normal file
View File

@@ -0,0 +1,11 @@
{
"error": "transaction rejected",
"reason": "BadNonce",
"reason_data": {
"actual": 4,
"expected": 0,
"is_origin": true,
"principal": "ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH"
},
"txid": "caf6fd60ae05b0c2d19ef14ab6a7670b1095d117fa7c80224c74e76214d0a791"
}

25
docs/rpc/api/transaction/post-core-node-transactions-error.schema.json Normal file
View File

@@ -0,0 +1,25 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "GET request that returns transactions",
"title": "PostCoreNodeTransactionsError",
"type": "object",
"required": ["error", "reason", "reason_data", "txid"],
"properties": {
"error": {
"type": "string",
"description": "The error"
},
"reason": {
"type": "string",
"description": "The reason for the error"
},
"reason_data": {
"type": "object",
"description": "More details about the reason"
},
"txid": {
"type": "string",
"description": "The relevant transaction id"
}
}
}