docs: add Chopsticks testing infrastructure for runtime migrations

drewstone · claude · drewstone · commit c7f0bb2cf565 · 2025-11-12T17:40:33.000-03:00
Added comprehensive Chopsticks testing setup for validating the Polkadot SDK stable2503 runtime migration: - Mainnet and testnet fork configurations - Complete README with setup instructions and best practices - Package.json for Node.js dependencies - .gitignore for generated files and databases Chopsticks enables safe testing of runtime upgrades by forking live chain state locally, allowing validation of storage migrations without risk to production networks. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/chopsticks/.gitignore b/chopsticks/.gitignore
@@ -0,0 +1,25 @@
+# Node modules
+node_modules/
+
+# Database files (chain state cache)
+db/*.sqlite
+db/*.sqlite-shm
+db/*.sqlite-wal
+
+# Test outputs
+output/
+*.html
+*.json
+
+# Coverage reports
+coverage/
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# OS files
+.DS_Store
+Thumbs.db
diff --git a/chopsticks/README.md b/chopsticks/README.md
@@ -0,0 +1,285 @@
+# Tangle Network - Chopsticks Testing Suite
+
+This directory contains configuration files and tests for validating Tangle runtime upgrades using [Chopsticks](https://github.com/AcalaNetwork/chopsticks), a powerful tool for forking and testing Substrate-based blockchains.
+
+## Overview
+
+Chopsticks enables safe, local testing of runtime migrations by creating a fork of the live Tangle network. This allows us to:
+
+- Test runtime upgrades against real mainnet state
+- Validate storage migrations without risk
+- Debug issues before deploying to production
+- Simulate complex scenarios (governance, XCM, etc.)
+
+## Prerequisites
+
+- **Node.js** >= 18.0.0
+- **Rust** toolchain with wasm32 target
+- **Tangle node** built with `try-runtime` feature
+
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+cd chopsticks
+npm install
+```
+
+### 2. Build Runtime with Try-Runtime
+
+```bash
+# From repository root
+cargo build --release -p tangle-mainnet-runtime --features=try-runtime
+cargo build --release -p tangle-testnet-runtime --features=try-runtime
+```
+
+### 3. Fork Tangle Network
+
+```bash
+# Fork mainnet
+npm run fork:mainnet
+
+# Or fork testnet
+npm run fork:testnet
+```
+
+The forked chain will be available at `ws://localhost:8000`.
+
+### 4. Connect with Polkadot.js Apps
+
+1. Open https://polkadot.js.org/apps
+2. Connect to `ws://localhost:8000`
+3. Interact with forked chain as if it were live
+
+### 5. Run Automated Tests
+
+```bash
+npm test
+```
+
+## Directory Structure
+
+```
+chopsticks/
+├── configs/
+│   ├── tangle-mainnet.yml      # Mainnet fork configuration
+│   └── tangle-testnet.yml      # Testnet fork configuration
+├── tests/
+│   ├── migration.test.ts       # Migration testing suite
+│   └── integration.test.ts     # Integration tests
+├── db/
+│   └── *.sqlite                # Cached chain state (gitignored)
+├── output/
+│   └── *.json                  # Test outputs (gitignored)
+├── package.json
+├── tsconfig.json
+├── vitest.config.ts
+└── README.md
+```
+
+## Configuration Files
+
+### Mainnet Configuration (`configs/tangle-mainnet.yml`)
+
+Connects to Tangle mainnet RPC and forks the chain with the new runtime.
+
+**Key settings:**
+- `endpoint`: Live RPC endpoints
+- `wasm-override`: Path to new runtime WASM
+- `import-storage`: Custom storage for testing (Alice/Bob accounts)
+- `mock-signature-host`: Enables testing without real signatures
+
+### Testnet Configuration (`configs/tangle-testnet.yml`)
+
+Similar to mainnet but connects to Tangle testnet.
+
+## Usage Examples
+
+### Basic Forking
+
+```bash
+# Fork at latest block
+npx @acala-network/chopsticks --config=./configs/tangle-mainnet.yml
+
+# Fork at specific block
+npx @acala-network/chopsticks \
+  --config=./configs/tangle-mainnet.yml \
+  --block=1000000
+```
+
+### With Runtime Override
+
+```bash
+# Test new runtime against mainnet state
+npx @acala-network/chopsticks \
+  --config=./configs/tangle-mainnet.yml \
+  --wasm-override=../target/release/wbuild/tangle-mainnet-runtime/tangle_mainnet_runtime.compact.compressed.wasm
+```
+
+### Block Replay
+
+```bash
+# Analyze specific block
+npx @acala-network/chopsticks run-block \
+  --config=./configs/tangle-mainnet.yml \
+  --block=1000000 \
+  --output-path=./output/block-1000000.json \
+  --html \
+  --open
+```
+
+### Dry-Run Extrinsics
+
+```bash
+# Test extrinsic without committing
+npx @acala-network/chopsticks dry-run \
+  --config=./configs/tangle-mainnet.yml \
+  --extrinsic=0x... \
+  --html \
+  --open
+```
+
+## Testing Runtime Migrations
+
+### 1. Manual Testing via Polkadot.js
+
+```javascript
+// Connect to forked chain
+const api = await ApiPromise.create({
+  provider: new WsProvider('ws://localhost:8000')
+});
+
+// Check runtime version
+const version = await api.rpc.state.getRuntimeVersion();
+console.log('Runtime:', version.toHuman());
+
+// Simulate runtime upgrade
+const blockNumber = (await api.rpc.chain.getHeader()).number.toNumber();
+await api.rpc('dev_setStorage', {
+  Scheduler: {
+    Agenda: [[
+      [blockNumber + 1],
+      [{
+        call: { Inline: api.tx.system.setCode('0x...').toHex() },
+        origin: { system: 'Root' }
+      }]
+    ]]
+  }
+});
+
+// Execute upgrade
+await api.rpc('dev_newBlock', { count: 1 });
+
+// Verify success
+const events = await api.query.system.events();
+events.forEach(({ event }) => {
+  console.log(`${event.section}.${event.method}`);
+});
+```
+
+### 2. Automated Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run specific test file
+npx vitest run tests/migration.test.ts
+
+# Watch mode for development
+npm run test:watch
+
+# Generate coverage report
+npm run test:coverage
+```
+
+### 3. Try-Runtime CLI Integration
+
+```bash
+# Test migrations with try-runtime
+try-runtime \
+  --runtime ../target/release/wbuild/tangle-mainnet-runtime/tangle_mainnet_runtime.compact.compressed.wasm \
+  on-runtime-upgrade \
+  --checks=all \
+  live \
+  --uri ws://localhost:8000
+```
+
+## Best Practices
+
+### ✅ DO
+
+- Build runtime with `--features=try-runtime` for testing
+- Implement `pre_upgrade` and `post_upgrade` hooks
+- Test against both mainnet and testnet forks
+- Verify storage migrations are idempotent
+- Check weight consumption doesn't exceed limits
+- Test critical user flows after migration
+- Use try-runtime-cli for additional validation
+
+### ❌ DON'T
+
+- Deploy migrations without testing on fork
+- Iterate over unbounded storage
+- Forget to increment RuntimeVersion
+- Skip try-runtime checks
+- Test only happy paths
+
+## Troubleshooting
+
+### "Connection refused" error
+
+**Cause**: RPC endpoint unavailable or network issues
+
+**Solution**:
+- Check endpoint in config file
+- Try alternative RPC from `endpoint` list
+- Verify network connectivity
+
+### "WASM override not found" error
+
+**Cause**: Runtime WASM not built or wrong path
+
+**Solution**:
+```bash
+cargo build --release -p tangle-mainnet-runtime --features=try-runtime
+ls -lh ../target/release/wbuild/tangle-mainnet-runtime/*.wasm
+```
+
+### "Weight limit exceeded" error
+
+**Cause**: Migration consumes too much weight
+
+**Solution**: Implement multi-block migration or optimize code
+
+### Database corruption
+
+**Cause**: Interrupted fork or version mismatch
+
+**Solution**: Delete and recreate database
+```bash
+rm -rf db/*.sqlite
+```
+
+## Additional Resources
+
+- [Chopsticks Documentation](https://github.com/AcalaNetwork/chopsticks)
+- [Chopsticks Recipe Book](https://hackmd.io/@seadanda/Sk3qcRlM0)
+- [Polkadot SDK Runtime Migrations Guide](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/frame_runtime_upgrades_and_migrations/index.html)
+- [Try-Runtime CLI](https://github.com/paritytech/try-runtime-cli)
+- [Substrate Stack Exchange](https://substrate.stackexchange.com/)
+
+## Support
+
+For issues with Chopsticks:
+- [GitHub Issues](https://github.com/AcalaNetwork/chopsticks/issues)
+- [Polkadot Forum](https://forum.polkadot.network/)
+
+For Tangle-specific questions:
+- [Tangle Discord](https://discord.gg/tangle)
+- [Tangle GitHub](https://github.com/tangle-network/tangle)
+
+## License
+
+This testing suite is part of the Tangle Network project and follows the same license terms.
diff --git a/chopsticks/configs/tangle-mainnet.yml b/chopsticks/configs/tangle-mainnet.yml
@@ -0,0 +1,47 @@
+# Tangle Mainnet Chopsticks Configuration
+# This configuration forks Tangle mainnet for testing runtime migrations
+# Usage: npx @acala-network/chopsticks --config=./configs/tangle-mainnet.yml
+
+endpoint:
+  - wss://rpc.tangle.tools
+  - wss://archive-rpc.tangle.tools  # Fallback archive node
+
+# Mock signatures for testing without real keys
+mock-signature-host: true
+
+# Optional: Fork from specific block (useful for regression testing)
+# Uncomment and set block number to fork from a specific point
+# block: 1000000
+
+# Database for caching chain state (speeds up subsequent forks)
+db: ./chopsticks/db/tangle-mainnet.sqlite
+
+# Runtime logging level (0-5, higher = more verbose)
+# Use 5 for detailed migration debugging
+runtime-log-level: 5
+
+# IMPORTANT: Path to your new runtime WASM for testing migration
+# Build with: cargo build --release -p tangle-mainnet-runtime --features=try-runtime
+# Uncomment when testing runtime upgrade:
+# wasm-override: ./target/release/wbuild/tangle-mainnet-runtime/tangle_mainnet_runtime.compact.compressed.wasm
+
+# Import custom storage for testing
+# This sets up Alice and Bob accounts with funds for testing
+import-storage:
+  System:
+    Account:
+      # Alice account with funds for testing
+      - - "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"
+        - providers: 1
+          data:
+            free: "100000000000000000000000"  # 100k TNT with 18 decimals
+      # Bob account
+      - - "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty"
+        - providers: 1
+          data:
+            free: "100000000000000000000000"
+
+  # Optional: Override sudo key for testing privileged operations
+  # Uncomment if you need to test governance/sudo operations
+  # Sudo:
+  #   Key: "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"
diff --git a/chopsticks/configs/tangle-testnet.yml b/chopsticks/configs/tangle-testnet.yml
@@ -0,0 +1,38 @@
+# Tangle Testnet Chopsticks Configuration
+# This configuration forks Tangle testnet for testing runtime migrations
+# Usage: npx @acala-network/chopsticks --config=./configs/tangle-testnet.yml
+
+endpoint:
+  - wss://testnet-rpc.tangle.tools
+
+# Mock signatures for testing without real keys
+mock-signature-host: true
+
+# Optional: Fork from specific block
+# block: 1000000
+
+# Database for caching chain state
+db: ./chopsticks/db/tangle-testnet.sqlite
+
+# Runtime logging level (0-5, higher = more verbose)
+runtime-log-level: 5
+
+# IMPORTANT: Path to your new runtime WASM for testing migration
+# Build with: cargo build --release -p tangle-testnet-runtime --features=try-runtime
+# Uncomment when testing runtime upgrade:
+# wasm-override: ./target/release/wbuild/tangle-testnet-runtime/tangle_testnet_runtime.compact.compressed.wasm
+
+# Import custom storage for testing
+import-storage:
+  System:
+    Account:
+      # Alice account with funds
+      - - "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"
+        - providers: 1
+          data:
+            free: "100000000000000000000000"
+      # Bob account
+      - - "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty"
+        - providers: 1
+          data:
+            free: "100000000000000000000000"
diff --git a/chopsticks/package.json b/chopsticks/package.json
