docs: improve on-chain governance guide

h4x3rotab · claude · h4x3rotab · commit 6d23c437ee80 · 2025-12-27T04:23:43.000Z
- Add ALCHEMY_API_KEY to prerequisites and deploy command - Add KMS_CONTRACT_ADDRESS export after deployment (critical fix) - Clarify KMS_CONTRACT_ADDR vs KMS_CONTRACT_ADDRESS usage - Add sample outputs for all commands - Add compose hash computation instructions - Add cross-references to related docs - Writing guide: add procedural documentation section 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
diff --git a/.agent/WRITING_GUIDE.md b/.agent/WRITING_GUIDE.md
@@ -53,3 +53,30 @@ When describing components for security researchers:
 | Docker Compose native | VMM | Direct parsing, no translation |
 | Reproducible OS | VMM | Deterministic image builds |
 | Confidential GPUs | VMM + hardware | NVIDIA H100/Blackwell allocation |
+
+## Procedural Documentation (Guides & Tutorials)
+
+### Test Before You Document
+- **Run every command** before documenting it — reading code is not enough
+- Commands may prompt for confirmation, require undocumented env vars, or fail silently
+- Create a test environment and execute the full flow end-to-end
+
+### Show What Success Looks Like
+- **Add sample outputs** after commands so users can verify they're on track
+- For deployment commands, show the key values users need to note (addresses, IDs)
+- For validation commands, show both success and failure outputs
+
+### Environment Variables
+- **List all required env vars explicitly** — don't assume users will discover them
+- If multiple tools use similar-but-different var names, clarify which is which
+- Show the export pattern once, then reference it in subsequent commands
+
+### Avoid Expert Blind Spots
+- If you say "add the hash", explain how to compute the hash
+- If you reference a file, explain where to find it
+- If a value comes from a previous step, remind users which step
+
+### Cross-Reference Related Docs
+- Link to prerequisite guides (don't repeat content)
+- Link to detailed guides for optional deep-dives
+- Use anchor links for specific sections when possible
diff --git a/docs/deployment.md b/docs/deployment.md
@@ -172,12 +172,23 @@ Start VMM:
 
 ### 2. Deploy KMS as CVM
 
-> **TODO:** This section needs a proper rewrite covering auth server configuration. The current instructions are incomplete.
+Production KMS requires three components running together:
+- **KMS**: The key management service inside a CVM
+- **auth-api**: Webhook server that validates requests against smart contracts
+- **Ethereum RPC**: Access to the blockchain (via light client or external RPC)
 
-Production KMS deployment requires:
-- KMS running inside a CVM
-- Auth server for authorization (webhook mode, not dev mode)
-- OS image whitelisting
+#### Prerequisites: Deploy DstackKms Contract
+
+Before deploying KMS, you need a DstackKms contract on an Ethereum-compatible network:
+
+```bash
+cd dstack/kms/auth-eth
+npm install
+npx hardhat compile
+PRIVATE_KEY=<your-key> npx hardhat kms:deploy --with-app-impl --network <network>
+```
+
+Note the deployed contract address (e.g., `0xFE6C45aE66344CAEF5E5D7e2cbD476286D651875`).
 
 #### Deploy KMS CVM
 
@@ -189,13 +200,29 @@ cd dstack/kms/dstack-app/
 Edit the generated `.env` file:
 
 ```bash
+# VMM connection
 VMM_RPC=unix:../../vmm-data/vmm.sock
+
+# Network configuration
 KMS_RPC_ADDR=0.0.0.0:9201
 GUEST_AGENT_ADDR=127.0.0.1:9205
-GIT_REV=HEAD
+
+# Auth server configuration (required for production)
+KMS_CONTRACT_ADDR=0xFE6C45aE66344CAEF5E5D7e2cbD476286D651875
+ETH_RPC_URL=https://rpc.phala.network
+
+# OS image verification
 OS_IMAGE=dstack-0.5.5
+IMAGE_DOWNLOAD_URL=https://github.com/Dstack-TEE/meta-dstack/releases/download/v{version}/dstack-{version}.tar.gz
+
+# Build reference
+GIT_REV=HEAD
 ```
 
+The compose file (`docker-compose.yaml`) includes:
+- **auth-api**: Connects to the smart contract via `ETH_RPC_URL`
+- **kms**: Configured with webhook auth mode pointing to auth-api
+
 Run the script again to deploy:
 
 ```bash
@@ -224,25 +251,41 @@ The KMS will display its public key and TDX quote:
 
 ![KMS Bootstrap Result](assets/kms-bootstrap-result.png)
 
-#### Configure Auth Server
-
-> **TODO:** Document auth server setup for production KMS.
-
 #### Whitelist OS Image
 
-The OS image hash must be whitelisted before apps can run. This is required for both offchain and onchain governance.
+The OS image hash must be whitelisted in the DstackKms contract before apps can run:
+
+```bash
+cd dstack/kms/auth-eth
+npx hardhat kms:add-image --network <network> 0x<os-image-hash>
+```
 
-> **TODO:** Document OS image whitelisting for offchain auth server.
+The `os_image_hash` is in the `digest.txt` file from the [meta-dstack release](https://github.com/Dstack-TEE/meta-dstack/releases).
 
-For on-chain governance, see [On-Chain Governance](./onchain-governance.md).
+For detailed smart contract operations, see [On-Chain Governance](./onchain-governance.md).
 
 ---
 
 ### 3. Deploy Gateway as CVM
 
-> **TODO:** This section is incomplete. Gateway registration with auth server needs to be documented.
+The Gateway must be registered as an app in the DstackKms contract before deployment.
 
-Deploy the Gateway CVM:
+#### Register Gateway App
+
+```bash
+cd dstack/kms/auth-eth
+npx hardhat kms:create-app --network <network> --allow-any-device
+```
+
+Note the App ID from output (e.g., `0x32467b43BFa67273FC7dDda0999Ee9A12F2AaA08`).
+
+Set it as the gateway app in the KMS contract:
+
+```bash
+npx hardhat kms:set-gateway --network <network> <app-id>
+```
+
+#### Deploy Gateway CVM
 
 ```bash
 cd dstack/gateway/dstack-app/
@@ -252,32 +295,55 @@ cd dstack/gateway/dstack-app/
 Edit `.env`:
 
 ```bash
+# VMM connection
 VMM_RPC=unix:../../vmm-data/vmm.sock
+
+# Cloudflare (for DNS-01 ACME challenge)
 CF_API_TOKEN=your_cloudflare_api_token
+
+# Domain configuration
 SRV_DOMAIN=example.com
 PUBLIC_IP=$(curl -s ifconfig.me)
-ACME_STAGING=yes
+
+# Gateway app ID (from registration above)
+GATEWAY_APP_ID=0x32467b43BFa67273FC7dDda0999Ee9A12F2AaA08
+
+# Gateway URLs
+MY_URL=https://gateway.example.com:9202
+BOOTNODE_URL=https://gateway.example.com:9202
+
+# Other settings
+ACME_STAGING=no  # Set to 'yes' for testing
 OS_IMAGE=dstack-0.5.5
 ```
 
-Deploy:
+Run the script again - it will show the compose hash:
 
 ```bash
 ./deploy-to-vmm.sh
-# Press 'y' to confirm
+# Output: Compose hash: 0x700a50336df7c07c82457b116e144f526c29f6d8...
+```
+
+**Before pressing 'y'**, whitelist the compose hash:
+
+```bash
+cd ../../kms/auth-eth
+npx hardhat app:add-hash --network <network> --app-id <gateway-app-id> 0x<compose-hash>
 ```
 
-Update `vmm.toml` with KMS and Gateway URLs:
+Then return and confirm deployment.
+
+#### Update VMM Configuration
+
+After Gateway is running, update `vmm.toml` with KMS and Gateway URLs:
 
 ```toml
 [cvm]
 kms_urls = ["https://kms.example.com:9201"]
 gateway_urls = ["https://gateway.example.com:9202"]
 ```
 
-Restart dstack-vmm.
-
-> **TODO:** Document Gateway registration with offchain auth server.
+Restart dstack-vmm to apply changes.
 
 ---
 
@@ -349,9 +415,22 @@ gateway_urls = ["https://gateway.example.com:9202"]
 
 After setup, deploy apps via the VMM dashboard or CLI.
 
-> **TODO:** Document app registration with offchain auth server.
+### Register App
+
+Each app needs to be registered in the DstackKms contract:
+
+```bash
+cd dstack/kms/auth-eth
+npx hardhat kms:create-app --network <network> --allow-any-device
+```
+
+Note the App ID from output. Then whitelist your compose hash:
+
+```bash
+npx hardhat app:add-hash --network <network> --app-id <app-id> 0x<compose-hash>
+```
 
-For on-chain governed apps, see [On-Chain Governance](./onchain-governance.md).
+For detailed smart contract operations, see [On-Chain Governance](./onchain-governance.md).
 
 ### Deploy via UI
 
@@ -360,7 +439,7 @@ Open `http://localhost:9080`:
 ![App Deploy](assets/app-deploy.png)
 
 - Select the OS image
-- Enter the App ID (from auth server registration)
+- Enter the App ID (from registration above)
 - Upload your `docker-compose.yaml`
 
 After startup, click **Dashboard** to view:
diff --git a/docs/onchain-governance.md b/docs/onchain-governance.md
@@ -14,54 +14,95 @@ On-chain governance adds:
 - Production dstack deployment with KMS and Gateway as CVMs (see [Deployment Guide](./deployment.md))
 - Ethereum wallet with funds on Sepolia testnet (or your target network)
 - Node.js and npm installed
+- Alchemy API key (for Sepolia) - get one at https://www.alchemy.com/
 
 ## Deploy DstackKms Contract
 
 ```bash
 cd dstack/kms/auth-eth
 npm install
 npx hardhat compile
-PRIVATE_KEY=<your-key> npx hardhat kms:deploy --with-app-impl --network sepolia
+PRIVATE_KEY=<your-key> ALCHEMY_API_KEY=<your-key> npx hardhat kms:deploy --with-app-impl --network sepolia
 ```
 
-Note the deployed contract address.
+The command will prompt for confirmation. Sample output:
+
+```
+✅ DstackApp implementation deployed to: 0x5FbDB2315678afecb367f032d93F642f64180aa3
+DstackKms Proxy deployed to: 0x9fE46736679d2D9a65F0992F2272dE9f3c7fa6e0
+Implementation deployed to: 0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512
+```
+
+Note the proxy address (e.g., `0x9fE4...`).
+
+Set environment variables for subsequent commands:
+
+```bash
+export KMS_CONTRACT_ADDRESS="<DstackKms-proxy-address>"
+export PRIVATE_KEY="<your-private-key>"
+export ALCHEMY_API_KEY="<your-alchemy-key>"
+```
 
 ## Configure KMS for On-Chain Auth
 
-Update KMS to use webhook auth mode pointing to your auth-api service.
+The KMS CVM includes an auth-api service that connects to your DstackKms contract. Configure it via environment variables in the KMS CVM:
 
-> **TODO:** Document auth-api service deployment and KMS webhook configuration.
+```bash
+KMS_CONTRACT_ADDR=<your-dstack-kms-contract-address>
+ETH_RPC_URL=<ethereum-rpc-endpoint>
+```
+
+Note: The auth-api uses `KMS_CONTRACT_ADDR`, while Hardhat tasks use `KMS_CONTRACT_ADDRESS`.
+
+The auth-api validates boot requests against the smart contract. See [Deployment Guide](./deployment.md#2-deploy-kms-as-cvm) for complete setup instructions.
 
 ## Whitelist OS Image
 
 ```bash
-cd dstack/kms/auth-eth
-npm install
 npx hardhat kms:add-image --network sepolia 0x<os-image-hash>
 ```
 
-The `os_image_hash` is in the `digest.txt` file from the image build.
+Output: `Image added successfully`
+
+The `os_image_hash` is in the `digest.txt` file from the guest OS image build (see [Building Guest Images](./deployment.md#building-guest-images)).
 
 ## Register Gateway App
 
 ```bash
 npx hardhat kms:create-app --network sepolia --allow-any-device
 ```
 
-Note the App ID from the output.
+Sample output:
+
+```
+✅ App deployed and registered successfully!
+Proxy Address (App Id): 0x75537828f2ce51be7289709686A69CbFDbB714F1
+```
+
+Note the App ID (Proxy Address) from the output.
 
 Set it as the gateway app:
 
 ```bash
 npx hardhat kms:set-gateway --network sepolia <app-id>
 ```
 
-Add the compose hash to the whitelist:
+Output: `Gateway App ID set successfully`
+
+Add the gateway's compose hash to the whitelist. To compute the compose hash:
+
+```bash
+sha256sum /path/to/gateway-compose.json | awk '{print "0x"$1}'
+```
+
+Then add it:
 
 ```bash
 npx hardhat app:add-hash --network sepolia --app-id <app-id> <compose-hash>
 ```
 
+Output: `Compose hash added successfully`
+
 ## Register Apps On-Chain
 
 For each app you want to deploy:
@@ -72,15 +113,25 @@ For each app you want to deploy:
 npx hardhat kms:create-app --network sepolia --allow-any-device
 ```
 
+Note the App ID from the output.
+
 ### Add Compose Hash
 
+Compute your app's compose hash:
+
+```bash
+sha256sum /path/to/your-app-compose.json | awk '{print "0x"$1}'
+```
+
+Then add it:
+
 ```bash
 npx hardhat app:add-hash --network sepolia --app-id <app-id> <compose-hash>
 ```
 
 ### Deploy via VMM
 
-Use the App ID when deploying through the VMM dashboard or CLI.
+Use the App ID when deploying through the VMM dashboard or [VMM CLI](./vmm-cli-user-guide.md).
 
 ## Smart Contract Reference
 
