From 15e35d8bff22f159428fafcd520578b7339c9bd4 Mon Sep 17 00:00:00 2001 From: Max Efremov <51917427+mefrem@users.noreply.github.com> Date: Thu, 20 Apr 2023 22:21:52 -0500 Subject: [PATCH 1/7] Walkthrough guide edits --- docs/getting-started.md | 30 ++++++++++++++++-------------- docs/overview.md | 2 +- 2 files changed, 17 insertions(+), 15 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 231683ef1..be6a6ba4e 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -7,6 +7,8 @@ title: Getting Started You understand subnets from the [overview](https://docs.hiro.so/subnets/overview)—now you can test one out in action. Hiro's Clarinet can serve a local subnet with [`clarinet integrate`](https://docs.hiro.so/clarinet/how-to-guides/how-to-run-integration-environment) as one of the networks in your Stacks development environment. +## What to expect + This guide walks a user through a **subnet demonstration**: minting and transferring NFTs between a main chain (local devnet) and a subnet to showcase subnet's high throughput and low latency functionality. By the end of this guide, the user will - Deploy the layer-1 contract that governs the interface to your subnet @@ -64,8 +66,7 @@ Now, we will use Clarinet to create our L1 contract: clarinet contract new simple-nft-l1 ``` -This creates the file, _./contracts/simple-nft-l1.clar_, which will include 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) @@ -129,11 +130,9 @@ Note that this contract implements the `mint-from-subnet-trait` and the SIP-009 #### Creating the subnet (L2) contract -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 will manually create this file and add the following contents: +Next, we will manually create the subnet contract at _./contracts/simple-nft-l2.clar_ with `touch contracts/simple-nft-l2.clar` in terminal. -:::note -You can use Clarinet to create the Clarity file at the specific location by entering into the terminal `clarinet contract new simple-nft-l2` or you can manually create a new file. But note that Clarinet will not deploy this contract to the subnet; instead, in a later step, you will write and run a Stacks.js script that communicates to the subnet node. -::: +As mentioned earlier, Clarinet does not support deploying subnet contracts yet, so this manually created Clarity contract file will be published to the subnet with a Stacks.js script created later in this guide. Include this Clarity code in the contract: ```clarity (define-constant CONTRACT_OWNER tx-sender) @@ -228,17 +227,17 @@ enable_subnet_node = true Also, in that file, we can see a few default settings that `clarinet` will be using for our subnet. `subnet_contract_id` specifies the L1 contract with which the subnet will be interacting. This will be automatically downloaded from the network and deployed by `clarinet` but you can take a look at it [here](https://explorer.hiro.so/txid/0x7d8a5d649d0f2b7583a456225c2e98b40ba62a124c5187f6dbfa563592b24e76?chain=testnet) if interested. ```toml -subnet_contract_id = "ST13F481SBR0R7Z6NMMH8YV2FJJYXA5JPA0AD3HP9.subnet-v1-2" +subnet_contract_id = "ST13F481SBR0R7Z6NMMH8YV2FJJYXA5JPA0AD3HP9.subnet-v1-1" ``` -`subnet_node_image_url` and `subnet_api_image_url` specify the docket images that will be used for the subnet node and the subnet API node, respectively. +`subnet_node_image_url` and `subnet_api_image_url` specify the docket images that will be used for the subnet node and the subnet API node, respectively. Make sure your settings match the ones below: ```toml -subnet_node_image_url = "hirosystems/stacks-subnets:0.4.1" +subnet_node_image_url = "hirosystems/stacks-subnets:0.4.2" subnet_api_image_url = "hirosystems/stacks-blockchain-api:7.1.0-beta.2" ``` -You do not need to modify or uncomment any of these, but you can if you'd like to test a custom subnet implementation. +These settings are modifiable if you'd like to test a custom subnet implementation. Once the configuration is complete, run the following command to start the devnet environment: @@ -384,7 +383,7 @@ async function main() { 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 nonce = (await getNonce(deployerAddr, network)) + BigInt(1); const txOptions = { contractAddress: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM", @@ -821,10 +820,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. 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. For the second part of the withdraw, we call `withdraw-nft-asset` on the L1 subnet contract: -For the second part of the withdraw, we call `withdraw-nft-asset` on the L1 -subnet contract: +:::note + +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. + +::: ```sh node ./withdraw-l1.js $height 0 diff --git a/docs/overview.md b/docs/overview.md index 036099d16..afaaf5bd4 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -4,7 +4,7 @@ title: Overview # Overview -A subnet is a layer-2 scaling solution for the Stacks blockchain, offering low latency and high throughput at the expense of centralization to a federated set of miners, enabling developers to build fast and reliable user experiences on Stacks. +A subnet is a layer-2 scaling solution for the Stacks blockchain, offering low latency and high throughput, enabling developers to build fast and reliable user experiences on Stacks. ## Background From 05c02747b54fe485019ff33e6ee1c2b5676d83e6 Mon Sep 17 00:00:00 2001 From: Max Efremov <51917427+mefrem@users.noreply.github.com> Date: Fri, 21 Apr 2023 09:19:22 -0500 Subject: [PATCH 2/7] Final changes to Getting Started guide Added clarification about subnet block confirmations. --- docs/getting-started.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index be6a6ba4e..a4bd925c3 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -272,11 +272,13 @@ By the end of this section, we will have these several scripts that correspond t - _withdraw-l1.js_ - the second step to withdrawal is to undeposit the NFT asset from L1 interface contract - _verify.js_ - querying the current owner of an NFT + To submit transactions to Hiro's Stacks node and subnet node, we will use the following simple scripts. We will save them in a new directory, _./scripts/_. ```sh mkdir scripts cd scripts +touch {publish.js,register.js,mint.js,deposit.js,transfer.js,withdraw-l2.js,withdraw-l1.js,verify.js} ``` Then we will initialize a Node.js project and install the Stacks.js dependencies: @@ -749,11 +751,12 @@ First, we will 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 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, select "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 succeeded when you see the contract deploy transaction for "simple-nft-l2" in the list of confirmed transactions. +Clarinet's terminal interface does not 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, select "Network" in the top right, then "Add a network." In the popup, choose a name, e.g., "Devnet Subnet" and then for the URL, use "http://localhost:13999". You will know this contract deployment succeeded when you see the contract deploy transaction for "simple-nft-l2" in the list of confirmed transactions. Be sure to confirm transactions before proceeding. + +:::note + +Each of these scripts depend upon the prior transaction to be published to either the L1 devnet or the L2 subnet before the next transaction can be completed successfully (for instance, the `register.js` transaction must be published to a devnet block before the `mint.js` transaction can be called). The Explorer shows these transactions in each new block; be sure to occasionally refresh the Explorer. +::: ![contract deploy confirmed](images/subnets-deployment-confirmed.png) From 94e69610d52186dd2ba530d83c36051a2252df3f Mon Sep 17 00:00:00 2001 From: Max Efremov <51917427+mefrem@users.noreply.github.com> Date: Fri, 21 Apr 2023 09:24:18 -0500 Subject: [PATCH 3/7] Jeff's suggestions --- docs/getting-started.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index a4bd925c3..8a5325ece 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -132,7 +132,11 @@ Note that this contract implements the `mint-from-subnet-trait` and the SIP-009 Next, we will manually create the subnet contract at _./contracts/simple-nft-l2.clar_ with `touch contracts/simple-nft-l2.clar` in terminal. -As mentioned earlier, Clarinet does not support deploying subnet contracts yet, so this manually created Clarity contract file will be published to the subnet with a Stacks.js script created later in this guide. Include this Clarity code in the contract: +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 will manually create this file and add the following contents: + +:::note +You can use Clarinet to create the Clarity file at the specific location by entering into the terminal `clarinet contract new simple-nft-l2` or you can manually create a new file. But note that Clarinet will not deploy this contract to the subnet; instead, in a later step, you will write and run a Stacks.js script that communicates to the subnet node. +::: ```clarity (define-constant CONTRACT_OWNER tx-sender) @@ -224,6 +228,8 @@ Uncomment, or add, the following line under `[devnet]`: enable_subnet_node = true ``` +### Subnet Settings + Also, in that file, we can see a few default settings that `clarinet` will be using for our subnet. `subnet_contract_id` specifies the L1 contract with which the subnet will be interacting. This will be automatically downloaded from the network and deployed by `clarinet` but you can take a look at it [here](https://explorer.hiro.so/txid/0x7d8a5d649d0f2b7583a456225c2e98b40ba62a124c5187f6dbfa563592b24e76?chain=testnet) if interested. ```toml From 3a81693cde8519ec738b347f6b816a585a873b5b Mon Sep 17 00:00:00 2001 From: Max Efremov <51917427+mefrem@users.noreply.github.com> Date: Fri, 21 Apr 2023 10:10:58 -0500 Subject: [PATCH 4/7] Update docs/getting-started.md Co-authored-by: jbencin --- docs/getting-started.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 8a5325ece..7365c0901 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -243,7 +243,6 @@ subnet_node_image_url = "hirosystems/stacks-subnets:0.4.2" subnet_api_image_url = "hirosystems/stacks-blockchain-api:7.1.0-beta.2" ``` -These settings are modifiable if you'd like to test a custom subnet implementation. Once the configuration is complete, run the following command to start the devnet environment: From 7b2f36a629e878cc7a148d4ed45e5aa9c2e595aa Mon Sep 17 00:00:00 2001 From: Max Efremov <51917427+mefrem@users.noreply.github.com> Date: Fri, 21 Apr 2023 10:11:15 -0500 Subject: [PATCH 5/7] Update docs/getting-started.md Co-authored-by: jbencin --- docs/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 7365c0901..5a69d87d7 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -228,7 +228,7 @@ Uncomment, or add, the following line under `[devnet]`: enable_subnet_node = true ``` -### Subnet Settings +### Optional Settings Also, in that file, we can see a few default settings that `clarinet` will be using for our subnet. `subnet_contract_id` specifies the L1 contract with which the subnet will be interacting. This will be automatically downloaded from the network and deployed by `clarinet` but you can take a look at it [here](https://explorer.hiro.so/txid/0x7d8a5d649d0f2b7583a456225c2e98b40ba62a124c5187f6dbfa563592b24e76?chain=testnet) if interested. From 508e12d977b290c17085a016adac5a100e1bc26b Mon Sep 17 00:00:00 2001 From: Max Efremov <51917427+mefrem@users.noreply.github.com> Date: Fri, 21 Apr 2023 10:11:31 -0500 Subject: [PATCH 6/7] Update docs/getting-started.md Co-authored-by: jbencin --- docs/getting-started.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 5a69d87d7..da5a3a500 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -230,7 +230,10 @@ enable_subnet_node = true ### Optional Settings -Also, in that file, we can see a few default settings that `clarinet` will be using for our subnet. `subnet_contract_id` specifies the L1 contract with which the subnet will be interacting. This will be automatically downloaded from the network and deployed by `clarinet` but you can take a look at it [here](https://explorer.hiro.so/txid/0x7d8a5d649d0f2b7583a456225c2e98b40ba62a124c5187f6dbfa563592b24e76?chain=testnet) if interested. +Also, in that file, we can see a few default settings that `clarinet` will be using for our subnet. +It is not necessary to modify any of these settings, but doing so allows you to customize your test environment. +`subnet_contract_id` specifies the L1 contract with which the subnet will be interacting. +This will be automatically downloaded from the network and deployed by `clarinet` but you can take a look at it [here](https://explorer.hiro.so/txid/0x7d8a5d649d0f2b7583a456225c2e98b40ba62a124c5187f6dbfa563592b24e76?chain=testnet) if interested. ```toml subnet_contract_id = "ST13F481SBR0R7Z6NMMH8YV2FJJYXA5JPA0AD3HP9.subnet-v1-1" From 377e3bc764a9e38f203beb6dd61e54deba6ffef4 Mon Sep 17 00:00:00 2001 From: Max Efremov <51917427+mefrem@users.noreply.github.com> Date: Fri, 21 Apr 2023 10:11:46 -0500 Subject: [PATCH 7/7] Update docs/getting-started.md Co-authored-by: jbencin --- docs/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index da5a3a500..157e25ef1 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -286,7 +286,7 @@ To submit transactions to Hiro's Stacks node and subnet node, we will use the fo ```sh mkdir scripts cd scripts -touch {publish.js,register.js,mint.js,deposit.js,transfer.js,withdraw-l2.js,withdraw-l1.js,verify.js} +touch {publish,register,mint,deposit,transfer,withdraw-l2,withdraw-l1,verify}.js ``` Then we will initialize a Node.js project and install the Stacks.js dependencies: