docs: add DevNet guide

Author: pgray-hiro

.vale/styles/Vocab/docs/accept.txt

@@ -12,4 +12,5 @@ Clarinet
 Clarity
 application
 PoX
-HODL
+HODL
+DevNet

public/images/devnet-interface.png

@@ -43,6 +43,7 @@ sections:
           - path: /principals
           - path: /values
           - path: /clarinet
+          - path: /devnet
           - path: /tokens
         sections:
           - title: Tutorials

src/common/navigation.yaml

@@ -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