From e2e01edcd63527f9601c5d6864cf47adb5d51f65 Mon Sep 17 00:00:00 2001 From: Aaron Blankstein Date: Tue, 28 Feb 2023 13:50:20 -0600 Subject: [PATCH] docs: add openapi docs for POST block proposal, GET FT withdrawal --- .../core-node/get-ft-withdrawal.example.json | 5 ++ .../core-node/get-ft-withdrawal.schema.json | 19 ++++++++ .../post-block-proposal.error.schema.json | 13 ++++++ .../post-block-proposal.example.json | 4 ++ .../post-block-proposal.okay.example.json | 1 + .../post-block-proposal.okay.schema.json | 6 +++ .../core-node/post-block-proposal.schema.json | 16 +++++++ docs/rpc/openapi.yaml | 46 ++++++++++++++++++- .../stacks-node/src/tests/l1_multiparty.rs | 2 +- .../stacks-node/src/tests/l1_observer_test.rs | 2 +- 10 files changed, 111 insertions(+), 3 deletions(-) create mode 100644 docs/rpc/api/core-node/get-ft-withdrawal.example.json create mode 100644 docs/rpc/api/core-node/get-ft-withdrawal.schema.json create mode 100644 docs/rpc/api/core-node/post-block-proposal.error.schema.json create mode 100644 docs/rpc/api/core-node/post-block-proposal.example.json create mode 100644 docs/rpc/api/core-node/post-block-proposal.okay.example.json create mode 100644 docs/rpc/api/core-node/post-block-proposal.okay.schema.json create mode 100644 docs/rpc/api/core-node/post-block-proposal.schema.json diff --git a/docs/rpc/api/core-node/get-ft-withdrawal.example.json b/docs/rpc/api/core-node/get-ft-withdrawal.example.json new file mode 100644 index 0000000000..c8326c53ef --- /dev/null +++ b/docs/rpc/api/core-node/get-ft-withdrawal.example.json @@ -0,0 +1,5 @@ +{ + "withdrawal_root": "0x02000000206794fd20ad2cf30ea11e7e1c5cfc236a920f672d99e02fa8351577db1cac71f8", + "withdrawal_leaf_hash": "0x02000000205ea1394c234f8688feb6ff1e77250d70d5bb4970ce005024a18043c9c56859b1", + "sibling_hashes": "0x0b000000010c0000000204686173680200000020df140d8faa513a8c7b5d3cecd0df8eb6459d196c945b6a73acd9bddb22d810470c69732d6c6566742d7369646504", +} diff --git a/docs/rpc/api/core-node/get-ft-withdrawal.schema.json b/docs/rpc/api/core-node/get-ft-withdrawal.schema.json new file mode 100644 index 0000000000..23b5275a78 --- /dev/null +++ b/docs/rpc/api/core-node/get-ft-withdrawal.schema.json @@ -0,0 +1,19 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "description": "GET request for FT withdrawal data", + "title": "WithdrawalFtResponse", + "type": "object", + "additionalProperties": false, + "required": ["withdrawal_root", "withdrawal_leaf_hash", "sibling_hashes"], + "properties": { + "withdrawal_root": { + "type": "string" + }, + "withdrawal_leaf_hash": { + "type": "string" + }, + "sibling_hashes": { + "type": "string" + } + } +} diff --git a/docs/rpc/api/core-node/post-block-proposal.error.schema.json b/docs/rpc/api/core-node/post-block-proposal.error.schema.json new file mode 100644 index 0000000000..6657a78a0a --- /dev/null +++ b/docs/rpc/api/core-node/post-block-proposal.error.schema.json @@ -0,0 +1,13 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "description": "Error response for block proposals", + "title": "Error block proposal RPC response", + "type": "object", + "additionalProperties": true, + "required": ["error_message"], + "properties": { + "error_message": { + "type": "string" + } + } +} diff --git a/docs/rpc/api/core-node/post-block-proposal.example.json b/docs/rpc/api/core-node/post-block-proposal.example.json new file mode 100644 index 0000000000..d2f06af1d3 --- /dev/null +++ b/docs/rpc/api/core-node/post-block-proposal.example.json @@ -0,0 +1,4 @@ +{ + "message": "7b22706172656e745f626c6f636b5f68617368223a2230303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030222c22706172656e745f636f6e73656e7375735f68617368223a2230303030303030303030303030303030303030303030303030303030303030303030303030303030222c22626c6f636b223a7b22686561646572223a7b2276657273696f6e223a302c22746f74616c5f776f726b223a7b226275726e223a302c22776f726b223a317d2c2270726f6f66223a2230313031303130313031303130313031303130313031303130313031303130313031303130313031303130313031303130313031303130313031303130313031303130313031303130313031303130313031303130313031303130313031303130313031303130313031303130313031303130313031303130313031303130313031303130313031303130313031303130313031303130313031303130313031222c22706172656e745f626c6f636b223a2230303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030222c22706172656e745f6d6963726f626c6f636b223a2230303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030222c22706172656e745f6d6963726f626c6f636b5f73657175656e6365223a302c2274785f6d65726b6c655f726f6f74223a2236636431643462313734663932636366623731383263336434393861363233373563623163653737343762303133666564343065333534623434643434366231222c2273746174655f696e6465785f726f6f74223a2265643834393761373862633030626439636465383634306263623035356138313261626235663336343666633031393031303663656264393162356635336566222c227769746864726177616c5f6d65726b6c655f726f6f74223a2230303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030222c226d6963726f626c6f636b5f7075626b65795f68617368223a2231353861386561326662633333373464333430356237366536656462623036343434386562316633222c226d696e65725f7369676e617475726573223a7b227369676e617475726573223a5b5d7d7d2c22747873223a5b7b2276657273696f6e223a22546573746e6574222c22636861696e5f6964223a333839383238303631382c2261757468223a7b225374616e64617264223a7b2253696e676c65736967223a7b22686173685f6d6f6465223a225032504b48222c227369676e6572223a2261306533343733646432303364346634366164356332346535623434346635323132653131643362222c226e6f6e6365223a302c2274785f666565223a302c226b65795f656e636f64696e67223a22436f6d70726573736564222c227369676e6174757265223a2230316137656262343737323162353863396666636535636135316237633733663131633837343464313034653464613536366239356435613635346233663066303230343965373866353435636333336134656432386531323231306461393966656130623638623839373865313634333461363333333465653262393266663463227d7d7d2c22616e63686f725f6d6f6465223a224f6e436861696e4f6e6c79222c22706f73745f636f6e646974696f6e5f6d6f6465223a2244656e79222c22706f73745f636f6e646974696f6e73223a5b5d2c227061796c6f6164223a7b22436f696e62617365223a2230303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030227d7d5d7d2c226d6963726f626c6f636b735f636f6e6669726d6564223a5b5d2c226275726e5f746970223a2230303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030222c226275726e5f7469705f686569676874223a322c2269735f6d61696e6e6574223a66616c73652c226d6963726f626c6f636b5f7075626b65795f68617368223a2231353861386561326662633333373464333430356237366536656462623036343434386562316633222c22746f74616c5f6275726e223a307d", + "signature": "01e0447fa58307e03ecd0c7a4d9d2c7b53bfc1b308331869041f2279c1fdbcaa660a19755ad4b2785bd09d1578e35a588ce3c23e7ba660f72c5a21736e2a21b297" +} diff --git a/docs/rpc/api/core-node/post-block-proposal.okay.example.json b/docs/rpc/api/core-node/post-block-proposal.okay.example.json new file mode 100644 index 0000000000..7101b23f5c --- /dev/null +++ b/docs/rpc/api/core-node/post-block-proposal.okay.example.json @@ -0,0 +1 @@ +"0xb3b1bdf21ecb659e6929e65470a5493f8cfd57e7a6da58a7b453096a76670cf75b489bb8ef3e1aa920a05c139af63102150a732f9baa403ad8164d541b34bcdc00" diff --git a/docs/rpc/api/core-node/post-block-proposal.okay.schema.json b/docs/rpc/api/core-node/post-block-proposal.okay.schema.json new file mode 100644 index 0000000000..70aa3322c4 --- /dev/null +++ b/docs/rpc/api/core-node/post-block-proposal.okay.schema.json @@ -0,0 +1,6 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "description": "POST response for block proposal (hex encoded signature)", + "title": "Success response for block proposal", + "type": "string", +} diff --git a/docs/rpc/api/core-node/post-block-proposal.schema.json b/docs/rpc/api/core-node/post-block-proposal.schema.json new file mode 100644 index 0000000000..850cdab321 --- /dev/null +++ b/docs/rpc/api/core-node/post-block-proposal.schema.json @@ -0,0 +1,16 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "description": "POST request for block proposals", + "title": "Block proposal RPC request", + "type": "object", + "additionalProperties": false, + "required": ["message", "signature"], + "properties": { + "message": { + "type": "string" + }, + "signature": { + "type": "string" + } + } +} diff --git a/docs/rpc/openapi.yaml b/docs/rpc/openapi.yaml index 3638229b87..67aa24d659 100644 --- a/docs/rpc/openapi.yaml +++ b/docs/rpc/openapi.yaml @@ -9,6 +9,36 @@ info: This is the documentation for the `stacks-node` RPC interface. paths: + /v2/block_proposal: + post: + summary: Propose a block to a subnet validator + tags: + - Subnet Mining + description: Subnet mining occurs through federation participation. In order for a block to be mined, it must be signed by a quorum of validators. This endpoint allows the quorum leader to propose a block to the validators. The validators check that the block is legal, and return a signature if so. + operationId: post_block_proposal + requestBody: + content: + application/json: + schema: + $ref: ./api/core-node/post-block-proposal.schema.json + example: + $ref: ./api/core-node/post-block-proposal.example.json + responses: + 200: + description: The block proposal was accepted, and the validator returns their signature as a hex string + content: + application/json: + schema: + $ref: ./api/core-node/post-block-proposal.okay.schema.json + example: + $ref: ./api/core-node/post-block-proposal.okay.example.json + 406: + description: The block proposal was rejected + content: + application/json: + schema: + $ref: ./api/core-node/post-block-proposal.error.schema.json + /v2/transactions: post: summary: Broadcast raw transaction @@ -386,7 +416,21 @@ paths: $ref: ./api/core-node/get-fee-transfer.schema.json example: $ref: ./api/core-node/get-fee-transfer.example.json - /v2/withdrawal/nft/{block_height}/{sender}/{withdrawal_id}/{contract_address}/{contract_name}/{asset_name}/{id}: + + /v2/withdrawal/ft/{block_height}/{sender}/{withdrawal_id}/{contract_address}/{contract_name}/{amount}: + get: + summary: Get merkle tree data associated with a processed FT withdrawal. + responses: + 200: + description: The merkle leaf hash, root hash, and merkle proof path for the requested withdrawal entry. These are used as parameters to the `ft-withdraw` method of a layer-1 subnet contract, and returned as hex-encoded Clarity serialized values. + content: + application/json: + schema: + $ref: ./api/core-node/get-ft-withdrawal.schema.json + example: + $ref: ./api/core-node/get-ft-withdrawal.example.json + + /v2/withdrawal/nft/{block_height}/{sender}/{withdrawal_id}/{contract_address}/{contract_name}/{id}: get: summary: Get merkle tree data associated with a processed NFT withdrawal. responses: diff --git a/testnet/stacks-node/src/tests/l1_multiparty.rs b/testnet/stacks-node/src/tests/l1_multiparty.rs index a7dc21fdf7..19b0fccdec 100644 --- a/testnet/stacks-node/src/tests/l1_multiparty.rs +++ b/testnet/stacks-node/src/tests/l1_multiparty.rs @@ -179,7 +179,7 @@ fn l1_multiparty_1_of_n_integration_test() { // simple progress. fn l1_multiparty_2_of_2_integration_test() { // running locally: - // STACKS_BASE_DIR=~/devel/stacks-blockchain/target/release/stacks-node STACKS_NODE_TEST=1 cargo test --workspace l1_integration_test + // STACKS_BASE_DIR=~/devel/stacks-blockchain/target/release/stacks-node STACKS_NODE_TEST=1 cargo test --workspace l1_multiparty_2_of_2 if env::var("STACKS_NODE_TEST") != Ok("1".into()) { return; } diff --git a/testnet/stacks-node/src/tests/l1_observer_test.rs b/testnet/stacks-node/src/tests/l1_observer_test.rs index 143636f1ea..c4043a0609 100644 --- a/testnet/stacks-node/src/tests/l1_observer_test.rs +++ b/testnet/stacks-node/src/tests/l1_observer_test.rs @@ -458,7 +458,7 @@ fn l1_integration_test() { #[test] fn l1_deposit_and_withdraw_asset_integration_test() { // running locally: - // STACKS_BASE_DIR=~/devel/stacks-blockchain/target/release/stacks-node STACKS_NODE_TEST=1 cargo test --workspace l1_deposit_asset_integration_test + // STACKS_BASE_DIR=~/devel/stacks-blockchain/target/release/stacks-node STACKS_NODE_TEST=1 cargo test --workspace l1_deposit_and_withdraw_asset_integration_test if env::var("STACKS_NODE_TEST") != Ok("1".into()) { return; }