From b2c36920a6712afe5befb990c2eec467dc938587 Mon Sep 17 00:00:00 2001 From: Thomas Richards Date: Sun, 26 Feb 2023 16:01:15 -0800 Subject: [PATCH 01/10] added new folders and files for subnets --- docs/feature-guides/trust-models.md | 13 + docs/getting-started.md | 427 ++++++++++++++++++ docs/how-to-guides/how-to-deposit-nft.md | 20 + docs/how-to-guides/how-to-mint-nft.md | 12 + docs/how-to-guides/how-to-publish-contract.md | 47 ++ .../how-to-register-nft-asset.md | 12 + docs/how-to-guides/how-to-run-tests.md | 15 + docs/how-to-guides/how-to-transfer-nft.md | 22 + docs/how-to-guides/how-to-withdraw-nft.md | 61 +++ docs/overview.md | 41 ++ 10 files changed, 670 insertions(+) create mode 100644 docs/feature-guides/trust-models.md create mode 100644 docs/getting-started.md create mode 100644 docs/how-to-guides/how-to-deposit-nft.md create mode 100644 docs/how-to-guides/how-to-mint-nft.md create mode 100644 docs/how-to-guides/how-to-publish-contract.md create mode 100644 docs/how-to-guides/how-to-register-nft-asset.md create mode 100644 docs/how-to-guides/how-to-run-tests.md create mode 100644 docs/how-to-guides/how-to-transfer-nft.md create mode 100644 docs/how-to-guides/how-to-withdraw-nft.md create mode 100644 docs/overview.md diff --git a/docs/feature-guides/trust-models.md b/docs/feature-guides/trust-models.md new file mode 100644 index 000000000..846115b5d --- /dev/null +++ b/docs/feature-guides/trust-models.md @@ -0,0 +1,13 @@ +--- +title: Trust Models +--- + + +The current implementation of subnets uses a federated system of miners. This federation is fully-trusted, but future work on subnets will explore alternative trust models. + +In a fully - trusted model: + +- Miners are responsible for issuing subnet blocks. +- Users can validate, but subnet miners control withdrawals. +- Trust can be federated with a 2-phase commit and BFT protocol for miner block issuance. +- Federation requires a majority of miners to approve withdrawals. \ No newline at end of file diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 000000000..5c3f98398 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,427 @@ +--- +# The default id is the same as the one being defined below. so not needed +title: Getting Started +--- + +# Getting Started + +Subnets can be built using any of the following methods: +- Build with Clarinet +- Build with Testnet +- Test Locally + +> **_NOTE:_** +> +> Subnets was earlier referred as Hyperchains. While we are in the process of updating the content, you might still see subnets being referred as Hyperchains. + +## Build with Clarinet + +Make sure you have `clarinet` installed locally, and that it is at version 0.33.0 or above. +If you do not have clarinet, you can find installation instructions [here](https://github.com/hirosystems/clarinet). + +Let's create a new clarinet project. This will create a new directory with a Clarinet project initialized. +``` +clarinet new nft-use-case +``` + +Let us copy contract files and scripts over from the `stacks-hyperchains` repository into the `nft-use-case` directory. +If you don't already have the stacks-hyperchains repository, you can [clone it](https://github.com/hirosystems/stacks-hyperchains). +Here's the command to clone the stacks-hyperchains repository: +``` +git clone https://github.com/hirosystems/stacks-hyperchains.git +``` +Set the environment variable `HYPERCHAIN_PATH` to the location of the stacks-hyperchains repository on your computer. +``` +export HYPERCHAIN_PATH= +``` + +Now, we can copy files from the stacks-hyperchains repository. These files are contracts which will define the layer-1 +and layer-2 Clarity traits for NFTs and fungible tokens, implement an NFT in layer-1 and layer-2, and some NodeJS scripts for +helping to deploy the contracts. +``` +mkdir nft-use-case/contracts-l2 +mkdir nft-use-case/scripts +cp $HYPERCHAIN_PATH/core-contracts/contracts/helper/simple-nft.clar nft-use-case/contracts/ +cp $HYPERCHAIN_PATH/core-contracts/contracts/helper/trait-standards.clar nft-use-case/contracts/ +cp $HYPERCHAIN_PATH/core-contracts/contracts/helper/simple-nft-l2.clar nft-use-case/contracts-l2/ +cp $HYPERCHAIN_PATH/core-contracts/contracts/helper/trait-standards.clar nft-use-case/contracts-l2/ +cp $HYPERCHAIN_PATH/contrib/scripts/nft-use-case/* nft-use-case/scripts/ +cd nft-use-case/scripts +``` + +To use the scripts in this demo, we need to install some NodeJS libraries. +Before running the following instructions, make sure you have [node](https://nodejs.org/en/) installed. +``` +npm install +``` + +The `Devnet.toml` file in the `nft-use-case` directory is responsible for configuring the `clarinet integrate` +local network. Make the following change in `settings/Devnet.toml` to enable the hyperchain: +``` +[devnet] +... +enable_hyperchain_node = true +``` + +Let's spin up a hyperchain node. Before you call this, make sure that you have a working installation of Docker running +locally. + +``` +clarinet integrate +``` + +Before we publish any transactions, you will need to set up some environment variables. +These environment variables contain the address and private key of the hyperchain miner, two user addresses +and private keys, and the RPC URL which we can query for hyperchain state. +Open a separate terminal window, navigate to the directory `nft-use-case/scripts`, and enter the following. +``` +export AUTH_HC_MINER_ADDR=ST3AM1A56AK2C1XAFJ4115ZSV26EB49BVQ10MGCS0 +export AUTH_HC_MINER_KEY=7036b29cb5e235e5fd9b09ae3e8eec4404e44906814d5d01cbca968a60ed4bfb01 + +export USER_ADDR=ST2NEB84ASENDXKYGJPQW86YXQCEFEX2ZQPG87ND +export USER_KEY=f9d7206a47f14d2870c163ebab4bf3e70d18f5d14ce1031f3902fbbc894fe4c701 + +export ALT_USER_ADDR=ST2REHHS5J3CERCRBEPMGH7921Q6PYKAADT7JP2VB +export ALT_USER_KEY=3eccc5dac8056590432db6a35d52b9896876a3d5cbdea53b72400bc9c2099fe801 + +export HYPERCHAIN_URL="http://localhost:30443" +``` + +## Build with Testnet + +#### 1. Getting Testnet STX + +```bash +./target/debug/blockstack-cli generate-sk --testnet +{ + "publicKey": "02c3c7ab279c5637ea5f024f8036c5218b6d1e71518adba0693c3dcc7bead92305", + "stacksAddress": "STFTX3F4XCY7RS5VRHXP2SED0WC0YRKNWTNXD74P" +} +``` + +```bash +curl -X POST "https://stacks-node-api.testnet.stacks.co/extended/v1/faucets/stx?address=STFTX3F4XCY7RS5VRHXP2SED0WC0YRKNWTNXD74P&stacking=true" +``` + +#### 2. Spin up testnet `stacks-node` + + +```toml +[node] +working_dir = "/var/testnet-stacks-node" +rpc_bind = "127.0.0.1:20443" +p2p_bind = "0.0.0.0:20444" +bootstrap_node = "047435c194e9b01b3d7f7a2802d6684a3af68d05bbf4ec8f17021980d777691f1d51651f7f1d566532c804da506c117bbf79ad62eea81213ba58f8808b4d9504ad@testnet.stacks.co:20444" + +[burnchain] +chain = "bitcoin" +mode = "xenon" +peer_host = "bitcoind.testnet.stacks.co" +username = "blockstack" +password = "blockstacksystem" +rpc_port = 18332 +peer_port = 18333 + +# Used for sending events to a local stacks-blockchain-api service +# [[events_observer]] +# endpoint = "localhost:3700" +# retry_count = 255 +# events_keys = ["*"] + +[[ustx_balance]] +address = "ST2QKZ4FKHAH1NQKYKYAYZPY440FEPK7GZ1R5HBP2" +amount = 10000000000000000 + +[[ustx_balance]] +address = "ST319CF5WV77KYR1H3GT0GZ7B8Q4AQPY42ETP1VPF" +amount = 10000000000000000 + +[[ustx_balance]] +address = "ST221Z6TDTC5E0BYR2V624Q2ST6R0Q71T78WTAX6H" +amount = 10000000000000000 + +[[ustx_balance]] +address = "ST2TFVBMRPS5SSNP98DQKQ5JNB2B6NZM91C4K3P7B" +amount = 10000000000000000 +``` + + +```bash +./target/release/stacks-node start --config=/var/devel/stacks-hyperchains/contrib/conf/stacks-l1-testnet.toml 2>&1 | tee -i /tmp/stacks-testnet-0426-1055.log +``` + +Note: You can use an existing testnet chain state if you have one available. +I used `cp /root/stacks-node/` on one of the Hiro deployed xenon followers. +The first bootup did not work: I `CTRL-C`'d the execution, which triggered a panic, +but on the next start, the node booted fine. + +#### 3. Launch the contract + +Collect the contracts: + +```bash +mkdir my-hyperchain/ +mkdir my-hyperchain/contracts +cp stacks-hyperchains/core-contracts/contracts/hyperchains.clar my-hyperchain/contracts/ +cp stacks-hyperchains/core-contracts/contracts/helper/trait-standards.clar my-hyperchain/contracts/ +``` + +Set the miners list to contain the address generated in Step 1: + +```bash +sed -ie "s#^(define-constant miners.*#(define-constant miners (list \'STFTX3F4XCY7RS5VRHXP2SED0WC0YRKNWTNXD74P))#" my-hyperchain/contracts/hyperchains.clar +``` + +Make the transactions -- you will need to set the private key of the contract publisher as an env var: + +```bash +export CONTRACT_PUBLISH_KEY= +``` + +This is the private key from the first step. + +```bash +mkdir my-hyperchain/scripts +cp stacks-hyperchains/contrib/scripts/* my-hyperchain/scripts/ +cd my-hyperchain/scripts/ +npm i @stacks/network +npm i @stacks/transactions +mkdir ../transactions/ +node ./publish_tx.js trait-standards ../contracts/trait-standards.clar 0 > ../transactions/trait-publish.hex +node ./publish_tx.js hc-alpha ../contracts/hyperchains.clar 1 > ../transactions/hc-publish.hex +``` + +Submit the transactions: + +```bash +$ node ./broadcast_tx.js ../transactions/trait-publish.hex +{ + txid: '93cae889b9382c512e55715e5357b388734c0448643e2cc35d2a1aab90dcf61a' +} + +$ node ./broadcast_tx.js ../transactions/hc-publish.hex +{ + txid: '8c457091916a7f57b487162e0692c2cd28e71dd0b2dc9a9dfad73f93babe1dfd' +} +``` + +#### 4. Configure the HC miner + +Create a `toml` configuration for the hyperchains miner. Importantly, +you should set the `contract_identifier` to the contract published in +Steps 3 (e.g., `STFTX3F4XCY7RS5VRHXP2SED0WC0YRKNWTNXD74P.hc-alpha`). + +```toml +[node] +working_dir = "/var/my-hyperchain/hc-alpha" +rpc_bind = "127.0.0.1:80443" +p2p_bind = "127.0.0.1:80444" +mining_key = "" +miner = true +wait_time_for_microblocks = 50_000 + +[miner] +first_attempt_time_ms = 60_000 +subsequent_attempt_time_ms = 60_000 +microblock_attempt_time_ms = 30_000 + +[burnchain] +chain = "stacks_layer_1" +mode = "xenon" +first_burn_header_height = 46_721 +first_burn_header_hash = "9ba2f357115308fb1c503715f3a1b0cb3e8fdbe6baea7e7634635affdf675501" +contract_identifier = "" +peer_host = "127.0.0.1" +rpc_port = 20443 +peer_port = 20444 +rpc_ssl = false + +[[ustx_balance]] +address = "STFTX3F4XCY7RS5VRHXP2SED0WC0YRKNWTNXD74P" +amount = 10000000000000000 +``` + +Add to L1 node config: +``` +[[events_observer]] +endpoint = "localhost:50303" +retry_count = 255 +events_keys = ["*"] +``` + +#### 5. Start the nodes + +The `hyperchain-node` must be started before the `stacks-node`: + +```bash +./target/release/hyperchain-node start --config=/var/my-hyperchain/configs/hc-miner.toml 2>&1 | tee /var/my-hyperchain/hc-miner.log +``` + +The `stacks-node` must be started from a state _before_ the +`first_burn_header_height` and `first_burn_header_hash` configured +in the hyperchain node's TOML. + +```bash +./target/release/stacks-node start --config=/var/stacks-hyperchains/contrib/conf/stacks-l1-testnet.toml 2>&1 | tee -i /tmp/stacks-testnet.log +``` + +## Test Locally + +#### 1. Start the hyperchain miner + +```bash +hyperchain-node start --config=$STACKS_HYPERCHAINS_PATH/contrib/conf/hyperchain-l2.toml 2>&1 | tee -i /tmp/stacks-hc.log +``` + +#### 2. Start a local Stacks network + +```bash +stacks-node start --config=$STACKS_HYPERCHAINS_PATH/contrib/conf/stacks-l1-mocknet-local.toml 2>&1 | tee -i /tmp/stacks-mocknet.log +``` + +#### 3. Launch the contract + +Collect the contracts: + +```bash +mkdir my-hyperchain/ +mkdir my-hyperchain/contracts +cp stacks-hyperchains/core-contracts/contracts/hyperchains.clar my-hyperchain/contracts/ +cp stacks-hyperchains/core-contracts/contracts/helper/ft-trait-standard.clar my-hyperchain/contracts/ +cp stacks-hyperchains/core-contracts/contracts/helper/nft-trait-standard.clar my-hyperchain/contracts/ +``` + +Set the miners list to contain the address generated in Step 1: + +```bash +sed -ie "s#^(define-data-var miner (optional principal) none)#(define-data-var miner (optional principal) (some \'ST2GE6HSXT81X9X3ATQ14WPT49X915R8X7FVERMBP))#" my-hyperchain/contracts/hyperchains.clar +``` + +Make the transactions -- you will need to set the private key of the contract publisher as an env var: + +```bash +export CONTRACT_PUBLISH_KEY=0916e2eb04b5702e0e946081829cee67d3bb76e1792af506646843db9252ff4101 +``` + +This is the private key from the first step. + +```bash +mkdir my-hyperchain/scripts +cp stacks-hyperchains/contrib/scripts/* my-hyperchain/scripts/ +cd my-hyperchain/scripts/ +npm i @stacks/network +npm i @stacks/transactions +mkdir ../transactions/ +node ./publish_tx.js ft-trait-standard ../contracts/ft-trait-standard.clar 0 > ../transactions/ft-publish.hex +node ./publish_tx.js nft-trait-standard ../contracts/nft-trait-standard.clar 1 > ../transactions/nft-publish.hex +node ./publish_tx.js hyperchain ../contracts/hyperchains.clar 2 > ../transactions/hc-publish.hex +``` + +Submit the transactions: + +```bash +for I in `ls ../transactions/`; do node ./broadcast_tx.js "../transactions/$I" http://localhost:20443; done +``` + +#### 4. Deposit some funds to L2 + +```js +const network = require('@stacks/network'); +const transactions = require('@stacks/transactions'); +const senderKey = "aaf57b4730f713cf942bc63f0801c4a62abe5a6ac8e3da10389f9ca3420b0dc701" +const layer1 = new network.StacksTestnet(); +layer1.coreApiUrl = "http://localhost:20443"; + +const depositTransaction = await transactions.makeContractCall({ + senderKey, network: layer1, anchorMode: transactions.AnchorMode.Any, + nonce: 0, + contractAddress: "ST2GE6HSXT81X9X3ATQ14WPT49X915R8X7FVERMBP", + contractName: "hyperchain", + functionName: "deposit-stx", + functionArgs: [ transactions.uintCV(100000000000), + transactions.standardPrincipalCV("ST18F1AHKW194BWQ3CEFDPWVRARA79RBGFEWSDQR8")], + fee: 10000, + postConditionMode: transactions.PostConditionMode.Allow, +}); + +const depositTxid = await transactions.broadcastTransaction(depositTransaction, layer1); +``` + +Check that you received the funds in L2: + +```js +const layer2 = new network.StacksTestnet(); +layer2.coreApiUrl = "http://localhost:19443"; +await fetch(layer2.getAccountApiUrl("ST18F1AHKW194BWQ3CEFDPWVRARA79RBGFEWSDQR8")).then(x => x.json()).then(x => parseInt(x.balance)); +``` + +#### 5. Submit an L2 transaction + + +```js +const codeBody = "(define-public (stx-withdraw (amount uint)) (stx-withdraw? amount tx-sender))"; +const contractName = "withdraw-helper"; +const deployWithdrawal = await transactions.makeContractDeploy({ + codeBody, contractName, senderKey, network: layer2, + anchorMode: transactions.AnchorMode.Any, nonce: 0, + fee: 10000, + }); + +await transactions.broadcastTransaction(deployWithdrawal, layer2); +``` + + +#### 6. Withdraw + +Perform the withdrawal on layer-2 + +```js +const withdrawTransaction = await transactions.makeContractCall({ + senderKey, network: layer2, anchorMode: transactions.AnchorMode.Any, + nonce: 1, + contractAddress: "ST18F1AHKW194BWQ3CEFDPWVRARA79RBGFEWSDQR8", + contractName: "withdraw-helper", + functionName: "stx-withdraw", + functionArgs: [ transactions.uintCV(50000) ], + fee: 10000, + postConditionMode: transactions.PostConditionMode.Allow, +}); + +await transactions.broadcastTransaction(withdrawTransaction, layer2); +``` + +Find the withdrawal event in our log: + +```bash +cat /tmp/stacks-hc.log | grep "Parsed L2" +``` + +Perform the withdrawal on layer-1 + +```js +let withdrawUrl = "http://localhost:19443/v2/withdrawal/stx/14/ST18F1AHKW194BWQ3CEFDPWVRARA79RBGFEWSDQR8/0/50000"; +let json_merkle_entry = await fetch(withdrawUrl).then(x => x.json()) +let cv_merkle_entry = { + withdrawal_leaf_hash: transactions.deserializeCV(json_merkle_entry.withdrawal_leaf_hash), + withdrawal_root: transactions.deserializeCV(json_merkle_entry.withdrawal_root), + sibling_hashes: transactions.deserializeCV(json_merkle_entry.sibling_hashes), +}; + +const layer1WithdrawTransaction = await transactions.makeContractCall({ + senderKey, network: layer1, anchorMode: transactions.AnchorMode.Any, + nonce: 1, + contractAddress: "ST2GE6HSXT81X9X3ATQ14WPT49X915R8X7FVERMBP", + contractName: "hyperchain", + functionName: "withdraw-stx", + functionArgs: [ transactions.uintCV(50000), + transactions.standardPrincipalCV("ST18F1AHKW194BWQ3CEFDPWVRARA79RBGFEWSDQR8"), + cv_merkle_entry.withdrawal_root, + cv_merkle_entry.withdrawal_leaf_hash, + cv_merkle_entry.sibling_hashes ], + fee: 5000, + postConditionMode: transactions.PostConditionMode.Allow, +}); + +await transactions.broadcastTransaction(layer1WithdrawTransaction, layer1) +; +``` \ No newline at end of file diff --git a/docs/how-to-guides/how-to-deposit-nft.md b/docs/how-to-guides/how-to-deposit-nft.md new file mode 100644 index 000000000..a058ebf3f --- /dev/null +++ b/docs/how-to-guides/how-to-deposit-nft.md @@ -0,0 +1,20 @@ +--- +title: How to Deposit NFT +--- + +Now, we can call the deposit NFT function in the hyperchains interface contract. This +function is called by the principal `USER_ADDR`. +``` +node ./deposit_nft.js 3 +``` +Verify that the transaction is acknowledged in the next few blocks of the L1 chain. +After the transaction is confirmed in an anchored block on the L1 (this means it is included in an explicitly +numbered block in the Clarinet console), you also may want to verify that the asset was successfully deposited +on the hyperchain by grepping for the deposit transaction ID. +``` +docker logs hyperchain-node.nft-use-case.devnet 2>&1 | grep "8d042c14323cfd9d31e121cc48c2c641a8db01dce19a0f6dd531eb33689dff44" +``` +Look for a line like: +``` +Jul 19 12:51:02.396923 INFO ACCEPTED burnchain operation (ThreadId(8), src/chainstate/burn/db/sortdb.rs:3042), op: deposit_nft, l1_stacks_block_id: 8b5c4eb05afae6daaafdbd59aecaade6da1a8eab5eb1041062c6381cd7104b75, txid: 67cfd6220ed01c3aca3912c8f1ff55d374e5b3acadb3b995836ae913108e0514, l1_contract_id: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG.simple-nft-l1, hc_contract_id: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG.simple-nft-l2, hc_function_name: hyperchain-deposit-nft-token, id: 5, sender: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG +``` \ No newline at end of file diff --git a/docs/how-to-guides/how-to-mint-nft.md b/docs/how-to-guides/how-to-mint-nft.md new file mode 100644 index 000000000..a53d85cd0 --- /dev/null +++ b/docs/how-to-guides/how-to-mint-nft.md @@ -0,0 +1,12 @@ +--- +title: How to Mint NFT +--- + +Let's create a transaction to mint an NFT on the L1 chain. Once this transaction is processed, the principal `USER_ADDR` +will own an NFT. +``` +node ./mint_nft.js 2 +``` +Verify that the transaction is acknowledged within the next few blocks in the Stacks explorer. + +🟩 invoked: ST2NEB84ASENDXKYGJPQW86YXQCEFEX2ZQPG87ND.simple-nft-l1::gift-nft(ST2NEB84ASENDXKYGJPQW86YXQCEFEX2ZQPG87ND, u5) (ok true) \ No newline at end of file diff --git a/docs/how-to-guides/how-to-publish-contract.md b/docs/how-to-guides/how-to-publish-contract.md new file mode 100644 index 000000000..d8a6b6518 --- /dev/null +++ b/docs/how-to-guides/how-to-publish-contract.md @@ -0,0 +1,47 @@ +--- +title: How to Publish Contract +--- + +## Publish the NFT contract to the Stacks and Subnets + +Once the Stacks node and the hyperchain node boots up (use the indicators in the top right panel to determine this), we can start to interact with the chains. To begin with, we want to publish NFT contracts onto both the L1 and L2. When the user deposits their L1 NFT onto the hyperchain, their asset gets minted by the L2 NFT contract. +The publish script takes in four arguments: the name of the contract to be published, the filename for the contract source code, the layer on which to broadcast the transaction (1 or 2), and the nonce of the transaction. +First, publish the layer 1 contracts. You can enter this command (and the following transaction commands) in the same terminal window as you entered the environment variables. Make sure you are in the `scripts` directory. +These transactions are called by the principal `USER_ADDR`. +``` +node ./publish_tx.js trait-standards ../contracts/trait-standards.clar 1 0 +node ./publish_tx.js simple-nft-l1 ../contracts/simple-nft.clar 1 1 +``` + +Verify that the contracts were published by using the Clarinet console. +For the layer 1 contracts, you should see the following in the "transactions" region in a recent block. + +🟩 deployed: ST2NEB84ASENDXKYGJPQW86YXQCEFEX2ZQPG87ND.trait-standards (ok true) + +🟩 deployed: ST2NEB84ASENDXKYGJPQW86YXQCEFEX2ZQPG87ND.simple-nft-l1 (ok true) + +Then, publish the layer 2 contracts. Note, it might take a minute for the hyperchain node to start accepting transactions, +so these commands could fail if you send them too early (but you can always re-try when the node is ready). +These transactions are called by the principal `USER_ADDR`. +``` +node ./publish_tx.js trait-standards ../contracts-l2/trait-standards.clar 2 0 +node ./publish_tx.js simple-nft-l2 ../contracts-l2/simple-nft-l2.clar 2 1 +``` + +To verify that the layer 2 transactions were processed, grep the hyperchains log for the transaction IDs +of *each* hyperchain transaction. +The transaction ID is logged to the console after the call to `publish_tx` - make sure this is the ID you grep for. +``` +docker logs hyperchain-node.nft-use-case.devnet 2>&1 | grep "17901e5ad0587d414d5bb7b1c24c3d17bb1533f5025d154719ba1a2a0f570246" +``` + +Look for a log line similar to the following in the results: +``` +Jul 19 12:34:41.683519 INFO Tx successfully processed. (ThreadId(9), src/chainstate/stacks/miner.rs:235), event_name: transaction_result, tx_id: 17901e5ad0587d414d5bb7b1c24c3d17bb1533f5025d154719ba1a2a0f570246, event_type: success, payload: SmartContract +``` + +To ensure the contracts were successfully parsed and published, we will grep for the name of the contract and ensure there are no +error lines returned (not atypical for no lines to be returned at this step). +``` +docker logs hyperchain-node.nft-use-case.devnet 2>&1 | grep "simple-nft-l2" +``` \ No newline at end of file diff --git a/docs/how-to-guides/how-to-register-nft-asset.md b/docs/how-to-guides/how-to-register-nft-asset.md new file mode 100644 index 000000000..6601def79 --- /dev/null +++ b/docs/how-to-guides/how-to-register-nft-asset.md @@ -0,0 +1,12 @@ +--- +title: How to Register NFT asset +--- + +Create the transaction to register the new NFT asset we just published. This must be called by a miner of the hyperchains contract. +Specifically, this transaction will be sent by `AUTH_HC_MINER_ADDR`. +``` +node ./register_nft.js 0 +``` +Look for the following transaction confirmation in the Clarinet console in an upcoming block on the layer 1. + +🟩 invoked: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.hyperchain::register-new-nft-contract(ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG.simple-nft-l1, "hyperchain-deposit-nft-token") (ok true) \ No newline at end of file diff --git a/docs/how-to-guides/how-to-run-tests.md b/docs/how-to-guides/how-to-run-tests.md new file mode 100644 index 000000000..5503c8522 --- /dev/null +++ b/docs/how-to-guides/how-to-run-tests.md @@ -0,0 +1,15 @@ +--- +title: How to Run Tests +--- + +You can run tests by navigating to the `testnet/stacks-node/` directory and run the following command: + +``` +testnet/stacks-node$ cargo test +``` + +If you want to ignore some tests, navigate to the `testnet/stacks-node` directory and use the following command: + +``` +testnet/stacks-node$ cargo test -- --ignored --num-threads=1 +``` \ No newline at end of file diff --git a/docs/how-to-guides/how-to-transfer-nft.md b/docs/how-to-guides/how-to-transfer-nft.md new file mode 100644 index 000000000..b5c04bd54 --- /dev/null +++ b/docs/how-to-guides/how-to-transfer-nft.md @@ -0,0 +1,22 @@ +--- +title: How to Transfer NFT +--- + +On the hyperchains, the NFT should belong to the principal that sent the deposit transaction, `USER_ADDR`. +This principal can now transfer the NFT within the hyperchain. The principal `USER_ADDR` will now make a +transaction to transfer the NFT to `ALT_USER_ADDR`. +``` +node ./transfer_nft.js 2 +``` +Grep for the transaction ID of the transfer transaction. +``` +docker logs hyperchain-node.nft-use-case.devnet 2>&1 | grep "6acc2c756ddaed2c4cfb7351dd5930aa93ba923504be85e47db056c99a7e81aa" +``` + +Look for something like the following line: +``` +Jul 19 13:04:43.177993 INFO Tx successfully processed. (ThreadId(9), src/chainstate/stacks/miner.rs:235), event_name: transaction_result, tx_id: 74949992488b2519e2d8408169f242c86a6cdacd927638bd4604b3b8d48ea187, event_type: success, payload: ContractCall +``` + +For a bonus step, you can try minting an NFT on the hyperchain. This would require calling the `gift-nft` function in the +contract `simple-nft-l2`. You can tweak the `transfer_nft.js` file to make this call. \ No newline at end of file diff --git a/docs/how-to-guides/how-to-withdraw-nft.md b/docs/how-to-guides/how-to-withdraw-nft.md new file mode 100644 index 000000000..9d34f09e6 --- /dev/null +++ b/docs/how-to-guides/how-to-withdraw-nft.md @@ -0,0 +1,61 @@ +--- +title: How to Withdraw NFT +--- + +### Background on withdrawals +Withdrawals from the hyperchain are a 2-step process. + +The owner of an asset must call `withdraw-ft?` / `withdraw-stx?` / `withdraw-nft?` in a Clarity contract on the hyperchain, +which destroys those assets on the hyperchain, and adds that particular withdrawal to a withdrawal data structure for that block. +The withdrawal data structure serves as a cryptographic record of the withdrawals in a particular block, and has an +overall associated hash. This hash is committed to the L1 interface contract via the `commit-block` function. + +The second step involves calling the appropriate withdraw function in the hyperchains interface +contract on the L1 chain. You must also pass in the "proof" that corresponds to your withdrawal. +This proof includes the hash of the withdrawal data structure that this withdrawal was included in, +the hash of the withdrawal itself, and a list of hashes to be used to prove that the particular withdrawal is valid. Currently, +this function must be called by a hyperchain miner, but in an upcoming hyperchain release, the asset owner must call +this function. + +### Step 6a: Withdraw the NFT on the hyperchain +Perform the withdrawal on the layer 2 by calling `withdraw-nft-asset` in the `simple-nft-l2` contract. This will be called +by the principal `ALT_USER_ADDR`. +``` +node ./withdraw_nft_l2.js 0 +``` +Grep the hyperchain node to ensure success: +``` +docker logs hyperchain-node.nft-use-case.devnet 2>&1 | grep "5b5407ab074b4d78539133fe72020b18d44535a586574d0bd1f668e05dc89c2f" +Jul 19 13:07:33.804109 INFO Tx successfully processed. (ThreadId(9), src/chainstate/stacks/miner.rs:235), event_name: transaction_result, tx_id: 3ff9b9b0f33dbd6087f302fa9a7a113466cf7700ba7785a741b391f5ec7c5ba4, event_type: success, payload: ContractCall + +docker logs hyperchain-node.nft-use-case.devnet 2>&1 | grep "withdraw-nft-asset" +Jul 19 13:22:34.800652 INFO Contract-call successfully processed (ThreadId(8), src/chainstate/stacks/db/transactions.rs:731), contract_name: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG.simple-nft-l2, function_name: withdraw-nft-asset, function_args: [u5, ST2JHG361ZXG51QTKY2NQCVBPPRRE2KZB1HR05NNC], return_value: (ok true), cost: ExecutionCost { write_length: 2, write_count: 2, read_length: 1647, read_count: 5, runtime: 2002000 } +``` + +In order to successfully complete the withdrawal on the L1, it is necessary to know the height at which the withdrawal occurred. +You can find the height of the withdrawal using grep: +``` +docker logs hyperchain-node.nft-use-case.devnet 2>&1 | grep "Parsed L2 withdrawal event" +Jul 19 13:22:34.801290 INFO Parsed L2 withdrawal event (ThreadId(8), src/clarity_vm/withdrawal.rs:56), type: nft, block_height: 47, sender: ST2JHG361ZXG51QTKY2NQCVBPPRRE2KZB1HR05NNC, withdrawal_id: 0, asset_id: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG.simple-nft-l2::nft-token +``` +Get the withdrawal height by looking at the `block_height` in the returned line. There may be multiple lines returned +by the grep. Try the higher heights first, and work backward. + +### Step 6b: Complete the withdrawal on the Stacks chain +Use the withdrawal height we just obtained from the grep and substitute that for `WITHDRAWAL_BLOCK_HEIGHT`. +You might need to wait a little bit for the hyperchain block to become official (even if +the grep already returned a result) for the transaction to succeed. If the hyperchain has not advanced sufficiently, you +may get the error `Supplied block height not found`. For now, this script assumes that the requested +withdrawal was the only one in the hyperchain block it was a part of (thus, you may run into issues using this script +if you are attempting to withdraw multiple assets in a short span of time). +``` +node ./withdraw_nft_l1.js {WITHDRAWAL_BLOCK_HEIGHT} 1 +``` + +Check for the success of this transaction in the Clarinet console: + +🟩 invoked: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.hyperchain::withdraw-nft-asset(u5, ST2JHG361ZXG51QTKY2NQCVBPPRRE2KZB1HR05... + +You can also navigate to the Stacks Explorer (the URL of this will be listed in the Clarinet console), and check that the expected +principal now owns the NFT (`ALT_USER_ADDR`). You can check this by clicking on the transaction corresponding to +`withdraw-nft-asset`. \ No newline at end of file diff --git a/docs/overview.md b/docs/overview.md new file mode 100644 index 000000000..af8bf607a --- /dev/null +++ b/docs/overview.md @@ -0,0 +1,41 @@ +--- +title: Overview +--- +# Overview + +Subnets are a layer-2 scaling solution in the Stacks blockchain that offers low latency and high throughput workloads. It enables developers to build fast and reliable experiences on Stacks. + +## Background + +Subnets are a network that is separate from the Stacks chain. Subnets can be thought of as a layer-2 (L2), +and the Stacks chain can be thought of as a layer-1 (L1). The subnets interfaces with the Stacks chain via a smart +contract that is specific to the subnet. Different subnets will use distinct Stacks contracts as an interface. +This interface contract has several functions that allow it to act as an intermediary between the Stacks chain and +some particular subnet. These functions include but are not limited to: +- `commit-block`: Called by subnet miners to record block hashes and withdrawal state on the Stacks chain. +- `deposit-ft-asset` / `deposit-stx` / `deposit-nft-asset`: Called by users to deposit assets into the subnets + contract. The subnet "listens" for calls to these functions, and performs a mint on the subnets to + replicate this state. Meanwhile, on the L1, the assets live in the contract. +- `withdraw-ft-asset` / `withdraw-stx` / `withdraw-nft-asset`: Called by miners to withdraw assets from the subnets. + In an upcoming update to the subnets repo, this function will be called by users directly. + +In order to register new allowed assets, a valid miner may call `setup-allowed-contracts`, `register-ft-contract`, or `register-nft-contract`. +The transaction sender must be part of the miners list defined in the subnets contract. + +## Features + +Subnets are designed to transact on Stacks assets, meaning users can move assets in and out of subnets. While a user’s assets are in a subnet, they trust that subnet’s consensus rules. This subnet will interact with the Stacks chain using a smart contract specific to that subnet. + +> **_NOTE:_** +> +> The current implementation of subnets uses a 2-phase commit protocol amongst a fully-trusted pool of miners. + +Below are some of the features of subnets: + +- Each subnet may define its throughput settings. The default implementation should support at least 4x high throughput for transactions and may reduce confirmation time from 10 minutes to 1 minute. +- Interacting with a subnet is similar to interacting with a different Stacks network (example: testnet vs. mainnet). +- The Stacks blockchain can support many different subnets. +- Each subnet may use the same or different consensus rules. +- This repository implements a consensus mechanism that uses a two-phase commit among a federated pool of miners. +- To deposit into a subnet, users submit a layer-1 transaction to invoke the deposit method on that subnet's smart contract. +- For withdrawals, users commit the withdrawal on the subnet and then submit a layer-1 transaction to invoke the subnet's smart contract's withdraw method. \ No newline at end of file From ea6ea93bdfeff5a2ea4c539a5cb187406eeea02a Mon Sep 17 00:00:00 2001 From: Thomas Richards Date: Thu, 2 Mar 2023 02:13:11 -0800 Subject: [PATCH 02/10] added new subnets files and folders for inclusion into subnets repo --- docs/developer-resources.md | 0 docs/feature-guides/trust-models.md | 3 +- docs/getting-started.md | 116 +++++++++++------- docs/how-to-guides/how-to-deposit-nft.md | 19 +-- docs/how-to-guides/how-to-mint-nft.md | 13 +- docs/how-to-guides/how-to-publish-contract.md | 30 +++-- .../how-to-register-nft-asset.md | 10 +- docs/how-to-guides/how-to-run-tests.md | 6 +- docs/how-to-guides/how-to-transfer-nft.md | 13 +- docs/how-to-guides/how-to-withdraw-nft.md | 44 +++---- docs/init.md | 17 +-- docs/overview.md | 20 +-- docs/troubleshooting.md | 0 yarn.lock | 4 + 14 files changed, 184 insertions(+), 111 deletions(-) create mode 100644 docs/developer-resources.md create mode 100644 docs/troubleshooting.md create mode 100644 yarn.lock diff --git a/docs/developer-resources.md b/docs/developer-resources.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/feature-guides/trust-models.md b/docs/feature-guides/trust-models.md index 846115b5d..e420592b7 100644 --- a/docs/feature-guides/trust-models.md +++ b/docs/feature-guides/trust-models.md @@ -2,10 +2,11 @@ title: Trust Models --- +## Overview The current implementation of subnets uses a federated system of miners. This federation is fully-trusted, but future work on subnets will explore alternative trust models. -In a fully - trusted model: +In a fully federated trusted model: - Miners are responsible for issuing subnet blocks. - Users can validate, but subnet miners control withdrawals. diff --git a/docs/getting-started.md b/docs/getting-started.md index 5c3f98398..9f78a8a76 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -6,38 +6,53 @@ title: Getting Started # Getting Started Subnets can be built using any of the following methods: + - Build with Clarinet - Build with Testnet - Test Locally > **_NOTE:_** > -> Subnets was earlier referred as Hyperchains. While we are in the process of updating the content, you might still see subnets being referred as Hyperchains. +> Subnets was earlier referred as Hyperchains. While the process of updating the content is ongoing, there may still be some references to hyperchains instead of subnets. ## Build with Clarinet -Make sure you have `clarinet` installed locally, and that it is at version 0.33.0 or above. -If you do not have clarinet, you can find installation instructions [here](https://github.com/hirosystems/clarinet). +Make sure you have `clarinet` installed locally, and the clarinet version is at version 0.33.0 or above. +If you do not already have clarinet installed, please refer to the clarinet installation instructions [here](https://github.com/hirosystems/clarinet) for installation procedures. + +### Create a new clarinet project + +To create a new clarinet project, run the command shown below. -Let's create a new clarinet project. This will create a new directory with a Clarinet project initialized. ``` clarinet new nft-use-case ``` -Let us copy contract files and scripts over from the `stacks-hyperchains` repository into the `nft-use-case` directory. -If you don't already have the stacks-hyperchains repository, you can [clone it](https://github.com/hirosystems/stacks-hyperchains). -Here's the command to clone the stacks-hyperchains repository: +This command creates a new directory with a clarinet project already initialized. + +### Copy contract files and scripts + +Next, copy the contract files and scripts over from the `stacks-hyperchains` repository into the `nft-use-case` directory. If you do not already have the `stacks-hyperchains` repository, simply [clone the repository](https://github.com/hirosystems/stacks-hyperchains). + +To clone the `stacks-hyperchains` repository, use the following command: + ``` git clone https://github.com/hirosystems/stacks-hyperchains.git ``` -Set the environment variable `HYPERCHAIN_PATH` to the location of the stacks-hyperchains repository on your computer. + +### Set HYPERCHAIN_PATH environment variable + +After copying contract files and scripts, set the environment variable `HYPERCHAIN_PATH` to the location of the `stacks-hyperchains` repository on your computer using the command below. + ``` export HYPERCHAIN_PATH= ``` -Now, we can copy files from the stacks-hyperchains repository. These files are contracts which will define the layer-1 -and layer-2 Clarity traits for NFTs and fungible tokens, implement an NFT in layer-1 and layer-2, and some NodeJS scripts for -helping to deploy the contracts. +### Copy files from the `stacks-hyperchains` repository + +Now, copy files from the `stacks-hyperchains` repository. These files are contracts that define the layer-1 +and layer-2 Clarity traits for NFTs and fungible tokens, implement an NFT in layer-1 and layer-2, and some NodeJS scripts for helping to deploy the contracts. Enter the commands shown below. + ``` mkdir nft-use-case/contracts-l2 mkdir nft-use-case/scripts @@ -49,31 +64,35 @@ cp $HYPERCHAIN_PATH/contrib/scripts/nft-use-case/* nft-use-case/scripts/ cd nft-use-case/scripts ``` -To use the scripts in this demo, we need to install some NodeJS libraries. -Before running the following instructions, make sure you have [node](https://nodejs.org/en/) installed. +### Install node and NodeJs libraries + +To use the scripts in this demo, you need to install some NodeJS libraries. Before running the following instructions, make sure you have installed [node](https://nodejs.org/en/). + ``` npm install ``` The `Devnet.toml` file in the `nft-use-case` directory is responsible for configuring the `clarinet integrate` local network. Make the following change in `settings/Devnet.toml` to enable the hyperchain: + ``` [devnet] ... enable_hyperchain_node = true ``` -Let's spin up a hyperchain node. Before you call this, make sure that you have a working installation of Docker running -locally. +You can now spin up a hyperchain node; however, before calling the hyperchain, make sure you have a working Docker installation running locally by entering the command below. ``` clarinet integrate ``` -Before we publish any transactions, you will need to set up some environment variables. -These environment variables contain the address and private key of the hyperchain miner, two user addresses -and private keys, and the RPC URL which we can query for hyperchain state. -Open a separate terminal window, navigate to the directory `nft-use-case/scripts`, and enter the following. +### Set environment variables + +Before publishing any transactions, you will need to set up some environment variables. These environment variables contain the address and private key of the hyperchain miner, two user addresses and private keys, and the RPC URL which we can query for hyperchain state. + +Open a separate terminal window, navigate to the directory `nft-use-case/scripts`, and enter the following command: + ``` export AUTH_HC_MINER_ADDR=ST3AM1A56AK2C1XAFJ4115ZSV26EB49BVQ10MGCS0 export AUTH_HC_MINER_KEY=7036b29cb5e235e5fd9b09ae3e8eec4404e44906814d5d01cbca968a60ed4bfb01 @@ -89,7 +108,9 @@ export HYPERCHAIN_URL="http://localhost:30443" ## Build with Testnet -#### 1. Getting Testnet STX +### 1. Getting Testnet STX + +To get the testnet STX, enter the following command: ```bash ./target/debug/blockstack-cli generate-sk --testnet @@ -103,8 +124,9 @@ export HYPERCHAIN_URL="http://localhost:30443" curl -X POST "https://stacks-node-api.testnet.stacks.co/extended/v1/faucets/stx?address=STFTX3F4XCY7RS5VRHXP2SED0WC0YRKNWTNXD74P&stacking=true" ``` -#### 2. Spin up testnet `stacks-node` +### 2. Spin up testnet `stacks-node` +To spin up the `stacks-node` testnet, enter the command below. ```toml [node] @@ -150,14 +172,16 @@ amount = 10000000000000000 ./target/release/stacks-node start --config=/var/devel/stacks-hyperchains/contrib/conf/stacks-l1-testnet.toml 2>&1 | tee -i /tmp/stacks-testnet-0426-1055.log ``` -Note: You can use an existing testnet chain state if you have one available. -I used `cp /root/stacks-node/` on one of the Hiro deployed xenon followers. -The first bootup did not work: I `CTRL-C`'d the execution, which triggered a panic, -but on the next start, the node booted fine. +**_NOTE:_** -#### 3. Launch the contract +You can use an existing testnet chain state if one is available. -Collect the contracts: +In this example, `cp /root/stacks-node/` was used on one of the Hiro deployed xenon followers. Although the first attempt +failed, a subsequent attempt caused the node to boot correctly. + +### 3. Launch the contract + +Collect the contracts by using the command below: ```bash mkdir my-hyperchain/ @@ -166,13 +190,13 @@ cp stacks-hyperchains/core-contracts/contracts/hyperchains.clar my-hyperchain/co cp stacks-hyperchains/core-contracts/contracts/helper/trait-standards.clar my-hyperchain/contracts/ ``` -Set the miners list to contain the address generated in Step 1: +You then need to set the miners list to contain the address generated in Step 1 by entering the command: ```bash sed -ie "s#^(define-constant miners.*#(define-constant miners (list \'STFTX3F4XCY7RS5VRHXP2SED0WC0YRKNWTNXD74P))#" my-hyperchain/contracts/hyperchains.clar ``` -Make the transactions -- you will need to set the private key of the contract publisher as an env var: +Next, make the transactions -- you will need to set the private key of the contract publisher as an env var by using this command: ```bash export CONTRACT_PUBLISH_KEY= @@ -205,10 +229,9 @@ $ node ./broadcast_tx.js ../transactions/hc-publish.hex } ``` -#### 4. Configure the HC miner +### 4. Configure the HC miner -Create a `toml` configuration for the hyperchains miner. Importantly, -you should set the `contract_identifier` to the contract published in +Create a `toml` configuration for the hyperchains miner and set the `contract_identifier` to the contract published in Steps 3 (e.g., `STFTX3F4XCY7RS5VRHXP2SED0WC0YRKNWTNXD74P.hc-alpha`). ```toml @@ -241,7 +264,8 @@ address = "STFTX3F4XCY7RS5VRHXP2SED0WC0YRKNWTNXD74P" amount = 10000000000000000 ``` -Add to L1 node config: +You should then add to L1 node configuration by using this command: + ``` [[events_observer]] endpoint = "localhost:50303" @@ -249,9 +273,9 @@ retry_count = 255 events_keys = ["*"] ``` -#### 5. Start the nodes +### 5. Start the nodes -The `hyperchain-node` must be started before the `stacks-node`: +The `hyperchain-node` must be started before the `stacks-node`. To start `hyperchain-node`, enter the following command: ```bash ./target/release/hyperchain-node start --config=/var/my-hyperchain/configs/hc-miner.toml 2>&1 | tee /var/my-hyperchain/hc-miner.log @@ -267,19 +291,21 @@ in the hyperchain node's TOML. ## Test Locally -#### 1. Start the hyperchain miner +To test subnets locally, follow the setps listed below. + +### 1. Start the hyperchain miner ```bash hyperchain-node start --config=$STACKS_HYPERCHAINS_PATH/contrib/conf/hyperchain-l2.toml 2>&1 | tee -i /tmp/stacks-hc.log ``` -#### 2. Start a local Stacks network +### 2. Start a local Stacks network ```bash stacks-node start --config=$STACKS_HYPERCHAINS_PATH/contrib/conf/stacks-l1-mocknet-local.toml 2>&1 | tee -i /tmp/stacks-mocknet.log ``` -#### 3. Launch the contract +### 3. Launch the contract Collect the contracts: @@ -297,7 +323,7 @@ Set the miners list to contain the address generated in Step 1: sed -ie "s#^(define-data-var miner (optional principal) none)#(define-data-var miner (optional principal) (some \'ST2GE6HSXT81X9X3ATQ14WPT49X915R8X7FVERMBP))#" my-hyperchain/contracts/hyperchains.clar ``` -Make the transactions -- you will need to set the private key of the contract publisher as an env var: +Make the transactions -- you will need to set the private key of the contract publisher as an env variable using the following command: ```bash export CONTRACT_PUBLISH_KEY=0916e2eb04b5702e0e946081829cee67d3bb76e1792af506646843db9252ff4101 @@ -323,7 +349,7 @@ Submit the transactions: for I in `ls ../transactions/`; do node ./broadcast_tx.js "../transactions/$I" http://localhost:20443; done ``` -#### 4. Deposit some funds to L2 +### 4. Deposit some funds to L2 ```js const network = require('@stacks/network'); @@ -347,7 +373,7 @@ const depositTransaction = await transactions.makeContractCall({ const depositTxid = await transactions.broadcastTransaction(depositTransaction, layer1); ``` -Check that you received the funds in L2: +Verify you received the funds in L2: ```js const layer2 = new network.StacksTestnet(); @@ -355,7 +381,7 @@ layer2.coreApiUrl = "http://localhost:19443"; await fetch(layer2.getAccountApiUrl("ST18F1AHKW194BWQ3CEFDPWVRARA79RBGFEWSDQR8")).then(x => x.json()).then(x => parseInt(x.balance)); ``` -#### 5. Submit an L2 transaction +### 5. Submit an L2 transaction ```js @@ -371,7 +397,7 @@ await transactions.broadcastTransaction(deployWithdrawal, layer2); ``` -#### 6. Withdraw +### 6. Withdraw Perform the withdrawal on layer-2 @@ -390,13 +416,13 @@ const withdrawTransaction = await transactions.makeContractCall({ await transactions.broadcastTransaction(withdrawTransaction, layer2); ``` -Find the withdrawal event in our log: +Find the withdrawal event in the log: ```bash cat /tmp/stacks-hc.log | grep "Parsed L2" ``` -Perform the withdrawal on layer-1 +Perform the withdrawal on layer-1: ```js let withdrawUrl = "http://localhost:19443/v2/withdrawal/stx/14/ST18F1AHKW194BWQ3CEFDPWVRARA79RBGFEWSDQR8/0/50000"; diff --git a/docs/how-to-guides/how-to-deposit-nft.md b/docs/how-to-guides/how-to-deposit-nft.md index a058ebf3f..690175b22 100644 --- a/docs/how-to-guides/how-to-deposit-nft.md +++ b/docs/how-to-guides/how-to-deposit-nft.md @@ -2,19 +2,24 @@ title: How to Deposit NFT --- -Now, we can call the deposit NFT function in the hyperchains interface contract. This -function is called by the principal `USER_ADDR`. +## Calling the deposit NFT function + +In order to call the deposit NFT function in the hyperchains interface contract, the principal `USER_ADDR` must be called using the command shown below. + ``` node ./deposit_nft.js 3 ``` -Verify that the transaction is acknowledged in the next few blocks of the L1 chain. -After the transaction is confirmed in an anchored block on the L1 (this means it is included in an explicitly -numbered block in the Clarinet console), you also may want to verify that the asset was successfully deposited -on the hyperchain by grepping for the deposit transaction ID. + +## Verifying the transaction and successful deposit + +Verify that the transaction is acknowledged in the next few blocks of the L1 chain. After the transaction is confirmed in an anchored block on the L1 (this means it is included in an explicitlynumbered block in the Clarinet console), you may also want to verify the asset was successfully deposited on the hyperchain by grepping for the deposit transaction ID. + +To `grep` the deposit transaction ID, use the following command: ``` docker logs hyperchain-node.nft-use-case.devnet 2>&1 | grep "8d042c14323cfd9d31e121cc48c2c641a8db01dce19a0f6dd531eb33689dff44" ``` -Look for a line like: +In the response, look for a line similr to the example shown below. + ``` Jul 19 12:51:02.396923 INFO ACCEPTED burnchain operation (ThreadId(8), src/chainstate/burn/db/sortdb.rs:3042), op: deposit_nft, l1_stacks_block_id: 8b5c4eb05afae6daaafdbd59aecaade6da1a8eab5eb1041062c6381cd7104b75, txid: 67cfd6220ed01c3aca3912c8f1ff55d374e5b3acadb3b995836ae913108e0514, l1_contract_id: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG.simple-nft-l1, hc_contract_id: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG.simple-nft-l2, hc_function_name: hyperchain-deposit-nft-token, id: 5, sender: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG ``` \ No newline at end of file diff --git a/docs/how-to-guides/how-to-mint-nft.md b/docs/how-to-guides/how-to-mint-nft.md index a53d85cd0..bfc53d3d5 100644 --- a/docs/how-to-guides/how-to-mint-nft.md +++ b/docs/how-to-guides/how-to-mint-nft.md @@ -2,11 +2,18 @@ title: How to Mint NFT --- -Let's create a transaction to mint an NFT on the L1 chain. Once this transaction is processed, the principal `USER_ADDR` -will own an NFT. +## Mint an NFT + +To mint an NFT, create a transaction to mint an NFT on the L1 chain by using the command shown below. + ``` node ./mint_nft.js 2 ``` -Verify that the transaction is acknowledged within the next few blocks in the Stacks explorer. + +Once the transaction is processed, the principal `USER_ADDR` will own an NFT. + +## Verify the transaction was successful + +To verify the transaction was successful in the next few blocks in the Stacks explorer, look for a line in the response similar to the example below. 🟩 invoked: ST2NEB84ASENDXKYGJPQW86YXQCEFEX2ZQPG87ND.simple-nft-l1::gift-nft(ST2NEB84ASENDXKYGJPQW86YXQCEFEX2ZQPG87ND, u5) (ok true) \ No newline at end of file diff --git a/docs/how-to-guides/how-to-publish-contract.md b/docs/how-to-guides/how-to-publish-contract.md index d8a6b6518..b7f9e970e 100644 --- a/docs/how-to-guides/how-to-publish-contract.md +++ b/docs/how-to-guides/how-to-publish-contract.md @@ -4,44 +4,56 @@ title: How to Publish Contract ## Publish the NFT contract to the Stacks and Subnets -Once the Stacks node and the hyperchain node boots up (use the indicators in the top right panel to determine this), we can start to interact with the chains. To begin with, we want to publish NFT contracts onto both the L1 and L2. When the user deposits their L1 NFT onto the hyperchain, their asset gets minted by the L2 NFT contract. +Once the Stacks node and the hyperchain node boots up (use the indicators in the top right panel to determine this), you can begin interacting with the chains. Initially, you will want to publish NFT contracts onto both the L1 and L2. When you deposit your L1 NFT onto the hyperchain, your asset will be minted by the L2 NFT contract. + The publish script takes in four arguments: the name of the contract to be published, the filename for the contract source code, the layer on which to broadcast the transaction (1 or 2), and the nonce of the transaction. + First, publish the layer 1 contracts. You can enter this command (and the following transaction commands) in the same terminal window as you entered the environment variables. Make sure you are in the `scripts` directory. These transactions are called by the principal `USER_ADDR`. + +Here is an example of how to publish a layer 1 contract. + ``` node ./publish_tx.js trait-standards ../contracts/trait-standards.clar 1 0 node ./publish_tx.js simple-nft-l1 ../contracts/simple-nft.clar 1 1 ``` -Verify that the contracts were published by using the Clarinet console. -For the layer 1 contracts, you should see the following in the "transactions" region in a recent block. +Verify the contracts were published by using the Clarinet console. For layer 1 contracts, you should see the following lines in the "transactions" region in a recent block. 🟩 deployed: ST2NEB84ASENDXKYGJPQW86YXQCEFEX2ZQPG87ND.trait-standards (ok true) 🟩 deployed: ST2NEB84ASENDXKYGJPQW86YXQCEFEX2ZQPG87ND.simple-nft-l1 (ok true) -Then, publish the layer 2 contracts. Note, it might take a minute for the hyperchain node to start accepting transactions, -so these commands could fail if you send them too early (but you can always re-try when the node is ready). +Next, you should publish the layer 2 contracts. Note that it may take a minute for the hyperchain node to start accepting transactions, so these commands may fail if you send them too early (but you can always re-try when the node is ready). These transactions are called by the principal `USER_ADDR`. + +Here is an example of how to publish a layer 2 contract. + ``` node ./publish_tx.js trait-standards ../contracts-l2/trait-standards.clar 2 0 node ./publish_tx.js simple-nft-l2 ../contracts-l2/simple-nft-l2.clar 2 1 ``` -To verify that the layer 2 transactions were processed, grep the hyperchains log for the transaction IDs -of *each* hyperchain transaction. -The transaction ID is logged to the console after the call to `publish_tx` - make sure this is the ID you grep for. +To verify the layer 2 transactions were processed, grep the hyperchains log for the transaction IDs +of *each* hyperchain transaction. The transaction ID is logged to the console after the call to `publish_tx` - make sure this is the ID you grep for. + +For example, + ``` docker logs hyperchain-node.nft-use-case.devnet 2>&1 | grep "17901e5ad0587d414d5bb7b1c24c3d17bb1533f5025d154719ba1a2a0f570246" ``` Look for a log line similar to the following in the results: + ``` Jul 19 12:34:41.683519 INFO Tx successfully processed. (ThreadId(9), src/chainstate/stacks/miner.rs:235), event_name: transaction_result, tx_id: 17901e5ad0587d414d5bb7b1c24c3d17bb1533f5025d154719ba1a2a0f570246, event_type: success, payload: SmartContract ``` -To ensure the contracts were successfully parsed and published, we will grep for the name of the contract and ensure there are no +To ensure the contracts were successfully parsed and published, `grep` for the name of the contract and ensure there are no error lines returned (not atypical for no lines to be returned at this step). + +For example, + ``` docker logs hyperchain-node.nft-use-case.devnet 2>&1 | grep "simple-nft-l2" ``` \ No newline at end of file diff --git a/docs/how-to-guides/how-to-register-nft-asset.md b/docs/how-to-guides/how-to-register-nft-asset.md index 6601def79..dff981acd 100644 --- a/docs/how-to-guides/how-to-register-nft-asset.md +++ b/docs/how-to-guides/how-to-register-nft-asset.md @@ -2,11 +2,15 @@ title: How to Register NFT asset --- -Create the transaction to register the new NFT asset we just published. This must be called by a miner of the hyperchains contract. -Specifically, this transaction will be sent by `AUTH_HC_MINER_ADDR`. +## Register an NFT asset + +To create an NFT asset, you must create the transaction so a published NFT asset can be registered. This transaction must be called by a miner of the hyperchains contract. + +Specifically, this transaction will be sent by `AUTH_HC_MINER_ADDR` using the following command: + ``` node ./register_nft.js 0 ``` -Look for the following transaction confirmation in the Clarinet console in an upcoming block on the layer 1. +In the response, look for the following transaction confirmation in the Clarinet console in an upcoming block on the layer 1. 🟩 invoked: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.hyperchain::register-new-nft-contract(ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG.simple-nft-l1, "hyperchain-deposit-nft-token") (ok true) \ No newline at end of file diff --git a/docs/how-to-guides/how-to-run-tests.md b/docs/how-to-guides/how-to-run-tests.md index 5503c8522..34f558d43 100644 --- a/docs/how-to-guides/how-to-run-tests.md +++ b/docs/how-to-guides/how-to-run-tests.md @@ -2,13 +2,17 @@ title: How to Run Tests --- +## NFT Testing + +Tests can often be helpful in ensuring NFTs are properly managed and maintained (for example, minted, published, registered). + You can run tests by navigating to the `testnet/stacks-node/` directory and run the following command: ``` testnet/stacks-node$ cargo test ``` -If you want to ignore some tests, navigate to the `testnet/stacks-node` directory and use the following command: +To ignore some tests, navigate to the `testnet/stacks-node` directory and use the following command: ``` testnet/stacks-node$ cargo test -- --ignored --num-threads=1 diff --git a/docs/how-to-guides/how-to-transfer-nft.md b/docs/how-to-guides/how-to-transfer-nft.md index b5c04bd54..0696a2c3c 100644 --- a/docs/how-to-guides/how-to-transfer-nft.md +++ b/docs/how-to-guides/how-to-transfer-nft.md @@ -2,21 +2,26 @@ title: How to Transfer NFT --- +## Transfer an NFT + On the hyperchains, the NFT should belong to the principal that sent the deposit transaction, `USER_ADDR`. This principal can now transfer the NFT within the hyperchain. The principal `USER_ADDR` will now make a -transaction to transfer the NFT to `ALT_USER_ADDR`. +transaction to transfer the NFT to `ALT_USER_ADDR` using the command shown below. + ``` node ./transfer_nft.js 2 ``` -Grep for the transaction ID of the transfer transaction. +Next, use the `grep` command to retrieve the transaction ID of the transfer transaction like the example below. + ``` docker logs hyperchain-node.nft-use-case.devnet 2>&1 | grep "6acc2c756ddaed2c4cfb7351dd5930aa93ba923504be85e47db056c99a7e81aa" ``` -Look for something like the following line: +In the response, look for text similar to the following line: ``` Jul 19 13:04:43.177993 INFO Tx successfully processed. (ThreadId(9), src/chainstate/stacks/miner.rs:235), event_name: transaction_result, tx_id: 74949992488b2519e2d8408169f242c86a6cdacd927638bd4604b3b8d48ea187, event_type: success, payload: ContractCall ``` +## Mint an NFT on the hyperchain -For a bonus step, you can try minting an NFT on the hyperchain. This would require calling the `gift-nft` function in the +As an added step, you may try minting an NFT on the hyperchain. This requires calling the `gift-nft` function in the contract `simple-nft-l2`. You can tweak the `transfer_nft.js` file to make this call. \ No newline at end of file diff --git a/docs/how-to-guides/how-to-withdraw-nft.md b/docs/how-to-guides/how-to-withdraw-nft.md index 9d34f09e6..bce899255 100644 --- a/docs/how-to-guides/how-to-withdraw-nft.md +++ b/docs/how-to-guides/how-to-withdraw-nft.md @@ -1,29 +1,28 @@ --- -title: How to Withdraw NFT +title: How to Withdraw an NFT --- ### Background on withdrawals Withdrawals from the hyperchain are a 2-step process. -The owner of an asset must call `withdraw-ft?` / `withdraw-stx?` / `withdraw-nft?` in a Clarity contract on the hyperchain, -which destroys those assets on the hyperchain, and adds that particular withdrawal to a withdrawal data structure for that block. -The withdrawal data structure serves as a cryptographic record of the withdrawals in a particular block, and has an -overall associated hash. This hash is committed to the L1 interface contract via the `commit-block` function. +The owner of an asset must first call `withdraw-ft?` / `withdraw-stx?` / `withdraw-nft?` in a Clarity contract on the hyperchain. This call destroys those assets on the hyperchain, and then adds that particular withdrawal to a withdrawal data structure for that block. The withdrawal data structure serves as a cryptographic record of the withdrawals in a particular block, and has an overall associated hash. This hash is committed to the L1 interface contract via the `commit-block` function. The second step involves calling the appropriate withdraw function in the hyperchains interface contract on the L1 chain. You must also pass in the "proof" that corresponds to your withdrawal. This proof includes the hash of the withdrawal data structure that this withdrawal was included in, -the hash of the withdrawal itself, and a list of hashes to be used to prove that the particular withdrawal is valid. Currently, -this function must be called by a hyperchain miner, but in an upcoming hyperchain release, the asset owner must call -this function. +the hash of the withdrawal itself, and a list of hashes to be used to prove that the particular withdrawal is valid. + +Currently, this function must be called by a hyperchain miner, but in a future hyperchain release, the asset owner will need to call this function. ### Step 6a: Withdraw the NFT on the hyperchain Perform the withdrawal on the layer 2 by calling `withdraw-nft-asset` in the `simple-nft-l2` contract. This will be called -by the principal `ALT_USER_ADDR`. +by the principal `ALT_USER_ADDR` using the following command: + ``` node ./withdraw_nft_l2.js 0 ``` -Grep the hyperchain node to ensure success: +Use the `grep` command on the hyperchain node to ensure the withdrawal is successful. + ``` docker logs hyperchain-node.nft-use-case.devnet 2>&1 | grep "5b5407ab074b4d78539133fe72020b18d44535a586574d0bd1f668e05dc89c2f" Jul 19 13:07:33.804109 INFO Tx successfully processed. (ThreadId(9), src/chainstate/stacks/miner.rs:235), event_name: transaction_result, tx_id: 3ff9b9b0f33dbd6087f302fa9a7a113466cf7700ba7785a741b391f5ec7c5ba4, event_type: success, payload: ContractCall @@ -33,29 +32,32 @@ Jul 19 13:22:34.800652 INFO Contract-call successfully processed (ThreadId(8), s ``` In order to successfully complete the withdrawal on the L1, it is necessary to know the height at which the withdrawal occurred. -You can find the height of the withdrawal using grep: + +You can find the height of the withdrawal using the `grep` command: ``` docker logs hyperchain-node.nft-use-case.devnet 2>&1 | grep "Parsed L2 withdrawal event" Jul 19 13:22:34.801290 INFO Parsed L2 withdrawal event (ThreadId(8), src/clarity_vm/withdrawal.rs:56), type: nft, block_height: 47, sender: ST2JHG361ZXG51QTKY2NQCVBPPRRE2KZB1HR05NNC, withdrawal_id: 0, asset_id: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG.simple-nft-l2::nft-token ``` -Get the withdrawal height by looking at the `block_height` in the returned line. There may be multiple lines returned -by the grep. Try the higher heights first, and work backward. +Retrieve the withdrawal height by looking at the `block_height` in the returned line. There may be multiple lines returned +by the `grep`. Try the higher heights first, and then work backward. ### Step 6b: Complete the withdrawal on the Stacks chain -Use the withdrawal height we just obtained from the grep and substitute that for `WITHDRAWAL_BLOCK_HEIGHT`. -You might need to wait a little bit for the hyperchain block to become official (even if -the grep already returned a result) for the transaction to succeed. If the hyperchain has not advanced sufficiently, you -may get the error `Supplied block height not found`. For now, this script assumes that the requested +Use the withdrawal height we obtained from the `grep` command in the previous step, and substitute that for `WITHDRAWAL_BLOCK_HEIGHT`. + +You might need to wait a short time for the hyperchain block to become official (even if +the `grep` already returned a result) for the transaction to succeed. If the hyperchain has not advanced sufficiently, you +may receive a `Supplied block height not found` error. For now, this script assumes the requested withdrawal was the only one in the hyperchain block it was a part of (thus, you may run into issues using this script -if you are attempting to withdraw multiple assets in a short span of time). +if you are attempting to withdraw multiple assets in a short span of time). + ``` node ./withdraw_nft_l1.js {WITHDRAWAL_BLOCK_HEIGHT} 1 ``` -Check for the success of this transaction in the Clarinet console: +Verify the transaction was successful by reviewing the response in the Clarinet console. 🟩 invoked: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.hyperchain::withdraw-nft-asset(u5, ST2JHG361ZXG51QTKY2NQCVBPPRRE2KZB1HR05... -You can also navigate to the Stacks Explorer (the URL of this will be listed in the Clarinet console), and check that the expected -principal now owns the NFT (`ALT_USER_ADDR`). You can check this by clicking on the transaction corresponding to +You may also navigate to the Stacks Explorer (the URL of this will be listed in the Clarinet console), and check that the expected +principal now owns the NFT (`ALT_USER_ADDR`). You may check this by clicking on the transaction corresponding to `withdraw-nft-asset`. \ No newline at end of file diff --git a/docs/init.md b/docs/init.md index f3b98076c..cf5d3802f 100644 --- a/docs/init.md +++ b/docs/init.md @@ -9,7 +9,7 @@ can be found in the [contrib/init](../contrib/init) folder. ## Service User All Linux startup configurations assume the existence of a "stacks" user -and group. They must be created before attempting to use these scripts. +and group. Users and groups must be created before attempting to use these scripts. The MacOS configuration assumes stacks-blockchain will be set up for the current user. ## Configuration @@ -30,14 +30,16 @@ All three configurations assume several paths that might need to be adjusted. PID file: /run/stacks-blockchain/stacks.pid Lock file: /var/lock/subsys/stacks (SysVinit) -The PID directory and data directory should both be owned by the +The PID directory and data directory should be owned by both the stacks user and group. It is advised for security reasons to make the configuration file and data directory only readable by the stacks user and group. -NOTE: When using the systemd .service file, the creation of the aforementioned + **_NOTE:_** + +When using the `systemd .service` file, the creation of the aforementioned directories and the setting of their permissions is automatically handled by -systemd. Directories are given a permission of 710, giving the stacks group +`systemd`. Directories are given a permission of 710, giving the stacks group access to files under it _if_ the files themselves give permission to the stacks group to do so. This does not allow for the listing of files under the directory. @@ -60,14 +62,15 @@ The Config.toml file is presumed to have group ownership by the `wheel` group, w ### systemd -Installing this .service file consists of just copying it to -/usr/lib/systemd/system directory, followed by the command +Installing this .service file consists of just copying it to /usr/lib/systemd/system directory, followed by the command `systemctl daemon-reload` in order to update running systemd configuration. To test, run `systemctl start stacks` and to enable for system startup run `systemctl enable stacks` -NOTE: When installing for systemd in Debian/Ubuntu the .service file needs to be copied to the /lib/systemd/system directory instead. +**_Note_** + +When installing for systemd in Debian/Ubuntu the .service file needs to be copied to the /lib/systemd/system directory instead. ### SysVinit diff --git a/docs/overview.md b/docs/overview.md index af8bf607a..fc743562c 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -3,16 +3,15 @@ title: Overview --- # Overview -Subnets are a layer-2 scaling solution in the Stacks blockchain that offers low latency and high throughput workloads. It enables developers to build fast and reliable experiences on Stacks. +Subnets are a layer-2 scaling solution in the Stacks blockchain that offers low latency and high throughput workloads, in addition to enabling developers to build fast and reliable experiences on Stacks. ## Background -Subnets are a network that is separate from the Stacks chain. Subnets can be thought of as a layer-2 (L2), -and the Stacks chain can be thought of as a layer-1 (L1). The subnets interfaces with the Stacks chain via a smart -contract that is specific to the subnet. Different subnets will use distinct Stacks contracts as an interface. -This interface contract has several functions that allow it to act as an intermediary between the Stacks chain and -some particular subnet. These functions include but are not limited to: -- `commit-block`: Called by subnet miners to record block hashes and withdrawal state on the Stacks chain. +Subnets are a network separate from the Stacks chain. Subnets can be thought of as a layer-2 (L2), and the Stacks chain can be thought of as a layer-1 (L1). Subnets interface with the Stacks chain via a smart contract specific to the subnet. Different subnets use distinct Stacks contracts as an interface. + +This interface contract has several functions that allow it to act as an intermediary between the Stacks chain and some particular subnet. These functions include, but are not limited to, the following functions: + +- `commit-block`: Called by subnet miners to record block hashes and withdrawal states on the Stacks chain. - `deposit-ft-asset` / `deposit-stx` / `deposit-nft-asset`: Called by users to deposit assets into the subnets contract. The subnet "listens" for calls to these functions, and performs a mint on the subnets to replicate this state. Meanwhile, on the L1, the assets live in the contract. @@ -24,18 +23,19 @@ The transaction sender must be part of the miners list defined in the subnets co ## Features -Subnets are designed to transact on Stacks assets, meaning users can move assets in and out of subnets. While a user’s assets are in a subnet, they trust that subnet’s consensus rules. This subnet will interact with the Stacks chain using a smart contract specific to that subnet. +Subnets are designed to transact on Stacks assets, meaning users can move assets in and out of subnets. While a user’s assets are in a subnet, they trust that subnet’s consensus rules. This subnet interacts with the Stacks chain using a smart contract specific to that subnet. > **_NOTE:_** > > The current implementation of subnets uses a 2-phase commit protocol amongst a fully-trusted pool of miners. -Below are some of the features of subnets: +Listed below are some of the features of subnets: - Each subnet may define its throughput settings. The default implementation should support at least 4x high throughput for transactions and may reduce confirmation time from 10 minutes to 1 minute. -- Interacting with a subnet is similar to interacting with a different Stacks network (example: testnet vs. mainnet). +- Interacting with a subnet is similar to interacting with a different Stacks network (for example: testnet vs. mainnet). - The Stacks blockchain can support many different subnets. - Each subnet may use the same or different consensus rules. - This repository implements a consensus mechanism that uses a two-phase commit among a federated pool of miners. +- FTs, NFTs, and STX deposits and withdrawals are supported via user-submitted L1 transactions. - To deposit into a subnet, users submit a layer-1 transaction to invoke the deposit method on that subnet's smart contract. - For withdrawals, users commit the withdrawal on the subnet and then submit a layer-1 transaction to invoke the subnet's smart contract's withdraw method. \ No newline at end of file diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 000000000..e69de29bb diff --git a/yarn.lock b/yarn.lock new file mode 100644 index 000000000..fb57ccd13 --- /dev/null +++ b/yarn.lock @@ -0,0 +1,4 @@ +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. +# yarn lockfile v1 + + From 1329606bf76469143d18a7463504f1085907c91b Mon Sep 17 00:00:00 2001 From: Brice Dobry Date: Mon, 6 Mar 2023 08:36:32 -0500 Subject: [PATCH 03/10] docs: update the devnet example --- docs/getting-started.md | 1004 ++++++++++++++++++++++----------- docs/images/confirmed.png | Bin 0 -> 267431 bytes docs/images/subnet-devnet.png | Bin 0 -> 59082 bytes docs/overview.md | 67 ++- 4 files changed, 734 insertions(+), 337 deletions(-) create mode 100644 docs/images/confirmed.png create mode 100644 docs/images/subnet-devnet.png diff --git a/docs/getting-started.md b/docs/getting-started.md index 9f78a8a76..55016f196 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -5,449 +5,819 @@ title: Getting Started # Getting Started -Subnets can be built using any of the following methods: +Developers can test their applications on a subnet either locally, or on Hiro's +hosted testnet subnet. -- Build with Clarinet -- Build with Testnet -- Test Locally +- Run a local subnet +- Use the testnet subnet > **_NOTE:_** > -> Subnets was earlier referred as Hyperchains. While the process of updating the content is ongoing, there may still be some references to hyperchains instead of subnets. +> Subnets were earlier referred to as Hyperchains. While the process of updating +> the content is ongoing, there may still be some references to hyperchains +> instead of subnets. -## Build with Clarinet +## Run a devnet subnet locally -Make sure you have `clarinet` installed locally, and the clarinet version is at version 0.33.0 or above. -If you do not already have clarinet installed, please refer to the clarinet installation instructions [here](https://github.com/hirosystems/clarinet) for installation procedures. +Clarinet provides a tool to setup a complete local development environment, +referred to as "devnet", which uses Docker to spin up a Bitcoin node, a Stacks +node, a Stacks API node, a Stacks Explorer, and now, a subnet node and subnet +API node. This allows developers to test locally on a system that matches the +production environment. -### Create a new clarinet project +In this section, we will explain how to launch and interact with this devnet +subnet environment using a simple NFT example project. -To create a new clarinet project, run the command shown below. +Make sure you have `clarinet` installed, and the clarinet version is at 1.5.0 or +above. If you do not already have clarinet installed, please refer to the +clarinet installation instructions +[here](https://github.com/hirosystems/clarinet) for installation procedures. +### Create a new project with Clarinet + +To create a new project, run: + +```sh +clarinet new subnet-nft-example +cd subnet-nft-example ``` -clarinet new nft-use-case -``` -This command creates a new directory with a clarinet project already initialized. +This command creates a new directory with a clarinet project already +initialized, and then switches into that directory. + +### Create the contracts -### Copy contract files and scripts +Clarinet does not yet fully support development on subnets, so we will not be +using it to manage our subnet contracts, but will instead do that manually for +now. -Next, copy the contract files and scripts over from the `stacks-hyperchains` repository into the `nft-use-case` directory. If you do not already have the `stacks-hyperchains` repository, simply [clone the repository](https://github.com/hirosystems/stacks-hyperchains). +#### Creating the Stacks (L1) contract -To clone the `stacks-hyperchains` repository, use the following command: +Our L1 NFT contract is going to implement the +[SIP-009 NFT trait](https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md#trait). +We can add this to our project as a requirement, so that Clarinet takes care of +deploying it for us. +```sh +clarinet requirements add SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.nft-trait ``` -git clone https://github.com/hirosystems/stacks-hyperchains.git + +Now, let's use Clarinet to create our L1 contract: + +```sh +clarinet contract new simple-nft-l1 ``` -### Set HYPERCHAIN_PATH environment variable +This will create the file, _./contracts/simple-nft-l1.clar_, which we can fill +in with the following clarity code: -After copying contract files and scripts, set the environment variable `HYPERCHAIN_PATH` to the location of the `stacks-hyperchains` repository on your computer using the command below. +```clarity +(define-constant CONTRACT_OWNER tx-sender) +(define-constant CONTRACT_ADDRESS (as-contract tx-sender)) -``` -export HYPERCHAIN_PATH= -``` +(define-constant ERR_NOT_AUTHORIZED (err u1001)) -### Copy files from the `stacks-hyperchains` repository +(impl-trait 'SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.nft-trait.nft-trait) +(impl-trait 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.subnet-traits.mint-from-subnet-trait) -Now, copy files from the `stacks-hyperchains` repository. These files are contracts that define the layer-1 -and layer-2 Clarity traits for NFTs and fungible tokens, implement an NFT in layer-1 and layer-2, and some NodeJS scripts for helping to deploy the contracts. Enter the commands shown below. +(define-data-var lastId uint u0) +(define-map CFG_BASE_URI bool (string-ascii 256)) -``` -mkdir nft-use-case/contracts-l2 -mkdir nft-use-case/scripts -cp $HYPERCHAIN_PATH/core-contracts/contracts/helper/simple-nft.clar nft-use-case/contracts/ -cp $HYPERCHAIN_PATH/core-contracts/contracts/helper/trait-standards.clar nft-use-case/contracts/ -cp $HYPERCHAIN_PATH/core-contracts/contracts/helper/simple-nft-l2.clar nft-use-case/contracts-l2/ -cp $HYPERCHAIN_PATH/core-contracts/contracts/helper/trait-standards.clar nft-use-case/contracts-l2/ -cp $HYPERCHAIN_PATH/contrib/scripts/nft-use-case/* nft-use-case/scripts/ -cd nft-use-case/scripts -``` +(define-non-fungible-token nft-token uint) -### Install node and NodeJs libraries +(define-read-only (get-last-token-id) + (ok (var-get lastId)) +) -To use the scripts in this demo, you need to install some NodeJS libraries. Before running the following instructions, make sure you have installed [node](https://nodejs.org/en/). +(define-read-only (get-owner (id uint)) + (ok (nft-get-owner? nft-token id)) +) -``` -npm install -``` +(define-read-only (get-token-uri (id uint)) + (ok (map-get? CFG_BASE_URI true)) +) + +(define-public (transfer (id uint) (sender principal) (recipient principal)) + (begin + (asserts! (is-eq tx-sender sender) ERR_NOT_AUTHORIZED) + (nft-transfer? nft-token id sender recipient) + ) +) + +;; test functions +(define-public (test-mint (recipient principal)) + (let + ((newId (+ (var-get lastId) u1))) + (var-set lastId newId) + (nft-mint? nft-token newId recipient) + ) +) + +(define-public (mint-from-subnet (id uint) (sender principal) (recipient principal)) + (begin + ;; Check that the tx-sender is the provided sender + (asserts! (is-eq tx-sender sender) ERR_NOT_AUTHORIZED) -The `Devnet.toml` file in the `nft-use-case` directory is responsible for configuring the `clarinet integrate` -local network. Make the following change in `settings/Devnet.toml` to enable the hyperchain: + (nft-mint? nft-token id recipient) + ) +) +(define-public (gift-nft (recipient principal) (id uint)) + (begin + (nft-mint? nft-token id recipient) + ) +) ``` -[devnet] -... -enable_hyperchain_node = true + +Note that this contract implements the `mint-from-subnet-trait` in addition to +the SIP-009 `nft-trait`. When `mint-from-subnet-trait` is implemented, it allows +an NFT to be minted on the subnet, then later withdrawn to the L1. + +#### Creating the subnet (L2) contract + +Next, we'll create the subnet contract at _./contracts/simple-nft-l2.clar_. As +mentioned earlier, Clarinet cannot properly handle subnet contracts yet, so +we'll manually create this file, and add the following contents: + +```clarity +(define-constant CONTRACT_OWNER tx-sender) +(define-constant CONTRACT_ADDRESS (as-contract tx-sender)) + +(define-constant ERR_NOT_AUTHORIZED (err u1001)) + +(impl-trait 'ST000000000000000000002AMW42H.subnet.nft-trait) + +(define-data-var lastId uint u0) + +(define-non-fungible-token nft-token uint) + + +;; NFT trait functions +(define-read-only (get-last-token-id) + (ok (var-get lastId)) +) + +(define-read-only (get-owner (id uint)) + (ok (nft-get-owner? nft-token id)) +) + +(define-read-only (get-token-uri (id uint)) + (ok (some "unimplemented")) +) + +(define-public (transfer (id uint) (sender principal) (recipient principal)) + (begin + (asserts! (is-eq tx-sender sender) ERR_NOT_AUTHORIZED) + (nft-transfer? nft-token id sender recipient) + ) +) + +;; mint functions +(define-public (mint-next (recipient principal)) + (let + ((newId (+ (var-get lastId) u1))) + (var-set lastId newId) + (nft-mint? nft-token newId recipient) + ) +) + +(define-public (gift-nft (recipient principal) (id uint)) + (begin + (nft-mint? nft-token id recipient) + ) +) + +(define-read-only (get-token-owner (id uint)) + (nft-get-owner? nft-token id) +) + +(impl-trait 'ST000000000000000000002AMW42H.subnet.subnet-asset) + +;; Called for deposit from the burnchain to the subnet +(define-public (deposit-from-burnchain (id uint) (recipient principal)) + (begin + (asserts! (is-eq tx-sender 'ST000000000000000000002AMW42H) ERR_NOT_AUTHORIZED) + (nft-mint? nft-token id recipient) + ) +) + +;; Called for withdrawal from the subnet to the burnchain +(define-public (burn-for-withdrawal (id uint) (owner principal)) + (begin + (asserts! (is-eq tx-sender owner) ERR_NOT_AUTHORIZED) + (nft-burn? nft-token id owner) + ) +) ``` -You can now spin up a hyperchain node; however, before calling the hyperchain, make sure you have a working Docker installation running locally by entering the command below. +Note that this contract implements the `nft-trait` and the `subnet-asset` trait. +The `nft-trait` is the same as the SIP-009 trait on the Stacks network. +`subnet-asset` defines the functions required for deposit and withdrawal. These +will be called by the subnet miner. + +### Start the devnet +The settings for the devnet are found in _./settings/Devnet.toml_. We want to +enable a subnet node, and the corresponding API node, plus, we need to enable +"next" features, so that we can get 2.1 support, since the subnet contract +requires Clarity 2. Add (or uncomment) the following lines under `[devnet]`: + +```tomml +enable_subnet_node = true +disable_subnet_api = false +enable_next_features = true ``` + +Run the following command to start the development environment -- launching a +bitcoin node, Stacks node, Stacks API service, subnet node, subnet API service, +and explorer service. + +```sh clarinet integrate ``` -### Set environment variables +This will open a terminal UI that shows various data points about the state of +the network. We'll know that all of the nodes/services are up and ready when we +see: + +![Clarinet integrate services](images/subnet-devnet.png) -Before publishing any transactions, you will need to set up some environment variables. These environment variables contain the address and private key of the hyperchain miner, two user addresses and private keys, and the RPC URL which we can query for hyperchain state. +Once this state is reached, we should see successful calls to `commit-block` in +the transactions console. This is the subnet miner committing blocks to the L1. +Leasve this running and perform the next steps in another terminal. + +### Setup Node.js scripts + +To submit transactions to our Stacks node and subnet node, we'll use +[Stacks.js](https://stacks.js.org). Let's create a new directory, _./scripts/_ +for these scripts. + +```sh +mkdir scripts +cd scripts +``` -Open a separate terminal window, navigate to the directory `nft-use-case/scripts`, and enter the following command: +Then we'll initialize a Node.js project and install the stacks.js dependencies: +```sh +npm init -y +npm install @stacks/network @stacks/transactions ``` -export AUTH_HC_MINER_ADDR=ST3AM1A56AK2C1XAFJ4115ZSV26EB49BVQ10MGCS0 -export AUTH_HC_MINER_KEY=7036b29cb5e235e5fd9b09ae3e8eec4404e44906814d5d01cbca968a60ed4bfb01 + +In the generated package.json file, add the following into the json to enable +modules: + +```json + "type": "module", +``` + +To simplify our scripts, let's define some environment variables that we can +reuse: + +```sh +export DEPLOYER_ADDR=ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM +export DEPLOYER_KEY=753b7cc01a1a2e86221266a154af739463fce51219d97e4f856cd7200c3bd2a601 export USER_ADDR=ST2NEB84ASENDXKYGJPQW86YXQCEFEX2ZQPG87ND export USER_KEY=f9d7206a47f14d2870c163ebab4bf3e70d18f5d14ce1031f3902fbbc894fe4c701 export ALT_USER_ADDR=ST2REHHS5J3CERCRBEPMGH7921Q6PYKAADT7JP2VB export ALT_USER_KEY=3eccc5dac8056590432db6a35d52b9896876a3d5cbdea53b72400bc9c2099fe801 - -export HYPERCHAIN_URL="http://localhost:30443" +export SUBNET_URL="http://localhost:30443" ``` -## Build with Testnet +#### Publish contract script + +First, let's define a script to publish a contract. We'll be deploying multiple +contracts, so this script takes 4 arguments to make it reusable: -### 1. Getting Testnet STX +1. Contract name +2. Path to contract +3. Network layer (1 = Stacks, 2 = Subnet) +4. Nonce -To get the testnet STX, enter the following command: +_publish.js_: -```bash -./target/debug/blockstack-cli generate-sk --testnet -{ - "publicKey": "02c3c7ab279c5637ea5f024f8036c5218b6d1e71518adba0693c3dcc7bead92305", - "stacksAddress": "STFTX3F4XCY7RS5VRHXP2SED0WC0YRKNWTNXD74P" +```js +import { + AnchorMode, + makeContractDeploy, + broadcastTransaction, +} from "@stacks/transactions"; +import { StacksTestnet, HIRO_MOCKNET_DEFAULT } from "@stacks/network"; +import { readFileSync } from "fs"; + +async function main() { + const contractName = process.argv[2]; + const contractFilename = process.argv[3]; + const networkLayer = parseInt(process.argv[4]); + const nonce = parseInt(process.argv[5]); + const senderKey = process.env.USER_KEY; + const networkUrl = + networkLayer == 2 ? process.env.SUBNET_URL : HIRO_MOCKNET_DEFAULT; + + const codeBody = readFileSync(contractFilename, { encoding: "utf-8" }); + + const transaction = await makeContractDeploy({ + codeBody, + contractName, + senderKey, + network: new StacksTestnet({ url: networkUrl }), + anchorMode: AnchorMode.Any, + fee: 10000, + nonce, + }); + + const txid = await broadcastTransaction( + transaction, + new StacksTestnet({ url: networkUrl }) + ); + + console.log(txid); } -``` -```bash -curl -X POST "https://stacks-node-api.testnet.stacks.co/extended/v1/faucets/stx?address=STFTX3F4XCY7RS5VRHXP2SED0WC0YRKNWTNXD74P&stacking=true" +main(); ``` -### 2. Spin up testnet `stacks-node` - -To spin up the `stacks-node` testnet, enter the command below. - -```toml -[node] -working_dir = "/var/testnet-stacks-node" -rpc_bind = "127.0.0.1:20443" -p2p_bind = "0.0.0.0:20444" -bootstrap_node = "047435c194e9b01b3d7f7a2802d6684a3af68d05bbf4ec8f17021980d777691f1d51651f7f1d566532c804da506c117bbf79ad62eea81213ba58f8808b4d9504ad@testnet.stacks.co:20444" - -[burnchain] -chain = "bitcoin" -mode = "xenon" -peer_host = "bitcoind.testnet.stacks.co" -username = "blockstack" -password = "blockstacksystem" -rpc_port = 18332 -peer_port = 18333 - -# Used for sending events to a local stacks-blockchain-api service -# [[events_observer]] -# endpoint = "localhost:3700" -# retry_count = 255 -# events_keys = ["*"] - -[[ustx_balance]] -address = "ST2QKZ4FKHAH1NQKYKYAYZPY440FEPK7GZ1R5HBP2" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST319CF5WV77KYR1H3GT0GZ7B8Q4AQPY42ETP1VPF" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST221Z6TDTC5E0BYR2V624Q2ST6R0Q71T78WTAX6H" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST2TFVBMRPS5SSNP98DQKQ5JNB2B6NZM91C4K3P7B" -amount = 10000000000000000 -``` +#### Register NFT script +This script will register the NFT with the subnet, allowing it to be deposited +into the subnet and later withdrawn. We only need to do this once, so all of the +details have been hard-coded into this script. It calls +`register-new-nft-contract` on the L1 subnet contract, passing the L1 and L2 NFT +contracts we will publish. -```bash -./target/release/stacks-node start --config=/var/devel/stacks-hyperchains/contrib/conf/stacks-l1-testnet.toml 2>&1 | tee -i /tmp/stacks-testnet-0426-1055.log +_register.js_: + +```js +import { + makeContractCall, + AnchorMode, + contractPrincipalCV, + broadcastTransaction, + getNonce, +} from "@stacks/transactions"; +import { StacksTestnet, HIRO_MOCKNET_DEFAULT } from "@stacks/network"; + +async function main() { + const network = new StacksTestnet({ url: HIRO_MOCKNET_DEFAULT }); + const senderKey = process.env.DEPLOYER_KEY; + const deployerAddr = process.env.DEPLOYER_ADDR; + const userAddr = process.env.USER_ADDR; + const nonce = await getNonce(deployerAddr, network); + + const txOptions = { + contractAddress: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM", + contractName: "subnet", + functionName: "register-new-nft-contract", + functionArgs: [ + contractPrincipalCV(deployerAddr, "simple-nft-l1"), + contractPrincipalCV(userAddr, "simple-nft-l2"), + ], + senderKey, + validateWithAbi: false, + network, + anchorMode: AnchorMode.Any, + fee: 10000, + nonce, + }; + + const transaction = await makeContractCall(txOptions); + + const txid = await broadcastTransaction(transaction, network); + + console.log(txid); +} + +main(); ``` -**_NOTE:_** +#### Mint NFT script -You can use an existing testnet chain state if one is available. +This script will mint an NFT on the Stacks network. It takes one argument, to +specify the nonce. -In this example, `cp /root/stacks-node/` was used on one of the Hiro deployed xenon followers. Although the first attempt -failed, a subsequent attempt caused the node to boot correctly. +_mint.js_: -### 3. Launch the contract +```js +import { + makeContractCall, + AnchorMode, + standardPrincipalCV, + uintCV, + broadcastTransaction, +} from "@stacks/transactions"; +import { StacksTestnet, HIRO_MOCKNET_DEFAULT } from "@stacks/network"; + +async function main() { + const network = new StacksTestnet({ url: HIRO_MOCKNET_DEFAULT }); + const senderKey = process.env.USER_KEY; + const deployerAddr = process.env.DEPLOYER_ADDR; + const addr = process.env.USER_ADDR; + const nonce = parseInt(process.argv[2]); + + const txOptions = { + contractAddress: deployerAddr, + contractName: "simple-nft-l1", + functionName: "gift-nft", + functionArgs: [standardPrincipalCV(addr), uintCV(5)], + senderKey, + validateWithAbi: false, + network, + anchorMode: AnchorMode.Any, + fee: 10000, + nonce, + }; -Collect the contracts by using the command below: + const transaction = await makeContractCall(txOptions); -```bash -mkdir my-hyperchain/ -mkdir my-hyperchain/contracts -cp stacks-hyperchains/core-contracts/contracts/hyperchains.clar my-hyperchain/contracts/ -cp stacks-hyperchains/core-contracts/contracts/helper/trait-standards.clar my-hyperchain/contracts/ -``` + const txid = await broadcastTransaction(transaction, network); -You then need to set the miners list to contain the address generated in Step 1 by entering the command: + console.log(txid); +} -```bash -sed -ie "s#^(define-constant miners.*#(define-constant miners (list \'STFTX3F4XCY7RS5VRHXP2SED0WC0YRKNWTNXD74P))#" my-hyperchain/contracts/hyperchains.clar +main(); ``` -Next, make the transactions -- you will need to set the private key of the contract publisher as an env var by using this command: +#### Deposit NFT script -```bash -export CONTRACT_PUBLISH_KEY= -``` +The next script calls the `deposit-nft-asset` function on the L1 subnet contract +to deposit an NFT into the subnet. -This is the private key from the first step. - -```bash -mkdir my-hyperchain/scripts -cp stacks-hyperchains/contrib/scripts/* my-hyperchain/scripts/ -cd my-hyperchain/scripts/ -npm i @stacks/network -npm i @stacks/transactions -mkdir ../transactions/ -node ./publish_tx.js trait-standards ../contracts/trait-standards.clar 0 > ../transactions/trait-publish.hex -node ./publish_tx.js hc-alpha ../contracts/hyperchains.clar 1 > ../transactions/hc-publish.hex -``` +_deposit.js_ -Submit the transactions: +```js +import { + makeContractCall, + AnchorMode, + standardPrincipalCV, + uintCV, + contractPrincipalCV, + PostConditionMode, + broadcastTransaction, +} from "@stacks/transactions"; +import { StacksTestnet, HIRO_MOCKNET_DEFAULT } from "@stacks/network"; + +async function main() { + const network = new StacksTestnet({ url: HIRO_MOCKNET_DEFAULT }); + const senderKey = process.env.USER_KEY; + const addr = process.env.USER_ADDR; + const deployerAddr = process.env.DEPLOYER_ADDR; + const nonce = parseInt(process.argv[2]); + + const txOptions = { + contractAddress: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM", + contractName: "subnet", + functionName: "deposit-nft-asset", + functionArgs: [ + contractPrincipalCV(deployerAddr, "simple-nft-l1"), // contract ID of nft contract on L1 + uintCV(5), // ID + standardPrincipalCV(addr), // sender + ], + senderKey, + validateWithAbi: false, + network, + anchorMode: AnchorMode.Any, + fee: 10000, + postConditionMode: PostConditionMode.Allow, + nonce, + }; -```bash -$ node ./broadcast_tx.js ../transactions/trait-publish.hex -{ - txid: '93cae889b9382c512e55715e5357b388734c0448643e2cc35d2a1aab90dcf61a' -} + const transaction = await makeContractCall(txOptions); -$ node ./broadcast_tx.js ../transactions/hc-publish.hex -{ - txid: '8c457091916a7f57b487162e0692c2cd28e71dd0b2dc9a9dfad73f93babe1dfd' + const txid = await broadcastTransaction(transaction, network); + + console.log(txid); } -``` -### 4. Configure the HC miner - -Create a `toml` configuration for the hyperchains miner and set the `contract_identifier` to the contract published in -Steps 3 (e.g., `STFTX3F4XCY7RS5VRHXP2SED0WC0YRKNWTNXD74P.hc-alpha`). - -```toml -[node] -working_dir = "/var/my-hyperchain/hc-alpha" -rpc_bind = "127.0.0.1:80443" -p2p_bind = "127.0.0.1:80444" -mining_key = "" -miner = true -wait_time_for_microblocks = 50_000 - -[miner] -first_attempt_time_ms = 60_000 -subsequent_attempt_time_ms = 60_000 -microblock_attempt_time_ms = 30_000 - -[burnchain] -chain = "stacks_layer_1" -mode = "xenon" -first_burn_header_height = 46_721 -first_burn_header_hash = "9ba2f357115308fb1c503715f3a1b0cb3e8fdbe6baea7e7634635affdf675501" -contract_identifier = "" -peer_host = "127.0.0.1" -rpc_port = 20443 -peer_port = 20444 -rpc_ssl = false - -[[ustx_balance]] -address = "STFTX3F4XCY7RS5VRHXP2SED0WC0YRKNWTNXD74P" -amount = 10000000000000000 +main(); ``` -You should then add to L1 node configuration by using this command: +#### Transfer NFT script -``` -[[events_observer]] -endpoint = "localhost:50303" -retry_count = 255 -events_keys = ["*"] -``` +This script calls the NFT's `transfer` function in the subnet to move it from +one principal to another. It takes one argument, to specify the nonce. -### 5. Start the nodes +_transfer.js_ -The `hyperchain-node` must be started before the `stacks-node`. To start `hyperchain-node`, enter the following command: +```js +import { + makeContractCall, + AnchorMode, + standardPrincipalCV, + uintCV, + PostConditionMode, + broadcastTransaction, +} from "@stacks/transactions"; +import { StacksTestnet } from "@stacks/network"; + +async function main() { + const network = new StacksTestnet({ url: process.env.SUBNET_URL }); + const senderKey = process.env.USER_KEY; + const addr = process.env.USER_ADDR; + const alt_addr = process.env.ALT_USER_ADDR; + const nonce = parseInt(process.argv[2]); + + const txOptions = { + contractAddress: addr, + contractName: "simple-nft-l2", + functionName: "transfer", + functionArgs: [ + uintCV(5), // ID + standardPrincipalCV(addr), // sender + standardPrincipalCV(alt_addr), // recipient + ], + senderKey, + validateWithAbi: false, + network, + anchorMode: AnchorMode.Any, + fee: 10000, + nonce, + postConditionMode: PostConditionMode.Allow, + }; -```bash -./target/release/hyperchain-node start --config=/var/my-hyperchain/configs/hc-miner.toml 2>&1 | tee /var/my-hyperchain/hc-miner.log -``` + const transaction = await makeContractCall(txOptions); -The `stacks-node` must be started from a state _before_ the -`first_burn_header_height` and `first_burn_header_hash` configured -in the hyperchain node's TOML. + const txid = await broadcastTransaction(transaction, network); + + console.log(txid); +} -```bash -./target/release/stacks-node start --config=/var/stacks-hyperchains/contrib/conf/stacks-l1-testnet.toml 2>&1 | tee -i /tmp/stacks-testnet.log +main(); ``` -## Test Locally +#### L2 withdraw script -To test subnets locally, follow the setps listed below. +This script handles the first-part of a withdrawal, calling the `nft-withdraw?` +function on the L2 subnet contract, to initiate the withdrawal. The script takes +a single argument, to specify the nonce. -### 1. Start the hyperchain miner +_withdraw-l2.js_ -```bash -hyperchain-node start --config=$STACKS_HYPERCHAINS_PATH/contrib/conf/hyperchain-l2.toml 2>&1 | tee -i /tmp/stacks-hc.log -``` +```js +import { + makeContractCall, + AnchorMode, + standardPrincipalCV, + contractPrincipalCV, + uintCV, + broadcastTransaction, + PostConditionMode, +} from "@stacks/transactions"; +import { StacksTestnet } from "@stacks/network"; + +async function main() { + const network = new StacksTestnet({ url: process.env.SUBNET_URL }); + const senderKey = process.env.ALT_USER_KEY; + const contractAddr = process.env.USER_ADDR; + const addr = process.env.ALT_USER_ADDR; + const nonce = parseInt(process.argv[2]); + + const txOptions = { + contractAddress: "ST000000000000000000002AMW42H", + contractName: "subnet", + functionName: "nft-withdraw?", + functionArgs: [ + contractPrincipalCV(contractAddr, "simple-nft-l2"), + uintCV(5), // ID + standardPrincipalCV(addr), // recipient + ], + senderKey, + validateWithAbi: false, + network, + anchorMode: AnchorMode.Any, + fee: 10000, + nonce, + postConditionMode: PostConditionMode.Allow, + }; -### 2. Start a local Stacks network + const transaction = await makeContractCall(txOptions); -```bash -stacks-node start --config=$STACKS_HYPERCHAINS_PATH/contrib/conf/stacks-l1-mocknet-local.toml 2>&1 | tee -i /tmp/stacks-mocknet.log + const txid = await broadcastTransaction(transaction, network); + + console.log(txid); +} + +main(); ``` -### 3. Launch the contract +#### L1 withdraw script -Collect the contracts: +This script handles the second part of the withdrawal, calling +`withdraw-nft-asset` on the L1 subnet contract. It takes in the withdrawal +height (from the L2 withdrawal transaction) and then fetches from the API to get +the details required to verify the withdrawal in the subnet's withdrawal tree. -```bash -mkdir my-hyperchain/ -mkdir my-hyperchain/contracts -cp stacks-hyperchains/core-contracts/contracts/hyperchains.clar my-hyperchain/contracts/ -cp stacks-hyperchains/core-contracts/contracts/helper/ft-trait-standard.clar my-hyperchain/contracts/ -cp stacks-hyperchains/core-contracts/contracts/helper/nft-trait-standard.clar my-hyperchain/contracts/ -``` +It takes two arguments: + +1. Withdrawal block height: this comes from the L2 withdrawal +2. Nonce + +_withdraw-l1.js_ + +```js +import { + makeContractCall, + deserializeCV, + AnchorMode, + standardPrincipalCV, + uintCV, + someCV, + PostConditionMode, + contractPrincipalCV, + broadcastTransaction, +} from "@stacks/transactions"; +import { StacksTestnet, HIRO_MOCKNET_DEFAULT } from "@stacks/network"; + +async function main() { + const network = new StacksTestnet({ url: HIRO_MOCKNET_DEFAULT }); + const subnetUrl = process.env.SUBNET_URL; + const senderKey = process.env.ALT_USER_KEY; + const addr = process.env.ALT_USER_ADDR; + const contractAddr = process.env.AUTH_SUBNET_ADMIN_ADDR; + const withdrawalBlockHeight = process.argv[2]; + const nonce = parseInt(process.argv[3]); + const withdrawalId = 0; + + let json_merkle_entry = await fetch( + `${subnetUrl}/v2/withdrawal/nft/${withdrawalBlockHeight}/${addr}/${withdrawalId}/${contractAddr}/simple-nft-l2/5` + ).then((x) => x.json()); + console.log(JSON.stringify(json_merkle_entry)); + let cv_merkle_entry = { + withdrawal_leaf_hash: deserializeCV(json_merkle_entry.withdrawal_leaf_hash), + withdrawal_root: deserializeCV(json_merkle_entry.withdrawal_root), + sibling_hashes: deserializeCV(json_merkle_entry.sibling_hashes), + }; + + const txOptions = { + senderKey, + network, + anchorMode: AnchorMode.Any, + contractAddress: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM", + contractName: "subnet", + functionName: "withdraw-nft-asset", + functionArgs: [ + contractPrincipalCV(contractAddr, "simple-nft-l1"), // nft-contract + uintCV(5), // ID + standardPrincipalCV(addr), // recipient + uintCV(withdrawalId), // withdrawal ID + uintCV(withdrawalBlockHeight), // withdrawal block height + someCV(contractPrincipalCV(contractAddr, "simple-nft-l1")), // nft-mint-contract + cv_merkle_entry.withdrawal_root, // withdrawal root + cv_merkle_entry.withdrawal_leaf_hash, // withdrawal leaf hash + cv_merkle_entry.sibling_hashes, + ], // sibling hashes + fee: 10000, + postConditionMode: PostConditionMode.Allow, + nonce, + }; + + const transaction = await makeContractCall(txOptions); + + const txid = await broadcastTransaction(transaction, network); -Set the miners list to contain the address generated in Step 1: + console.log(txid); +} -```bash -sed -ie "s#^(define-data-var miner (optional principal) none)#(define-data-var miner (optional principal) (some \'ST2GE6HSXT81X9X3ATQ14WPT49X915R8X7FVERMBP))#" my-hyperchain/contracts/hyperchains.clar +main(); ``` -Make the transactions -- you will need to set the private key of the contract publisher as an env variable using the following command: +#### Verify script + +This final script queries the `get-owner` function to check the owner of an +asset. -```bash -export CONTRACT_PUBLISH_KEY=0916e2eb04b5702e0e946081829cee67d3bb76e1792af506646843db9252ff4101 +_verify.js_ + +```js +import { + uintCV, + callReadOnlyFunction, + cvToString, + cvToHex, + hexToCV, +} from "@stacks/transactions"; +import { StacksTestnet, HIRO_MOCKNET_DEFAULT } from "@stacks/network"; + +async function main() { + const networkLayer = parseInt(process.argv[2]); + const senderAddress = process.env.ALT_USER_ADDR; + const contractAddress = + networkLayer == 2 ? process.env.USER_ADDR : process.env.DEPLOYER_ADDR; + const networkUrl = + networkLayer == 2 ? process.env.SUBNET_URL : HIRO_MOCKNET_DEFAULT; + const network = new StacksTestnet({ url: networkUrl }); + const contractName = networkLayer == 2 ? "simple-nft-l2" : "simple-nft-l1"; + + const txOptions = { + contractAddress, + contractName, + functionName: "get-owner", + functionArgs: [uintCV(5)], + network, + senderAddress, + }; + + const result = await callReadOnlyFunction(txOptions); + + console.log(cvToString(result.value)); +} + +main(); ``` -This is the private key from the first step. - -```bash -mkdir my-hyperchain/scripts -cp stacks-hyperchains/contrib/scripts/* my-hyperchain/scripts/ -cd my-hyperchain/scripts/ -npm i @stacks/network -npm i @stacks/transactions -mkdir ../transactions/ -node ./publish_tx.js ft-trait-standard ../contracts/ft-trait-standard.clar 0 > ../transactions/ft-publish.hex -node ./publish_tx.js nft-trait-standard ../contracts/nft-trait-standard.clar 1 > ../transactions/nft-publish.hex -node ./publish_tx.js hyperchain ../contracts/hyperchains.clar 2 > ../transactions/hc-publish.hex +### Interacting with the subnet + +We'll now use that set of scripts to demonstrate the subnet functionality. + +First, we'll publish the L2 NFT contract to the subnet: + +```sh +node ./publish.js simple-nft-l2 ../contracts/simple-nft-l2.clar 2 0 ``` -Submit the transactions: +Clarinet's interface doesn't show the transactions on the subnet, but, we can +instead open the explorer, and see this transaction there. In a web browser, +visit http://localhost:8000. By default, it will open the explorer for the +devnet L1. To switch to the subnet, click on "Network" in the top right, then +"Add a network". In the popup, choose a name, e.g. "Devnet Subnet", then for the +URL, use "http://localhost:13999". You will know this contract deployment +succeedeed when you see the contract deploy transaction for "simple-nft-l2" in +the list of confirmed transactions. + +![contract deploy confirmed](images/confirmed.png) + +Now that the NFT contracts are deployed to both the L1 and the L2, we can +register the NFT with the subnet. -```bash -for I in `ls ../transactions/`; do node ./broadcast_tx.js "../transactions/$I" http://localhost:20443; done +```sh +node ./register.js ``` -### 4. Deposit some funds to L2 +This is an L1 transaction, so you can watch for it in the Clarinet interface or +in the Devnet network on the explorer. + +Now, we need an asset to work with, so we'll mint an NFT on the L1: ```js -const network = require('@stacks/network'); -const transactions = require('@stacks/transactions'); -const senderKey = "aaf57b4730f713cf942bc63f0801c4a62abe5a6ac8e3da10389f9ca3420b0dc701" -const layer1 = new network.StacksTestnet(); -layer1.coreApiUrl = "http://localhost:20443"; - -const depositTransaction = await transactions.makeContractCall({ - senderKey, network: layer1, anchorMode: transactions.AnchorMode.Any, - nonce: 0, - contractAddress: "ST2GE6HSXT81X9X3ATQ14WPT49X915R8X7FVERMBP", - contractName: "hyperchain", - functionName: "deposit-stx", - functionArgs: [ transactions.uintCV(100000000000), - transactions.standardPrincipalCV("ST18F1AHKW194BWQ3CEFDPWVRARA79RBGFEWSDQR8")], - fee: 10000, - postConditionMode: transactions.PostConditionMode.Allow, -}); - -const depositTxid = await transactions.broadcastTransaction(depositTransaction, layer1); +node ./mint.js 0 ``` -Verify you received the funds in L2: +Once the mint has been processed, we can deposit it into the subnet: ```js -const layer2 = new network.StacksTestnet(); -layer2.coreApiUrl = "http://localhost:19443"; -await fetch(layer2.getAccountApiUrl("ST18F1AHKW194BWQ3CEFDPWVRARA79RBGFEWSDQR8")).then(x => x.json()).then(x => parseInt(x.balance)); +node ./deposit.js 1 ``` -### 5. Submit an L2 transaction +We can verify that the NFT is now owned by the subnet contract +(`ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.subnet`) on the L1 using: + +```js +node ./verify.js 1 +``` +Similarly, we can verify that the NFT is owned by the expected address +(`ST2NEB84ASENDXKYGJPQW86YXQCEFEX2ZQPG87ND`) on the L2: ```js -const codeBody = "(define-public (stx-withdraw (amount uint)) (stx-withdraw? amount tx-sender))"; -const contractName = "withdraw-helper"; -const deployWithdrawal = await transactions.makeContractDeploy({ - codeBody, contractName, senderKey, network: layer2, - anchorMode: transactions.AnchorMode.Any, nonce: 0, - fee: 10000, - }); - -await transactions.broadcastTransaction(deployWithdrawal, layer2); +node ./verify.js 2 ``` +Now that the NFT is inside the subnet, we can transfer it from one address to +another: + +```js +node ./transfer.js 1 +``` -### 6. Withdraw +If we call the `verify.js` script again, we should now see that the NFT is owned +by `ST2REHHS5J3CERCRBEPMGH7921Q6PYKAADT7JP2VB`. -Perform the withdrawal on layer-2 +Now, we will initiate a withdrawal from the subnet, by calling the +`nft-withdraw?` function on the L2 subnet contract. ```js -const withdrawTransaction = await transactions.makeContractCall({ - senderKey, network: layer2, anchorMode: transactions.AnchorMode.Any, - nonce: 1, - contractAddress: "ST18F1AHKW194BWQ3CEFDPWVRARA79RBGFEWSDQR8", - contractName: "withdraw-helper", - functionName: "stx-withdraw", - functionArgs: [ transactions.uintCV(50000) ], - fee: 10000, - postConditionMode: transactions.PostConditionMode.Allow, -}); - -await transactions.broadcastTransaction(withdrawTransaction, layer2); +node ./withdraw-l2.js 0 ``` -Find the withdrawal event in the log: +We can confirm that this transaction is successful in the L2 explorer. + +@@@@ TODO: Get the block height from somewhere easy and set the variable +`height`. @@@@ + +For the second part of the withdraw, we call `withdraw-nft-asset` on the L1 +subnet contract: -```bash -cat /tmp/stacks-hc.log | grep "Parsed L2" +```sh +node ./withdraw_nft_l1.js $height 0 ``` -Perform the withdrawal on layer-1: +This is an L1 transaction, so it can be confirmed in the L1 explorer or in the +Clarinet terminal UI. -```js -let withdrawUrl = "http://localhost:19443/v2/withdrawal/stx/14/ST18F1AHKW194BWQ3CEFDPWVRARA79RBGFEWSDQR8/0/50000"; -let json_merkle_entry = await fetch(withdrawUrl).then(x => x.json()) -let cv_merkle_entry = { - withdrawal_leaf_hash: transactions.deserializeCV(json_merkle_entry.withdrawal_leaf_hash), - withdrawal_root: transactions.deserializeCV(json_merkle_entry.withdrawal_root), - sibling_hashes: transactions.deserializeCV(json_merkle_entry.sibling_hashes), -}; - -const layer1WithdrawTransaction = await transactions.makeContractCall({ - senderKey, network: layer1, anchorMode: transactions.AnchorMode.Any, - nonce: 1, - contractAddress: "ST2GE6HSXT81X9X3ATQ14WPT49X915R8X7FVERMBP", - contractName: "hyperchain", - functionName: "withdraw-stx", - functionArgs: [ transactions.uintCV(50000), - transactions.standardPrincipalCV("ST18F1AHKW194BWQ3CEFDPWVRARA79RBGFEWSDQR8"), - cv_merkle_entry.withdrawal_root, - cv_merkle_entry.withdrawal_leaf_hash, - cv_merkle_entry.sibling_hashes ], - fee: 5000, - postConditionMode: transactions.PostConditionMode.Allow, -}); - -await transactions.broadcastTransaction(layer1WithdrawTransaction, layer1) -; -``` \ No newline at end of file +If everything went well, now the NFT should be owned by the correct user on the +L1 (`ST2REHHS5J3CERCRBEPMGH7921Q6PYKAADT7JP2VB`): + +```sh +node ./verify.js 1 +``` diff --git a/docs/images/confirmed.png b/docs/images/confirmed.png new file mode 100644 index 0000000000000000000000000000000000000000..489bdd83aa0709a344767934710e6998ef2db8ec GIT binary patch literal 267431 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ºiJ{fdzzK4Yp(Ac$2F=M2T%J}V>Y$mpBR#xQk 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 z zCHuAxef6XCbS%I-Ym~mn3;fG}W#`dVXBT$rIdRba=kkB@|=@S-j2&7%j{G zKw2MrckoQsU~mEWU(rw1~yi))F5ja2mG0lxVEzVcY!z?IwbvpQ)Yx#3Fw zk6?ky>kRm0dF?wmG?0ZPxK!yz61{9hTg3ctY;vxE$TZPqQ}8wR28>OpOYY;`&V{4du5`Qe9u z|J*XZ+>1s=pIL`WlMpsJ8>GNK0V|8iZ4iqv#pyd{;Wr?1)<(mB>OUt-B)ZArK0klb z4*!;61<`t7G}5mv7YM@(v!11UKO-+5(RK^B(M|eyP7MgRo<#WBHDN<;ZF)b^e4kq6 z^U{poq8>|Wq{(W^~?MAac068*kgG$9eOB~B@ieK24AM~`Y z;T)1s{_m>x>a1YVM}sipqUEgrZw7TsB<0JY`PcUi7BnMrB6?&uov+=Ly3;0#`^QqE zQy&*)ap{v|_7uon5uW$kZ5Gur`)Q-?_?=A`A(u%t9U;Fi)W{Hyz!w=pXLE(ZdK6Kw zMWNYp2#oZ83UGqlj_#6zUf9=8STNn%>kMJuckky_TCP{Sb-V&{rif*U>p%(Ud7}W< zUk+RqFTZbJDzqsLr8VBbli>}{t=JP|-?tKieJj@?PG&KLKa?q@M_@>{`J|`D8+_#& ztl_OBc{1AYFTtjAd*29FKx8Od|I&H7fEqD5(*zWt0Itf{s}mlcn4T}5O+X8WLxYu=R&}0;7FzVUs=&T_~w%nGx zc)5sqL+O2#;H|~-JvSxYi%N36ykx%~bg<9i^-@R^evP0ysXvDB!1i1vX+$Fr_|GVt z(7t=zy><=Z{7MPN%?r5?8b*3oaZQfp*;1TjtLX0$g#qfvra^AU5|xhL?1HHL$ZX68 zWw`wG4>&q~{A@a^vPq6Du9@dcJ84V%q2~JF@3-$=s|;kW6Lt68bXb0-4|noI@y;@V zQ@H`4lBR#pT88k!NK)V15nQ@Y9cKjpk2P9fKBgeOJBn*^ET*`>e>II;oJRdl<(^Jl zz3%&5$DcEV30t~zlp7h7YTp|MQc*I5Q6t|^#f2{oj-?@mE=(f@&Nea;l1%L3XS=q0 zGXe$n`-)JS$>Ho)%$2fX&cbcn*@o!z< zMtRdgX+iyF)U$UZqw-0)u(puf`R6^?VTQAOb$#{8|I@g>w-Gh~Iw|C4HUwlaN%#7< zde4ZCx@Mi85`pt2UJrihi(fdIEbSnjcN#r<(NnxFjgWHx>JTuH>wnX~Ek8oC*|(l=O9$7h+P^0{ z2faU8SqcOwc^K(ECraR3oWmtr&oYt{MQ2i!V)-oX2E==+!;BV6=iFWCT;Rc(NxRE` zPztk5=g?u3IsD{$4B^@fR$g%MCjWNqRo|A+Z9{7Kx7j*aZsY<}9jh%PuX|IKGmCxy z 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 UKb)wPfPjDUGRo4Wk_P_&2XR<~VE_OC literal 0 HcmV?d00001 diff --git a/docs/images/subnet-devnet.png b/docs/images/subnet-devnet.png new file mode 100644 index 0000000000000000000000000000000000000000..108ccd43ec2757c26b78472802ca0991baa20065 GIT binary patch literal 59082 zcmZ^~1zZ+gw>}I=x3qMFba!`mBVE$n-H1qcBho3Y(%s$N-Q9eHKIeVUcm9uX-#><# z*)u!Wx~{dZ{YgPi903*^76b$YK~h3Q2?PXu6$Atn9vTujV-3+q2Lb{wWG*bMASo^@fz)o` z#!y13LJ_Jb(?`Nw7evWR<;P`$p?w5%UWLBoSmb%jOhtv;$~5`h)c6Y#+1#^BxAsDjd(UFSQHLfrtKCciXLR+R@L7qoM5A&|*k=08+fd=p>BARu-q(r{xI5?6D^U)Zn_MwG#O6G$$Gh!cI{nB>RTsNtRcFg%?I#WjUN6ko$ZT0W6VqEX+B zJ~Qe|#;Nwf29dD$$Z43+D8z(n!Lvm4+-x!i%ykTL=#0iBiJcM~?4cYX^zhe72SyNk z>)BYr-sU#Tqh8;?q=2~uft?JDM8L)DKw0iM7@u|g&`-J*GJT9jtGP&lH;-5btMtCPeQP?aw*R z+G*rI#`EBNaY94UAcO1*fLUTEgH`!uS637vE%$i_fIx)_Lax5?gkWYNR-7gYn$b{z zehvylIuGf&8}PWx207OY)x4X+|2E(OXG~Jnh8pH5h}G+VgEB|CR#^{zip3P*>$cO{ zAAGjmN_F&d^N9SAVIV~Qp-m!$XM8Gz=97OXh#@p%*vG(w4Za3Ue8dW$O0G5dMWc`S zD@QQ$&^ke(L6$)_?PYxd#Aot~k#Ck1_$6XK*AO`RYYWM$FB05@>?^#RX}j|0JqCMX zu-Dt2L$9I{T^uhR^&Nj+fcJ63hUKmzc}EsS_z+X(i(h0>vd>jYJaiRx7t@o2y;%l*0St}gvBvk4mCWW5C^B2ozo*(K@@gD?!`AcF6Nf)Qzt z!6Jo`6lFptA{I0yf{SMQhFc`WM&#V9yNT=o#u@5FR38l`L4S^Y7i3rnTO5r2HF5W2 zyg$=^+f&9$T*GXbl#zZNr|94?Qc8zOCf+$c6* z_34%!EJ0tOlEe*VHs~w}zMVw~CMTdW!7kbk_Bao}otrqOP`HNpXGc@A$RP1BDIHNc z$uT)Th09xlw@?zKvG{$Fo3i1g_7ZpBP{y^!<&>!Rn2JI#1tm56H2NgpOT5>VEL8cX zl2aqRmppEgS0I(uw{HwrMZp<6NHRi5Phtx+o<7#IH|sq%8g)23S!AqeihR*G76m!Q zW2I$EYU(s9PfBrWxcHs->QpC+d?k+pce&yD;bpMWWTK*9t5i(V`t1|6scZ{Xipi#; zQe}n;=<=o&<&{p9`3uKY@KolCd8U38PZfVDPEyq?j+vsFOty%dgq@ywD=t&G;#>X1gDkv^kPIn#nhcjLUz%1*cN#{@ zFCId0g-{=MA^iVQm3+6 zwP3X?HP^DD>E>zWGRv}xd1PxWwmG%~E4sO_b>(#_byIbiM+)5R-2O{kzsePZ6!CL| zaxKJ{D%HQ6&125aEb!Zn+C#fiI(&3+Ug7a zgMEVoPb-FI1hY{J)z-0MRNnJ8Dk{?^^Dgs&=jFWWrvG|=?aHcjO5=H!)`-A8&BL*g z-QD$J)LY4$?cV7j_13}5(wpEuS?8#N3&Y9=S`*G zs^7TZu)t93ZEJDsgJ8bkJHac#r?&Do=D?^>WTAE;wV*|PoT?v(TrR$ap1X&m*9-}j zvz5h_p=)((>!*qKyA7lE)ICdID#MV)SVRLPTsHfAJr&gym2(lrQFC*@mgHu2Mtn*^ zcO*~5;O2A@Km5h<(qLlmx?Z+Hc4iG@0rMWl8Ri7_4axxOubwD;e$U5X(kD_uB}blqieKq_^M8dnKl;#xl6mPJ^Y^hT!YEnz# z>4(GKL+iOf&QF}b91|Rr9g$#IgXh|>--{{d%kQDgeUcJcQsylv&zz@6M713fJ}2L1 z-LY&VxI_F@yNTHs2$mJFAAmH0l7Ey{&ZxuDWE64~(Z!sJ0g3+1hMLuvF~>GwJpHJN zWXf!2n;JMMnKr>TV`X!;nCaejQ8!XBIFk9|8DpgAKDGey2~H~<;qwkU|2^4l(ml!) zihbXgU|l$Nns!VW3}-qQ-A0$QdL`YxJEoqh@G5%g2I=7!uI-tAJ*cF7`lAoqbyiOf z>kez@2h?8bR`fHJ^fbOT4vYQWs+X#HCClZRjrSjdrMp5{<5^=_mlD==2`) zsH*q1YJIPcu>(`PSWjlorgd~r>YEJ$*Fvfgve;nRmKV_)i@r}+)fqC|JGO08Xrt7n z-+ejLUQ&B1Gtq9bLA5zp#;)Io;Lt74g`|NGPBYks{agN;YE$^#~esLE4I8fNlsl%v93=G9X zwBMAL!X0D3uDGyS$4$|b)i{s8wCqlGI5{^VSRkKi zkZI0);CP%skAlWA|%xc5UAN)OBVB$>paro32yKtXJQLlJv}MxlxigeO3dC z-PWb*^%UF;ak;ZjREy7rSpS#fw8pd%o2^9;=U=PWJKPt?D94G*$}Q^lE2}<71Z=*C z$1Vqa_k^p0Jsq>5uK4x@O>XHox6<-wsQYo@1>N!onVh`b<2aL^dv`%Qy!0aUd^ZV? zMQ3J1(g#UU&*u*%xxQY$Bh+UlZ8Or#yG?V~(_7XH0+X#zu0KxrTIip$Zwwy9yL*_k zQ22SDc#h!qq_@=5Dri^Qo0sqg@o>@XJ8|bKKp?48GZ9-4tU(mwK(gB|-kAhEK2lJJ zJq}U{ukst*y;D?M1o`Oqax&(9da?}(;#t?afjOxz4N4deE07K)kdYC3Fsdo*QXY>% z%mZZ=ahsZ$2Kg)-lf~&9_OOE?p{mn5a?}EXZQR)i0g(d5`OmQuDCIx*fPsL7nuCD`THg| z1Oy8B4+Z!JWrO|C-QcU)Z~o^P6dt$+BB(4ZDGB^lHgYgAv2pxp>-1~$V-j!z#!f=h z5d;K-?DY#OsYH4T0s=N`uALg!{}_xcuGvo!r!+zS@IHV$SM#D+d7yKve7ZnF%a{?5)u;fI2fC9DT#>v zQyln@m-wTTlN}d5y{oG$ohvh)t%DgoBPS;(Jp&Ux6B8|P2d$&Kjgx^Jt&JnepNIU< zb3{xWjU3GFoXl-)2w$ITU})>?#7j*4`lA2*{HdpjoB4m=WaIcxvw#NDzh0qdq+_7} zw_;A_rhh5+dgV{C-|hPII-b{uaVeO)nOJFvm|Fu~4OESfk%@(a=l6U5pG*I(>7Syi zjwTMmw$?yNC%*p<)<1>+_r?EP@b^14|NBlRw*TKN|JRlORr0kBTuLU6wpPxseW+?< z?!?E$L;r85|8FVH{}$t8WMTQI(EmRBe@kfmYl;7T_WzcUcQ6O~!Qi!Oe2o9R;eVg| z=YAgg*RlU!bK%cK`+XLeX?(Ce^#7T)e6a0&QFS070w9tif+}vHhZ#_QXrdD#2ayrr zebCU*VF3YO4G}2|2?@U@D<}@WMQ4U&$T7U`01tmV2+CmAc1SOVjE?*%maG8orTGi% z_3+T~QBYG;lPBD@X@0>3Pn<__Nr_`ByR9xI8VVukUq1dd$i1@C<%99y5`KUAv?6DN zMPh=%M1%bM=UWU2x}AB@K&j;4p5O<|q5FnZ0PNpC(PCgKt$A%OWNl>a)H-x{v zK3V`9MgcTQtYI+qFAeYmFZA1B{oCsWz|2VnAU<^3JzO7A%cin?;!rmg|65hdz^TL( z&z_$i2IRPpNQctclVsD_`UrdS+eiJJHJ1u@Dw$|`b&8bn0QSvf3H?N zw^e_{X!D7D&Vyrgc>Z7lj$VAv!x#ln*I9$mzUPM%dh3O{1S-|y-YS!U%?Ww_1hY){ z?u@)@@0X_=X`n&r)}@1)yxJj11a!c-CTv7<%W2hF?RC1}Z6$3r-7GVojc^^%>@EJN z*5rRUtR7+-%L2MW+hV%(eaqwdXP(p6H*z(?NW3bMyw@6L3%YIKXh?jw*?93z-aUA( z@%X$R&@{W)tQN*0=U*FlGCk#1@e)-b?aj9Hqm(i4>lH6RK;4B#Or{KGWrSwPD5Qp$~>4op2}1w|Ov)ePnsa`7dS( zlmHw|ww=LwU!`wgfVr#FtGBOugpc~yVby1|?|NQm!K*taeGnxqs?FBRjdO$8um|50 zsMS*&fw3jU`dKW+@C#(K{^J<&#l%mmrmJcDes&pne@UX#YBR%NL*xg-Py(NZ4C_T; zZDt)?2`iewg)Cd#{hZ`Ea_gHGkHW_*@Y1d_{`3e;888SU@am%LqXqRtkJ-E6wNNjs zt%dnoONbrxXZA9_gTpN9SA3`?| z)-@IY0XKNsRln>pK)t1|R@&00jpFa6k z5aMphVSqOBDkEe;8lGaxpfE|tB}EZs{^2`f7g4-^JL%VQs`iiItB(U5+fUh~(kXn{Spq zj}Es!QDib;I6ya^w!>`!vz+;1gkvM3!EN#1eTjdS7|4Bgd;8`^q7Sf|#Gn%UzxN;r z27{GzKzycJ)#rr>UNA4nAg@#jR4M{7bjRo;8#6zeE0*+gw2c1HQY(E z4fm@$5V^6)7U1X`_3NyC?XkFEEvwhT`Xkt!jYSg!jL`#Ee)Cz7KHY7w)qsW0=Ty!JA-tRL2|gyqK|}@)1{1j4-9v~ zzr1SwoMt{P{JY;*z=zg%%GQJUkS&R&@9#XRD4vpqLlZBiP=n_<$jIb!sA0zLm0F}P zQ3M-rioM@h5O1?A?>ey;qJhPQj&FXY#jrkvCrRf=b>fw%&I|+CpzU?Ep zG|T#TA$^dmt_T5hvWyGnlZHrnwG>ejwds_1OD+r60R-UHL+kYua@>+7YGo1fEr7@D z(S*v^67MGYixrs_B8-MujCjY4>+|$*<2v1>=2S@L)l~HOcro&mO6RAO{qzzw!=C3( zhU;Jj;N*^%VyujqV9+(1*9x5LD0oLX6lo3ap!P;{gxhJ>v`+vl#KsT5rwR-n0{f!A z*TP)Cyo`wbjE-wxtN)v=>_9}OIIHZzr<)bM&)czo!Bwpk{sOQK_8Z-tUHTz1+MJt* zVPyg-x#t7)ExW~leV2cJez2|nvQ`RAeCO-EexT`QkJVGBive*eE3lX6FR~q z(G`x~bwB*7AGulzt|4O4j{@hOSccv z&mT}R74!x?p2@>e{mf>jw1$?BeHXeI=T4;GS_!6(Qw%qU4UQCbg+Y0i@AD646&5=G z9>~W@LBV91Y@V8eWIP6aKhm@uw4QI%4t?iS-pPadondc(nkPcx+W9F8&2M#!hFJq+ zt@hLTU>lKb!QhrCuq_a3;Cm1LK}tO&opzl}HgewIV0_r^RF=OcFkY}YQpF3lElcne z&LaY_CF~k8NA)W{nf>gW{zRDtnI6Th1?l%96OA)v+7z!Yq2L_B-sxKDOO{niR#ui( z{hS$6OmNFj<9>G1(Y2H=(??tIirY8}`NTLmE=dOXX>Xp@yXys83YBJ}1%}7y=Sj^#s4<^V z3fG<{o+{H;-=8W`FFmK9vk%>x$(O~+MV3{Ayovc&{v_Z|hTI887md_l?AJlL5^d|Q z+PpTKM6YM#qk%+aa5u-i2wC=K;@=B{z&wf*P9jgfRIOqEyH9xSZa++bKs6RJMEqqP z`+*Y^0}M!nFa_bS4{>`Nrre5-fsxAb^HQpn;om(cfD8cVsbULEHIB~rt4fls9RF_m ze{-=S)KgwKiw#t2$&9+GF06qkOU5J*`>xKxzL;5GO-{=u8aGpA#+V;zf33C@Kj;c< z!#$pb#8w%VR9?R-DLaMM8?NMI>-ic%DwW{`2qB0Mdo5lX!hfl+|2p)oTI-fIW%Pb6 zwd4Y1#y5*Di&(vA^$+jfAB_x^5xPU9ncRPUiF3v&@{)$ZCi&Yi#Cw1}%g#RIx%~X0 zpIbVjO^tItBYrNdn|98g=%K$?uD{akohKPbzDJioxvjSx)iRlhr4|8Rjuu;e7EwG6 z=n95ip{~K}E1zUP;WhLSD0u!nwntMKVRJqPCsgX=x+3P?kq{z}_ zfM9)aaBRy_kmG-HO5yYNFm^W+7TbEdov@D#LByk~wVX+;Xug-y^*ZZvLTlrZ%vM3} zy}Tfq*h-p|3|oJ4-A*x+0@x{U$s=It2Qc-#)_zpffa3$)%i-0B?~BYqQX=%Y0$f9? zLbpjqHIYt-ioWqwXmd*F9bmoUPMRO&x+C#$+@A%R2CpC37Y+zE(-ZPpFhAJ&*Vru0 z*DQ#C!A@|Pny)b@3B`2?I|K{}Bf%`^Ie>r%D6+hW0sN{g_hn4>Sh_XJ z_HFf%hICbPL*y&r01P`ix*Zuzrbz;&zYIS=la7yMdnC|PudK6f!RA2o$oXJ8!2@DZ z*YgP79j6sl369IzNKp%Bw&@Q2@5O#BH@Z8%QrK)d_9dq{yx@aBYt)>0RSy)i1e#{` z9F{GGtaSA&vdpdma<$)Q^UJTjbO-0R+iA8DTR8Ey(PtYy1zzv~pNW;GZ<_23Jx7pg zu!>{o$+GV0zmElh5s@aG7>SZeBA^|*+_?rOv;+Vj*I@(l=*S$wUnwr<)ugg4L^gP^ zP)?)7e;TXVAeIfS+wA4OnBx}QC2D8=abXEP-R=Sa@ClK4+*}VcrJ5uV5D>$TZ(-Rq z-rO9_jC{(aRv7;R05f)@xEbqMGU-GKfX085%izjKCFpnDgd)=+ZezFrCWp=|?MCyT z$d_d{ArBw1`)v{YKSF~mwdQ=3NmihQV9c9qfn}z7QN?#xD@%S-;5OJL^XaQP8~gN`zpKy;1br&taaH$26_%s;os}Xa!AMuhqxW{i^9NinD32Df0(KMWTOP;p zI*(9D?JkDcx%13JGf@?~)vJE5WwY~hkK46S698)^03i?2VIZQQj2?m8u$8DC0S1TB zQWQp@_X(KV6}eu4=Z6u@!^r8v&@{wZp2wWb7CAt415COWh+B}C!@4dxCsjX9YukSE zKC!7^auMSUy$7(kxam-8g45-j$h%kk5ROjWFN&!n0+BA9Nc}q0(R^TSXm*Tbn!3-X z8!xn6S=M3@nB3#%=Afa<5z7>h{Uz}?8}t=B89lOKivKKq@wRC9czG~&J?~m0_Y1&% z799E((~R~1UcOmHmXZ{_X}q3w%E1{f^L?ejvY&^kR$o0C!p}so)aA#p1FXdNxQsF{ zVM3a@Vg47djUI#rU@1GKgV~%k-LUz1e@EI`RBI-JZ(dmy#+G8ejpqYEd@R+f0)Bk7 zLbEEs7=b_-{(DOw+P2`|ZaMFh03if!yiKLw0BwXU7II3v)n_m|u3+6h!;tqk0CBf9 zWzea$NYD>McoZN#?|~$s?7{aeH6!zVJQH_6ZG+;yAwousjp8|%Fna;I@TjyS6i&CH z4gfII@4i}u9&mYywIV^J8+M@KU5VQgdaSLE)^hkWTW~}NpTMyQjc!~6=$OKJ8F%|u zG3%hBW%(94mBApO@vIvspAr1oE&%RsEtDX_Hf0@mEVUQ(SwzzZ*~cY8p8JSpB5>iW zDBN75d$kvU#m?s~D>!+JT|QJe-x`7asYp3e_|;g+ewHtAVm%W37JlJ z9OkTYJ2Sk%4fW_j9G9%{$Uo}D zD+xawcT$l!HC$T-xp5r}q#v7KzLtv5?wHNq=zTS66G6Cj3t1(Z8Q4d9U^qnW;D04s zcXxM8X2ZCSOHnxNh`*#ooEqMTWZqxBL5JXnuMX7X)i}|oTs~=eu_>RqyV#-N_0hOn z)dYjOti%mqeVa-B5w#Iu;xH4Y=g(ihK4IiPYw^vy0CA2IgZRD&_BBbW9K3m-5GH9+ z3X0o@lNMG=8<>{_!O%h5>LE6;7E9#xH?>~XaDG=Au<@P>KMja!q37qRka#bn%e!eY zX|;^KBywe=&a;g_RO$y0C0yLCrs|U^Q4lGZzCf54e zHklWiUfN5bc-16S>^(M@0L#IO`*+H&+no zDJnnq3dKN>5j+aN1~{pU6dRU2Pnt~Gn7P6F`FFDeH-UyS_Z&|lBRW1(!gYX+f&`4f zv9zu|PGhi;Msln}|9E+Rh@%2KV)2>Ir6hnI$bM9qq0{-<3&eUN#s|x}Z*v({(+LE< z8dte2=c@8D7QLXqLSYG`o{n+2pKmriEfV@OfS+28nGuBC7sBImD7?Y|=1Z{-J8R-& zKhQTUy)?{EkG)QJeyh$e!k^x}2vim~0HMo4X5?zwuSV2(unpNKEe&z+>_`qTP`g6h zU&u<>$}KhW1wO%F>kf~OiMegYi1TEvxV2=HAS5#ExrqDUkdlk|xiyu<;hAap*bzqE zsC0xNY=qAlgyId#T)6SKBPAxa3i6T@*lFXhJwcK2&l6w;?2x52`sRLY2`*|$MCwkq z=8$-p`dqZaP|HJ2hj*M642Ow9B$&BmE zC7*+fTj^{ye}~i%ZLW9}-FQe3w*tD|E~RQ4P5USCeoNXCvysdIuejgwKy@AGgdbVM zd=H256tNPC6#rmsH&h@d+5yMdLYUfz8LmQ|=*kA;fjkD%35Ufivn$v=fP)|%lnV;I zmHrDf5|i7b$jX0xKy7pG;qWSj*{nMc@K(hWI8c`CmxK#o;-$I)m`r@rDx=aZhF!4c z?;dtVbHT5A&~_?|v6xLG#F(WoRW<_Ua9VcVyWt3MM?u6gMzP*;ITfa0KLI>DQkr1< z_9&vJ0L8%W>*xDi1E?VRzStR_KumFcz)<8Qb^`)59gD*Ey`GCRNc z09Mx?kM{V&$aVuiV5Ei;!kXZgr$Zh>m|j(d2%cKaNoZppo8@ElF$VlZ_Xvj70rvo+ zYsCR2LeR_QguMN)vAHs92MvZ?T7jOeeqOAx{lR=^;Ln~9XaqBzVYTnS=ofZkY)KmizjHFjCit|tpzSc;((5)r3XdI& zAkE+h!-<Cv`31=NHJAFYL=7 z*>ZNJO)yksuCwVqC~dO~t8m^ZEVt6bgHNN`Kr8~L_vz#glX-K@CY|uh5_4qK+j=m% z!7~zH?QEW(+o_g=4AclM03IHU#yBMa0+g+0;y+0x?f}-;k)kiST2~chg5&WM6=wJo z)yk;f#M}uBU%8$}t3Sc){IeVjViGBGA_y9)n@i4Gh4A^6d$?IVVoWZE=zFvRInFF*TKi%(fookg)?moV2=!U8zFlTbqFBXXb`ijkiFk?|Czq|BTdec zgaU4x5F)I(h9g~c1aTj+tsU7=<1wK)Wv%GMqA_g zgx5?I$h%fGtcO!?0*MBO1%;|MY}{O=Y|@$pb30o{04b%pVXa3#bVwgsuE?FBt9L}R zmu_c27X0Br-=bQ5H^{vc6%{n}OIOd0rd2=rXslXc z?XbL3RCz;1MZ5zkK$w|JxabYP9WqPeD3*d?1))bOkpk7v1Y2nF3jRlS!O;l|_GDT8 zAYX_Hp%!34a}@$Ih(3(Xw@l(1M3uLMDcZ{ngSCQhURpFqcUzI1cDQf0NdRsTqN z{8AW6gnH5fEK^+1rcmP*&h@Ct!7}g0}&eiCtEz8x?$1AbsJXCfEGM!(@(rjjml*QHK=$s2HtluTGfVu)K z02m-};?)H(#Jtrm#bkXAqiii>d*XVNWN%6aiqI`&UDLW1NN&0OY3F_?4*y!(mBV{| z=r}FDw(s?@>0~8^!QnOw(q0jbKs1INns1FEo!mn3x%DM=*Z;N{4r}cxhpQPBXR!nNsZn-4A@K&%b zx|f}Z3uMg>ze90pJ@X^1aIETg|AvMN6{Xtev0I-+!DBuCy8><-@?$;RIG5x6hg*~_ zq#5jJm!tWVgKdDeupYA^hpY{KJZVJ;=oWTU`8tzd*QU?BPHrLtD z5E+(x6BN!NqONVztbu-PTeN_^c_JF|M6O;Nd#I zEQ@HCIc?#X;2kwyz8OcXo>_~7-(EaDQqlsSCY|36>2oLcf7htKF{?&yST`XOaJfJ5 zJ|U;})43!@W~qTc5-f{YqsPT+=WJ9fMQRcl-K*`|Lx$8A+;*n9XWUsf)2?o-hxW+% zj7m=(v_5Xf4-@YKCV0F;8TB5x_2h-}AnVhO-ftwDl}7M^W%Z2)#7PDayX)*2WxkD2 z_079YR)fR(fVzv-aj|glRI(+~BvX5YPSygX`^b6VHD-iC3&LStMJQ<*tnh@vnaO~M z%S=s`EXpjl=w9`zBqP?=pv!(_7Si`lMf|QacDXy&0k0{}sj%2FkA#sPWE<;j8WydX2B zfi=nXfp2djAN5IL)PK7!3e=2GDg{k1B4io&{bGq1M@ z70dnQ=yrM;^V?(P<0LUiQ(hMgU-2RVLmd+u@3+$(jdW73=k;-WpsP&(bQQ(_+f`X* zULAatQ~IFli$Rb*xQ-EL6`zP|cUQ-DSjgYDej~Xx&?w=R4ES|OS$BpgK#`DyL{ssY zyBUhuFJkD*u$Ey$O{CAdi?6k>Mo2Xxawq;4e-pszi-qUColiKbOM%;gecbwYkcuUe zAEc8JFu<}tBlDQC!296kqEODLPWs}M>%<#Gi78Smch)92q+8X$Z@1aazL)v)6= z+=LQyYwbtQRUoW0Nz1>{ve-eqHkp?iEAfGUO>p>E2@zI;m6w7*d*bf;pP#RNy_+sk zA1Q@YbTY?Rq(9o5KAKBVqJ`pPIsK|e{nL1_26JfSG|~7@v{pV8PBbAa%d7o7a0P`0 z(YdZ(#H2&1?SQ1y#;M~)PEt#gw3xaB$dxORAYVVrm&H#Snyf!zUf;dDe%cX*%;3d> z1tbs*xq|_$I9`(8=Y15qV;PkTHos&~1NFbYeav>VoGMOuCl<06SEK!DUr;Ntgvgb(`f=)d}zC*#zwJ$i6{mWM;_#bMb_rA4f zx*eQq()1@-&qA*hbHb-qIfvJhI;#>1uP2!XBH+H*RtXh(J!+;9b#dkRQ~x9}hUlCW zw^d0ja$I$5Xmyf+d&LpIj8%O2uHBJw#!S&>$3L;uJ{a)KAR_m=EwhRR%un8%Zj!}d z7C=nrx;&zyME(;Z9v5jT9C?yJE(pIT3Z&;YdB*!GYSded2}psjMdMB530IYsk4_w* zXxWutB}kL|CZ&CVkQqh8t7PM+CqyD%avlo5=WG%;em&5SQjr3)5B&Y9roVgf(+1MT zv*Sfa50&X&kRChbstUtfMdA`Bjb{CGkY5*X)aFhXIPF#i{6|!3?Ygb9_t2U$FE_Xo zs=jU}Nx8e=QodJZ2&BQ`Mkk3tM5WJtCu0Y^<#Jql*uz~9 zW?;l69X^XlcgG6|!?~D_J6wb?Y0#oD5(QqL&!4UOVZ!pje+hUIqEfKt`at17_!ipp zMO^bjrtzhnkKg{$VA9J_YaME}Kce z6=Wmc?QFdZ+t|x%Puw3;Xb&^90SiPxYV zd?O2zHyPlBiLNW&GnW8NTm=B5-E|HR3)`aUjUs*vzA_ta$7x5cpW||siL~RFoSRD^ z0LB{GGUnHAhcK93FdeG^2|^wbS=C$tSJ{#Hx(5ysz!Y3+6rdRS`QR2=Ty~ z06J}ar?~i{m>EZS!av9at!J(qu#@`mR6sC*%|Cd7>K^3%V$NIX^dKeFgR^{uH69YR z3uq)3QixP1*4&q>&E%_L_+^u^phnJsR8Sh?Tih0{5&0A*(YQPln7SlApC9fk9V?54 zin-ym6jDB27~A1~E*PcYM8YBPj7R8$urPvVC^R?LS=AimP8@Tnh{os7tmw7R;N~r& znlFSm6{=4HC6&*EHHE4z)=Sex$`l1!eepKQpXPWyL};%@4fd|#KC#6g-M{G=9vc>V zc!&Ch=VsBdyI=Oi_hDfb2tM2If1|GSn(zcU;-DO3G=~c*-_QofD?!$nC)?MbX>>9l zX->7kmK`AbO``nx0gc|>hAJuB;N)0uNIMvRy};X$?lNrvWbO=lY%fEJrh9&*(5)m9 zi?9=CU2yx}5d~-ZCQuKdA}7?&#p`?)CSTVyPB+y-o}P` zY4?2M`@&ppLxd}({J03#Rl;@de6qm?V;ufZQYGPmfZ)1PD0aAE=i{zH9i z6E_vgF|$(9*V-yqNFFcqS0mHTS9hlJ3VtzfkTZB_$G#g7L)CaUfzObVi&a8kRMdeX zKIn5kw7x;YDq(iwYDjRA2+Y|(9=81!9E%&yO$loMWrH&yi}sfM^d6&fW0xzFcOMCR zg#3>pM8E^a4%z~`IXM7dm?392;A=m|VPNn(kE*d=`_Fn51zlYP0J}a5T<(cXuQ`9u$#e1p=%wXnC2=U@w@P%x+hG&-n#t2t|v`0 z=tt^6>IuVF(U6_3?jpi{<~}_O6-&_dtQ&dT>7R{>-jsml z;eK+Bl~UP^t>%V=XY2yxp^;S4>&E#cVVaso(MQ+*Z6c-5=y{CU*9Tu9*}t6uPL@Hn zVwEp}6CC9J63l5+<_QcEK#9Iy6ghXG2+v;L2j^ZwB4E${f=Hx2MGZx=x?#rMflJio z=piFI)hUpI(ugKgikx?b>5#vW49@MYP1?!yEdPEl$SwTNh=19;vODyJnvw@q$INFy z7L8x=*+oZL^Jc+ES|v-wge;t(<|(x>-3qosxgfHr+PCjK*HylwfcH=eEe9y zVW06kk4cCP#`#@0TWAOt$?LMc)fNW-PQCEMa_Zm~Uwy zrhY1xMwES+bRRy3JFWamracE#ZfpFQ!v_UG@zK+LQ%C z^5H^7V-^8E|Eq~0C5{e%9?Y1&L7s$F9k*psM=@y-6#4!IiRcL{oVX=+_)Vm)wONJF zz{s}Ijc4gz7(mrDws0cfhx3fLg}4KJ(TWJvm1e6&SA_ z32E!NAqoCH*xAO=w{?DLFPma1^xFBYbSYF-|J7oXf$S`uw!lC=Co>}P-yZw()7%{P zyhdioH)6rV$^2lLR>Q%oIh6omc0W0&#-M>A^eq%Fr-Shvj|4vYYoEs}fiJ!;~4ZIc{JDrIK_VxNOpffqSyOP zGR_!C=pO4V{zth@2@3d$1Q25k!GB~ad&H-J4~Fsi-E0XlkZLQ)40C49=EeU=tfR4C zlla{fYO!3_B|Tn4ov;kPO4O8j8l0TpiCBn}gACf3)0CvzB>?0>Ca>Q!z0hm#X^qi0 z6qD3kPTBJOok4*tm8G15!nKH$mD(z{K7T5jz9kEll7O7}|5a1@kIS^ygO&S)Vk^0q zgew&}B+S;=pGd02Rr$Ty12n%9!Tmp~1PcA6VLx+A5(_W4->|E2iLs6ABYEg}~(fj1n&xcdSMlzr~^aS1i8Ib>qHT}osfR@XJX4ufpQU<$2 zC@E+l_c3mxZFW|5H>kZ%U~}@y)hwYqGwU1`o!clhn^~HH8T9@~^k)Jx-$6ZEX0_?) z42+7n^zZ?bj(M;PKU7J6*lR)R2?L0>bW- zlzdyYwcJuS6yBr_vlrYOY8N6JZBhVEz;mX=>~>uLsd$kC}QqE9fV zVxxRh-@Z;6|3CVOGyM1QfIxg{5K=2v_@cjL!c@!0>*jFYFKSo|A2D0Yj`N z?S!AIgXayN(()k%|E*szQ71>hWLM* z{WCX!IPta?`V*)jqyqjUafkurVTrK+XdHb1XdK4VDKd4q4=V#JsOl_d*Z~rqK@>GRMQCy-h7QevHHJwb z``?$Bq-((-bO%X>8w@T*;tz>{BiS)uYpmLZu4G@3yk5#6p6^{J;bJi-#HLnCT2@~| zIaRXLzdv=y^iVMb<{Ei*uq}0AP2Gh?%E{y_m`S6RPJwRNUw4%Dspcr10!MAT*E24u zcN{$}Pv-(ssp(kl{2?MZ@9b2wKuKyf&9<2_(N>{Zuse!C?G`mgk==7LyVThn~Q60fW>32L{fO1G!Hq(qx7lh1EC5 zdM(x(&ktuCpGuRTZmrr!i5_E3Hd5H%yt4bC*4VDk;4M^1wXxU_CzL0R)f$k#Ow!v! zchYoN8hSPjjXH;O3Y0VO4?28LZbdBC&9(4+)kU~I5`b>G-+}XJo!{g*-FNer?ISFSduM z$Aky|>7EdxFq=C-QnVzvNGAveNGhw9Q(d6BKux^J7EV^IDtyW5D*&CZhRc$(I_cSee811{`_9kVab9f4?yQ)p8nEVk(LGE;8KZ*0`_cSy=&eaT z4|VnO<+RBe`g`(MOH zzI5qOFLcK{BcYruST&vcC?366vT>=KZE{$#Dnb;uL9-gby z$Pu3F;#hJ^z3s|!a(jhVZT}@CA7C6_MO*Iql4Qt{#qxZ2#;E9D;OR@C4lf7j6RJLc zc6_>;NizUPC6{3+T|F=bHWegImuaVc<9|F2Jd=$p-BB87HAb`R{{@&JoEPP4)1g?v z&G4D*Oci9fr0)4!1ACIJmK!yjpRTo;sWCiimEYcy3N9_wSzA8t(*SBzK0rt24yf6b zB#)_w$3mx~ZJ=0VozomQ$HrFrlk{lgO@|KpS3fUEq`5e64vZxAW+2ffLO8NZy=?6F z_EA`4rmfWkM0lF}d)-Lu(j2QfY_JZQL=9hUjm%kY#q_)+zC8GRI$Zft^}(raSt(De zoJJFWsM19bs=Jp=OdrtJvyag56rAQnJwQD#FkJcox~*+t@Mki{bhME%ZeT4+EUgOf z1CoDQlt@2dkC`IA*Qwx$H#XMw^N7=(2d>8a2vP$>D@`SkK`bB4;8uTC)?8TmzvKWi z*?u{UJ+2U?wRb^LnvMJnooG8%q>m{f-p`3WH(3vx2X@NvytHx#t8zFHEj~~8Fpv9y z`F5!?9m2i?bS*S^cQGrLy{E3%6HQ2Y1f9+0pCzCHLGo z68(lEJwZlrZTZj{1 z3<%)pW9cYch~Gg#x8C`WZktj- zz62t2{ePUDWmHw$+qadF4(XJT4(XIqL^>s<8wu&&bO{J3jdXWQNq2(?(%lWx%{#Yx z&i{$=e0j%U@WI2;&01@&Ip=*}ziaj!HiO3to8e`>!xklAAdVY6zY{PHMc@hvrJ0!l zTtmA-5iSz}Uz9lQBuT*4ZuX9q*s8jaMulOcN1A0gmZd45@J*go^ut?o>A2gSeqTO| z)w|Ce#&=1lY&$jPcKZp;S?~8kj#`64S3lF@^)DQA_ax;0jGLb$?k(`*?tPkR(n}i^ zCw;tLwHDG^FWH}iySBp;*HfSRXvY!VUQ0&P4$6jXkfmTVz#^dIpw5j%;QOykzn*;v z`^b#5vf~rQ;M4cwmWGK|)%2d=y^RA|RD<3&l0Z_s^%sRjwY-+=g zV-qicC|czJgF1#H#VauLD?I`oT>y5JLO-=R?~SX+{nQ5R0iVo=2a;8za-%_OYMHOm zj#Dfq%hFBW#oE|KBsl%@lwHMUl)0vjI=9BzYi2#2IBF%RL^IvKQ|Yg)#XczaF`Z}& z*g8f+Dda$mHf9+7(n&JbMTNVTkTXKf|B5`XMzClGj^^@sw{o~oMNQjydY~*#6yed| zEtMq}6z&M6ZYGyiWhif`6te_dyD_~sok|lK`p53BD}HbxMSv|+0_zMsX9*6|p=hyC zJU)F8tK{kc5_eABIIYtbkrb077z^BO%&tlqez8DoyF)bA|e3(YochhmT*l^M8hu zbFsZKBY4RcbOmB+oksvC4X&qsB6xa{CPsqDgz=b`g=Lsd!B*~Shj5V=+GV%vL&$KbTz6(USG%Q zA}Z)#&2g{RYVJNYr=UG6p|glBjtLSU{G>*6W5u*w!dF`I)ml;G?x4SUEobSCVRyC8 z*`BiO5O34x)h-hg@IeI#1=m^VnbcWmNq@dRn>V&dINi~;>%ML7^X*i@MTuMUey~q^ zi>S0lTwA@1tQ6 zf%8Q(5`z2C;8-aEkxdwi{wlU`2V|?S|+nP1hMbgq`W2=Je*?zi(mZ+^0yeJ7twwn6G7EYU`M&0aebhJ@Yalt!X;U{=#g8G~GF z^tCnux<#)@Z1J*A#ff-2p2O{%9;+FR5sYi{J^LMm%Ff!lSMr{6g*l4VOyZr+GOUC! zCb*?yqi-xG@IzSCA1?ZV@CtNUU+KO(S#IKz`A9_HaV3oBi!3BBiyfultb$?$5Fn%z z(x@m*bU|rJFGw5UhWhmBANm|2gwV_!pa><6O)(YGE2*@k^W1*hDdCuSL?lPBeG0fi zy!@90o?`4Mgb&t!a!qJq^T^(S45le)QWHTz5iOfmc-w66%h(++Y0>^U-b!ZJw2uyq zi@Qs;We)b5!7UYNfl``c{xveeo}ur;xjOQa@$kiKG8@IDLdzc55Lbcg!=-dl zDYla<=$amzVH1-c;ys1T3lXVfHiXj2@1@6;3E=APIkY_|H^dpVl!E;>LQ`0t3#ACh zr>Bhe+`|!kah-b%>|y|iW?QvAuqlSfMNFW$lG@?K=O z=eGamEr=l3wZgBKt`Wina7&LI18F*J85b}gWn-EI_@RFB3D>+ zrC<0YpL03YeWZ%xPVkQlU^6qKi+-W(AX54n+qjXsTC1}|{qTzTRevXky`x?+<@B@&xyf`_Bh6p}N1|T5HwxfT4!|9j; zIlhI-SE&!ta_t=XVH?rD*3M#YwCrwgeAmWIX45?UmWf67M!Ku0uVOlkmw zOU{c!txkKmjPt~)4;K*&*TT!ooz|C%0>T;mj|9BZm>f}3gv&M+f`8<@fLprVah{q& zXiK9jan^Lnau!=fcPV%_X$Vrg(Kem9YVqMOie^*`CIkJg?k#(%zchOuESO1!(Zqos ze;(hojG1BfQTr;KA~I9%FUvLz)i}(L{3EPidzCqvJ`0)H4S)ApIMlDeN5hED7oT7(3TbZ#%4EJX7SY}6cbToHNrzPyTF&E z(!bOnr&BSYW@twj_h=w`wP?i1xW`GLgepwW&m?!=s_`}C?dE26qd)u6AkPBli$kPy zBTHWPEW_?_lVD+;zUOnUpeX2iwcvMzB_)R#h|um+5!X_onEe}Mk>i{_sCb|Jr~=Z7 z#mC2O{w_C`tbagwqBlg0LzdfpZ(RMEP;T&8v6_aCt4H}qPp4QUVJ|%kzU>c>%6oCS zdp$6Q;;g;iQa!J-B9BX%cvWqosFEY+rO_o=sbw;lKuR1w{fa@kgjv4%qHv*r%@Yr+ zg#$Z-?8(04Y$`#dpDsUD&n=m;ARuqfE*~4;Mrpimccz;M6F~K#8T5p*)uO;UYpxPfaT*mFyq(~vi6vV7OcX14KutUJow z(`NADyNQzIcRcr?xYVVM(8k(8xJO<4;=2nXi(EM0IsrEP-a=aYJ=>THyp&wN_cjf81GZG6=?Tj{@D0Lx?h-AijRIU}7=-uh zTKTHfYHqp;@=gm}YM$2~q5s+52m zNhMPp*Tu~XKJu5BMa}iK9?PTJJ+5JDxX&Z7(s+)ye$>)(^gPEXL zU%rZqq2B}Bj%A7RWN#$s_;ML;W6a};mGKj|#ifXHUP*_W&TRVw;ggncc2~W{MmvFA z#+Cz8dwUUh1Zy)1xg91vdvh;inP%uRQ?v*YksL)Wokrd4*4Fm2T?>oXikdrc#Uj2QP$Xi4(gJl*; zd^!T0Wk%6`k%nfG7WP_jy6-1sTn4I;<>vx_E<8k3I`Y8*rUSd{Wy_Hi95CL9ria!O-gyI`eW34esxqPd?URnALn;@oe5It({ z>U||1vZ&+hHJ_G|%qWrijX2mlzgNKS#&D8v+NhwFHUVih(uE6V(~=;d!1i{&RY%;iJbX0tuju^IBmd`H}Rgc z-Aj%^H6*z2khp0fr7Byoz2NA$v~ach8n0&=J~6v{Nwb%pwzDL2vTV|{YcPiX4UhEb zx{C4S&zY{kneopWl@on_nd?0b@k;w?w}t%)xz@BlEtDfSbmN~|H#ASvEesKTS3u`4 zOJ|C2lxn)?D_0t`_8?4!>m%|h8;+oJZ6R!q!%$|<)M<1x;R*?VGRX1g4n&LLNYi~j z6smac6uCxB-K@-CKI@1yb7#AumQurEd+*DmRh>uK$a`nDl98g=`&s4DPqX2v zK9*h4Zh9INzqF?9#4$K^FILG9;gJe)PsiWu7H&VIQQRmk9Uw^fGq;RkAqpUg<_l(E z6%gori@#}6^=x54@vMJ@PC|EhnT;nGKgcLmo@>;NT9oIvCyHeJjzuTKZsg7Hly(MP zR~@&>K?lne6{;DNUM%~CqaTbMJoaO%ZIxjv;bPtI)PchVn=<9!tXP&3WpT~o^OePh zadBL>d0w4QNe@tMQUg@G5_>jV8sBuT5vKpu0DEw%pk+Vl@UT-=UqFS!$QSkDL!5j? z56!L7`r;&8C6D|!jpXYcF0lf4yFcPHtnyEUvLa7-Yr~n6jw5DWCx(xfvc%Y=>k91V zx5BbC{Io7_MqSx=&+5wc3s8)QwTUF}SNMAaV=N4}OncN8>?t1!Z}{8xB$^4*uZztaGbOVjd*L+kdhe&vXt64fjEpbh+!sko*@gF{LDbd zW;bIgCPhGpq_?zxH@ncS!1Z<#Xx@2asv4uVFvaxdzUWEi;Vf0Xa}ga^O##b6L$jhz zLK$_<`=GB;(A74XXXGU7PsgKMmMX)>{?lx=njEEKbC1i-QCar=HRg8r^O?fNlYJdE z)n}LDUCos`La7zTE~N`@Y(hxU_%P6!!R{qO_)yR8&_qhwIshJR56~M(&n`oKFYm4~ z?k!3|$mP3+zq2O;78oOal`G)Blppt>d|NovjXoXhxDCBpdD3Oi6hmf`5T=wywF5$v zAIXI0jY1Rj%8P}WQ8Jl0nG~;)M3o(>Itojh3M65fM@&jVfL`+XyB}F1uB?xLvn3)< zP?*Sj1Bpdb<&$2uG;dcB*EDFEguToH0wlSEdr*dqjAeh$J(JT1;w}SO$f5Ww&pUCF}G+{=VYX6T>Kr+?xL%iC2Z`=HZUenavx4|>JwqNB)A_XA=SF_hgQ}}FF zGtKNCU08Mc9awV?u@Z$_TxD+uuav5W*w`I)d>YQzt}AS8?NXJ#g!doGK0r2c=T`Xs zUE{O9W57l!bL~c?VEb-uevxU#4P6RZK8az0?V{U*WCa%%eHSLCg~O$SkVs&)kev50KZB*~| zgomEzjF$wN@hw;=>>D1|hmAZ8lha&8BbLh+kx0*z28dp(kP0jI%^{R zje!fApns*o=?kB!*2N%rDPhQ}o=cwlhs}Wm4*0vd#Y7l1G`e?C@j!H_0ILdrG_S&m zh(=&S(yZ_N3)JirMhVz^>pZf+k9x#XLNRog?^3Ai;CR$UmPN5{4j*nCBOwLQ0MefC zH*Z7^p;{twO%}c2_l?rK{Zw@pEfe#nzW}#eWW#dktxuQ8mVQqCKOn@S@JM(KJoXs zJG#Y>coMs_+0lCaD0T)z_{IhTH=+9NvMwZa<|DW_Th|jpk<1DgYEEZr7ZW7!#o$p?GPZgdne`wiQu)8{~naQZXtvL{RJvK^FTTumMV5UH#3 zjaVw#ndh$b+GVCIRp>#J^)6@cIES{-cI@V5x%p3qQ4QEX_)%|o|8NtR#dwE_(7sjQ zOYtz~Ndy!N^@=TyfqAm%`ecxwgw`TPNVqNIGabC)Jt)^Uz35-H9fCc^y!e-Ame<|Z zb-~NxwxlcZH`O3_BYs&M7rczn=rwm~y5a=V(=t_7(md*TFB?)cOoC3uJs!W*hzt3d z7xT4ed$H9|mS8%3e<+jkGvObW;L|D4uQiIW%|tQVbrG5p1U$TP5(FY1B9auw310hY7N#7R!yX7kz#Qyy`|%?bLp&*fg>^7XkT|IRPv@ zki#L+I`D%q&-_M-gfn}d#z=vs+82w!_`C=~?&vMK$S`Mk-~}Lq#Hl{uyBK@-f1Ed()A7V!GW;*x`P9G z_Oxr>27lB|hS~k5ZS*NMO^Xs)YxPg_oP&jmA;FPf`bHn#u25f}NkympB~25kpH$!o2>1{F>)b9 zv`%sLv(#<6*+6e=Wg08D17|I~*8BGXlbHMQ^x85E%7?eS>{}N>aDCVh)oZo~+!fqf z+#W4Aom<7hP^aUxAG7RounxGQYC5@k-GfGkd&N#kJ@QRU`crglQ>w)58IKb7UY3xv zh-;U=87J^79CZT1+(2xT#RDr8#D@ee{4CM5Uv3{oaW=?XXQ zc;M*6I$15ifAxlArNR`oPWRTVanf$ldIdZ;1pTJAG6`yQ06RcR!oZFcai#DEo}_d* zY9xq48!|d}+2$*F0wKiai0xs-_7~||>7PVw;TCBhmr$~@Vbk=sbjZ*q*}SyvtxbiK zXrX<0aTu^h1NYu?(f#uut%-sV)O|7NWtTaC&(PD?z1EsZ_0SroOu1pZfU&{(3NgU` zlky>V`ZA5OLHqf43FafFw-_A=_p_h#l!%1BthnbKn7v;01?eU;e93O1ft~Orq1^d z{Ur53w8hbdoW`Vu3N=0qCl*&>ND=yvw8-iW#4|^c7K31VW9WZ;RMaBiZ@}^%poIPq z_#)Sa1D#^V)`;Jis233`F*?lrQ&j-pjRL)`;kEu6OAMP#3~;%PG7OqP|OoKlqmS1(IXXx4IF9WGU=UZsrgiC4w@r!m%_MT}|w zYz6=KcS71l&4;<|ay|#9qEV;yOWAQeMjr+>Usn!02f1ymTn91><_{1HiC1xe;pV}`1e-_B?uteFi@fU zul$aA3^wu5TY@+1ib(kIzzksvo~b@XaZ+PsA^{hhD-ObPl(Cf6{b`p+6eLh~x zCkA{}Hc*=gSUs(Rntv3CV8)8VYzeMHa~r@B$q0mFNLk*D&u$Y;Q{I_qpYn(N2g@<0 zVcPw5d=;^;1m)@V@D}%~XNKsKpqh{b0oMxG>MSK>{zj(-59fCv`C&O*s|Zv}EUw%6 zxvQWlAwykf#NVh!9a`_z_`@Xtjg(*6e4@mP#>ExjMU5H%QR;vZc8|XPvwK4}5*iiDE{`7Pp7WwR8VS#Qz zVIgT!aJmA*6`tas zrT_}f$l~g0DL_)Z4!Qnk>^Q>Q;o6ip=s%28E9+&_hsO`ldx^l2R7HX=x;K^|rRBDj z{pe}5wL+U>AHL5Y<>-scM0!BF4(N=*!0Q&H!DvRWz1{T3;8 z1?;M#pk<32N6lp17Yh6oHN*Bf`>EnjTs!D~DaQHw!e~@mCTO$)*Li1%$-?GH<{GG; ze+C4_cuB=BNa#aDBD9vk{!wAniPlONu zE2Z>_{38)CX!C#RgHh{sTdjXtdem}^88U@Y1sgcO6vsq7+(0M+qamjU+Je6NvQS@* zB2*E=(jW2RCvZacz&)%*@GjD-V_(yEa1wkY89@>KmvS+7s&63k%8}oNt}Vqc1D!YM zbCa;tvJsxRi10h_TNd?!i1;oga&7(oxBg)04x$$nh<7aw=@_H!3EJjz<;fDbEL0!w zl*;5fGwhT{_TBD${`lhG(N6t}oJWE0kLP15shPg|<{bY`58n=v2}|fyGhZxOw3`XU zB29|zF_IC_L)4fT?Oyw{byFVXMS@^Jzea3{h|CA-}@RR zSp|Rr%08Z50ApobY5u9p#x#iU`5f?E=mn^duKHuku}XtQ>B(D+ zQtAU;7KYyuFzA%{Lku|WNQ%bNn1I29?_EOlY!_pB z=3PYRT{oaGiq(a{)<|ZMZNVJy$#9?t3u0$uen^>&k{6ol=r}}YDSQZJ zQ35jFgk$-qrU>&|Gy(oaR^yPb5=>UoAP|EpjH(E{GRiN#JP#i_08x?K_%Rq;(O{nX zZchd)nZ|^*302OOQWeRw+O_~ZH(nm0?U; zwckmTj;e*MKQ97iTaGXJHEN>H@vq7bBO&+Q@*ojKUy6$|-YZ}?Sqs3|k)TgxJt!p~ zzK>>DZNwx<#8?o*tm-$BE!q#lW2eWBkY>kNwrXr2s;<=Z%V{k?^UWAFxVinxmowASsrVTZ{FQb#fsYyENft_N9>x|1jQ(do8n zHtm-I!_PEr&@uQo$&c@R?~9E{CH3cZU!>kUX}6ak)ZJALl->9?d9}|Azx8t8I=_-P zhM{W+qKKawiv`9P{>1nIzRx0;81N);!;}|Meqh$gf8{IexxesN6#~E(+j~-vlabD= zbTs$dCCs+jW+Y73_}}XmK=KI!7b7p7@)1f#0wf(VU44Fv61tKyuQVNw1!@Omlk~p9 zL0r0u6v&a}7T~C6DF&1H-h6K_P^vOlF_nNj@`3-r%#YKCzVil8a9<~V)bCkh0y(Jeo(n^}4F-7_1(E5UA0iIJ z)$Tp0QA120b2p~K=x<$sR|sD>YQGhoz#&Nh%!3WGSZVO^aUn-X2;bF8oPpb;C~zOD zOeZ4pX@{)yRV&NpHBZ5HcNcEwsr804i1qPD`L}!-$D_+tNt3ZZnD8JNNi#^zmC2pp zuZ#2C*LC=mv7%rMppBf{4}|izMK0Cpdyx_uwRhmw1aEi#QA~j;;1QJ4zxR9^5BLHh z0xZUXH0jX`@1^;01pkN#fERQG#SJlY>N%Lf=9r4hH!&+f(qH&*&FF`joPP!0E7ij{ zK5g4w#MYdN3S$5)U^T!SMLGGfh# zIWy$uO2TmGB`tEBjTHn|%V^Nswiwrn6saSBkc|?UJ0sM8_z+DDXP-=6vgPwPDQJia zyx^Jq=I@=JsCRR~g@{W~26#^;tjd2{GIes&ADwZoQ$DPom*a^hwU^^n)~+{~}7BUz!T2WXC8iA{BoD?tK}Kv&NO4mGz?5hV$u zoqZ25q%0XdKGZVK!=fz2CAK*BHC+MU2=umrFP^#9=gMZ zXzQM*Gne!ToQHE9W%^`HkJun;@Ua5W;6(-;z`e_P*N6?YfPT|A{Gmi5x79!e=Uwpj zT{Bo#%K`za`4R%>hs`p92K?Fas{B=aZVv`ya&(AaLB-=_toNWN*3bOB@16~{V0ht+usxG~57h|@^DOx%>2{DiBhPr-uJ*t(l3O&JMn1(d#OJBio^e=()?mLN2Yw*j zdzI(P|H=2`a!IVn-jn3SnpP~+@O=Une9ugG#1?f+~NuGc)E@+ z`U75pZkvuD42tvjWm)J93PM0SGDj7J!Pkrh-VH~rQ-L9J2AMNwSjl`~A)15aE6-bN zuYmOXVJtmG`i5$EE8fbod(E@?i$)rM{VGU>Xuh)Ss@o&2goJefZ~SY#atoeAczu;6$vBW?K=Idkm6w?K?Lp|4uBw$4}vP_ zD7>SzgasXcW=YWIvkK{>yd@oJ^$#z0^#c?enls$)+<#8VtAE-NW&&Ng`18_r#kX-# zQ5m!rmg83T@%hPj(NJYv&+pJUGjN$$!zBm0%rDNjem6xO?Z|s{dK`*WG7AQwlgG_$ zv$^8OVEGX2dhJ5nb{#Lp+2*(S|Mf|!_U`ZUlNC?4uHWNs#i#(_?-#P@-%Z_i0@j;j z=$;2ODOf6&*>3Bv9Q^_w&_G;(U~k#&-Ci*1Ec`uy4doQT$}Z`YmGMHMO(7fzvlG(E z%O3fAeU=YN2xFlWCfz5>8Uh9);|zqkeuT6xpEqU_I3aR_QDB5I!YL`XMXwt&qn!&2 zHJxT&0q5MWFi-_(hJPuE$VgJvCKvl8ir_^WxgvBh9bJ|>B0~pL(3W^<|BOTs`{5Wq_Vq~+~T(j29b!+U0F%!!Zki= zmqNzY$6hC$Gk&I@Cl`B%WfQuS*Apcu{~U_|9Yw#dO<2WHJReG>`m`vg{%81RLa=7x zL=)cA@38b#M8@%8I85~AuMLtggH>Fqi`#x$0u}`O+C$udHhO1#H<7Y!57vlHi2QU3 zf!bhEqFyoc^*6$r0Vhv4*7v$EiNdLed^|;lpeGk}f=!|iyGR=6>^)S-Ez!0SqYK82 zwJX70UIvHNPIaRIsLhhXd%K%Vf<-#re5#Y6w3{HZX9DCta4o=@KDy>Y|E2dUnC4mr z1)_XCrMS;e#lI{7n>J@{k5Z6hM%3uOQNM$mv)Ju?^Rz0Qu=)!ctbx^iYDFzC{e9h1 zezt!~L>0l{_?3slcy1+N9x+eaaXy%zv&=-A>aZpwjQy{P0JlAmwLLNJRqrt4y^+4+;pk0z z%gGlpv}-GbmC}Zz5Sk^xPm#Zb@k~wK&uGtzIJy&F{_qs;j`LP3S1wrw>tX)7qn zh;TVlqTt{XOR>b{)T>poNnm(i-+h^g1oQ+yrja$m90s{2;?GE{9Vs#A;-LFV?W;zw zy_Sxi^NMA212JpN&y2$Ns)n3$=YVe*dfiK8bWP71`(K9f5x2Hm3rs<_wr_ zD9c`JHo8?g>`kixP-sP6xHVUTJpt$}E8SbXA9j__EO&+`m)+bz#Pb70I1%-Y5eNZ- zdFkC+q=gxc*3UI#DhKqwgP2cd^m(J-U*xr7!v4>G<6#)g0zKx1@FiGG41Sv+8&EYv z!I6)DhtmFWv3_g6{=msZ;^*&n$Q$j~t;5eyKrz@~tchU$VL#7_)K1VmsAS;r+`zvZ zIjk{#DoQ|e?A>CHJ`uqjpU*wTSGHo83@u_e56kl;mTmdX-tY6HlJbuUh+@uz{{Jzm zbN8?5z$1}Vjzf(#HQ$`>GMqiKqzxEC*yU760aif>bg=eYPKp#2}Nv$Vv`Z5AQ z*XP&eqtwFqTKHJ)_+A{}^Bh4~{x-eK9IL$N`?c*C+nrgkHl)7Jm!K;3!OT|?RfjY> zLC%^1{~CMsPD~SK1NEFfh19HO+0EMkdw{j*Nr-IeQtsRLlRGQ}w}p<2|H$YoVnpO* zB$s7O3o13*%(p-s>RcelNz_96Cx48ac0!GXWB$OqN(+kbV|0m z6e-Ny!caXG%`pL+!K(})HTNl^OdEbgmkafP4u5NRrU|5YsYk!o6tw#aj3%eIMc0yK zowozARpg|UxGUo0w$$qx`k%XeKJ9>GxnZSjBG{Qr;j4%q%&WKMH)Th z1^Yl+g1}(Hy+*3hEk)YKM}Qk6$WIe8Zw$w1cVc_PG;O0Wo&IJVk9h{&zBG5|&M~gt z>hI>i2ggVG#B~3gEn-39hlstu{X)T_vyUDwofOc?d(Wi8k3GvW32+UhCwhEu*dY>!^T(OYwVmW;R9N zakTJoVoozmd}b+6Tf*G3$MC{9u$>QZGR-z;plKCDeMD()md+OpH@i1CT{WX%BuFv( z9&ti6EbP!Vu6KUzq$CP@QZoLuY z{CM611V!ZYAfnY^bEpsY?jBJj2Ici_TKD>wVwZPlZufL)J4pKE zGUoY$q;^t7ywcs5YV{nzqVXee!O_;)6oT8BCwF3RzsjadIMryk!Xg`}=b6ul-4Z@c zmik|h^XCW5iN*HTrR=%1W49W@-#34BxF0{^G-l8g)t z6=ukTg9U|)_WDVP{3cOcF1+Ke|NplIHS+BfO0<(V7X1(0QR+I*us55$Kd z{X+}1t);4A9FxIX^Q-4+L_FxF%~_e#!^noW@NFa+f^C2hhd~FTJ;;x6)m?F&BWpWN z8JmC#H5VX`da}F=Sv)M7@BOQFH@rO6CV@BJcwEa~wz30DIvyCl;=u_WQy)qAe$3hr z3*zEd%-Z!QfE4Txkcj1nC+n~p0Ais5;1?bM17d;chnlja7}mqbn7_Zw*x`OKF2+-* z>*aA9Zqln-aMf|rD7CCbY999)`M~3`YFd^D6rTXIyOAe|+0ra{pHAp5I2_D3_D)o0 ztJ;8wdKC+a!(^7xi0XlK85{Vw3stZJ7#3e1q^55rqK+ltYJdn7vl_Rq z`(D-9&qAs{zmo9qvGD1`A-)$?C8?l`)R*Kqu95R5S5A!iEoc!9y6qI3LfLL8U-AVy zJ)1Q*+k$#UBB|44D+YUEarKueulw7*ZXawp-gGlvNapm`%IQco;s@{FUm~NlpL8Co znPKDEjGE_8QmfjyB4YDTE)^Bq5SW8GeE@V>4A?RtqDZuleeB?%AyAG9Eqh!s;Ka8d zspfu_#)XO4=oOe_ZT=C1Z}n526xc(29B0(d|NZ&Do}FE9C~=jL6*aRoT^LxDzt)Bp zJD?%cH=3Fj3gpnHO%6DMXZ?pXOVzIwk28(tKBq>n`@6vOaXG+HHM*AoNx<|Y3p=LW z$gJtDsO>D)zqba{Cr6$<3MSlyO~1{-52H50b4J~OR84AoN?s~3^@uS}Hh&lQ8BB5T z1JU^9qtyEw+9z37k1>5zUq3j1&;#}k1K@fkd^?TFvfevS9iP7&qg5F~0_)-oiA!#f zHnRsl0=yXS(-{yjdcQ&fOz1Qv-ZM7sXiwK>0Ax1+C0)U%=SW1r^MD#es*1p~&^Z9@ zTrP*~n&+~Z7jeH5f&26I1=puK!CX@zQnoO`JZD^np2_qM8M)4EF5t4??M$9|HArbV z+Uq&_luHtPB5Ocu`@S#4h~ z=?WQGEq+;}LJfN2mUqfm0noq1FJFiNRJNc_+v4{KP3qNXrZ`4r|Fim6*XuxrWp)dM z*&M*duKRVcuOk>clcGTEIWjTtv=E4)ps~n7>eejwfsWlM5S7s2f?X@P=<5%uaSY^k ze!RD46wsDWJZR!IpD`YSajq?i7i?RWWs|JNUnQvuOC{6KQeNgQa&u`3-0&s=xT1vXgX|TPcLFbSBog*wAPy42u2vw1t)BMrye^I9)Flaun>CaR;Jn zKl7vOJ!iweo)0(t;ORIGHCO`g6K7fJMu&4vEGRG@mLlZn69A{NFYL)jFdS1gQcu%Mkas!SH@I1;m9my0YrcoE+6&JeNd|EF@C=mC! zMBnt%1lHuPZZ%RmLpCt$eOc?Hb>LSn)Bh<)rXs^gNe=VpYcNuT2A+hun4WIY9960k zLe1i+(^Mrj6ejmOm>k3HiE6SkZI&5UL>b1C?*QkaVNqNq1I!(_X=ce^Zx|kvz>(Rs zJRDI#jSD=vVA%qVpD9q6)3#Y=?+s=RX)un{9%n#G1^Q}x5ImyFVaEU9XS9(CAHW=v zP;0b?KTNyB&7uoEH$w&I(lt#&8&od`LDtzSCQveb!1ZB^28Ufc8qb(w8>wx_V-pZW zuekmt3yM>4wJXiQaXj6NwYgi5k9?Nt?}x_14^Cv^21AywwGIWj#-gOIYv}cs>Ck26 zlu6>$aZp7RP95Fu4S!UM!v*`ROFVoXyJh5B%sba;veL|I;?x!r`vHAuKc{lh7X=S@ zsH*j}{WADy9N+o&LjQfT{U=?%UPh0U36^u){SCTPU6&>Jb`QQ#%ZgqaZo>1#3;W#2 zo0p?%N`ax+cK5cf{sPTME}q}qjI>So?zJ`2Zz_bmL`%ukyu1?5Zp0-q>g^`@o3=1- zzVWRQ&)n@UMF^e|yb!a4o+i~BclYH@i^_8kMdK=pzqg9=`!1ppk#ES$?40VZA^$$h zJl8wq^_PQ>GD;!sQhVS@EgQFXxWL5GfFifr=l4+dV;u~okDeFXwl9V5gvO(oD4}46 zJ>W!M_wg{5mwm}F-1d)~hBm~l#x;J7oR~gnmqP2uF51M@c|?z3tVGnB(W}<9R0<#3 z@bB$9(?(W(+XMRjR>|}tF&3OJd-TLp>reP76diXGr!D!3~8sLnmGka zrf(igD;ZJXt-eq^O-)8T7sMr$#HV4NpFLY}%e%#0@OeI_IQ!o@^qA_?G|c<;=f0%o zd@BLzU)xZ%zl36>TsX0@>j;_1v?-9xbJmm{W*i3zfb!#n!FH1CGJaE{eWZ3h=u z_CUAq>n++9Ns}@6KIihVD$h-Hg-3ra)JSxJmj;n(yK3~fK6_N?Li+h2xmlMmn#>exepIhTZFJ|~x#yqNL+FI>d|QP2 zOfO2Yb$E}kAjfra9?@>LYs715yufRg#f&9Qb{|lsC78rsnRFC(;(91wAfCNOo2{bm zh&T(50T%1yF>mcJtMs?`Oe%O&f0PX#`n%f$uNpGjLnMtpgKCKE$1Om4g|*o~+!_0d z^`+^@(NXQazfkkb)YO>jsz{f2!}kIgD%Y398qolDrC@WH4)my^)Z z!Ues-7k7w1ua`b*9e}a+h%(F)O(7YN0<&tvDIU+3iHzTt)>uBhSa?a$x1rfI)so;f z1bVYQM>}9ya^n0`!xRw-PaiSaKqn3K!cO^rX^GGYM{EC*e4sTiDZTCINYvJkknHFm zr$QqlftC9}Zvjm576d6o_~C-ca!nx|Ngv2wHmSpm)2=b05Tg5?688xP{#>Qzt#@9g z@v)h?!!q6m&ySVgAyOP?(sabITiuP;tiWZxz+6S-k+v3dp}aS~R?+h)e~bsH2m6!d zhClXc9>;E+?nGZ|5LE+#P9l&Q%+YiPX}v{~P0eW#*cVP8F8%)dMHC8NM8kf%o5wX; zi52_O_IDgI(L&yDYDZ|-3{62JYS(eGtsJN0+c;U|-qq_84DX*!Z`@WwTJOolJwHgV zl&Uc{7Js_?yMp&dg7QOY?mh~GP=kVH z`bWl7y99BMP0oGrW*-Sv%XT%mUFFYPV~Qc**O0s=%-DvcC<2=8BE9G+j5qxTx{0dD zS1*&YN9JAl5|$nXJ%p(7GP<%&zXGM`=OJNGnm1JumTh>lbfn>Y&bd&V`S0xxZy2& zp1V;L=l)R7i+Y)H;lnUfih2?oNoA7%A)~2woN~@V(4ZPk`q%vYd`T%Kob_CmX~jvs zRAHPzM;x^niP;wp0%3`ptscP<2g4P6fuk3W&tfp}i0BrR?8=n|+U8bC*OtpztnW%1 zr23tIRTT+6#2Lu$s1aF9`lahDo&9e2&|Iro(yHSnzW(OBI(HSNw{0&+U{u5f6nnvU`7xUSqfkzGZJWSgGra+uSMxSHZFg;ysO^YW&hj( zkFTZIEMtiF!QRVjQ(VbYC z`)k754aVAr8t=~W#BgT$M9ri@XkHIkx%0e@C}ou{No-9{2$-`M>fKJg(|}}9@MQQv zJhC;bM!RS7!Orqe&A?|}jQp4ib+9nuaw3)`7wR(~%g=->swinVl7gPlK@2hB3nk(A zaz&OBqP>t!Hw+%;(;Wv_(yMal+wr>}pqkEqt@R)Z_B;KW+Iy@=(bfY>Jria)HgYzr z&EH?5)D31Bb6tiJaWNG1gX{97xLd7kcO@V;Rd}~MqFVuz1)EV|pty#7ykpL8pQB3Fg^~{z^X=`nlqOB>>)n z>(b(1ZW9Y_>d<`9EEw$(qD4h=fVyDnewy`uM}j0qM?HS}dU9@6#XOHrii?TyLVr+I zO5tT)989zg2(y(d64LkvXhg2|ve4h#>C;sviQ!|zux3#|lQD0dun)vr@nV*I7_efu z@jN&^L!8XxD=1WmW-R5B_}L)~^}TwyZ2}iI(VD8T2=*pn2SW{mha{%1tyCE5mR-hx zs$e-XghCbFnMU(Np;M$TG`~FFWcNPh^!QTo zA@SeqWtDjRF%_X%AhnrdB4RlE$MHhVkakdxOEp zo>{1GeP(d zv}|NNIrU9JaQx#sblnE+N(~+Wkycm|i5I8>tb-GZsS01U9`)nnh|}f%KhnN3AgZlx zTTzr0C8R-Ax;q60k#0!|5h;ET0(vL&ta&Maa;r4ACGs`F9FSz0 z1I94E+t<#c%fx$PfAiT5p=#%vp|fl&NF z@rCq?Wg5f4r@f26hS9<}K$B0lb@JdJeYjhoeWCO_Hx-BRI-dk!Fd?Fp;k7(5F-2ThH4&i`8W zU%O!ZhJ}V|q@qiubGh!b%2xo5sGG@L?D7yv3ft|8-zc?^38ReiOnQOZY_=C(`o^UT zX|MYv^*9az@G}u+SSz&N;(*uogjsl_VyI_pwk7L39{-McRETpAa2oIS%(GbT34Q-+U2=8-_CCEpp76A>Hcl#9lL-myj7m$h&0b@wjo&Xw zPIui4u&AwJDg*(T{PmsPic>)mbmDzDH@c$%7}rf-DW&mUoT|H?)Q`!h+UIuc8qY7U zRMH^&Se@ozT~Cs=hMLSh5JC~2TpTAKDk&h|dBt9sly#dZ(NjXsjwXY~0>Kdd>L{#ndgg50z{b z8T)r4rC6ip82n6?j5baPtg+oZ{lq1tCeu2Qn_&in_D;sxzoyswcacd;$M#OUaiCQ& zy8>l-+k;rRhEpfDGYiJ9+L{5lPsT|E@wAFwk<&!%-4W%q$Bce~e@;IRZ}~m*Z3;`Q z7s;|g)`*a~Wjy*&2@_gfE@2F#31pXE;NI#;w;oPyhWCE9@UNQr9w^pYbqm?IY(E;# zPb76m%@x@qHRpynn6O#`;j4T?m0@w++9qr)bMm5b0hESoRZ+1zpK9w;K(3a*ayh5l z&hBpEtCVYEMqT9Xl*_F^Ms{|>$TA&2KFT}|)S?Zeo|+haX;pv`;FV7ZyLEmoe>?|#U)oeR5j?TiK{G-ueHR+)?-h~gN?;K+tq;rzQCyAgq@-`9Z`a4P3H?!b|w?0m%I z==p7Ry@2b&w0%z1=fptpYc1(dtF zPb$GP8aDM@R`Ao?VQaxT;^TOZmg1h`Z~He+}xf zt|)weSzr87?oQ~`wuV-pwl0!lp}bn}RDXj~54qGOr#HvSE}mqq-r$duZ#G_}G_tU{ znx2jIoNnOTSaDJU1?zl8m*50xqBw4rgQeuA#9#2>;>0M~i6m03m2eXTb{QdI_7?4rm`rCoM2Y#%j=UB(@?NK3#fiIC- zK_aOc^{*E@UnJ;-n{LQjUtA^xB+l)KP#_Gs)B{8$FF?d=8vCVefN|$iTr_CZlq&Z5 z*DIv!5=CGX>C%d8B7_N_##R>a7V>u-eC)eD5Q+8k*ji3T!}`Ygp$OGm-tBiH^e$F! zp{RSrSbJ=6h>8=);SL2alLT_MrbABVIC;%xqN#YbwEkeC|NVt3HAWtZ-L6YYOV425 zrxmX5f*k84n86n%PK*5<#f0Y*y@R76-0Dr5%h9TN|NWoOfmSy{*+Q=*fxOY4AGL3E zjlFGhOisoXl{PB$SBI*sMR^OIKO%p2pv_UqY>Q7gRAU1FwVZz%xwrR6u-|Jn)f#`$ zuwn$s!7r3H_9pZxzUEXZ(OI=uR@saLA#*RlX)M9hV2I@bU{|WU-V{9w_QG0_f4V=S zEeIIDvIGI^M7O=KG8)U&i2!hxKYx>dz4=0~`|gA@htwXQ46gH~_&FL6Ec~J2Y1hxMX>Ng5PTaS9T5Yex&Yd2lV^Cd0+qF{QvDH$fWv-uVo>@O?^~2F!u&QX1T|9K2gf<{21|9_e3u#yeK})+daj0Z+D>oDtW1y7TqT+T*F}8Y_}dF111G9^3I@AXHd^V6R-uup5q06181={EyNZ!<*f_AK6#5k;6%%S&&NO*{bvwzS= zYV=Y!^_*1?scQ$>W*+^fT^__)IWwvVNV|aJJd6MR5lDGYje^$Z{ob*8BNK4^as0nu6lQnzodhkwn=t=~TxP8Thu_|pSGc(uwSfDL>pC&@;BO6F-e&AlEVA0*rWqq%Fd_8}j@ zI+(xyRe%*#sUiNkH#g#IO9$mybtRba)^sc~{9c}+Po~im#Z3UQN zDBI~S+w_Q3_xfeBrAlCvr92hnCSC`2xl+z1AY?E|QT&eFbbkK{y%>X_E0Q3_1&Z`f zR(h-ST^NjD-HM+Sx{@a%=6o97>i(iNbRgO}ZC?Ee+A@A7no?LZ#p;JN&$51EwtNZ& z(3@B9aB;C1^pJUko^nMReLaajzcyQ(>h?j6hZyfS;54WKnmIw+;LC)$ZL zoMUYTo-U<<6}UU`P`K*z70P&E1#I#6%V8v92(b&=$-Pzh z=d`N8fndjoymNLjyLP;h8+kE>e~ixeioB2r?A2qn>jpp-;dG1JN*l0>YraJHuNH$L z=7p7`ED5n;)Q$4=fJfxK%~Ynka}O}OOF^tfvOU-QCP9X$i8=4y9aWTBlC_!p!Mf#S z>fUXlLC>ydxA8gW!vg0?WZ&L_y5HNbK$TX{cy-r`=vsZ2^~)C%>rfqww+1 zEPSb$NU97+#LPN*?W{lLD${H{=2&k-4Z? z%ANkOv0-r8?Ti~6|Jt-#S0i{Z_@6l3{JeT~*7IFk=mU#mKBsH7@EQlnRHH5b*Hb%h z9kI|xVvSHbyY}NZYyj3Qx}9GjF7W{XB5|;|0EwFOGfsw_cmKI)FQJR3lQ%NF#EX=q zZt!bJihAn(@M`L{;dpKnJYLzk%kh15v#(~<_@0i>YU zlrW%KW4e+|G6v{KFf}$<;3$J?{ckc7>U&pvSb`kFI(cNndEV}}Dm8o#CP7`eQS)ph z{w`Hk!LpIMr)9HbxJ2w#p{_>|f;fcmc>RVx3XqHq*=MqmnyL`VSWPmNb_;{4E9Ddz zMGuY_FI_$)_~rNM^oA^zQLmu=;0VTg`oX{ zfs?DIeqxQTMbseoK`o}%)&$vByG)izi~!Ei0?tyVXML=?eejPFS0w;<(s&Vf0l?%# z2SzmqN7r3|dN>Jy6?M5IZUz#bIe>BjGJ0v8d?=J0%B^)CRo`hPOu?o|_9MTELYR?-+mrHgdI8HAhKiiSb|6sQ$x1oNDmb{s)+4wn4NFa`@!^}K-M0x)G^L& z4k7g)#NmBq$sry%H_7YZ0Pl2dzl+E5UYO0;%jsH}yT@lAY#YGzit$8o^3)4ONs@=(!t9URYk_ddgWkD>Byg`ybdwBaRq-XBX z7kSmMe#|$cft&pBJh2|i*XGowuHR!P`bpJ6Vn?^Z$&y>*y%S8A2-KtD&IUm3W12-v>soK^g_MY4dRj)HZ== zLDFv0Yi#9_6yG0c$)S4plAg8Wc@X6L#tvovZeTVGbcn;kd#D@7ry}bmEt#w8q-foc zLBD1GLzn1Ce0G2+tP*wE0(DhT^gYPFQpvYJ894W@$_0cu>0JsVOX;km?2yww<`7^Ut~2_4Ko>4qh*;yX_Z)I@#T9R$?PxXlz+1;%4%5=Wi$i&rzE z;N9%iWW)r&y3e3V*heu@FOuQ-Zl@^_8;MT?*vL6OOQf77No;5nm}dYgraPpD{zxvb zBdsEVbnLUvwc`_TyxYXw(y53ob1f_$2i-=s+LkCqbx{!~`-v2gT3oT;seuEbMQ#fy z0ZiHJ-E5A!1P_dnzLA~Ss74BPK;XM=?UDq`(XJm^`0WH4NmbKUft|Mc^T}Zr-XQ=y zf-ybyllx_-r@8vKKuB)Oqs1w^U$jRx0W(+o{>L)ke}OB+_0>MX@R^Q@RSQ`)-tJ`h zCLddxY7rM(CUaoYPHKj${bEx7GP!y34PBd0z@EhMO)s_~-szDn3mG=KIkF<3CoU0URxo_!GluMgEQ(2W^YmB6^V?5o+ zw5t;0>q5aYsSohrtsM!w+FcQ7(9&=en`uR>B<|9#d8E!N&pt{cHl_0%v9taUFBw+& z+JByPl=+jr+YDUQ(G&Ek6mz5HImKB1xBp-h6*|yqGqBZ2vn2N+W2d(~%+s)syO?&V zcs>fxh~-GjlEr5~aV`ix&~WlG4nYByqKxN|9;N?ERsEH+Y6z`x?NJTHhlZhWVc8RO~hf`&!0I zr_}8~ZHzni@QC8$FPXK>T`VuPRxRwWHg4mQ^?B8B=53#id^<3wVmri8{b*w&{kP_euw3+g}Fe>Bp+z|po{zP577t*L}T;K-$bL*KZ!>0K+II`+xb>( z)Sxm%7BtPa3}=!UTLRG&L&uD!vaGc6`mYmweRLa;;3l&1$7W58oN4UaXDnF=25wDO z9FbJ?(X(s=JZ7h^hta{xQ!iVnUbFR`eZA1v6-fl;|zYD=ZyYhonVMMVN0TbvOFKgFye?gwk&@b?;c6}w*RFWh#_ZQm!g zrSIYuRCM_{kg@%J-zFfZxY|p{ci=?k=WeiWPKpt)_$#j2CZM=9;u|WHC{-&suC)Og zFexMwzh=Fx8&Bdn(6m)Z5ZiXMm51zq@7j98){roqoA>4Blb1I%7eQkbIy%qV6B&$g z&DhNNFj=|m_=CrGU}m!Ptrfr~TDb2-{ij?r#7JN?w)pfV=n2gs{ro0$THZmMfVr** zE}92tM+n=x+m%`9;(OKCTIA);#TMq;-fZC1s8L84w=A<;oMw302{eg z&=?ut)Hi&KM7H>!y5hyyw`gp;Es7jA9Mu%>dY&G+^Y=Brphb%zJKSD8xjc9sT8-i~ ziL6afp-@a4Y&u&UyW_r<{xXlcv2!ZVWO36t5D+Y)a7uN)S)t@-ih1tMi;=_jQ) zkYKYH63%Xoud?~58S>NH?`JCGvR9~feyk15oV#I{G`s9gFn$;9*mF62%XrBMeXJd= zWO2-N=e%_B!m5zRP;bJdaVFNWdDQNzg^)S~Q#wlP0RmTPsPK)SN+-rt}nP4~ln?Uh-Tfz(q{}Yoh|NbapmF+nGx)&X{ z{pUPEqiOPqH|WN@n0LeaQ#R@SSpdNGbtyvXTA+X0Tv|@DPdHD$JxcTBXt_q#Ui)6>RK5+HeoR82OwN4H0Nzv`D=0A>nzZu1y9cH>gh z(2qAAs}-5i4<=ZX0}p7)mxv5;1})e4X6w=2b1A=qAeF)B44cxX7?cv0ULNz8vh=uVMgTY z*b$W^nLDM#CZPKk|4sLe{Jumn*ObzLH94-|Jx$!>wltQ!OF=m6je^=KNB;!2A^Fk0 z5d>6R)TlgL^s_5oyhIo^a|@>E{b`r`5!s=Uc+C-!jc-*NOzQ3)>IAgix{VgY-s4>f z->$HhY|nQ*xiS@ya`G1VP-6>U0D^GIvJak$dE}X$_9ij}K|&PHr6JmNpF!stgT{yZ zEfefEv+X5MQit}8;(soJMx$EGrs&LbdL5kAMMJ28y`JZkv>r45?{+_5TXQq|DRopt zdg^hG+g-e2VR(6h80MzrqPestO5k~__Z@&W95oiT4rzTk^J2VaR%{dR=G)&-=Om)* zOZL`Xg>S|%v-;cCa4ra4aiRY7zDL#fGykvqRDQvmCU=<&X%B$6ISI7C%>*oZ9pv`4 z<5SAOV#fQcQeOt1R2FM;x$KpfZ!IBzub?}= z6W@GL&H>QmGEOpdvDN9%O-Cyndw-heO4oPC`IRaDFI>WK3sW(}yp4jD zd=GT`Jx~GpuO62(cOan-_6j=JCa3p^8`~OAv)m}^yj^!PnVs6$y7IlgIt6nS%%P(d zbuQ3++}1KbnK5Prh^>T0$eTCSk>u(zB@pXbLA0o^FNETHMe8$nBG+B1JQ;cSt_OWb zA7>P*8IT>Pw+aC$|JP%j?;=Lb&;GfQ;p@Xf?}#UXW2J=CzoBR7!J(grPW(2#@JicP z{LQVQ=qJUTo0gG(p;u&*d2ndg>HW3j5A}V z1?i4Yw$q5fF2TXkF`Bs}brytC5p5&)sN2OE1<{uHx&0Yj4>alwFn>L4%h9$>*XMx_ z$P>uo6Cg*7z?%$7VEt8mNf;E!wrtdZ2uv6wB6B#MUw%@XDc{SJ6eD4}sODKKVr67{ zS>9kQCL3i`z;@V(&Q7)GY#HR~b$f7JFqUQ{u%>cv|1q(zpH}u$6H3ZZX#@M!IOur$JnUXpx4;wl(9>f$G z&W^Tqd(Rjy-&SmtZAq;1M{Z(C2uQ`S4otMwQTS}Wqa*QZUqRvaY-UWA-+>8t#J*|C zphKcVgQk{l8w_Bq_iHwxwQx=9mfCXVc#=f%JS7~WbNb3+ z;&PczQ})5dF`H3;!9=SN9*Q~DXAeFX*W!4#cOfbAiw$~fH})$F2hZ>eVXWHWFVf&j zvq#!d@LH2B5B9YCCPr`@vlnbNgDlfR6d5bK;+YwT;StN)j@k%&Hc8|=8LdSU%Y60> zCzqScx|25&#jR@P8UNIq4OoC_Iy>l0%h?^IrmTpWZ%mm=N3uHp4M$t_UAD7s+Nv$+ z${N_~O-NZirxX7=dq!>nRN?UZ_o!Z%M>u6KsMuo8X_o6kK%nvFzHbfzi+ zi=*xLh1WkOvYo$;e{)mdwZot$EKU{FfZnUu$w0218=$p%kGALYH7>@mU=+rC6*X$X zwnko^!{)!26YJJ3O#KUD^d#Odu0M^fD&Vcu%tEkeT-GDJXaHwlvG~aT=g5S<7;uG1 z&znCQ-z1p(jVl??@$=5BgvD47wG*R~?2S%M+wqbkP1?KU&+npt5}Uuj{wQ^;62k^n z6Nr-$sB1%@y$;#t{-+ zfAwPHIj@IaVP1-1lER&d;VS0my)|0@7uN{ND=Lf?5<9;t70%Nnb>6&mSbk}vm|X=k zo_UI)>XIC`wnQ)FI9sn6QWkgy9BpeV>14gJ_rYnZ2&Rnof@F7NkdKyOHhE1`|9|<6 zdc59yI6`J}Ok^K>$=riR^prSGZ)56n)K;!53QSnsfog!8Ltij&>NEl0)Xl1UoS*h0 zp;483ij$I*K4q04Z31$-sWBD$GGXz?+7y#u^$LCJ5vbB`-*DOcEvfKbOlUG(oI?fFs~IzWDws47q0HMJO>zy_~gj}4r{?v zvlJ&SUgve4T@Zd6?|tbiLk<)q2&h?uOb?w}q2H1jP^m8qY&gud27bLhl1Y7$(ya;( zUZK3h65I%!I<{4%IG4iKKq0E5hEE{6&Q-pYXq5=?&Mw6ik&y<#Vl06u13^IU=}NB* z?G!Ur88seiKB-Qnc*X)QfV zddIcGYQ5~JX?@}+iqT%TS3sF0_`BPh+{YK38t4J?7Bk?tWXkiBqVrb|Fk;4}iXu(# zu>x~49|O{3)jty#a}q2C&4wfEaQHZXUJEFjtspkGx|@Ua$xCjCvPgvRp7*ycApD?PDX>_R#PohU;?x1<&Uy6P{1S<$glYn z>JP4DSNu^!pWkeHgx+XNYxN2o*2=^Q3Q;1K@{A=UtB|*XTGZ;J{TN#vOOLJ3S4WQv ztExt|LdNd_hV9pt!n;Aj(Y7EkwA>U9qz7OFVOJ>@ltT1|BPi_S3N9gHlXo_NM~@$r z9<@l2sg}71Y_S2!av>N~w(-8jTOsxg%j}Biw*)F9#UAbAU-dc8D z;j=nnbK~Pw98&N0yG_?$vwb%clL>i%bOt@0fEmf-*ncku(1cS!=F#CIXZH<7R-xF= zMsj;pH7CL#`C4!td8|q3=&_d%+1$zk$bECj|4Numg7|i14eW_(u0L3HLfT?%qq(0p zU9i%f>skY)_LIW$_31|VyPZ%h;4CPE5{5(9PMeX~YKe5w5b~^yJbEWpQu4$klz-h_ z<20)342-qT(}fJM8mceaV{F%Jz=+}k+WVvCK$U(wpN2R}*)4E~1K4cvar!~BU*O0? zOSw}b%G{=#DoyypPWX#i?YNu`Pd&7Ew$r)&GwaL#BeFf$Z~HR1-o?cE0Ks&akCm-->L-Z+rgRjuP;Jp{<*+y_G~cP*d(0vMZee>84Yr znWaRmx3WBP$wY$ao*2;b3b2UJPT4I0Bk*^6mB&A7Q?w1;vS-QKvzfQT$K)n&N5nQk zSj*YtXLJqVaX+y}o)&);u;2nl#p+4CmBU%BFl9#k_qBYS1RZuUHn|y@_%XIW(zjg% z%zDT~*O-ECB`@ttZGCR<$yO9^8tC^Yj`mz!09-xqQDzbtTuhWD47ZmP{Tq_?UJeFG zY)^_#_Xy*WUbjX(KVK-J|3uJOl)+E!S>cQx;1!o5@IFVkjHppGqhS8hu0LjT+Oc`SvNk8X}329?g z7kK=v*xoFhr(~CdnG)W7esrloMfK4lGbCL4xGo=)mVM^f%OA%+sZ^x~!r>oYTvo|} zG8K|qm8w)Z?u{jg7V9_UG)<34E8O@Jd?B_%8QI>-))Nv0SNNaD%w@arMrxK1$G?$rKTTtk@`5KWRjMPe!u@Q}`e-Idu zS(Q9v4s8NYjTxh&9}|oime@6NPh>lua{-U7-UJ)5(Z7oepnBo+KIX?#syiOZrz+PM z-}!P!x{I-(Y-`fb_72Qb821BUuWFQ~)tYbhC9=?X8)s!7Angw)Z6)C47Sz-7$`|?E z_kL!2&`|%@Yn#>Mc+)@;t7+ZOUKivjSl5#!2FIiodj)lvlI0T#*5^*z1a(7>$eP&?&~WKW z*N`zs0CEU|jyc2!Sfplwk3wi3j4uc=dmMV3SPN20mxKA@$Om8Df1GB8RNlr2RrDet zKUpsipY?o8phSG|N9uF_IV=Ky%lg$kfUN&ECU&{O92q(zfQDzjBfJ_X&%ot7f0;O? zu*35db+WqgPp@4lJ;A%DB-R3&xCULIkXgrFAyi;fV^qq!Q1D0)Od$Dg3spN`o7p1Fy zxLcj<-r?~j@lzCrT8DMKB&OYD$^P*0+xc|8C|hiz*f0`$Nv2hmq*cYAU9A08x27jejx%sq;R}KIQPZ{j;IY?0$S=r5vi-H= zIi=3U?OjYGM-U<6@?LiTaItf`UwiHL0NLfE3*Kpv_WMV4l3WeUL08rE_Ch zV7<6tS|9+0uDyu_%pdGLV&yi)p%J???(_?QGYtrwqz0?MB* zf++_~eAOY2@z9BV8YttL-AaqnWl_$vTlM^z5ipT}GmlJHg$7Agwz9_jAlMwqkNYf` zNI9{xY4v5__0v$abPBLoo2W)3kpowVi}CKX6BshjPBk5~d;a1wZU;u`0?9FI(Pfo^ zepVHfCqj?Z+yAbYPf9{m>0b0sA)Oqn?Z4YD@0^F}O2z^mD@BqZO#Zzl+0zuee_0n^ zG2wK-HW{?l=tUa{acsT>^Wqj`pY*Z3AH3$wl%H)Y}5r^7b?{v^M*pam1ufj4^Wd{}9C)#3j!yw~Nl z8ci8Fo{q_U4ut$&6`XHb@U6vD=zmRrzc&sue}BtrWMBhN zASnivIGOhTse|TE8}2CA8!%s{`cnp`^u+xLXv977Ud74$^t_lMiM7hDr@`SV4gR9_!RRBhkm;q^@0BA;d!^Mv+RvRRTK5(dF zgBMQ3yJ&z`T2jru{nzrdNBq`8H~&iut?;)NIyKsEe`xAOeqj$l#-HCg0BUH|<)E)@ zSbxc(yPdecQ-RcqB`~An#m#*!dg)v2-k><@=mBrZ3?#2Ffxbu~Nq>8d&JOgv2>`Dj zQ;g@Li^3>E?8#6&MT58_O+u^lxTAaaMhe(?){TAW(|+GS8s`39sQ;eBsG9bCT@I=7 zKwUk-QXmsbVG7zq{@1o2?-Ge876MO>8RW{0VpI_TN{LD!m3|F{+vv(UXl(4s#T0BF ztH?(YkAfKpL$!|PyTC6W51D+6#-5t8vir*LEegZ+2RQFq_- ztWW_SAkMJm4%L6^joAZeOykL2kk^x7T&;lr?>8{z?avHqK6;t2hWLFGLL?C(Ria^ZT zRp|*(5ZlIrDefA97&h54T0CdR`@FauHBWD_6L&+9g=P*l=wz2bkQ^K6e^u)s!6DS4 z+dXiWLjcM*1sYDG2ugwA10*G||Btm96)zkg&c{9ZKs%Hnb#*9DgOPcr%X?7#_tx;% z`Yn<6x{6z4S*fv3$XX-ji%q?5r-d)od&#`KD+^2)gNEjnIz2-A6Bbo=0(+Gy`?M;8 zPDLE~+)66_Am}~=kVA(L>?N>#_X-3jY6R0EKtCR>#S}e`M1dloAJmuHYOy+X6*nz6 zHV(rbHEKPl%7==d)b4{98}Yn+OWE4GkQ@*Y2G0^Efn=?I6EKB>P>19O;ueC-^Z=*Q z1F4DploEK_pq2sBqw?g}($b7#?=;Kv>S zmVI&k+p8fZ>ryZfE#H+a*{ENBkk^-o1C8v5&plvwuCJ_aWTw&a*VkqdoU)U851Su< z4e$a|`cFWd&4!g3v%U77r9eLK9|8tX;yZPFPcCm9?21AzL;DJ!$d`J(k9jN2!g>uU9DEM-p({t1=5U#ym0B9w5^^}9cGciO%5l9Ui&D#V|fkd(n%(?RC zpcfSg=BUfv5aM}wMS>~&G!Oi`+h{;PDA;-<=%nyk=w-u+Ocp>qQDxs(R{Ogl5>$gl zCCxYo`8-m>hHi@_8ZVAC{+4FXeYE)#@034eoFZiZjPD_TQ2Y>%Q67+)>a5)-Hxj_3 zM*>`sjY#B3Zf-Ta+|)&XaHr$y08llgM1OJvKxPk6&qvp&c;6l%#9jvoh#3TBgbgGJ z%|O!Uu%1S+YejmU#?mI=9iZN6A4jZBkK9A(gPy(zRFJd;MXo35Z>|N+L5WF_iy&i# zl^xW>;6XUPOciu3nn?$5TOS5)sWS`uvF+MQKns48ql1#APEJoY;b<#JY=5%OmQYf1 zr~3@ZrgRUp|BhIigk%4SSlX8O8U57rSbmJ0C1|UFoxbN`AD0zO^H?&i=l9?kt>9Ql z`no?GBq2QUu(7B2rQyb&G)buS^IFvZKqB>UL9so5rMp@F?%pYWEs8ZSZSK5n{c)Lx zc_#Ov(u0fICT2(ZUFGU-dAmCW8hH(_TPL0m^~FR26r-EsRFaPv@ENB-6I|GMo$4r7 zy(wdOF55RvW3Ps1DzXz-b&30R4w1;~;m|N1oT|IDcZb8Tu~DlLs|s-*m;(5m7v#le zK{c#A0&9E6Co@+ej>A(u|Lp?qE|j=L_L0ctGGbKEDxt`r{${p4WeMxz)MQ(ym0L45 zBN>ClTe$EC7}edw_3@!=bb)cpt5E)up834)(U38Fo7c5^VmtfQ37f#nHR#z*u3uOw zR>29W#kETmEd_~)nzeoc$F-O#i5+=b2N0!QM}J87OJ*th2jXsX=)ODYU5^AuH`u&tMAi`_3k$UL0=L$ zThhaPBG+8N9iKZEZv7Lf;2~86A5=I$DJh`qS>lzS*K5AxClboB@Lj)E8)2Lcx*4Mc zNZ892OpL>Ac=;FN#HJifz!B7mQtjCud~`LMv!Lg`4D!`FcE?q0CuV-iG0^3cj)ca6 z)BU8^vrw8_<~T}Or1KQWA_e4PnHtFIIXhuU==pAKUa9baF2Estyg1$z;$v77Ny1%W zbk2jo4gAwefU4AMyA6MFt3`4Q1PT2W0X06*+3s*-k#zlfGzPFN#0j5nwPd-Xy4cEl zo{?nf9+~L=rq zbKQJn66HxdvtK*k%SF9J2a3~LFCJ%Y>dNm3!KI4O>ig<7f7j4_R{&>Lldy^9oV)lR zS#)TiEvaBcTsV0Y7jb}KFT2RCqVhv9u6Udi>8YePHIQL^>{O7~<-xo^lx?s~c31dD z`&De^v+@2dbwlUKXp888opq2Z$pa~ygBpSFcO!yp5U>;DSJGG!TZ==?(?7jK%l0-&*3=tQA~rG` zdR%@&DU2x0{@oCPei|ic!)BxqObJ%>&v|95Fzv=?KFq7w#lxXZsK*W-F zw(kURH8_RxkCv<{EfVy_m4@73A=CEd#>U_zSMH*26g#SSs37(pm7M`$T1@JQ&oe;P zE6AjEeOi9(3SWkVn*kaQj7b|ZRBVacZxW=ZN<@BH*{@B=?|{4-Ir3KHSm_Th7qV3K zk&lwW(fs9D&6L`T!pQj1HxQ-S+$<0N{g(X2(d(5THFT-}^|=-rvI z$H$yuPk<<;o3-0vx7n@>!hH2?fhHb#cR%STrBFWXkzfrX!syo}0 z1^?ZxQeWBc570c^CRua?f29gm(iUeExnPg-H$=VlT}_j`-YTS?0z-ivd!9t{J$4?E>x zW<356kNT!&=UUP38_iQZ(T&|Q3O6i5FP9+NCivu3(`QPOXWuGm?lhoE-}kXF5tyZU zI44ojI#|*JJ>5?H%N9B2>6~@*%yghvn|Rd5IQ1RV<(l%AL=e{ve_Q0zLAls`2=DFg zHK-??)-=ydD>y`FD)PR3F8uexikC&~PWLl*i)dNyMg7#UqZZb_jyKds5hsTUo1JIy z?E87u_*1{dB?f}ohWGuxgWr_3w0_E@4+Phb-bVBoeG6Nn<+ z1<#dYxV8-Y-v|J(Q$wdcQ%bOZgnyUdW*vmsjV@D!xvx}wC7%x%7@upqV5*-N*WIxC zX0SMUhUn__v!fh^NY{>m@LkZveCxYQtziVS5->wF>lKN2P6qkO;SFMmufQ;=EKB)} z8PpHw5*Z{&1^=vGdnl!L*|?5O29N`zB5&l^Waa6jQCp>uqcJbgH%CPyebYB}Tp8Gg z%C>p~^RL1qZxt*j`&@35W2W<{UACn;M5~)>Q=~%KH!|N7<0A;=}iCHf>cVw1b;f8dk+C4A?CudK50rAyt8OQX*f>8ZEAgZ^no1*9P=G ze`PsBVYcI%f+78WjO=b#GQ4&JFpqhcVl|%9FD^Il)S>H7%Q${#PU#y^)}iOREW>`I z!s!;xJCUB>ps)jT#)C;8TE2qMTimkx#14BO$b`N8#BVm}*xy#%B943U;czW#>Dc9F zr(&{t+Q5gP!z{`EX|W>o@oM4O`9m+_G7swvMVWdp^Cn1H?b(tN0Ik!B)OHo{cYZU* z!ZT`>43Wc!&9-55*Q&=_wmO*|c-9?>7(I=G4b-{{kvu9x? zV?dNO+%wJ&5>Mal;N#*l^teL4M1=YYkyJEmF2!m0h|I~ubm1Gh53z@$Cx?iO;D)K+ z6}AU5q%`Jnl+vp1NBc6dC6hd<-RnEMIQmT))Z_Q6Uz9W{v%39255-c4r~M8~8l$s9 zxAkY$7S0n~Z}i5JFEOS!!)upd!x6eHQG*(=VHlN+*Y935z0@E9gE@6EG9+w)&h)JA z{U=mHAq9P6lKpspw^4_BZ{;)r!98d1|l1?PQy!5osAbL|%?7e-4N6B8-UCXOC07&sVBv)q<_ zxsj>i`p#|ub#&0Q&McFB%8ZM@2^sC}Igu|MhIyv^M{ys6o541wh`X;*gCY=`@yh*r zR3H!fkD=I(Eg43e9QEoA&TaNp!!vDB?n1--vMyBr=L?!41vHQu0n< zXNGhFZuve(K$d&YPZhOevM0&>nKPXz`jN8T2Yb-5O-!dhc%yHZl1(|yBj}l=4F^8ds;)J|u=Q2if%352*DefDv-BOs+EgT0yz&Q%QfI>G`Pa zE>c_(oKdTTY%@wfy|cB9)lj+Nekrwm1vM1I}bd8)&_OkKLi-aaZ?J`Z=!e88Cih{wyl))bCC!}S zS4AZMy_V5=cNhD-rdw;b?aBkA#jhiHfsf)`yZv=qlC)7)mU} z9Gsdn^w#WWQTq2@l_=Qs$RL=j?|Z7H4{LHjapRsgqV_o|EN+`(qT5bCBWOW!8vaCxI6YxhyW74rp<>MdOnJbR~461QUk z1qP|VPhe##6DqR5y3{cIGzF06@sTZ9@oiQ>I#eYrY?_fKAuo>biX{>$MqLj8b4@_3 zds+EAXjJHxG&VPEsmjxF{duG(cpQ&5MkHaG0QJ+2V6h{>qOE)_sNF7$s#=*b0@Lo~ z>WLXJdc&GZe5UCQe;f(fflOHXQQGMQJgJ8z;3?K}`Vj0$zLnh?)LC75-_;A^h+C*n z?N_3akXV~C`hm{gUER58xfd>`O8p8hiQx}n&zqS)aTdLlU_*pSvKJ}Z+p7*|oH89| z8U>ktIZNC5ouLF0eJap%VV6KN6`s~t_~9O!)v~@jiC*4t+98-L`q94bRGbK07V^`K zs9_NP^2H`6!`uR?!1d{wrj;wqn1wg{WyEDnv{%E6k zVc1SB?aJ2i*CHVNNKtc0-KJF9i^gJm?iG^LBixly{ubKEoxuFJ6THFo8Y)wB-_qy-4D4V z{2D1!srrkDohOd6chqXI_~}W4!yB`cwvGF5 zSPlCV5r~s#^dw%wu__I@C&+EQ8AJ%Bzj~M8PRHEO-yu+@;Sz#Ju71+#Ctk$GDnHMr zi*3a=`6lUrld5q56+GQnFc#i@XAQYII99!PqQk)Zu=7w^CP;Xt4C)OCWP5OK ztjfJ|QMYMPk@{-AoM+oAt3PMy5zTzCkya;Y^-Swur6=j$#QZ?Bb{13EgCwKng0r|66@r^QDV##U4WGy}xJMVcW4*rTW`xf0XdHl^ z)hZ%1=PGG$d93H9UJ78C%J%|%TfQ+e)5jQm3dw9;f?dXD%${_SGBk9HQB}e$)447* zoJLCC64sE_olo4m9fA7Zld7|oqltLH$mj9HS1Jt->~ZlFtEm&?)dNeA&zuo&+3YUnO+mYkcS*E$CuXQDN}HX^C~SP*-6iCJ_~w zT*V52my>UFxf4_Y9I1LGguHh8^}CP`jt+-zwFR&DyUNFz`k_p^X(>JUl9m_gxd^y8 zSCv!5oh8b;5p?Q&9dNxu<284O>-Dd#pJkz*0QJPt!8zdbf)zH vNejS`Z2ZOP!5D6@d=y;*9?FepSpL~>_BmU|KVLSC0SG)@{an^LB{Ts5!R3>9 literal 0 HcmV?d00001 diff --git a/docs/overview.md b/docs/overview.md index fc743562c..83190ee60 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -1,41 +1,68 @@ --- title: Overview --- + # Overview -Subnets are a layer-2 scaling solution in the Stacks blockchain that offers low latency and high throughput workloads, in addition to enabling developers to build fast and reliable experiences on Stacks. +Subnets are a layer-2 scaling solution in the Stacks blockchain that offers low +latency and high throughput workloads, enabling developers to build fast and +reliable experiences on Stacks. ## Background -Subnets are a network separate from the Stacks chain. Subnets can be thought of as a layer-2 (L2), and the Stacks chain can be thought of as a layer-1 (L1). Subnets interface with the Stacks chain via a smart contract specific to the subnet. Different subnets use distinct Stacks contracts as an interface. +A subnet is a network separate from the Stacks chain. A subnet can be thought of +as a layer-2 (L2), and the Stacks chain can be thought of as a layer-1 (L1). A +subnet interfaces with the Stacks chain via a smart contract specific to the +subnet. Different subnets use distinct contracts on the Stacks chain as an +interface. -This interface contract has several functions that allow it to act as an intermediary between the Stacks chain and some particular subnet. These functions include, but are not limited to, the following functions: +This interface contract has several functions that allow it to act as an +intermediary between the Stacks chain and some particular subnet. These +functions include, but are not limited to, the following functions: -- `commit-block`: Called by subnet miners to record block hashes and withdrawal states on the Stacks chain. -- `deposit-ft-asset` / `deposit-stx` / `deposit-nft-asset`: Called by users to deposit assets into the subnets - contract. The subnet "listens" for calls to these functions, and performs a mint on the subnets to - replicate this state. Meanwhile, on the L1, the assets live in the contract. -- `withdraw-ft-asset` / `withdraw-stx` / `withdraw-nft-asset`: Called by miners to withdraw assets from the subnets. - In an upcoming update to the subnets repo, this function will be called by users directly. +- `commit-block`: Called by subnet miners to record block hashes and withdrawal + states on the Stacks chain. +- `deposit-ft-asset` / `deposit-stx` / `deposit-nft-asset`: Called by users to + deposit assets into the subnet. The subnet miners "listens" for calls to these + functions, and performs a mint on the subnets to replicate this state. + Meanwhile, on the L1, the assets live in the subnet contract. +- `withdraw-ft-asset` / `withdraw-stx` / `withdraw-nft-asset`: Called by users + to withdrawal assets from the subnet. Withdrawal is a two step process, where + the user first initiates a withdrawal within the subnet, then calls these + functions on the Stacks chain to complete the withdrawal. -In order to register new allowed assets, a valid miner may call `setup-allowed-contracts`, `register-ft-contract`, or `register-nft-contract`. -The transaction sender must be part of the miners list defined in the subnets contract. +In order to register new allowed assets, a subnet admin may call +`register-new-ft-contract`, or `register-new-nft-contract`. Only assets that +have been registered can be deposited into the subnet. ## Features -Subnets are designed to transact on Stacks assets, meaning users can move assets in and out of subnets. While a user’s assets are in a subnet, they trust that subnet’s consensus rules. This subnet interacts with the Stacks chain using a smart contract specific to that subnet. +Subnets are designed to transact on Stacks assets, meaning users can move assets +from the Stacks chain in and out of subnets. While a user’s assets are in a +subnet, the asset is locked in the subnet contract on the Stacks chain. > **_NOTE:_** -> -> The current implementation of subnets uses a 2-phase commit protocol amongst a fully-trusted pool of miners. +> +> The current implementation of subnets uses a single miner or a 2-phase commit +> protocol amongst a fully-trusted pool of miners. Users of a subnet should be +> aware that they are sacrificing decentralization and security for the speed +> provided in the subnet, and therefore should only deposit assets into trusted +> subnets. Listed below are some of the features of subnets: -- Each subnet may define its throughput settings. The default implementation should support at least 4x high throughput for transactions and may reduce confirmation time from 10 minutes to 1 minute. -- Interacting with a subnet is similar to interacting with a different Stacks network (for example: testnet vs. mainnet). +- Each subnet may define its throughput settings. The default implementation + should support at least 4x higher throughput for transactions and reduce + confirmation time from 10 minutes to 1 minute. +- Interacting with a subnet is similar to interacting with a different Stacks + network (for example: testnet vs. mainnet). - The Stacks blockchain can support many different subnets. - Each subnet may use the same or different consensus rules. -- This repository implements a consensus mechanism that uses a two-phase commit among a federated pool of miners. -- FTs, NFTs, and STX deposits and withdrawals are supported via user-submitted L1 transactions. -- To deposit into a subnet, users submit a layer-1 transaction to invoke the deposit method on that subnet's smart contract. -- For withdrawals, users commit the withdrawal on the subnet and then submit a layer-1 transaction to invoke the subnet's smart contract's withdraw method. \ No newline at end of file +- This repository implements a consensus mechanism that uses a two-phase commit + among a federated pool of miners. +- FTs, NFTs, and STX deposits and withdrawals are supported via user-submitted + L1 transactions. +- To deposit into a subnet, users submit a layer-1 transaction to invoke the + deposit method on that subnet's smart contract. +- For withdrawals, users commit the withdrawal on the subnet and then submit a + layer-1 transaction to invoke the subnet's smart contract's withdraw method. From d4c77a2ea9c13aafef768715c05ee72ee4990e09 Mon Sep 17 00:00:00 2001 From: Brice Dobry Date: Tue, 7 Mar 2023 14:20:49 -0500 Subject: [PATCH 04/10] docs: fix some steps in walkthrough --- docs/getting-started.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 55016f196..b179b4e0b 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -634,15 +634,15 @@ async function main() { const subnetUrl = process.env.SUBNET_URL; const senderKey = process.env.ALT_USER_KEY; const addr = process.env.ALT_USER_ADDR; - const contractAddr = process.env.AUTH_SUBNET_ADMIN_ADDR; + const l1ContractAddr = process.env.DEPLOYER_ADDR; + const l2ContractAddr = process.env.USER_ADDR; const withdrawalBlockHeight = process.argv[2]; const nonce = parseInt(process.argv[3]); const withdrawalId = 0; let json_merkle_entry = await fetch( - `${subnetUrl}/v2/withdrawal/nft/${withdrawalBlockHeight}/${addr}/${withdrawalId}/${contractAddr}/simple-nft-l2/5` + `${subnetUrl}/v2/withdrawal/nft/${withdrawalBlockHeight}/${addr}/${withdrawalId}/${l2ContractAddr}/simple-nft-l2/5` ).then((x) => x.json()); - console.log(JSON.stringify(json_merkle_entry)); let cv_merkle_entry = { withdrawal_leaf_hash: deserializeCV(json_merkle_entry.withdrawal_leaf_hash), withdrawal_root: deserializeCV(json_merkle_entry.withdrawal_root), @@ -657,12 +657,12 @@ async function main() { contractName: "subnet", functionName: "withdraw-nft-asset", functionArgs: [ - contractPrincipalCV(contractAddr, "simple-nft-l1"), // nft-contract + contractPrincipalCV(l1ContractAddr, "simple-nft-l1"), // nft-contract uintCV(5), // ID standardPrincipalCV(addr), // recipient uintCV(withdrawalId), // withdrawal ID uintCV(withdrawalBlockHeight), // withdrawal block height - someCV(contractPrincipalCV(contractAddr, "simple-nft-l1")), // nft-mint-contract + someCV(contractPrincipalCV(l1ContractAddr, "simple-nft-l1")), // nft-mint-contract cv_merkle_entry.withdrawal_root, // withdrawal root cv_merkle_entry.withdrawal_leaf_hash, // withdrawal leaf hash cv_merkle_entry.sibling_hashes, @@ -800,16 +800,13 @@ Now, we will initiate a withdrawal from the subnet, by calling the node ./withdraw-l2.js 0 ``` -We can confirm that this transaction is successful in the L2 explorer. - -@@@@ TODO: Get the block height from somewhere easy and set the variable -`height`. @@@@ +We can confirm that this transaction is successful in the L2 explorer. In the explorer, note the block height that this withdrawal transaction is included in. Fill in this block height for `$height` in the next step. For the second part of the withdraw, we call `withdraw-nft-asset` on the L1 subnet contract: ```sh -node ./withdraw_nft_l1.js $height 0 +node ./withdraw-l1.js $height 0 ``` This is an L1 transaction, so it can be confirmed in the L1 explorer or in the @@ -821,3 +818,9 @@ L1 (`ST2REHHS5J3CERCRBEPMGH7921Q6PYKAADT7JP2VB`): ```sh node ./verify.js 1 ``` + +In the subnet, this asset should not be owned by anyone (`none`): + +```sh +node ./verify.js 2 +``` From f2207e015473e9bc560a4548255ce5027d413f71 Mon Sep 17 00:00:00 2001 From: Brice Dobry Date: Tue, 7 Mar 2023 14:57:55 -0500 Subject: [PATCH 05/10] chore: integrate Aaron's edits from PR review --- docs/feature-guides/trust-models.md | 15 ++- docs/getting-started.md | 164 +++++++++++++++++----------- docs/init.md | 2 +- docs/overview.md | 12 +- 4 files changed, 115 insertions(+), 78 deletions(-) diff --git a/docs/feature-guides/trust-models.md b/docs/feature-guides/trust-models.md index e420592b7..cd85affb7 100644 --- a/docs/feature-guides/trust-models.md +++ b/docs/feature-guides/trust-models.md @@ -4,11 +4,14 @@ title: Trust Models ## Overview -The current implementation of subnets uses a federated system of miners. This federation is fully-trusted, but future work on subnets will explore alternative trust models. +The current subnet implementation uses a federated system of miners. This +federation is fully-trusted, but future work on subnets will explore alternative +trust models. -In a fully federated trusted model: +In this fully-trusted federation model: -- Miners are responsible for issuing subnet blocks. -- Users can validate, but subnet miners control withdrawals. -- Trust can be federated with a 2-phase commit and BFT protocol for miner block issuance. -- Federation requires a majority of miners to approve withdrawals. \ No newline at end of file +- The federation is responsible for issuing subnet blocks. +- Users can validate these blocks, but the subnet's federation still controls + the blocks. +- Each block must be signed by a majority of the federation +- Federation signatures are validated on the L1 chain diff --git a/docs/getting-started.md b/docs/getting-started.md index b179b4e0b..1196968c1 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -9,7 +9,7 @@ Developers can test their applications on a subnet either locally, or on Hiro's hosted testnet subnet. - Run a local subnet -- Use the testnet subnet +- Use Hiro's subnet on testnet > **_NOTE:_** > @@ -31,7 +31,8 @@ subnet environment using a simple NFT example project. Make sure you have `clarinet` installed, and the clarinet version is at 1.5.0 or above. If you do not already have clarinet installed, please refer to the clarinet installation instructions -[here](https://github.com/hirosystems/clarinet) for installation procedures. +[here](https://docs.hiro.so/smart-contracts/clarinet#installing-clarinet) for +installation procedures. ### Create a new project with Clarinet @@ -47,16 +48,16 @@ initialized, and then switches into that directory. ### Create the contracts -Clarinet does not yet fully support development on subnets, so we will not be -using it to manage our subnet contracts, but will instead do that manually for -now. +Clarinet does not yet support deploying a contract to a subnet, so we will not +use it to manage our subnet contracts in this guide. Instead, we will manually +deploy our subnet contracts for now. #### Creating the Stacks (L1) contract Our L1 NFT contract is going to implement the [SIP-009 NFT trait](https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md#trait). -We can add this to our project as a requirement, so that Clarinet takes care of -deploying it for us. +We will add this to our project as a requirement so that Clarinet will deploy it +for us. ```sh clarinet requirements add SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.nft-trait @@ -68,7 +69,7 @@ Now, let's use Clarinet to create our L1 contract: clarinet contract new simple-nft-l1 ``` -This will create the file, _./contracts/simple-nft-l1.clar_, which we can fill +This will create the file, _./contracts/simple-nft-l1.clar_, which we will fill in with the following clarity code: ```clarity @@ -136,7 +137,7 @@ an NFT to be minted on the subnet, then later withdrawn to the L1. #### Creating the subnet (L2) contract Next, we'll create the subnet contract at _./contracts/simple-nft-l2.clar_. As -mentioned earlier, Clarinet cannot properly handle subnet contracts yet, so +mentioned earlier, Clarinet does not support deploying subnet contracts yet, so we'll manually create this file, and add the following contents: ```clarity @@ -212,45 +213,52 @@ we'll manually create this file, and add the following contents: Note that this contract implements the `nft-trait` and the `subnet-asset` trait. The `nft-trait` is the same as the SIP-009 trait on the Stacks network. -`subnet-asset` defines the functions required for deposit and withdrawal. These -will be called by the subnet miner. +`subnet-asset` defines the functions required for deposit and withdrawal. +`deposit-from-burnchain` is invoked by the subnet node's consensus logic +whenever a deposit is made in layer-1. `burn-for-withdrawal` is invoked by the +`nft-withdraw?` or `ft-withdraw?` functions of the subnet contract, that a user +calls when they wish to withdraw their asset from the subnet back to the +layer-1. ### Start the devnet -The settings for the devnet are found in _./settings/Devnet.toml_. We want to -enable a subnet node, and the corresponding API node, plus, we need to enable -"next" features, so that we can get 2.1 support, since the subnet contract -requires Clarity 2. Add (or uncomment) the following lines under `[devnet]`: +The settings for the devnet are found in _./settings/Devnet.toml_. In order to +launch a subnet in the devnet, we need to tell Clarinet to enable a subnet node +and a corresponding API node. Because the subnet contract requires Stacks 2.1 +support, we must also enable "next" features. -```tomml +Add, or uncomment, the following lines under `[devnet]`: + +```toml enable_subnet_node = true disable_subnet_api = false enable_next_features = true ``` -Run the following command to start the development environment -- launching a -bitcoin node, Stacks node, Stacks API service, subnet node, subnet API service, -and explorer service. +Run the following command to start the devnet environment: ```sh clarinet integrate ``` -This will open a terminal UI that shows various data points about the state of -the network. We'll know that all of the nodes/services are up and ready when we -see: +This will launch docker containers for a bitcoin node, a Stacks node, the Stacks +API service, a subnet node, the subnet API service, and an explorer service. +While running, `clarinet integrate` will open a terminal UI that shows various +data points about the state of the network. + +All of the nodes and services are running and ready when we see: ![Clarinet integrate services](images/subnet-devnet.png) Once this state is reached, we should see successful calls to `commit-block` in the transactions console. This is the subnet miner committing blocks to the L1. -Leasve this running and perform the next steps in another terminal. +Leave this running and perform the next steps in another terminal. ### Setup Node.js scripts To submit transactions to our Stacks node and subnet node, we'll use -[Stacks.js](https://stacks.js.org). Let's create a new directory, _./scripts/_ -for these scripts. +[Stacks.js](https://stacks.js.org) and some simple scripts. We'll start by +creating a new directory, _./scripts/_ for these scripts. ```sh mkdir scripts @@ -271,8 +279,8 @@ modules: "type": "module", ``` -To simplify our scripts, let's define some environment variables that we can -reuse: +To simplify our scripts, we'll define some environment variables that will be +used to hold the signing keys for various subnet transactions. ```sh export DEPLOYER_ADDR=ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM @@ -288,13 +296,13 @@ export SUBNET_URL="http://localhost:30443" #### Publish contract script -First, let's define a script to publish a contract. We'll be deploying multiple -contracts, so this script takes 4 arguments to make it reusable: +We'll start with a script to publish a contract. To make it reusable, we'll +allow this script to handle some command line arguments: 1. Contract name 2. Path to contract 3. Network layer (1 = Stacks, 2 = Subnet) -4. Nonce +4. The deployer's current account nonce _publish.js_: @@ -341,11 +349,12 @@ main(); #### Register NFT script -This script will register the NFT with the subnet, allowing it to be deposited -into the subnet and later withdrawn. We only need to do this once, so all of the -details have been hard-coded into this script. It calls -`register-new-nft-contract` on the L1 subnet contract, passing the L1 and L2 NFT -contracts we will publish. +We will also need to register our NFT with our subnet, allowing it to be +deposited into the subnet. To do this, we'll write another script, but because +we only need to do this once, we'll hardcode our details into the script. + +This script calls `register-new-nft-contract` on the L1 subnet contract, passing +the L1 and L2 NFT contracts we will publish. _register.js_: @@ -394,8 +403,10 @@ main(); #### Mint NFT script -This script will mint an NFT on the Stacks network. It takes one argument, to -specify the nonce. +In order to move NFTs to and from the subnet, we'll need to actually have some +NFTs on our devnet. To do this, we'll need to mint, so we also write a script +for submitting NFT mint transactions to the layer-1 network. This script will +take just one argument: the user's current account nonce. _mint.js_: @@ -441,8 +452,10 @@ main(); #### Deposit NFT script -The next script calls the `deposit-nft-asset` function on the L1 subnet contract -to deposit an NFT into the subnet. +We also want to be able to deposit an asset into the subnet. To do this, we will +write another script to call the `deposit-nft-asset` function on the layer-1 +subnet contract. Like the NFT minting script, this script will take just one +argument: the user's current account nonce. _deposit.js_ @@ -495,8 +508,10 @@ main(); #### Transfer NFT script -This script calls the NFT's `transfer` function in the subnet to move it from -one principal to another. It takes one argument, to specify the nonce. +To demonstrate some subnet transactions, we'll want to transfer an NFT from one +user to another. We'll write another script to invoke the NFT's `transfer` +function in the subnet. Again, this script takes just one argument: the user's +current account nonce. _transfer.js_ @@ -548,9 +563,10 @@ main(); #### L2 withdraw script -This script handles the first-part of a withdrawal, calling the `nft-withdraw?` -function on the L2 subnet contract, to initiate the withdrawal. The script takes -a single argument, to specify the nonce. +In order to withdraw an asset from a subnet, users must first submit a withdraw +transaction on that subnet. To support this, we'll write a script that invokes +the `nft-withdraw?` method on the layer-2 subnet contract. This script takes +just a single argument: the user's current account nonce. _withdraw-l2.js_ @@ -603,15 +619,14 @@ main(); #### L1 withdraw script -This script handles the second part of the withdrawal, calling -`withdraw-nft-asset` on the L1 subnet contract. It takes in the withdrawal -height (from the L2 withdrawal transaction) and then fetches from the API to get -the details required to verify the withdrawal in the subnet's withdrawal tree. - -It takes two arguments: +The second step of a withdrawal is to call the `withdraw-nft-asset` method on +the layer-1 subnet contract. This method requires information from the subnet to +verify that the withdrawal is valid. We'll write a script that queries our +subnet node's RPC interface for this information and then issues the layer-1 +withdrawal transaction. -1. Withdrawal block height: this comes from the L2 withdrawal -2. Nonce +This scripts has two input arguments: the (subnet) block height of the layer-2 +withdrawal transaction, and the user's current account nonce. _withdraw-l1.js_ @@ -684,8 +699,10 @@ main(); #### Verify script -This final script queries the `get-owner` function to check the owner of an -asset. +Lastly, we need a simple way to query for the current owner of an NFT, so we +will write a script that invokes the read-only `get-owner` function via either +the subnet or stacks node's RPC interface. This script takes just one argument +indicating whether it should query the subnet (`2`) or the stacks node (`1`). _verify.js_ @@ -728,7 +745,14 @@ main(); ### Interacting with the subnet -We'll now use that set of scripts to demonstrate the subnet functionality. +We'll now use this set of scripts to demonstrate some our subnet's +functionality. We will: + +1. Publish our NFT contract on the subnet +2. Mint a new NFT in the stacks network +3. Deposit this NFT into the subnet +4. Transfer the NFT from one user to another in the subnet +5. Withdraw the NFT from the subnet First, we'll publish the L2 NFT contract to the subnet: @@ -736,18 +760,18 @@ First, we'll publish the L2 NFT contract to the subnet: node ./publish.js simple-nft-l2 ../contracts/simple-nft-l2.clar 2 0 ``` -Clarinet's interface doesn't show the transactions on the subnet, but, we can -instead open the explorer, and see this transaction there. In a web browser, -visit http://localhost:8000. By default, it will open the explorer for the -devnet L1. To switch to the subnet, click on "Network" in the top right, then -"Add a network". In the popup, choose a name, e.g. "Devnet Subnet", then for the -URL, use "http://localhost:13999". You will know this contract deployment -succeedeed when you see the contract deploy transaction for "simple-nft-l2" in -the list of confirmed transactions. +Clarinet's interface doesn't show the transactions on the subnet, but we can see +the transaction in our local explorer instance. In a web browser, visit +http://localhost:8000. By default, it will open the explorer for the devnet L1. +To switch to the subnet, click on "Network" in the top right, then "Add a +network". In the popup, choose a name, e.g. "Devnet Subnet", then for the URL, +use "http://localhost:13999". You will know this contract deployment succeedeed +when you see the contract deploy transaction for "simple-nft-l2" in the list of +confirmed transactions. ![contract deploy confirmed](images/confirmed.png) -Now that the NFT contracts are deployed to both the L1 and the L2, we can +Now that the NFT contracts are deployed to both the L1 and the L2, we will register the NFT with the subnet. ```sh @@ -763,12 +787,18 @@ Now, we need an asset to work with, so we'll mint an NFT on the L1: node ./mint.js 0 ``` +We can see this transaction either on the Clarinet interface or in the Devnet +network on the explorer. + Once the mint has been processed, we can deposit it into the subnet: ```js node ./deposit.js 1 ``` +We can see this transaction either on the Clarinet interface or in the Devnet +network on the explorer. + We can verify that the NFT is now owned by the subnet contract (`ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.subnet`) on the L1 using: @@ -790,6 +820,8 @@ another: node ./transfer.js 1 ``` +We can see this transaction in the "Devnet Subnet" network in our explorer. + If we call the `verify.js` script again, we should now see that the NFT is owned by `ST2REHHS5J3CERCRBEPMGH7921Q6PYKAADT7JP2VB`. @@ -800,7 +832,9 @@ Now, we will initiate a withdrawal from the subnet, by calling the node ./withdraw-l2.js 0 ``` -We can confirm that this transaction is successful in the L2 explorer. In the explorer, note the block height that this withdrawal transaction is included in. Fill in this block height for `$height` in the next step. +We can confirm that this transaction is successful in the L2 explorer. In the +explorer, note the block height that this withdrawal transaction is included in. +Fill in this block height for `$height` in the next step. For the second part of the withdraw, we call `withdraw-nft-asset` on the L1 subnet contract: diff --git a/docs/init.md b/docs/init.md index cf5d3802f..553007bf3 100644 --- a/docs/init.md +++ b/docs/init.md @@ -30,7 +30,7 @@ All three configurations assume several paths that might need to be adjusted. PID file: /run/stacks-blockchain/stacks.pid Lock file: /var/lock/subsys/stacks (SysVinit) -The PID directory and data directory should be owned by both the +The PID directory and data directory should both be owned by the stacks user and group. It is advised for security reasons to make the configuration file and data directory only readable by the stacks user and group. diff --git a/docs/overview.md b/docs/overview.md index 83190ee60..b5ad20d1a 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -4,9 +4,9 @@ title: Overview # Overview -Subnets are a layer-2 scaling solution in the Stacks blockchain that offers low -latency and high throughput workloads, enabling developers to build fast and -reliable experiences on Stacks. +Subnets are a layer-2 scaling solution in the Stacks blockchain offering low +latency and high throughput and enable developers to build fast and reliable +experiences on Stacks. ## Background @@ -31,7 +31,7 @@ functions include, but are not limited to, the following functions: the user first initiates a withdrawal within the subnet, then calls these functions on the Stacks chain to complete the withdrawal. -In order to register new allowed assets, a subnet admin may call +In order to register new allowed assets, the subnet's administrator must call `register-new-ft-contract`, or `register-new-nft-contract`. Only assets that have been registered can be deposited into the subnet. @@ -43,8 +43,8 @@ subnet, the asset is locked in the subnet contract on the Stacks chain. > **_NOTE:_** > -> The current implementation of subnets uses a single miner or a 2-phase commit -> protocol amongst a fully-trusted pool of miners. Users of a subnet should be +> The current subnet implementation relies on either a single block producer or +> a fully-trusted federation of block producers. Users of a subnet should be > aware that they are sacrificing decentralization and security for the speed > provided in the subnet, and therefore should only deposit assets into trusted > subnets. From 1bb32b34d6cb945fb7a5d569e1be570597dffc32 Mon Sep 17 00:00:00 2001 From: Thomas Richards Date: Wed, 8 Mar 2023 16:37:07 -0800 Subject: [PATCH 06/10] incorporated comments and feedback for final draft --- docs/feature-guides/trust-models.md | 2 +- docs/getting-started.md | 67 +++++++++---------- docs/how-to-guides/how-to-deposit-nft.md | 4 +- docs/how-to-guides/how-to-publish-contract.md | 23 +++++-- .../how-to-register-nft-asset.md | 4 +- docs/how-to-guides/how-to-run-tests.md | 2 +- docs/how-to-guides/how-to-transfer-nft.md | 7 +- docs/how-to-guides/how-to-withdraw-nft.md | 33 +++++---- docs/overview.md | 12 ++-- 9 files changed, 80 insertions(+), 74 deletions(-) diff --git a/docs/feature-guides/trust-models.md b/docs/feature-guides/trust-models.md index cd85affb7..dcad3615d 100644 --- a/docs/feature-guides/trust-models.md +++ b/docs/feature-guides/trust-models.md @@ -5,7 +5,7 @@ title: Trust Models ## Overview The current subnet implementation uses a federated system of miners. This -federation is fully-trusted, but future work on subnets will explore alternative +federation is fully-trusted, but future work on the subnet feature will explore alternative trust models. In this fully-trusted federation model: diff --git a/docs/getting-started.md b/docs/getting-started.md index 1196968c1..416ddce0e 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -6,20 +6,20 @@ title: Getting Started # Getting Started Developers can test their applications on a subnet either locally, or on Hiro's -hosted testnet subnet. +hosted testnet subnet. This page describes two different walkthroughs that illustrate how to use a subnet. - Run a local subnet - Use Hiro's subnet on testnet > **_NOTE:_** > -> Subnets were earlier referred to as Hyperchains. While the process of updating -> the content is ongoing, there may still be some references to hyperchains -> instead of subnets. +> A subnet was previously referred to as a hyperchain. While the process of updating +> the content is ongoing, there may still be some references to a hyperchain +> instead of a subnet. -## Run a devnet subnet locally +## Run a local subnet -Clarinet provides a tool to setup a complete local development environment, +Clarinet provides a tool to set up a complete local development environment, referred to as "devnet", which uses Docker to spin up a Bitcoin node, a Stacks node, a Stacks API node, a Stacks Explorer, and now, a subnet node and subnet API node. This allows developers to test locally on a system that matches the @@ -56,6 +56,7 @@ deploy our subnet contracts for now. Our L1 NFT contract is going to implement the [SIP-009 NFT trait](https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md#trait). + We will add this to our project as a requirement so that Clarinet will deploy it for us. @@ -63,14 +64,13 @@ for us. clarinet requirements add SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.nft-trait ``` -Now, let's use Clarinet to create our L1 contract: +Now, we will use Clarinet to create our L1 contract: ```sh clarinet contract new simple-nft-l1 ``` -This will create the file, _./contracts/simple-nft-l1.clar_, which we will fill -in with the following clarity code: +This creates the file, _./contracts/simple-nft-l1.clar_, which will include the following clarity code: ```clarity (define-constant CONTRACT_OWNER tx-sender) @@ -130,15 +130,15 @@ in with the following clarity code: ) ``` -Note that this contract implements the `mint-from-subnet-trait` in addition to +Note that this contract implements the `mint-from-subnet-trait`, in addition to the SIP-009 `nft-trait`. When `mint-from-subnet-trait` is implemented, it allows an NFT to be minted on the subnet, then later withdrawn to the L1. #### Creating the subnet (L2) contract -Next, we'll create the subnet contract at _./contracts/simple-nft-l2.clar_. As +Next, we will create the subnet contract at _./contracts/simple-nft-l2.clar_. As mentioned earlier, Clarinet does not support deploying subnet contracts yet, so -we'll manually create this file, and add the following contents: +we will manually create this file, and add the following contents: ```clarity (define-constant CONTRACT_OWNER tx-sender) @@ -243,7 +243,7 @@ clarinet integrate This will launch docker containers for a bitcoin node, a Stacks node, the Stacks API service, a subnet node, the subnet API service, and an explorer service. -While running, `clarinet integrate` will open a terminal UI that shows various +While running, `clarinet integrate` opens a terminal UI that shows various data points about the state of the network. All of the nodes and services are running and ready when we see: @@ -256,8 +256,8 @@ Leave this running and perform the next steps in another terminal. ### Setup Node.js scripts -To submit transactions to our Stacks node and subnet node, we'll use -[Stacks.js](https://stacks.js.org) and some simple scripts. We'll start by +To submit transactions to Hiro's Stacks node and subnet node, we will use +[Stacks.js](https://stacks.js.org) and some simple scripts. We will start by creating a new directory, _./scripts/_ for these scripts. ```sh @@ -265,21 +265,21 @@ mkdir scripts cd scripts ``` -Then we'll initialize a Node.js project and install the stacks.js dependencies: +Then we will initialize a Node.js project and install the stacks.js dependencies: ```sh npm init -y npm install @stacks/network @stacks/transactions ``` -In the generated package.json file, add the following into the json to enable +In the generated `package.json` file, add the following into the `json` to enable modules: ```json "type": "module", ``` -To simplify our scripts, we'll define some environment variables that will be +To simplify our scripts, we will define some environment variables that will be used to hold the signing keys for various subnet transactions. ```sh @@ -296,7 +296,7 @@ export SUBNET_URL="http://localhost:30443" #### Publish contract script -We'll start with a script to publish a contract. To make it reusable, we'll +We will start with a script to publish a contract. To make it reusable, we will allow this script to handle some command line arguments: 1. Contract name @@ -349,9 +349,7 @@ main(); #### Register NFT script -We will also need to register our NFT with our subnet, allowing it to be -deposited into the subnet. To do this, we'll write another script, but because -we only need to do this once, we'll hardcode our details into the script. +We also need to register our NFT with our subnet, allowing it to be deposited into the subnet. To do this, we'll write another script, but because we only need to do this once, we will hardcode our details into the script. This script calls `register-new-nft-contract` on the L1 subnet contract, passing the L1 and L2 NFT contracts we will publish. @@ -403,10 +401,10 @@ main(); #### Mint NFT script -In order to move NFTs to and from the subnet, we'll need to actually have some -NFTs on our devnet. To do this, we'll need to mint, so we also write a script -for submitting NFT mint transactions to the layer-1 network. This script will -take just one argument: the user's current account nonce. +In order to move NFTs to and from the subnet, we will need to have some +NFTs on our devnet. To do this, we need to mint, so we also write a script +for submitting NFT mint transactions to the layer-1 network. This script +takes just one argument: the user's current account nonce. _mint.js_: @@ -454,7 +452,7 @@ main(); We also want to be able to deposit an asset into the subnet. To do this, we will write another script to call the `deposit-nft-asset` function on the layer-1 -subnet contract. Like the NFT minting script, this script will take just one +subnet contract. Like the NFT minting script, this script takes just one argument: the user's current account nonce. _deposit.js_ @@ -508,8 +506,8 @@ main(); #### Transfer NFT script -To demonstrate some subnet transactions, we'll want to transfer an NFT from one -user to another. We'll write another script to invoke the NFT's `transfer` +To demonstrate some subnet transactions, we will want to transfer an NFT from one +user to another. We will write another script to invoke the NFT's `transfer` function in the subnet. Again, this script takes just one argument: the user's current account nonce. @@ -564,7 +562,7 @@ main(); #### L2 withdraw script In order to withdraw an asset from a subnet, users must first submit a withdraw -transaction on that subnet. To support this, we'll write a script that invokes +transaction on that subnet. To support this, we will write a script that invokes the `nft-withdraw?` method on the layer-2 subnet contract. This script takes just a single argument: the user's current account nonce. @@ -621,7 +619,7 @@ main(); The second step of a withdrawal is to call the `withdraw-nft-asset` method on the layer-1 subnet contract. This method requires information from the subnet to -verify that the withdrawal is valid. We'll write a script that queries our +verify that the withdrawal is valid. We will write a script that queries our subnet node's RPC interface for this information and then issues the layer-1 withdrawal transaction. @@ -745,8 +743,7 @@ main(); ### Interacting with the subnet -We'll now use this set of scripts to demonstrate some our subnet's -functionality. We will: +We will now use this set of scripts to demonstrate a subnet's functionality. We will: 1. Publish our NFT contract on the subnet 2. Mint a new NFT in the stacks network @@ -754,7 +751,7 @@ functionality. We will: 4. Transfer the NFT from one user to another in the subnet 5. Withdraw the NFT from the subnet -First, we'll publish the L2 NFT contract to the subnet: +First, we will publish the L2 NFT contract to the subnet: ```sh node ./publish.js simple-nft-l2 ../contracts/simple-nft-l2.clar 2 0 @@ -781,7 +778,7 @@ node ./register.js This is an L1 transaction, so you can watch for it in the Clarinet interface or in the Devnet network on the explorer. -Now, we need an asset to work with, so we'll mint an NFT on the L1: +Now, we need an asset to work with, so we will mint an NFT on the L1: ```js node ./mint.js 0 diff --git a/docs/how-to-guides/how-to-deposit-nft.md b/docs/how-to-guides/how-to-deposit-nft.md index 690175b22..0976eaacc 100644 --- a/docs/how-to-guides/how-to-deposit-nft.md +++ b/docs/how-to-guides/how-to-deposit-nft.md @@ -12,13 +12,13 @@ node ./deposit_nft.js 3 ## Verifying the transaction and successful deposit -Verify that the transaction is acknowledged in the next few blocks of the L1 chain. After the transaction is confirmed in an anchored block on the L1 (this means it is included in an explicitlynumbered block in the Clarinet console), you may also want to verify the asset was successfully deposited on the hyperchain by grepping for the deposit transaction ID. +Verify the transaction is acknowledged in the next few blocks of the L1 chain. After the transaction is confirmed in an anchored block on the L1 (this means it is included in an explicitlynumbered block in the Clarinet console), verify the asset was successfully deposited on the hyperchain by grepping for the deposit transaction ID. To `grep` the deposit transaction ID, use the following command: ``` docker logs hyperchain-node.nft-use-case.devnet 2>&1 | grep "8d042c14323cfd9d31e121cc48c2c641a8db01dce19a0f6dd531eb33689dff44" ``` -In the response, look for a line similr to the example shown below. +In the response, look for a line similar to the example shown below. ``` Jul 19 12:51:02.396923 INFO ACCEPTED burnchain operation (ThreadId(8), src/chainstate/burn/db/sortdb.rs:3042), op: deposit_nft, l1_stacks_block_id: 8b5c4eb05afae6daaafdbd59aecaade6da1a8eab5eb1041062c6381cd7104b75, txid: 67cfd6220ed01c3aca3912c8f1ff55d374e5b3acadb3b995836ae913108e0514, l1_contract_id: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG.simple-nft-l1, hc_contract_id: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG.simple-nft-l2, hc_function_name: hyperchain-deposit-nft-token, id: 5, sender: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG diff --git a/docs/how-to-guides/how-to-publish-contract.md b/docs/how-to-guides/how-to-publish-contract.md index b7f9e970e..780fac914 100644 --- a/docs/how-to-guides/how-to-publish-contract.md +++ b/docs/how-to-guides/how-to-publish-contract.md @@ -4,11 +4,21 @@ title: How to Publish Contract ## Publish the NFT contract to the Stacks and Subnets -Once the Stacks node and the hyperchain node boots up (use the indicators in the top right panel to determine this), you can begin interacting with the chains. Initially, you will want to publish NFT contracts onto both the L1 and L2. When you deposit your L1 NFT onto the hyperchain, your asset will be minted by the L2 NFT contract. +Once the Stacks node and the hyperchain node boots up (use the indicators in the top right panel to determine this), you can begin interacting with the chains. Initially, you will want to publish NFT contracts on both L1 and L2. -The publish script takes in four arguments: the name of the contract to be published, the filename for the contract source code, the layer on which to broadcast the transaction (1 or 2), and the nonce of the transaction. +### Publish layer 1 contract + +When depositing your L1 NFT on the hyperchain, your asset will be minted by the L2 NFT contract. + +The publish script takes in four arguments: + +- the name of the contract to be published +- the filename for the contract source code +- the layer on which to broadcast the transaction (1 or 2) +- the nonce of the transaction First, publish the layer 1 contracts. You can enter this command (and the following transaction commands) in the same terminal window as you entered the environment variables. Make sure you are in the `scripts` directory. + These transactions are called by the principal `USER_ADDR`. Here is an example of how to publish a layer 1 contract. @@ -24,7 +34,10 @@ Verify the contracts were published by using the Clarinet console. For layer 1 c 🟩 deployed: ST2NEB84ASENDXKYGJPQW86YXQCEFEX2ZQPG87ND.simple-nft-l1 (ok true) +### Publish layer 2 contract + Next, you should publish the layer 2 contracts. Note that it may take a minute for the hyperchain node to start accepting transactions, so these commands may fail if you send them too early (but you can always re-try when the node is ready). + These transactions are called by the principal `USER_ADDR`. Here is an example of how to publish a layer 2 contract. @@ -34,8 +47,7 @@ node ./publish_tx.js trait-standards ../contracts-l2/trait-standards.clar 2 0 node ./publish_tx.js simple-nft-l2 ../contracts-l2/simple-nft-l2.clar 2 1 ``` -To verify the layer 2 transactions were processed, grep the hyperchains log for the transaction IDs -of *each* hyperchain transaction. The transaction ID is logged to the console after the call to `publish_tx` - make sure this is the ID you grep for. +To verify the layer 2 transactions were processed, `grep` the hyperchains log for the transaction IDs of *each* hyperchain transaction. The transaction ID is logged to the console after the call to `publish_tx` - make sure this is the ID you `grep` for. For example, @@ -49,8 +61,7 @@ Look for a log line similar to the following in the results: Jul 19 12:34:41.683519 INFO Tx successfully processed. (ThreadId(9), src/chainstate/stacks/miner.rs:235), event_name: transaction_result, tx_id: 17901e5ad0587d414d5bb7b1c24c3d17bb1533f5025d154719ba1a2a0f570246, event_type: success, payload: SmartContract ``` -To ensure the contracts were successfully parsed and published, `grep` for the name of the contract and ensure there are no -error lines returned (not atypical for no lines to be returned at this step). +To ensure the contracts were successfully parsed and published, `grep` for the name of the contract and ensure there are no error lines returned (not atypical for no lines to be returned at this step). For example, diff --git a/docs/how-to-guides/how-to-register-nft-asset.md b/docs/how-to-guides/how-to-register-nft-asset.md index dff981acd..c0561326d 100644 --- a/docs/how-to-guides/how-to-register-nft-asset.md +++ b/docs/how-to-guides/how-to-register-nft-asset.md @@ -4,9 +4,9 @@ title: How to Register NFT asset ## Register an NFT asset -To create an NFT asset, you must create the transaction so a published NFT asset can be registered. This transaction must be called by a miner of the hyperchains contract. +To create an NFT asset, create the transaction so a published NFT asset can be registered. This transaction must be called by a miner of the hyperchains contract. -Specifically, this transaction will be sent by `AUTH_HC_MINER_ADDR` using the following command: +This transaction will be sent by `AUTH_HC_MINER_ADDR` using the following command: ``` node ./register_nft.js 0 diff --git a/docs/how-to-guides/how-to-run-tests.md b/docs/how-to-guides/how-to-run-tests.md index 34f558d43..3ccc0a706 100644 --- a/docs/how-to-guides/how-to-run-tests.md +++ b/docs/how-to-guides/how-to-run-tests.md @@ -4,7 +4,7 @@ title: How to Run Tests ## NFT Testing -Tests can often be helpful in ensuring NFTs are properly managed and maintained (for example, minted, published, registered). +Tests may often be helpful in ensuring NFTs are properly managed and maintained (for example, minted, published, registered). You can run tests by navigating to the `testnet/stacks-node/` directory and run the following command: diff --git a/docs/how-to-guides/how-to-transfer-nft.md b/docs/how-to-guides/how-to-transfer-nft.md index 0696a2c3c..6733c6953 100644 --- a/docs/how-to-guides/how-to-transfer-nft.md +++ b/docs/how-to-guides/how-to-transfer-nft.md @@ -5,8 +5,8 @@ title: How to Transfer NFT ## Transfer an NFT On the hyperchains, the NFT should belong to the principal that sent the deposit transaction, `USER_ADDR`. -This principal can now transfer the NFT within the hyperchain. The principal `USER_ADDR` will now make a -transaction to transfer the NFT to `ALT_USER_ADDR` using the command shown below. + +This principal can now transfer the NFT within the hyperchain. The principal `USER_ADDR` will now make a transaction to transfer the NFT to `ALT_USER_ADDR` using the command shown below. ``` node ./transfer_nft.js 2 @@ -23,5 +23,4 @@ Jul 19 13:04:43.177993 INFO Tx successfully processed. (ThreadId(9), src/chainst ``` ## Mint an NFT on the hyperchain -As an added step, you may try minting an NFT on the hyperchain. This requires calling the `gift-nft` function in the -contract `simple-nft-l2`. You can tweak the `transfer_nft.js` file to make this call. \ No newline at end of file +As an added step, you may try minting an NFT on the hyperchain. This requires calling the `gift-nft` function in the contract `simple-nft-l2`. You can tweak the `transfer_nft.js` file to make this call. \ No newline at end of file diff --git a/docs/how-to-guides/how-to-withdraw-nft.md b/docs/how-to-guides/how-to-withdraw-nft.md index bce899255..8041d5b0f 100644 --- a/docs/how-to-guides/how-to-withdraw-nft.md +++ b/docs/how-to-guides/how-to-withdraw-nft.md @@ -7,16 +7,15 @@ Withdrawals from the hyperchain are a 2-step process. The owner of an asset must first call `withdraw-ft?` / `withdraw-stx?` / `withdraw-nft?` in a Clarity contract on the hyperchain. This call destroys those assets on the hyperchain, and then adds that particular withdrawal to a withdrawal data structure for that block. The withdrawal data structure serves as a cryptographic record of the withdrawals in a particular block, and has an overall associated hash. This hash is committed to the L1 interface contract via the `commit-block` function. -The second step involves calling the appropriate withdraw function in the hyperchains interface -contract on the L1 chain. You must also pass in the "proof" that corresponds to your withdrawal. -This proof includes the hash of the withdrawal data structure that this withdrawal was included in, -the hash of the withdrawal itself, and a list of hashes to be used to prove that the particular withdrawal is valid. +The second step involves calling the appropriate withdraw function in the hyperchains interface contract on the L1 chain. You must also pass in the "proof" that corresponds to your withdrawal. + +This proof includes the hash of the withdrawal data structure that this withdrawal was included in, the hash of the withdrawal itself, and a list of hashes to be used to prove that the particular withdrawal is valid. Currently, this function must be called by a hyperchain miner, but in a future hyperchain release, the asset owner will need to call this function. ### Step 6a: Withdraw the NFT on the hyperchain -Perform the withdrawal on the layer 2 by calling `withdraw-nft-asset` in the `simple-nft-l2` contract. This will be called -by the principal `ALT_USER_ADDR` using the following command: + +Perform the withdrawal on the layer 2 by calling `withdraw-nft-asset` in the `simple-nft-l2` contract. This will be called by the principal `ALT_USER_ADDR` using the following command: ``` node ./withdraw_nft_l2.js 0 @@ -34,21 +33,22 @@ Jul 19 13:22:34.800652 INFO Contract-call successfully processed (ThreadId(8), s In order to successfully complete the withdrawal on the L1, it is necessary to know the height at which the withdrawal occurred. You can find the height of the withdrawal using the `grep` command: + ``` docker logs hyperchain-node.nft-use-case.devnet 2>&1 | grep "Parsed L2 withdrawal event" Jul 19 13:22:34.801290 INFO Parsed L2 withdrawal event (ThreadId(8), src/clarity_vm/withdrawal.rs:56), type: nft, block_height: 47, sender: ST2JHG361ZXG51QTKY2NQCVBPPRRE2KZB1HR05NNC, withdrawal_id: 0, asset_id: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG.simple-nft-l2::nft-token ``` -Retrieve the withdrawal height by looking at the `block_height` in the returned line. There may be multiple lines returned -by the `grep`. Try the higher heights first, and then work backward. + +Retrieve the withdrawal height by reviewing the `block_height` in the returned line. There may be multiple lines returned by the `grep`. Try the higher heights first, and then work backward. ### Step 6b: Complete the withdrawal on the Stacks chain -Use the withdrawal height we obtained from the `grep` command in the previous step, and substitute that for `WITHDRAWAL_BLOCK_HEIGHT`. -You might need to wait a short time for the hyperchain block to become official (even if -the `grep` already returned a result) for the transaction to succeed. If the hyperchain has not advanced sufficiently, you -may receive a `Supplied block height not found` error. For now, this script assumes the requested -withdrawal was the only one in the hyperchain block it was a part of (thus, you may run into issues using this script -if you are attempting to withdraw multiple assets in a short span of time). +Use the withdrawal height obtained from the `grep` command in the previous step, and substitute that heght with `WITHDRAWAL_BLOCK_HEIGHT`. + +You may also need to wait a short time for the hyperchain block to become official (even if +the `grep` already returned a result) for the transaction to succeed. If the hyperchain has not advanced sufficiently, you may receive a `Supplied block height not found` error. + +For now, this script assumes the requested withdrawal was the only one in the hyperchain block it was a part of (thus, you may run into issues using this script if you are attempting to withdraw multiple assets in a short span of time). ``` node ./withdraw_nft_l1.js {WITHDRAWAL_BLOCK_HEIGHT} 1 @@ -58,6 +58,5 @@ Verify the transaction was successful by reviewing the response in the Clarinet 🟩 invoked: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.hyperchain::withdraw-nft-asset(u5, ST2JHG361ZXG51QTKY2NQCVBPPRRE2KZB1HR05... -You may also navigate to the Stacks Explorer (the URL of this will be listed in the Clarinet console), and check that the expected -principal now owns the NFT (`ALT_USER_ADDR`). You may check this by clicking on the transaction corresponding to -`withdraw-nft-asset`. \ No newline at end of file +You may also navigate to the Stacks Explorer (the URL of this will be listed in the Clarinet console), and check that the expected principal now owns the NFT (`ALT_USER_ADDR`). You may check this by clicking on the transaction corresponding to +`withdraw-nft-asset`. \ No newline at end of file diff --git a/docs/overview.md b/docs/overview.md index b5ad20d1a..6042a509c 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -4,8 +4,8 @@ title: Overview # Overview -Subnets are a layer-2 scaling solution in the Stacks blockchain offering low -latency and high throughput and enable developers to build fast and reliable +A subnet is a layer-2 scaling solution in the Stacks blockchain offering low +latency and high throughput, while also enabling developers to build fast and reliable experiences on Stacks. ## Background @@ -37,8 +37,8 @@ have been registered can be deposited into the subnet. ## Features -Subnets are designed to transact on Stacks assets, meaning users can move assets -from the Stacks chain in and out of subnets. While a user’s assets are in a +A subnets is designed to transact on Stacks assets, meaning users can move assets +from the Stacks chain in and out of a subnet. While a user’s assets are in a subnet, the asset is locked in the subnet contract on the Stacks chain. > **_NOTE:_** @@ -49,14 +49,14 @@ subnet, the asset is locked in the subnet contract on the Stacks chain. > provided in the subnet, and therefore should only deposit assets into trusted > subnets. -Listed below are some of the features of subnets: +Listed below are some of the features of a subnet: - Each subnet may define its throughput settings. The default implementation should support at least 4x higher throughput for transactions and reduce confirmation time from 10 minutes to 1 minute. - Interacting with a subnet is similar to interacting with a different Stacks network (for example: testnet vs. mainnet). -- The Stacks blockchain can support many different subnets. +- The Stacks blockchain may support many different subnets. - Each subnet may use the same or different consensus rules. - This repository implements a consensus mechanism that uses a two-phase commit among a federated pool of miners. From 829a8acd44b12481b31fa2688cbfa7bb0bee2c51 Mon Sep 17 00:00:00 2001 From: Brice Dobry Date: Mon, 13 Mar 2023 16:20:10 -0400 Subject: [PATCH 07/10] docs: remove outdated NFT_USE_CASE.md This is replaced with the tutorial in getting-started.md. --- NFT_USE_CASE.md | 377 ------------------------------------------------ 1 file changed, 377 deletions(-) delete mode 100644 NFT_USE_CASE.md diff --git a/NFT_USE_CASE.md b/NFT_USE_CASE.md deleted file mode 100644 index 45dc1db77..000000000 --- a/NFT_USE_CASE.md +++ /dev/null @@ -1,377 +0,0 @@ -# NFT Use Case Demo - -## Introduction - -In this demo, you will learn how to: - -1. Publish an NFT contract on the Stacks (L1) chain & subnet (L2) respectively. -2. Register NFT asset with the subnet interface contract. -3. Mint an NFT on the L1 chain. -4. Deposit that NFT to the subnet. -5. Transfer the NFT in the subnet. -6. Withdraw the NFT back to the L1 chain, which has two steps. - -▢️ -[Watch distributed systems engineer Pavi demonstrate interacting with a Subnet here.](https://www.youtube.com/watch?v=GbGNlOsPDXM) - -This guide will follow the list above, step by step. It is also possible to mint -assets directly on the subnet, and withdraw them onto the L1. This bonus step is -mentioned at the end of step 5. - -## Subnet Background - -A subnet is a network that is separate from the Stacks chain. A subnet can be -thought of as a layer-2 (L2), and the Stacks chain can be thought of as a -layer-1 (L1). The subnet interfaces with the Stacks chain via a smart contract -that is specific to the subnet. Different subnet networks will use distinct -Stacks contracts as an interface. This interface contract has several functions -that allow it to act as an intermediary between the Stacks chain and some -particular subnet. These functions include but are not limited to: - -- `commit-block`: Called by subnet miners to record block hashes and withdrawal - state on the Stacks chain. -- `deposit-ft-asset` / `deposit-stx` / `deposit-nft-asset`: Called by users to - deposit assets into the subnet contract. The subnet "listens" for calls to - these functions, and performs a mint on the subnet to replicate this state. - Meanwhile, on the L1, the assets live in the contract. -- `withdraw-ft-asset` / `withdraw-stx` / `withdraw-nft-asset`: Called by miners - to withdraw assets from the subnet. In an upcoming update to the subnet repo, - this function will be called by users directly. - -In order to register new allowed assets, a valid miner may call -`setup-allowed-contracts`, `register-ft-contract`, or `register-nft-contract`. -The transaction sender must be part of the miners list defined in the subnet -contract. - -## Setup - -Make sure you have `clarinet` installed locally, and that it is at version -0.33.0 or above. If you do not have clarinet, you can find installation -instructions [here](https://github.com/hirosystems/clarinet). - -Let's create a new Clarinet project. This will create a new directory with the -Clarinet project initialized. - -``` -clarinet new nft-use-case -``` - -Let us copy contract files and scripts over from the `stacks-subnets` repository -into the `nft-use-case` directory. If you don't already have the stacks-subnets -repository, you can [clone it](https://github.com/hirosystems/stacks-subnets). -Here's the command to clone the stacks-subnets repository: - -``` -git clone https://github.com/hirosystems/stacks-subnets.git -``` - -Set the environment variable `SUBNET_PATH` to the location of the stacks-subnets -repository on your computer. - -``` -export SUBNET_PATH= -``` - -Now, we can copy files from the stacks-subnets repository. These files are -contracts which will define the layer-1 and layer-2 Clarity traits for NFTs and -fungible tokens, implement an NFT in layer-1 and layer-2, and some NodeJS -scripts for helping to deploy the contracts. - -``` -mkdir nft-use-case/contracts-l2 -mkdir nft-use-case/scripts -cp $SUBNET_PATH/core-contracts/contracts/helper/simple-nft.clar nft-use-case/contracts/ -cp $SUBNET_PATH/core-contracts/contracts/helper/simple-nft-l2.clar nft-use-case/contracts-l2/ -cp $SUBNET_PATH/contrib/scripts/nft-use-case/* nft-use-case/scripts/ -cd nft-use-case/scripts -``` - -To use the scripts in this demo, we need to install some NodeJS libraries. -Before running the following instructions, make sure you have -[node](https://nodejs.org/en/) installed. - -``` -npm install -cd .. # back to nft-use-case/ -``` - -The `Devnet.toml` file in the `nft-use-case` directory is responsible for -configuring the `clarinet integrate` local network. Make the following change in -`settings/Devnet.toml` to enable the subnet: - -``` -[devnet] -... -enable_subnet_node = true -``` - -Our NFT contract relies on the published SIP-009 contract, so let's add it as a -requirement: - -``` -clarinet requirements add SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.nft-trait -``` - -Let's spin up a subnet node. Before you call this, make sure that you have a -working installation of Docker running locally. - -``` -clarinet integrate -``` - -Before we publish any transactions, you will need to set up some environment -variables. These environment variables contain the address and private key of -the subnet miner, two user addresses and private keys, and the RPC URL which we -can query for subnet state. Open a separate terminal window, navigate to the -directory `nft-use-case/scripts`, and enter the following. - -``` -export AUTH_SUBNET_MINER_ADDR=ST3NBRSFKX28FQ2ZJ1MAKX58HKHSDGNV5N7R21XCP -export AUTH_SUBNET_MINER_KEY=6a1a754ba863d7bab14adbbc3f8ebb090af9e871ace621d3e5ab634e1422885e01 - -export USER_ADDR=ST2NEB84ASENDXKYGJPQW86YXQCEFEX2ZQPG87ND -export USER_KEY=f9d7206a47f14d2870c163ebab4bf3e70d18f5d14ce1031f3902fbbc894fe4c701 - -export ALT_USER_ADDR=ST2REHHS5J3CERCRBEPMGH7921Q6PYKAADT7JP2VB -export ALT_USER_KEY=3eccc5dac8056590432db6a35d52b9896876a3d5cbdea53b72400bc9c2099fe801 -export SUBNET_URL="http://localhost:30443" -``` - -## Step 1: Publish the NFT contract to the Stacks L1 and the Subnet - -Once the Stacks node and the subnet node boots up (use the indicators in the top -right panel to determine this), we can start to interact with the chains. To -begin with, we want to publish NFT contracts onto both the L1 and L2. When the -user deposits their L1 NFT onto the subnet, their asset gets minted by the L2 -NFT contract. The publish script takes in four arguments: the name of the -contract to be published, the filename for the contract source code, the layer -on which to broadcast the transaction (1 or 2), and the nonce of the -transaction. First, publish the layer 1 contracts. You can enter this command -(and the following transaction commands) in the same terminal window as you -entered the environment variables. Make sure you are in the `scripts` directory. -These transactions are called by the principal `USER_ADDR`. - -``` -node ./publish_tx.js simple-nft-l1 ../contracts/simple-nft.clar 1 0 -``` - -Verify that the contracts were published by using the Clarinet console. For the -layer 1 contracts, you should see the following in the "transactions" region in -a recent block. - -🟩 deployed: ST2NEB84ASENDXKYGJPQW86YXQCEFEX2ZQPG87ND.trait-standards (ok true) - -🟩 deployed: ST2NEB84ASENDXKYGJPQW86YXQCEFEX2ZQPG87ND.simple-nft-l1 (ok true) - -Then, publish the layer 2 contracts. Note, it might take a minute for the subnet -node to start accepting transactions, so these commands could fail if you send -them too early (but you can always re-try when the node is ready). These -transactions are called by the principal `USER_ADDR`. - -``` -node ./publish_tx.js simple-nft-l2 ../contracts-l2/simple-nft-l2.clar 2 0 -``` - -To verify that the layer 2 transactions were processed, grep the subnet log for -the transaction IDs of _each_ subnet transaction. The transaction ID is logged -to the console after the call to `publish_tx` - make sure this is the ID you -grep for. - -``` -docker logs subnet-node.nft-use-case.devnet 2>&1 | grep "17901e5ad0587d414d5bb7b1c24c3d17bb1533f5025d154719ba1a2a0f570246" -``` - -Look for a log line similar to the following in the results: - -``` -Jul 19 12:34:41.683519 INFO Tx successfully processed. (ThreadId(9), src/chainstate/stacks/miner.rs:235), event_name: transaction_result, tx_id: 17901e5ad0587d414d5bb7b1c24c3d17bb1533f5025d154719ba1a2a0f570246, event_type: success, payload: SmartContract -``` - -To ensure the contracts were successfully parsed and published, we will grep for -the name of the contract and ensure there are no error lines returned (not -atypical for no lines to be returned at this step). - -``` -docker logs subnet-node.nft-use-case.devnet 2>&1 | grep "simple-nft-l2" -``` - -## Step 2: Register the new NFT asset in the interface subnet contract - -Create the transaction to register the new NFT asset we just published. This -must be called by a miner of the subnet contract. Specifically, this transaction -will be sent by `AUTH_SUBNET_MINER_ADDR`. - -``` -node ./register_nft.js -``` - -Look for the following transaction confirmation in the Clarinet console in an -upcoming block on the layer 1. - -🟩 invoked: -ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.subnet::register-new-nft-contract(ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG.simple-nft-l1, -"subnet-deposit-nft-token") (ok true) - -## Step 3: Mint an NFT on the L1 Chain - -Let's create a transaction to mint an NFT on the L1 chain. Once this transaction -is processed, the principal `USER_ADDR` will own an NFT. - -``` -node ./mint_nft.js 1 -``` - -Verify that the transaction is acknowledged within the next few blocks in the -Stacks explorer. - -🟩 invoked: -ST2NEB84ASENDXKYGJPQW86YXQCEFEX2ZQPG87ND.simple-nft-l1::gift-nft(ST2NEB84ASENDXKYGJPQW86YXQCEFEX2ZQPG87ND, -u5) (ok true) - -## Step 4: Deposit the NFT onto the Subnet - -Now, we can call the deposit NFT function in the subnet interface contract. This -function is called by the principal `USER_ADDR`. - -``` -node ./deposit_nft.js 2 -``` - -Verify that the transaction is acknowledged in the next few blocks of the L1 -chain. After the transaction is confirmed in an anchored block on the L1 (this -means it is included in an explicitly numbered block in the Clarinet console), -you also may want to verify that the asset was successfully deposited on the -subnet by grepping for the deposit transaction ID. - -``` -docker logs subnet-node.nft-use-case.devnet 2>&1 | grep "8d042c14323cfd9d31e121cc48c2c641a8db01dce19a0f6dd531eb33689dff44" -``` - -Look for a line like: - -``` -Jul 19 12:51:02.396923 INFO ACCEPTED burnchain operation (ThreadId(8), src/chainstate/burn/db/sortdb.rs:3042), op: deposit_nft, l1_stacks_block_id: 8b5c4eb05afae6daaafdbd59aecaade6da1a8eab5eb1041062c6381cd7104b75, txid: 67cfd6220ed01c3aca3912c8f1ff55d374e5b3acadb3b995836ae913108e0514, l1_contract_id: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG.simple-nft-l1, subnet_contract_id: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG.simple-nft-l2, subnet_function_name: subnet-deposit-nft-token, id: 5, sender: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG -``` - -## Step 5: Transfer the NFT within the Subnet - -On the subnet, the NFT should belong to the principal that sent the deposit -transaction, `USER_ADDR`. This principal can now transfer the NFT within the -subnet. The principal `USER_ADDR` will now make a transaction to transfer the -NFT to `ALT_USER_ADDR`. - -``` -node ./transfer_nft.js 1 -``` - -Grep for the transaction ID of the transfer transaction. - -``` -docker logs subnet-node.nft-use-case.devnet 2>&1 | grep "6acc2c756ddaed2c4cfb7351dd5930aa93ba923504be85e47db056c99a7e81aa" -``` - -Look for something like the following line: - -``` -Jul 19 13:04:43.177993 INFO Tx successfully processed. (ThreadId(9), src/chainstate/stacks/miner.rs:235), event_name: transaction_result, tx_id: 74949992488b2519e2d8408169f242c86a6cdacd927638bd4604b3b8d48ea187, event_type: success, payload: ContractCall -``` - -For a bonus step, you can try minting an NFT on the subnet. This would require -calling the `gift-nft` function in the contract `simple-nft-l2`. You can tweak -the `transfer_nft.js` file to make this call. - -## Step 6: Withdraw the NFT back to the L1 Chain - -### Background on withdrawals - -Withdrawals from the subnet are a 2-step process. - -The owner of an asset must call `withdraw-ft?` / `withdraw-stx?` / -`withdraw-nft?` in a Clarity contract on the subnet, which destroys those assets -on the subnet, and adds that particular withdrawal to a withdrawal data -structure for that block. The withdrawal data structure serves as a -cryptographic record of the withdrawals in a particular block, and has an -overall associated hash. This hash is committed to the L1 interface contract via -the `commit-block` function. - -The second step involves calling the appropriate withdraw function in the subnet -interface contract on the L1 chain. You must also pass in the "proof" that -corresponds to your withdrawal. This proof includes the hash of the withdrawal -data structure that this withdrawal was included in, the hash of the withdrawal -itself, and a list of hashes to be used to prove that the particular withdrawal -is valid. Currently, this function must be called by a subnet miner, but in an -upcoming subnet release, the asset owner must call this function. - -### Step 6a: Withdraw the NFT on the subnet - -Perform the withdrawal on the layer 2 by calling `withdraw-nft-asset` in the -`simple-nft-l2` contract. This will be called by the principal `ALT_USER_ADDR`. - -``` -node ./withdraw_nft_l2.js 0 -``` - -Grep the subnet node to ensure success: - -``` -docker logs subnet-node.nft-use-case.devnet 2>&1 | grep "5b5407ab074b4d78539133fe72020b18d44535a586574d0bd1f668e05dc89c2f" -Jul 19 13:07:33.804109 INFO Tx successfully processed. (ThreadId(9), src/chainstate/stacks/miner.rs:235), event_name: transaction_result, tx_id: 3ff9b9b0f33dbd6087f302fa9a7a113466cf7700ba7785a741b391f5ec7c5ba4, event_type: success, payload: ContractCall - -docker logs subnet-node.nft-use-case.devnet 2>&1 | grep "withdraw-nft-asset" -Jul 19 13:22:34.800652 INFO Contract-call successfully processed (ThreadId(8), src/chainstate/stacks/db/transactions.rs:731), contract_name: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG.simple-nft-l2, function_name: withdraw-nft-asset, function_args: [u5, ST2JHG361ZXG51QTKY2NQCVBPPRRE2KZB1HR05NNC], return_value: (ok true), cost: ExecutionCost { write_length: 2, write_count: 2, read_length: 1647, read_count: 5, runtime: 2002000 } -``` - -In order to successfully complete the withdrawal on the L1, it is necessary to -know the height at which the withdrawal occurred. You can find the height of the -withdrawal using grep: - -``` -docker logs subnet-node.nft-use-case.devnet 2>&1 | grep "Parsed L2 withdrawal event" -Jul 19 13:22:34.801290 INFO Parsed L2 withdrawal event (ThreadId(8), src/clarity_vm/withdrawal.rs:56), type: nft, block_height: 47, sender: ST2JHG361ZXG51QTKY2NQCVBPPRRE2KZB1HR05NNC, withdrawal_id: 0, asset_id: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG.simple-nft-l2::nft-token -``` - -Get the withdrawal height by looking at the `block_height` in the returned line. -There may be multiple lines returned by the grep. Try the higher heights first, -and work backward. - -### Step 6b: Complete the withdrawal on the Stacks chain - -Use the withdrawal height we just obtained from the grep and substitute that for -`WITHDRAWAL_BLOCK_HEIGHT`. You might need to wait a little bit for the subnet -block to become official (even if the grep already returned a result) for the -transaction to succeed. If the subnet has not advanced sufficiently, you may get -the error `Supplied block height not found`. For now, this script assumes that -the requested withdrawal was the only one in the subnet block it was a part of -(thus, you may run into issues using this script if you are attempting to -withdraw multiple assets in a short span of time). - -``` -node ./withdraw_nft_l1.js {WITHDRAWAL_BLOCK_HEIGHT} 0 -``` - -Check for the success of this transaction in the Clarinet console: - -🟩 invoked: -ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.subnet::withdraw-nft-asset(u5, -ST2JHG361ZXG51QTKY2NQCVBPPRRE2KZB1HR05... - -You can also navigate to the Stacks Explorer (the URL of this will be listed in -the Clarinet console), and check that the expected principal now owns the NFT -(`ALT_USER_ADDR`). You can check this by clicking on the transaction -corresponding to `withdraw-nft-asset`. - -That is the conclusion of this demo! If you have any issues with this demo, -reach out on the Stacks Discord or leave an issue in the stacks-subnets -repository. - -Verify that the correct address now owns the NFT by calling: - -``` -node ./verify.js -``` - -The result is printed to the terminal, and should show: - -``` -(some ST2REHHS5J3CERCRBEPMGH7921Q6PYKAADT7JP2VB) -``` From 4c2d55327dee735eb33ec37fdb51f94b51e2b16a Mon Sep 17 00:00:00 2001 From: Brice Dobry Date: Mon, 13 Mar 2023 16:21:50 -0400 Subject: [PATCH 08/10] docs: remove how-to guides for now This content is specific to the tutorial and needs to be re-worked to make sense for a more generate how-to guide. How-tos will be added in a future update. --- docs/how-to-guides/how-to-deposit-nft.md | 25 ------- docs/how-to-guides/how-to-mint-nft.md | 19 ----- docs/how-to-guides/how-to-publish-contract.md | 70 ------------------- .../how-to-register-nft-asset.md | 16 ----- docs/how-to-guides/how-to-run-tests.md | 19 ----- docs/how-to-guides/how-to-transfer-nft.md | 26 ------- docs/how-to-guides/how-to-withdraw-nft.md | 62 ---------------- 7 files changed, 237 deletions(-) delete mode 100644 docs/how-to-guides/how-to-deposit-nft.md delete mode 100644 docs/how-to-guides/how-to-mint-nft.md delete mode 100644 docs/how-to-guides/how-to-publish-contract.md delete mode 100644 docs/how-to-guides/how-to-register-nft-asset.md delete mode 100644 docs/how-to-guides/how-to-run-tests.md delete mode 100644 docs/how-to-guides/how-to-transfer-nft.md delete mode 100644 docs/how-to-guides/how-to-withdraw-nft.md diff --git a/docs/how-to-guides/how-to-deposit-nft.md b/docs/how-to-guides/how-to-deposit-nft.md deleted file mode 100644 index 0976eaacc..000000000 --- a/docs/how-to-guides/how-to-deposit-nft.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: How to Deposit NFT ---- - -## Calling the deposit NFT function - -In order to call the deposit NFT function in the hyperchains interface contract, the principal `USER_ADDR` must be called using the command shown below. - -``` -node ./deposit_nft.js 3 -``` - -## Verifying the transaction and successful deposit - -Verify the transaction is acknowledged in the next few blocks of the L1 chain. After the transaction is confirmed in an anchored block on the L1 (this means it is included in an explicitlynumbered block in the Clarinet console), verify the asset was successfully deposited on the hyperchain by grepping for the deposit transaction ID. - -To `grep` the deposit transaction ID, use the following command: -``` -docker logs hyperchain-node.nft-use-case.devnet 2>&1 | grep "8d042c14323cfd9d31e121cc48c2c641a8db01dce19a0f6dd531eb33689dff44" -``` -In the response, look for a line similar to the example shown below. - -``` -Jul 19 12:51:02.396923 INFO ACCEPTED burnchain operation (ThreadId(8), src/chainstate/burn/db/sortdb.rs:3042), op: deposit_nft, l1_stacks_block_id: 8b5c4eb05afae6daaafdbd59aecaade6da1a8eab5eb1041062c6381cd7104b75, txid: 67cfd6220ed01c3aca3912c8f1ff55d374e5b3acadb3b995836ae913108e0514, l1_contract_id: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG.simple-nft-l1, hc_contract_id: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG.simple-nft-l2, hc_function_name: hyperchain-deposit-nft-token, id: 5, sender: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG -``` \ No newline at end of file diff --git a/docs/how-to-guides/how-to-mint-nft.md b/docs/how-to-guides/how-to-mint-nft.md deleted file mode 100644 index bfc53d3d5..000000000 --- a/docs/how-to-guides/how-to-mint-nft.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: How to Mint NFT ---- - -## Mint an NFT - -To mint an NFT, create a transaction to mint an NFT on the L1 chain by using the command shown below. - -``` -node ./mint_nft.js 2 -``` - -Once the transaction is processed, the principal `USER_ADDR` will own an NFT. - -## Verify the transaction was successful - -To verify the transaction was successful in the next few blocks in the Stacks explorer, look for a line in the response similar to the example below. - -🟩 invoked: ST2NEB84ASENDXKYGJPQW86YXQCEFEX2ZQPG87ND.simple-nft-l1::gift-nft(ST2NEB84ASENDXKYGJPQW86YXQCEFEX2ZQPG87ND, u5) (ok true) \ No newline at end of file diff --git a/docs/how-to-guides/how-to-publish-contract.md b/docs/how-to-guides/how-to-publish-contract.md deleted file mode 100644 index 780fac914..000000000 --- a/docs/how-to-guides/how-to-publish-contract.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: How to Publish Contract ---- - -## Publish the NFT contract to the Stacks and Subnets - -Once the Stacks node and the hyperchain node boots up (use the indicators in the top right panel to determine this), you can begin interacting with the chains. Initially, you will want to publish NFT contracts on both L1 and L2. - -### Publish layer 1 contract - -When depositing your L1 NFT on the hyperchain, your asset will be minted by the L2 NFT contract. - -The publish script takes in four arguments: - -- the name of the contract to be published -- the filename for the contract source code -- the layer on which to broadcast the transaction (1 or 2) -- the nonce of the transaction - -First, publish the layer 1 contracts. You can enter this command (and the following transaction commands) in the same terminal window as you entered the environment variables. Make sure you are in the `scripts` directory. - -These transactions are called by the principal `USER_ADDR`. - -Here is an example of how to publish a layer 1 contract. - -``` -node ./publish_tx.js trait-standards ../contracts/trait-standards.clar 1 0 -node ./publish_tx.js simple-nft-l1 ../contracts/simple-nft.clar 1 1 -``` - -Verify the contracts were published by using the Clarinet console. For layer 1 contracts, you should see the following lines in the "transactions" region in a recent block. - -🟩 deployed: ST2NEB84ASENDXKYGJPQW86YXQCEFEX2ZQPG87ND.trait-standards (ok true) - -🟩 deployed: ST2NEB84ASENDXKYGJPQW86YXQCEFEX2ZQPG87ND.simple-nft-l1 (ok true) - -### Publish layer 2 contract - -Next, you should publish the layer 2 contracts. Note that it may take a minute for the hyperchain node to start accepting transactions, so these commands may fail if you send them too early (but you can always re-try when the node is ready). - -These transactions are called by the principal `USER_ADDR`. - -Here is an example of how to publish a layer 2 contract. - -``` -node ./publish_tx.js trait-standards ../contracts-l2/trait-standards.clar 2 0 -node ./publish_tx.js simple-nft-l2 ../contracts-l2/simple-nft-l2.clar 2 1 -``` - -To verify the layer 2 transactions were processed, `grep` the hyperchains log for the transaction IDs of *each* hyperchain transaction. The transaction ID is logged to the console after the call to `publish_tx` - make sure this is the ID you `grep` for. - -For example, - -``` -docker logs hyperchain-node.nft-use-case.devnet 2>&1 | grep "17901e5ad0587d414d5bb7b1c24c3d17bb1533f5025d154719ba1a2a0f570246" -``` - -Look for a log line similar to the following in the results: - -``` -Jul 19 12:34:41.683519 INFO Tx successfully processed. (ThreadId(9), src/chainstate/stacks/miner.rs:235), event_name: transaction_result, tx_id: 17901e5ad0587d414d5bb7b1c24c3d17bb1533f5025d154719ba1a2a0f570246, event_type: success, payload: SmartContract -``` - -To ensure the contracts were successfully parsed and published, `grep` for the name of the contract and ensure there are no error lines returned (not atypical for no lines to be returned at this step). - -For example, - -``` -docker logs hyperchain-node.nft-use-case.devnet 2>&1 | grep "simple-nft-l2" -``` \ No newline at end of file diff --git a/docs/how-to-guides/how-to-register-nft-asset.md b/docs/how-to-guides/how-to-register-nft-asset.md deleted file mode 100644 index c0561326d..000000000 --- a/docs/how-to-guides/how-to-register-nft-asset.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: How to Register NFT asset ---- - -## Register an NFT asset - -To create an NFT asset, create the transaction so a published NFT asset can be registered. This transaction must be called by a miner of the hyperchains contract. - -This transaction will be sent by `AUTH_HC_MINER_ADDR` using the following command: - -``` -node ./register_nft.js 0 -``` -In the response, look for the following transaction confirmation in the Clarinet console in an upcoming block on the layer 1. - -🟩 invoked: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.hyperchain::register-new-nft-contract(ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG.simple-nft-l1, "hyperchain-deposit-nft-token") (ok true) \ No newline at end of file diff --git a/docs/how-to-guides/how-to-run-tests.md b/docs/how-to-guides/how-to-run-tests.md deleted file mode 100644 index 3ccc0a706..000000000 --- a/docs/how-to-guides/how-to-run-tests.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: How to Run Tests ---- - -## NFT Testing - -Tests may often be helpful in ensuring NFTs are properly managed and maintained (for example, minted, published, registered). - -You can run tests by navigating to the `testnet/stacks-node/` directory and run the following command: - -``` -testnet/stacks-node$ cargo test -``` - -To ignore some tests, navigate to the `testnet/stacks-node` directory and use the following command: - -``` -testnet/stacks-node$ cargo test -- --ignored --num-threads=1 -``` \ No newline at end of file diff --git a/docs/how-to-guides/how-to-transfer-nft.md b/docs/how-to-guides/how-to-transfer-nft.md deleted file mode 100644 index 6733c6953..000000000 --- a/docs/how-to-guides/how-to-transfer-nft.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: How to Transfer NFT ---- - -## Transfer an NFT - -On the hyperchains, the NFT should belong to the principal that sent the deposit transaction, `USER_ADDR`. - -This principal can now transfer the NFT within the hyperchain. The principal `USER_ADDR` will now make a transaction to transfer the NFT to `ALT_USER_ADDR` using the command shown below. - -``` -node ./transfer_nft.js 2 -``` -Next, use the `grep` command to retrieve the transaction ID of the transfer transaction like the example below. - -``` -docker logs hyperchain-node.nft-use-case.devnet 2>&1 | grep "6acc2c756ddaed2c4cfb7351dd5930aa93ba923504be85e47db056c99a7e81aa" -``` - -In the response, look for text similar to the following line: -``` -Jul 19 13:04:43.177993 INFO Tx successfully processed. (ThreadId(9), src/chainstate/stacks/miner.rs:235), event_name: transaction_result, tx_id: 74949992488b2519e2d8408169f242c86a6cdacd927638bd4604b3b8d48ea187, event_type: success, payload: ContractCall -``` -## Mint an NFT on the hyperchain - -As an added step, you may try minting an NFT on the hyperchain. This requires calling the `gift-nft` function in the contract `simple-nft-l2`. You can tweak the `transfer_nft.js` file to make this call. \ No newline at end of file diff --git a/docs/how-to-guides/how-to-withdraw-nft.md b/docs/how-to-guides/how-to-withdraw-nft.md deleted file mode 100644 index 8041d5b0f..000000000 --- a/docs/how-to-guides/how-to-withdraw-nft.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: How to Withdraw an NFT ---- - -### Background on withdrawals -Withdrawals from the hyperchain are a 2-step process. - -The owner of an asset must first call `withdraw-ft?` / `withdraw-stx?` / `withdraw-nft?` in a Clarity contract on the hyperchain. This call destroys those assets on the hyperchain, and then adds that particular withdrawal to a withdrawal data structure for that block. The withdrawal data structure serves as a cryptographic record of the withdrawals in a particular block, and has an overall associated hash. This hash is committed to the L1 interface contract via the `commit-block` function. - -The second step involves calling the appropriate withdraw function in the hyperchains interface contract on the L1 chain. You must also pass in the "proof" that corresponds to your withdrawal. - -This proof includes the hash of the withdrawal data structure that this withdrawal was included in, the hash of the withdrawal itself, and a list of hashes to be used to prove that the particular withdrawal is valid. - -Currently, this function must be called by a hyperchain miner, but in a future hyperchain release, the asset owner will need to call this function. - -### Step 6a: Withdraw the NFT on the hyperchain - -Perform the withdrawal on the layer 2 by calling `withdraw-nft-asset` in the `simple-nft-l2` contract. This will be called by the principal `ALT_USER_ADDR` using the following command: - -``` -node ./withdraw_nft_l2.js 0 -``` -Use the `grep` command on the hyperchain node to ensure the withdrawal is successful. - -``` -docker logs hyperchain-node.nft-use-case.devnet 2>&1 | grep "5b5407ab074b4d78539133fe72020b18d44535a586574d0bd1f668e05dc89c2f" -Jul 19 13:07:33.804109 INFO Tx successfully processed. (ThreadId(9), src/chainstate/stacks/miner.rs:235), event_name: transaction_result, tx_id: 3ff9b9b0f33dbd6087f302fa9a7a113466cf7700ba7785a741b391f5ec7c5ba4, event_type: success, payload: ContractCall - -docker logs hyperchain-node.nft-use-case.devnet 2>&1 | grep "withdraw-nft-asset" -Jul 19 13:22:34.800652 INFO Contract-call successfully processed (ThreadId(8), src/chainstate/stacks/db/transactions.rs:731), contract_name: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG.simple-nft-l2, function_name: withdraw-nft-asset, function_args: [u5, ST2JHG361ZXG51QTKY2NQCVBPPRRE2KZB1HR05NNC], return_value: (ok true), cost: ExecutionCost { write_length: 2, write_count: 2, read_length: 1647, read_count: 5, runtime: 2002000 } -``` - -In order to successfully complete the withdrawal on the L1, it is necessary to know the height at which the withdrawal occurred. - -You can find the height of the withdrawal using the `grep` command: - -``` -docker logs hyperchain-node.nft-use-case.devnet 2>&1 | grep "Parsed L2 withdrawal event" -Jul 19 13:22:34.801290 INFO Parsed L2 withdrawal event (ThreadId(8), src/clarity_vm/withdrawal.rs:56), type: nft, block_height: 47, sender: ST2JHG361ZXG51QTKY2NQCVBPPRRE2KZB1HR05NNC, withdrawal_id: 0, asset_id: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG.simple-nft-l2::nft-token -``` - -Retrieve the withdrawal height by reviewing the `block_height` in the returned line. There may be multiple lines returned by the `grep`. Try the higher heights first, and then work backward. - -### Step 6b: Complete the withdrawal on the Stacks chain - -Use the withdrawal height obtained from the `grep` command in the previous step, and substitute that heght with `WITHDRAWAL_BLOCK_HEIGHT`. - -You may also need to wait a short time for the hyperchain block to become official (even if -the `grep` already returned a result) for the transaction to succeed. If the hyperchain has not advanced sufficiently, you may receive a `Supplied block height not found` error. - -For now, this script assumes the requested withdrawal was the only one in the hyperchain block it was a part of (thus, you may run into issues using this script if you are attempting to withdraw multiple assets in a short span of time). - -``` -node ./withdraw_nft_l1.js {WITHDRAWAL_BLOCK_HEIGHT} 1 -``` - -Verify the transaction was successful by reviewing the response in the Clarinet console. - -🟩 invoked: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.hyperchain::withdraw-nft-asset(u5, ST2JHG361ZXG51QTKY2NQCVBPPRRE2KZB1HR05... - -You may also navigate to the Stacks Explorer (the URL of this will be listed in the Clarinet console), and check that the expected principal now owns the NFT (`ALT_USER_ADDR`). You may check this by clicking on the transaction corresponding to -`withdraw-nft-asset`. \ No newline at end of file From 47bc65635f0cba5eaf00295a263c9277105eaa91 Mon Sep 17 00:00:00 2001 From: Brice Dobry Date: Mon, 13 Mar 2023 16:24:42 -0400 Subject: [PATCH 09/10] docs: remove init.md This content is not relevant at the moment. --- docs/init.md | 98 ---------------------------------------------------- 1 file changed, 98 deletions(-) delete mode 100644 docs/init.md diff --git a/docs/init.md b/docs/init.md deleted file mode 100644 index 553007bf3..000000000 --- a/docs/init.md +++ /dev/null @@ -1,98 +0,0 @@ -# Sample init scripts and service configuration for stacks-blockchain - -Sample scripts and configuration files for systemd and SysVinit -can be found in the [contrib/init](../contrib/init) folder. - - contrib/init/stacks.service: systemd service unit configuration - contrib/init/stacks.init: SysV style init script - -## Service User - -All Linux startup configurations assume the existence of a "stacks" user -and group. Users and groups must be created before attempting to use these scripts. -The MacOS configuration assumes stacks-blockchain will be set up for the current user. - -## Configuration - -For an example configuration file that describes the configuration settings, -see [mainnet-follower-conf.toml](../testnet/stacks-node/conf/mainnet-follower-conf.toml). -Available configuration options are documented here: https://docs.stacks.co/references/stacks-node-configuration - -## Paths - -### Linux - -All three configurations assume several paths that might need to be adjusted. - - Binary: /usr/local/bin/stacks-node - Configuration file: /etc/stacks-blockchain/Config.toml - Data directory: /stacks-blockchain - PID file: /run/stacks-blockchain/stacks.pid - Lock file: /var/lock/subsys/stacks (SysVinit) - -The PID directory and data directory should both be owned by the -stacks user and group. It is advised for security reasons to make the -configuration file and data directory only readable by the stacks user and -group. - - **_NOTE:_** - -When using the `systemd .service` file, the creation of the aforementioned -directories and the setting of their permissions is automatically handled by -`systemd`. Directories are given a permission of 710, giving the stacks group -access to files under it _if_ the files themselves give permission to the -stacks group to do so. This does not allow for the listing of files under the directory. - -```bash -$ mkdir -p /etc/stacks-blockchain/ -$ mkdir -p /stacks-blockchain -$ useradd stacks -$ chown -R stacks:stacks /stacks-blockchain/ -$ chgrp -R stacks /etc/stacks-blockchain -``` - -### macOS - - Binary: /usr/local/bin/stacks-node - Configuration file: /etc/stacks-blockchain/Config.toml - -The Config.toml file is presumed to have group ownership by the `wheel` group, with the current user having membership to that group. The data directory defined in the config is required to be writable by the current user. Logs (stdout & stderr) are saved under `/tmp/stacks-blockchain.log` - -## Installing Service Configuration - -### systemd - -Installing this .service file consists of just copying it to /usr/lib/systemd/system directory, followed by the command -`systemctl daemon-reload` in order to update running systemd configuration. - -To test, run `systemctl start stacks` and to enable for system startup run -`systemctl enable stacks` - -**_Note_** - -When installing for systemd in Debian/Ubuntu the .service file needs to be copied to the /lib/systemd/system directory instead. - -### SysVinit - -Copy stacks.init to /etc/init.d/stacks. Test by running `service stacks start`. - -Using this script, you can adjust the config path and log location to the stacks-node program by -setting the STACKS_BLOCKCHAIN_CONFIG and STACKS_BLOCKCHAIN_LOG environment variables in the file -/etc/sysconfig/stacks-blockchain. - -### MacOS - -Copy org.stacks.stacks-blockchain.plist into ~/Library/LaunchAgents. Load the launch agent by -running `launchctl load ~/Library/LaunchAgents/org.stacks.stacks-blockchain.plist`. - -This Launch Agent will **not** start the stacks-blockchain whenever the user logs in. - -To start the service, you'll need to manually run the start command: `launchctl start org.stacks.stacks-blockchain` - -NOTE: This approach is intended for those wanting to run stacks-blockchain as the current user. -You will need to modify org.stacks.stacks-blockchain.plist if you intend to use it as a -Launch Daemon with a dedicated stacks user. - -## Auto-respawn - -Auto respawning is currently disabled. From e977160e6fabc64c7df51a84b3a81ee08469b186 Mon Sep 17 00:00:00 2001 From: Brice Dobry Date: Mon, 13 Mar 2023 16:25:56 -0400 Subject: [PATCH 10/10] chore: remove yarn.lock --- yarn.lock | 4 ---- 1 file changed, 4 deletions(-) delete mode 100644 yarn.lock diff --git a/yarn.lock b/yarn.lock deleted file mode 100644 index fb57ccd13..000000000 --- a/yarn.lock +++ /dev/null @@ -1,4 +0,0 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. -# yarn lockfile v1 - -