Skip to content

README.md

Latest commit

 

History

History
116 lines (89 loc) · 4.86 KB

README.md

File metadata and controls

116 lines (89 loc) · 4.86 KB

scripts

Dev stack orchestration and CLI tools for the post-quantum account abstraction system. One command spins up a local Nitro devnode, deploys all contracts (EntryPoint, Stylus verifier, PQ module), and starts the Alto bundler.

Architecture

flowchart TD
    DS[dev-stack.sh] -->|1| DN[Nitro Devnode\nDocker · port 8547]
    DS -->|2| EP[Deploy EntryPoint v0.7]
    DS -->|3| SV[Deploy Stylus Verifier\ncargo stylus deploy]
    DS -->|4| PM[Deploy PQValidatorModule\ncast send --create]
    DS -->|5| AL[Start Alto Bundler\nNode.js · port 4337]
    DS -->|6| ENV[Write .env.local]

    E2E[e2e-test.sh] -->|sources| ENV
    E2E -->|deploys| KN[Kernel v3 + Factory]
    E2E -->|installs| PQV[PQ Validator on Kernel]
    E2E -->|executes| UO[PQ-signed UserOp]

    DEMO[demo/setup.sh] -->|sources| ENV
    DEMO -->|deploys| KN
    DEMO -->|installs| PQV
    DEMO -->|writes| DENV[demo/.env]
Loading

Prerequisites

Commands (checked by dev-stack.sh at startup):

Tool Purpose
docker Runs Nitro devnode container
cast / forge Foundry — chain interaction + contract compilation
cargo-stylus Deploys WASM contracts to Stylus
node Runs Alto bundler
jq JSON parsing
curl Health checks
python3 Arithmetic in e2e-test.sh

External repos (expected at ~/Developer/tools/dlt/):

Repo Path Purpose
nitro-devnode ~/Developer/tools/dlt/nitro-devnode/ run-dev-node.sh starts Docker container
alto ~/Developer/tools/dlt/alto/ ERC-4337 bundler CLI
account-abstraction ~/Developer/tools/dlt/account-abstraction/ EntryPoint v0.7 bytecode artifacts
kernel ~/Developer/tools/dlt/kernel/ Kernel v3 contracts (dev branch)

Quick Start

# Start everything (devnode + contracts + bundler)
./scripts/dev-stack.sh

# Run full E2E test (Kernel + PQ UserOp)
./scripts/e2e-test.sh

# Or just set up the demo environment
./demo/setup.sh

Script Inventory

Script What It Does
dev-stack.sh Starts devnode, deploys EntryPoint + Stylus verifier + PQ module, starts Alto bundler, writes .env.local
e2e-test.sh Deploys Kernel, installs PQ validator, generates ML-DSA keypair, signs and submits a PQ UserOp, verifies on-chain
demo/setup.sh Subset of e2e-test: deploys Kernel + installs PQ validator, writes demo/.env for the WalletConnect demo
spec_metadata.sh Collects git metadata (commit, branch, date) for thoughts documents

Manual Path

What dev-stack.sh does step-by-step:

  1. Preflight: Checks all required commands exist, Docker is running
  2. Clean state: Kills stale processes on ports 4337/8547, removes old nitro-dev container
  3. Start devnode: Runs run-dev-node.sh, waits for RPC at localhost:8547
  4. Deploy EntryPoint v0.7: Extracts bytecode from account-abstraction artifacts, deploys via cast send --create
  5. Deploy Stylus verifier: cargo stylus deploy from pq-validator/
  6. Deploy PQ module: Builds with forge build, deploys with cast send --create (constructor arg: verifier address)
  7. Fund test accounts: Sends 10 ETH to three well-known test addresses
  8. Start Alto: Launches bundler on port 4337 with --chain-type arbitrum --safe-mode false
  9. Health checks: Verifies chain ID, contract code exists, bundler responds
  10. Write .env.local: All deployed addresses + RPC endpoints

Cleanup runs on exit (Ctrl-C or script end): kills bundler, kills devnode, removes Docker container.

CLI Tools

Build:

cargo build --release --manifest-path scripts/cli/Cargo.toml
Binary Usage Output
pq-keygen pq-keygen --output /tmp/keys pk.bin (1,952 B), sk.bin (32 B seed)
pq-sign pq-sign --key sk.bin --hash 0x... --output sig.bin sig.bin (3,309 B)
pq-verify pq-verify --key pk.bin --hash 0x... --sig sig.bin Exit code 0/1

Outputs

File Generated By Contents
.env.local dev-stack.sh RPC, bundler URL, chain ID, deployed contract addresses, dev private key
demo/.env demo/setup.sh Same + Kernel account, ML-DSA seed, ECDSA validator, Reown project ID
.dev-stack-logs/ dev-stack.sh devnode.log, alto.log

Production Limitations

  • Hardcoded test keys: Uses well-known dev account private key. Never use these keys on public networks.
  • Local only: Scripts target localhost:8547. No Sepolia/mainnet deployment scripts yet.
  • External repo paths: Assumes specific directory layout at ~/Developer/tools/dlt/. Will fail if repos are elsewhere.
  • No idempotency: Re-running dev-stack.sh kills and redeploys everything. No incremental updates.
  • Gas estimates are conservative: 2M verification + 2M call gas limits are safe but wasteful. Production should tune these.