Development guide

The repository contains Solidity contracts and Foundry tooling plus a static Next.js frontend.

Requirements

• Foundry
• uv and Halmos 0.3.3 for symbolic tests
• Node.js 22 or newer
• pnpm 10.33.3
• jq, curl, and a POSIX shell for rehearsals

Repository map

Setup

git submodule update --init --recursive
forge build

cd app
pnpm install --frozen-lockfile
pnpm abis

Contract validation

forge fmt --check
forge build
forge test
forge test --match-test testFuzz --fuzz-runs 10000
bash scripts/symbolic.sh
bash scripts/coverage.sh
bash scripts/e2e-anvil.sh
ROBINHOOD_RPC_URL=https://rpc.mainnet.chain.robinhood.com bash scripts/e2e-production-fork.sh
bash scripts/e2e-testnet-safes.sh

The vault tests cover deposits, withdrawals, donations, rounding, slippage atomicity, vote checkpoints, adversarial first-deposit scenarios, fuzzed conservation, and stateful invariants. Changes to asset/share accounting require new adversarial rounding tests.

Frontend validation

cd app
pnpm abis
pnpm typecheck
pnpm build
pnpm test:e2e
cd ..
bash scripts/e2e-frontend-anvil.sh

Generated ABIs must match Foundry artifacts. Application code resolves addresses from manifests, not source constants.

Configuration

config/testnet.json drives local and testnet deployment. config/mainnet.json is a production input, not market authorization. config/chains.json pins canonical mainnet assets and feeds.

STONK and stSTONK use 9 decimals. PRICE uses USD18. Governance durations use seconds because stSTONK and Governor implement timestamp clocks.

Deployment discipline

1. Freeze a clean commit and exact toolchain.
2. Run all validation from a clean checkout.
3. Rehearse the exact configuration on a current fork.
4. Review the broadcast transaction list and deterministic output manifest.
5. Broadcast through a private RPC.
6. Independently verify live bytecode, roles, Safes, assets, feeds, and configuration.
7. Build the frontend from the same manifest and release commit.

For the live testnet, make verify-testnet-deployment checks runtime hashes, token/vault/governance wiring, active policies, markets, prices, seeded vault state, hardened Safe configuration, and the complete role handoff against the committed manifest.

Production-like testnet deployment

Use disposable testnet-only keys. The Genesis and Guardian Safes are separate canonical Safe 1.4.1, 2-of-3 accounts and may share at most one owner. Never reuse these automated rehearsal keys on mainnet.

scripts/generate-testnet-safe-env.sh
source .testnet-safe.env

make deploy-testnet-safes
export GENESIS_MULTISIG=$(jq -r .genesis deployments/46630-safes.json)
export GUARDIAN_MULTISIG=$(jq -r .guardian deployments/46630-safes.json)
make deploy-testnet-secure
make bootstrap-testnet-secure
make verify-testnet-deployment

The environment must provide DEPLOYER_PRIVATE_KEY, RPC_TESTNET, three public owner addresses for each Safe (GENESIS_SAFE_OWNER_1..3 and GUARDIAN_SAFE_OWNER_1..3), and two signing keys for each Safe (GENESIS_SAFE_OWNER_KEY_1..2 and GUARDIAN_SAFE_OWNER_KEY_1..2). The signing keys selected for bootstrap must correspond to owners in their Safe. The bootstrap creates all configured markets through the Timelock, proves Guardian cancellation, shuts down and restarts guarded modules, purchases and redeems the bootstrap bond, stakes STONK, and reruns independent verification.

Commit deployments/46630-safes.json and deployments/46630.json together. They contain public addresses only; private keys remain in ignored local storage and CI environment secrets.

Never hand-edit generated addresses or treat a successful deployment transaction as market-launch authorization.

Contribution rules

• Preserve explicit unit suffixes such as 9, 18, and Bps.
• Validate at external boundaries and fail closed on oracle or manifest ambiguity.
• Keep governance permissions least-privileged.
• Add unit, fuzz, or invariant coverage for every new accounting path.
• Update canonical docs and ABI exports in the same change.
• Do not add token emissions, external operators, or another representation without a complete economic and security review.