@@ -10,7 +10,7 @@ Clarinet ships with a complete local blockchain environment so you can build, te
 
 * A devnet refers to a local blockchain development environment in which your smart contracts and front end application can interact with simulated blockchain entities.
 * With a devnet, your smart contract application can interact with simulated blockchain entities (miners, nodes, and a stream of mined blocks), all within your local machine.
-* When devnets simulate a blockchain environment, the entities created—the other contracts, transactions, or nodes—resemble the conditions your application will inhabit once in production.
+* When devnets simulate a blockchain environment, the entities created (the other contracts, transactions, or nodes) resemble the conditions your application will inhabit once in production.
 * Devnets enable you to create different blockchain configurations.
 * You can share a simnet environment with other devs and collaborate with them.
 * You can start a devnet at an arbitrary block height with a specified network upgrade at a later block, and with many simulated users, to see how your application responds.
@@ -27,19 +27,21 @@ clarinet devnet start
 
 Useful flags:
 
-| Option                           | Description                                       |
-| -------------------------------- | ------------------------------------------------- |
-| `--manifest-path <path>`         | Use an alternate `Clarinet.toml`                  |
-| `--no-dashboard`                 | Stream logs instead of showing the interactive UI |
-| `--deployment-plan-path <path>`  | Apply a specific deployment plan                  |
-| `--use-on-disk-deployment-plan`  | Use an existing plan without recomputing          |
-| `--use-computed-deployment-plan` | Recompute and overwrite the plan                  |
-| `--package <path>`               | Load a packaged devnet configuration              |
+| Option                           | Description                                                                             |
+| -------------------------------- | --------------------------------------------------------------------------------------- |
+| `--manifest-path <path>`         | Use an alternate `Clarinet.toml`                                                        |
+| `--no-dashboard`                 | Stream logs instead of showing the interactive UI                                       |
+| `--deployment-plan-path <path>`  | Apply a specific deployment plan                                                        |
+| `--use-on-disk-deployment-plan`  | Use an existing plan without recomputing                                                |
+| `--use-computed-deployment-plan` | Recompute and overwrite the plan                                                        |
+| `--package <path>`               | Load a packaged devnet configuration                                                    |
+| `--from-genesis`                 | Skip the embedded Epoch 4.0 snapshot and boot from genesis, walking through every epoch |
+| `--create-new-snapshot`          | Boot from genesis and save a new global snapshot after the first Epoch 4.0 Stacks block |
 
 {% hint style="info" %}
 Prerequisites
 
-Devnet requires Docker. If you see “clarinet was unable to create network,” ensure Docker Desktop is running or the Docker daemon is started.
+Devnet requires Docker. If you see "clarinet was unable to create network," ensure Docker Desktop is running or the Docker daemon is started.
 {% endhint %}
 
 By default the dashboard displays service health, recent transactions, block production, contract deployments, and resource usage. Use `--no-dashboard` in CI or when you prefer streaming logs.
@@ -167,10 +169,10 @@ curl http://localhost:3999/v2/info
 
 Common endpoints:
 
-* `/v2/info` – network information
-* `/v2/accounts/{address}` – account details
-* `/v2/contracts/source/{address}/{name}` – contract source code
-* `/extended/v1/tx/{txid}` – transaction details
+* `/v2/info`: network information
+* `/v2/accounts/{address}`: account details
+* `/v2/contracts/source/{address}/{name}`: contract source code
+* `/extended/v1/tx/{txid}`: transaction details
 
 ### Direct RPC
 
@@ -184,9 +186,9 @@ curl -X POST http://localhost:20443/v2/transactions \
 
 Useful RPC endpoints:
 
-* `/v2/transactions` – broadcast transactions
-* `/v2/contracts/call-read` – read-only contract calls
-* `/v2/fees/transfer` – fee estimates for STX transfers
+* `/v2/transactions`: broadcast transactions
+* `/v2/contracts/call-read`: read-only contract calls
+* `/v2/fees/transfer`: fee estimates for STX transfers
 
 ## Advanced configuration
 
@@ -207,53 +209,75 @@ disable_stacks_api = false
 
 ### Epoch configuration
 
-Test different Stacks versions:
+Devnet activates each Stacks epoch at a Bitcoin block height set under `[devnet]` in `settings/Devnet.toml`. These are the Clarinet v3.24.1 defaults; a key you leave out takes the default.
 
 ```toml
-[epochs]
-epoch_2_0 = 0     # Stacks 2.0 from genesis
-epoch_2_05 = 0    # Stacks 2.05 from genesis  
-epoch_2_1 = 0     # Stacks 2.1 from genesis
-epoch_2_2 = 0     # Pox-2 from genesis
-epoch_2_3 = 0     # Pox-3 from genesis
-epoch_2_4 = 0     # Pox-4 from genesis
-epoch_3_0 = 101   # Nakamoto activation at block 101
+[devnet]
+epoch_2_0 = 100
+epoch_2_05 = 100
+epoch_2_1 = 101
+epoch_2_2 = 102
+epoch_2_3 = 103
+epoch_2_4 = 104
+epoch_2_5 = 108
+epoch_3_0 = 142   # Nakamoto
+epoch_3_1 = 144
+epoch_3_2 = 146
+epoch_3_3 = 148
+epoch_3_4 = 150
+epoch_4_0 = 162   # PoX-5 and Clarity 6
 ```
 
+Devnet's PoX cycle is 20 Bitcoin blocks long with a 5-block prepare phase, starting at block 100. `epoch_3_0` has to fall inside a reward phase; Clarinet refuses to start otherwise and names the offending height in the error.
+
+By default `clarinet devnet start` restores an embedded snapshot taken after the first Epoch 4.0 Stacks block, so the chain is in Epoch 4.0 with `pox-5` deployed as soon as the dashboard shows the network ready. Changing any `epoch_*` height makes the snapshot unusable; Clarinet prints which fields differ from the snapshot and boots from genesis instead, which takes longer because every epoch transition is mined live. `--from-genesis` forces that path without editing the file.
+
+To test against PoX-5 on Devnet, keep the defaults. To test a contract's behavior across an epoch boundary, raise `epoch_4_0` so the contract deploys before it, then watch the transition in the `--no-dashboard` logs.
+
+{% hint style="info" %}
+Devnet accounts carry an `sbtc_balance` next to `balance` in `settings/Devnet.toml` (1,000,000,000 sats for the generated wallets). Devnet funds each account's `sbtc_balance` on both snapshot and genesis boots, so sBTC-backed bond tests have a balance to draw on.
+{% endhint %}
+
 ### Custom node/signer images
 
-Clarinet runs Devnet with specific tags for each Docker image. For example, Clarinet v3.10.0 uses the following images:
+Clarinet runs Devnet with a pinned tag for each Docker image. Clarinet v3.24.1 uses:
 
-* stacks node: `blockstack/stacks-core:3.3.0.0.6-alpine`
-* stacks signer: `blockstack/stacks-signer:3.3.0.0.6.0-alpine`
+* stacks node: `ghcr.io/stacks-network/stacks-core:4.0.1-alpine`
+* stacks signer: `ghcr.io/stacks-network/stacks-signer:4.0.1-alpine`
 
-We recommend Devnet users let Clarinet handle it and use the default version. This ensures that your Clarinet version can handle and properly configure the images it uses.
+Keep the defaults unless you are testing a node build. The Clarinet release pins the image that matches its epoch defaults; an older node image cannot reach `epoch_4_0`.
 
-In some cases, you may need to use other images. Clarinet lets you do this by configuring it in `settings/Devnet.toml`. For example, if you don't want to run the `alpine` images:
+To run other images, set `stacks_node_image_url` and `stacks_signer_image_url` under `[devnet]` in `settings/Devnet.toml`. This example runs the stacks-core 4.0.4 release in its Debian build, pinned by digest so the image cannot change under the same tag:
 
 ```toml
-# setting/Devnet.toml
+# settings/Devnet.toml
 [network]
 name = "devnet"
 deployment_fee_rate = 10
 
 # ...
 
 [devnet]
-stacks_node_image_url = "blockstack/stacks-core:3.3.0.0.6"
-stacks_signer_image_url = "blockstack/stacks-signer:3.3.0.0.6.0"
+# stacks-core 4.0.4 (Debian)
+stacks_node_image_url = "ghcr.io/stacks-network/stacks-core@sha256:a35bf7468139469c3da248f37396d59eed51f9c4df86a9b28df73814d13d38fa"
+# stacks-signer 4.0.4 (Debian)
+stacks_signer_image_url = "ghcr.io/stacks-network/stacks-signer@sha256:af346187bc779d75daef47baaa12a0ece7fda78b5357f338d2db5536dd176608"
 ```
 
+For the Alpine builds of the same release, use the `4.0.4-alpine` tags (`ghcr.io/stacks-network/stacks-core:4.0.4-alpine` and `ghcr.io/stacks-network/stacks-signer:4.0.4-alpine`).
+
+Clarinet does not compare the image when it decides whether to restore its snapshot: the check covers the `epoch_*` heights, the signer keys and the stacking orders. A custom image therefore still starts from the snapshot embedded in the Clarinet release. Add `--from-genesis` to boot the custom image from genesis instead.
+
 <details>
 
 <summary>Build an image locally and use it</summary>
 
-* Clone the stacks-core repository (or a fork) and checkout the desired branch.
+* Clone the stacks-core repository (or a fork) and check out the release tag or branch you want to test.
 
 ```
 git clone git@github.com:stacks-network/stacks-core.git
 cd stacks-core
-git checkout develop
+git checkout 4.0.4
 ```
 
 * Build the Docker image `stacks-node:local`:
@@ -273,7 +297,7 @@ docker push localhost:5001/stacks-node:local
 * Set the image to be used:
 
 ```
-# setting/Devnet.toml
+# settings/Devnet.toml
 [network]
 name = "devnet"
 deployment_fee_rate = 10
@@ -287,7 +311,7 @@ stacks_node_image_url = "localhost:5001/stacks-node:local"
 * Then start Devnet:
 
 ```
-clarinet devnet sta
+clarinet devnet start
 ```
 
 </details>
@@ -312,11 +336,14 @@ $ clarinet devnet start --package demo-env.json
 
 <details>
 
-<summary>Docker connection errors — “clarinet was unable to create network”</summary>
+<summary>Docker connection errors: "clarinet was unable to create network"</summary>
 
 Follow these steps to fix Docker connection issues:
 
-Ensure Docker Desktop is running (macOS/Windows).Start the Docker daemon (sudo systemctl start docker) on Linux.Confirm permissions with docker ps.Reset Docker to factory defaults if problems persist.
+* Ensure Docker Desktop is running (macOS/Windows).
+* Start the Docker daemon (`sudo systemctl start docker`) on Linux.
+* Confirm permissions with `docker ps`.
+* Reset Docker to factory defaults if problems persist.
 
 Verify Docker status:
 
@@ -329,7 +356,7 @@ docker ps
 
 <details>
 
-<summary>Port already in use — “bind: address already in use”</summary>
+<summary>Port already in use: "bind: address already in use"</summary>
 
 Find and stop the conflicting process (macOS/Linux):
 
@@ -385,7 +412,7 @@ rm -rf tmp/devnet
 
 <details>
 
-<summary>Network already exists — “network with name `.devnet` already exists”</summary>
+<summary>Network already exists: "network with name `.devnet` already exists"</summary>
 
 Remove the orphaned network:
 
@@ -410,7 +437,7 @@ docker network prune
 
 <details>
 
-<summary>Docker stream error during startup — “Fatal: unable to create image: Docker stream error”</summary>
+<summary>Docker stream error during startup: "Fatal: unable to create image: Docker stream error"</summary>
 
 **Error**: "Fatal: unable to create image: Docker stream error"
 
@@ -487,4 +514,12 @@ clarinet deployments apply --devnet
 
 </details>
 
+<details>
+
+<summary>Epoch settings have no effect</summary>
+
+Older versions of this page showed the epoch keys in a top-level `[epochs]` table. Clarinet reads them only under `[devnet]`. Move the keys there and start Devnet again.
+
+</details>
+
 ***
@@ -45,15 +45,17 @@ description = "A counter smart contract"
 
 [contracts.traits]
 path = "contracts/traits.clar"
-clarity_version = 4
+clarity_version = 6
 epoch = "latest"
 
 [contracts.counter]
 path = "contracts/counter.clar"
-clarity_version = 4
+clarity_version = 6
 epoch = "latest"
 ```
 
+`clarinet contract new` writes these two keys for you. Clarinet v3.24.1 accepts `clarity_version` values 1 through 6.
+
 The manifest handles several critical functions:
 
 * **Contract registration**: Every contract must be listed here
@@ -62,19 +64,27 @@ The manifest handles several critical functions:
 
 ### Epoch configuration
 
-You can specify the epoch in two ways:
+Set the epoch per contract, either to a specific version or to the current mainnet epoch:
 
 ```toml
-# Use a specific epoch version
-epoch = 3.1
+# A specific epoch. Accepted: 2.0, 2.05, 2.1, 2.2, 2.3, 2.4, 2.5, 3.0, 3.1, 3.2, 3.3, 3.4, 4.0
+epoch = 4.0
 ```
 
 ```toml
-# Use the latest available epoch (default)
+# The epoch running on mainnet, as pinned by your Clarinet release (default for new contracts)
 epoch = "latest"
 ```
 
-Using `"latest"` ensures your contracts always use the newest Clarity features and optimizations available in your version of Clarinet.
+`"latest"` means the epoch active on mainnet, which Clarinet v3.24.1 pins to 4.0. It is not the newest epoch the Clarity VM knows about, so a contract marked `"latest"` deploys with the features mainnet has today.
+
+The two keys depend on each other:
+
+* `epoch` set, `clarity_version` omitted: Clarinet uses the default Clarity version for that epoch. Epoch 4.0 defaults to Clarity 6.
+* Both omitted: Clarinet falls back to epoch 2.05 and Clarity 1, which rejects most current syntax. Set both.
+* `clarity_version` newer than the epoch supports: `clarinet check` stops with `Clarity 6 can not be used with 3.4` (the message names your values).
+
+A contract that calls `pox-5` or implements its `signer-manager-trait` needs `epoch = 4.0` or `"latest"`, because `pox-5` does not exist in earlier epochs; any `clarity_version` up to 6 compiles in that epoch. Pick Clarity 6 when the contract uses what Clarity 6 added: the `with-staking` and `with-pox` allowances for `restrict-assets?` and `as-contract?`, `get-bitcoin-tx-output?`, `verify-merkle-proof`, `ed25519-verify`, `secp256k1-decompress?`, or variadic `concat`. In Clarity 4 and 5 contracts the allowance keeps its old spelling, `with-stacking`; the `renamed_builtin` lint in `clarinet check` flags it once the contract's `clarity_version` is 6.
 
 ## Testing infrastructure
 
 
@@ -2,7 +2,7 @@
 description: Documentation and use cases for conditional code deployment with Clarinet
 ---
 
-# Simnet-only code deployment
+# Simnet-only code
 
 Clarinet 3.17.0 introduced conditional code deployment, letting you write Clarity expressions that Clarinet only deploys in Simnet and never on-chain.
 
@@ -77,12 +77,20 @@ This feature only works at the tooling level, in Clarinet. If you deploy a contr
 
 Smart contracts sometimes need to behave differently on testnet and mainnet. Simnet-only code deployment only covers Simnet vs "real-nets" (Devnet/Testnet/Mainnet). We may expand conditional deployments to more environments and conditions in the future, but we want to keep it simple for now.
 
-If a smart contract needs different behavior on testnet vs mainnet, take a look at how the PoX contracts handle it (for example [pox-4](https://explorer.hiro.so/txid/SP000000000000000000002Q6VF78.pox-4?chain=mainnet&tab=sourceCode)) using `is-in-mainnet`:
+If a smart contract needs different behavior on testnet and mainnet, look at how the PoX contracts handle it. `pox-5`, the contract deployed at `SP000000000000000000002Q6VF78.pox-5`, sets its cycle lengths with `is-in-mainnet`:
 
 ```clarity
-;; Default length of the PoX registration window, in burnchain blocks.
-(define-constant PREPARE_CYCLE_LENGTH (if is-in-mainnet u100 u50))
-
-;; Default length of the PoX reward cycle, in burnchain blocks.
-(define-constant REWARD_CYCLE_LENGTH (if is-in-mainnet u2100 u1050))
+;; Data vars that store a copy of the burnchain configuration.
+;; Implemented as data-vars, so that different configurations can be
+;; used in e.g. test harnesses.
+(define-data-var pox-prepare-cycle-length uint (if is-in-mainnet
+    u100
+    u50
+))
+(define-data-var pox-reward-cycle-length uint (if is-in-mainnet
+    u2100
+    u1050
+))
 ```
+
+`is-in-mainnet` is evaluated when the contract is deployed, so the same source gives mainnet a 2,100-block reward cycle with a 100-block prepare phase and testnet a 1,050-block cycle with a 50-block prepare phase. pox-5 uses the same keyword to pick the address version when it reconstructs a signer principal. Read the [deployed contract](https://explorer.hiro.so/txid/SP000000000000000000002Q6VF78.pox-5?chain=mainnet\&tab=sourceCode) or the [source at release 4.0.4](https://github.com/stacks-network/stacks-core/blob/4.0.4/stackslib/src/chainstate/stacks/boot/pox-5.clar#L356-L366).