diff --git a/.vale/styles/Vocab/docs/accept.txt b/.vale/styles/Vocab/docs/accept.txt index ccffd620..08105395 100644 --- a/.vale/styles/Vocab/docs/accept.txt +++ b/.vale/styles/Vocab/docs/accept.txt @@ -12,4 +12,5 @@ Clarinet Clarity application PoX -HODL \ No newline at end of file +HODL +DevNet \ No newline at end of file diff --git a/public/images/devnet-interface.png b/public/images/devnet-interface.png new file mode 100644 index 00000000..aaa38530 Binary files /dev/null and b/public/images/devnet-interface.png differ diff --git a/src/common/navigation.yaml b/src/common/navigation.yaml index 6c09be6a..95426731 100644 --- a/src/common/navigation.yaml +++ b/src/common/navigation.yaml @@ -43,6 +43,8 @@ sections: - path: /overview - path: /principals - path: /values + - path: /clarinet + - path: /devnet - path: /tokens sections: - title: Tutorials diff --git a/src/pages/write-smart-contracts/devnet.md b/src/pages/write-smart-contracts/devnet.md new file mode 100644 index 00000000..e62d4c08 --- /dev/null +++ b/src/pages/write-smart-contracts/devnet.md @@ -0,0 +1,156 @@ +--- +title: 'Developing a frontend with DevNet' +description: 'Integrate a frontend using a locally running blockchain with Clarinet DevNet' +--- + +## Introduction + +Once you have reached a point where your Clarity smart contract is functional, you may want to develop a web frontend +against your contract. This can be challenging, as the contract must be deployed to a live blockchain to fully +interact with it from a web application. Clarinet provides an easy method to deploy your contract to a blockchain that +runs locally on your machine that is configurable and controllable. This integration feature is called DevNet. + +DevNet allows you to perform frontend development and integration testing without the need to deploy your contract to +public testnet. This is valuable if you are in the early stages of developing a product, or if you are developing a +contract and application in stealth. DevNet uses Docker to launch local instances of Bitcoin, Stacks, Stacks API, Stacks +Explorer, and Bitcoin Explorer, and provides total configuration control over all those instances. Once running, DevNet +automatically deploys your contracts and creates Stacks accounts with pre-defined balances. + +The services launched by DevNet represent a full instance of the Stacks blockchain with the Proof of Transfer consensus +mechanism running against a locally running Bitcoin testnet. DevNet allows you to control block times, PoX transactions, +and contract deployments. Because DevNet is running locally, it can be reset or re-configured at any time. This allows +for rapid frontend development without the need to interact with the public blockchain. + +## Prerequisites + +In order to run DevNet, you must have [Clarinet installed][], and you also should have Docker installed locally. Refer +to the [Docker documentation][] for instructions on installing Docker on your development machine. + +## Launching DevNet + +Clarinet provides sensible a sensible default configuration for DevNet. If you wish to use the default configuration, +you can launch DevNet from the root of your Clarinet project with the command: + +```sh +clarinet integrate +``` + +Clarinet fetches the appropriate Docker images for the Bitcoin node, Stacks node, Stacks API node, and the Bitcoin +and Stacks Explorers. This can take several minutes on first launch. Once the images are launched, the DevNet interface +is displayed in your terminal window. The contracts in your project are deployed to the DevNet blockchain in the second +block of the chain, so you may need to wait for the third block before launching your frontend development environment. + +Review the following sections for information about the DevNet interface and configuration options for DevNet. + +## DevNet interface + +![DevNet interface](/images/devnet-interface.png) + +The DevNet interface is displayed as a terminal GUI and consists of four primary panels: the system log, service status, +mempool summary, and a minimal block explorer. + +The system log provides a log of events happening throughout the DevNet stack. You can use this log to monitor the +health of the local blockchain and review any events that occur. For services that provide a web interface, the URL +for the local service is displayed next to the container name. You can connect to these URLs using a web browser to +access the service. + +The service status provides a status summary for the Docker containers that make up the DevNet stack. A green icon next +to the container indicates that it is in a healthy state, a yellow icon indicates that the container is booting, and a +red icon indicates that there is a problem with the service. + +The mempool summary displays a list of transactions in the mempool. These include historical transactions from the +beginning of the blockchain. + +The block explorer has two sub-panels: the block summary and the block transactions. You can use the `Arrow` keys to +select a block within the chain (shown at the top of the block explorer), and the block summary and block transactions +panels display information about that block. The block summary displays the Stacks block height, the Stacks block hash, +the Bitcoin block height of the anchor block, and the PoX cycle number of the block. The block transactions panel +displays all Stacks transactions that were included in the block. + +You can access the locally running Stacks Explorer and Bitcoin Explorer from the URLs in the service status window for +more detailed information about the blocks. + +You can press `0` in the interface to reset the DevNet. Press `Ctrl` + `C` to stop the DevNet and shut down the +containers. + +## Configuring DevNet + +By default, DevNet launches a local Stacks 2.0 testnet with a fixed block time of 30 seconds. It runs Docker images +that host a Bitcoin node, a Stacks Node, the Stacks API, the Stacks Explorer, and the Bitcoin Explorer. The default +settings should be adequate for most developers, but you can change many of the settings to customize your +development environment. + +DevNet settings are located in the `settings/Devnet.toml` file. The file defines the wallets that are created in the +DevNet blockchain, the Stacks miner configuration, Proof of Transfer activity, and many other options. + +### Accounts configuration + +By default, Clarinet generates 10 wallets in the DevNet configuration file, a deployer wallet and 9 other accounts. +The accounts are seeded with a configurable balance of STX. Each wallet is defined under the heading +`[accounts.wallet_name]` in the TOML configuration file. Each heading has the following options: + +- `mnemonic`: the 24-word keyphrase used to generate the wallet address +- `balance`: the balance in micro-STX of the account when the blockchain starts + +The private key (`secret_key`), Stacks address, and BTC address are provided as comments under each wallet. These are +useful for configuring [stacking orders][] on DevNet. + +### Blockchain configuration + +DevNet provides a sensible default configuration for the local blockchain, with a fixed block time of 30 seconds and +the latest development images for each of the Stacks and Bitcoin nodes. These parameters are defined under the +`[devnet]` heading. You can customize these defaults by setting any of the following parameters. + +-> Note: if any of the parameters are not supplied in the configuration file, the default value is used. + +- `pox_stacking_orders`: defined by [stacking orders][] headings later in the file +- `orchestrator_port`: the port number for the Bitcoin orchestrator service +- `bitcoin_node_p2p_port`: the port number for Bitcoin P2P network traffic +- `bitcoin_node_rpc_port`: the port number for Bitcoin RPC network traffic +- `bitcoin_node_username`: the username for the Bitcoin node container +- `bitcoin_node_password`: the password for the Bitcoin node container +- `bitcoin_controller_port`: the port number for the Bitcoin controller network traffic +- `bitcoin_controller_block_time`: the fixed block time for the testnet in milliseconds +- `stacks_node_rpc_port`: the port number for Stacks RPC network traffic +- `stacks_node_p2p_port`: the port number for Stacks P2P network traffic +- `stacks_node_events_observers`: a whitelist of addresses for observing Stacks node events +- `stacks_api_port`: the port number for Stacks API network traffic +- `stacks_api_events_port`: the port number for Stacks API events network traffic +- `bitcoin_explorer_port`: the port number for Bitcoin Explorer HTTP traffic +- `stacks_explorer_port`: the port number for Stacks Explorer HTTP traffic +- `miner_mnemonic`: the 24-word keyphrase for the STX miner wallet +- `miner_derivation_path`: the derivation path for the STX miner +- `working_dir`: the local working directory for filesystem storage for the testnet +- `postgres_port`: the port number for the Postgres DB (for running the Stacks API) +- `postgres_username`: the username for the Postgres DB +- `postgres_password`: the password for the Postgres DB +- `postgres_database`: the database name of the Postgres DB +- `bitcoin_node_image_url`: a Docker image path for the Bitcoin node container +- `stacks_node_image_url`: a Docker image path for the Stacks node container +- `stacks_api_image_url`: a Docker image path for the Stacks API node container +- `stacks_explorer_image_url`: a Docker image path for the Stacks Explorer node container +- `bitcoin_explorer_image_url`: a Docker image path for the Bitcoin Explorer node container +- `postgres_image_url`: a Docker image path for the Postgres DB container +- `disable_bitcoin_explorer`: Boolean to set if the Bitcoin Explorer container runs in the DevNet stack +- `disable_stacks_explorer`: Boolean to set if the Stacks Explorer container runs in the DevNet stack +- `disable_stacks_api`: Boolean to set if the Stacks API container runs in the DevNet stack + +### Stacking orders + +You can configure any of the wallets in the DevNet to participate in stacking to exercise the PoX contract +within DevNet. This can be useful if you are developing a contract that interacts with the PoX contract and you need +to set specific test conditions. + +Each stacking order is defined under the heading `[[devnet.pox_stacking_orders]]`. This heading is repeated for as many +stacking orders that are necessary for your configuration. + +- `start_at_cycle`: the stacking cycle that the wallet should start particiating in. The wallet's stacking order + occurs at the block preceding the beginning of that cycle. +- `duration`: the stacking duration for the stacking cycle +- `wallet`: the alias of the wallet participating +- `slots`: the number of stacking slots that the wallet will participate in +- `btc_address`: the BTC address that stacking rewards should be sent to + +[clarinet installed]: /write-smart-contracts/clarinet#installing-clarinet +[docker documentation]: https://docs.docker.com/get-docker/ +[stacking orders]: #stacking-orders