Development guide

This repository contains Solidity contracts and Foundry deployment tooling, a Next.js application, and a Bun-based permissionless rebase service.

Prerequisites

• Foundry with forge, cast, and anvil
• Node.js 22 and pnpm 10
• Bun for the keeper
• Git submodules for Foundry dependencies

Repository map

Setup

git submodule update --init --recursive
forge build

cd app
pnpm install --frozen-lockfile
pnpm abis

cd ../keeper
bun install --frozen-lockfile

The application tolerates a missing deployment manifest and renders an explicit unavailable state. Contract interactions require deployments/<chainId>.json generated by a deployment or local end-to-end script.

Contract workflow

forge fmt --check
forge build
forge test

Run a focused test while iterating:

forge test --match-path test/policies/BondDepository.t.sol -vv
forge test --match-test testFullLifecycle -vvv

Tests must exercise authorization failures and boundary conditions, not only happy paths. New accounting behavior should include fuzz or invariant coverage when its state space is larger than a few explicit cases.

Architecture rules

• Modules expose reusable capabilities and accept writes only from active policies with exact Kernel selector permission.
• Policies compose modules and enforce business rules and roles.
• Avoid granting a policy a selector it does not need.
• Store role identifiers as validated lowercase bytes32 values.
• Preserve 9-decimal STONK accounting and 18-decimal USD/feed accounting explicitly.
• Use full-precision mulDiv and round conservative values down.
• External token transfers must support standard, no-return and explicit-false behavior safely.
• A price failure must not be replaced with cached or offchain data.

Local end-to-end environment

The local script builds contracts, starts Anvil, deploys and seeds mocks, exports ABIs and deployment addresses, then exercises the integrated surfaces.

bash scripts/e2e-anvil.sh

For current production configuration against a Robinhood mainnet fork:

ROBINHOOD_RPC_URL=https://rpc.mainnet.chain.robinhood.com \
  bash scripts/e2e-production-fork.sh

Use a private, trusted RPC for deployment rehearsal. Public endpoints may be rate-limited or disagree near the chain head.

Application workflow

cd app
pnpm deployments
pnpm dev

Environment variables are documented in app/README.md. Use a browser-safe, rate-limited and origin-restricted RPC URL. Never expose a private operator RPC or keeper key through NEXT_PUBLIC_*.

The app is statically exported. All routes must be prerenderable and must handle disconnected wallets, missing manifests, slow RPC reads, wrong networks, reverted simulation, transaction replacement and confirmation errors.

UI quality gates

• one descriptive h1 per route;
• keyboard-visible focus and complete mobile navigation focus handling;
• minimum 40-pixel interactive targets;
• no horizontal page overflow at supported mobile widths;
• semantic tables, labels, tab state and live regions;
• loading dimensions that avoid layout shift;
• explicit empty, unavailable, stale, pending, confirmed and failed states;
• numeric values rendered tabular and with units;
• transaction hashes available from submission through confirmation; and
• reduced-motion behavior for nonessential animation.

Build and browser test:

pnpm build
pnpm test:e2e

Documentation workflow

Public documentation lives in docs/*.md. The application documentation portal reads the canonical Markdown at build time. A documentation change therefore ships both as repository documentation and as the styled web experience.

When behavior changes:

1. update the contract, tests and ABI;
2. update the relevant protocol, architecture, governance, security or production document;
3. verify internal links and code examples;
4. rebuild the app so every public document is prerendered; and
5. inspect desktop and mobile rendering.

Do not document intended behavior that the current source does not implement. Call out deployment-specific values as defaults or inputs and direct readers to live onchain state.

ABI and deployment manifests

After building contracts:

cd app
pnpm abis
pnpm deployments

pnpm abis exports selected Foundry artifacts into typed application modules. pnpm deployments converts available chain manifests into a tolerant static bundle. Review generated diffs: stale ABIs can make a successful build present the wrong transaction surface.

Application and keeper code must resolve addresses from manifests, not source constants. The manifest and deployed bytecode must come from the same reviewed release.

Keeper workflow

cd keeper
bun install --frozen-lockfile
bun run typecheck
bun run src/index.ts

Configure at least two RPC URLs for production and use a distinct low-balance key for each independent instance. The keeper needs no protocol role. Validate /healthz, /readyz, and /metrics, including partial RPC failure, low gas, stale oracle, module inactivity and rebase backlog states.

Configuration changes

config/mainnet.json and config/testnet.json are deployment inputs. Validate changes against the schemas consumed by Deploy.s.sol and the referenced addresses in config/chains.json.

For asset changes, confirm token/feed addresses, bytecode, descriptions, decimals, heartbeat, cap, haircut, category, maximum deviation and Robinhood pause behavior. For governance changes, express durations in seconds because gSTONK and Governor use timestamp clocks.

Production boundary

Local tests and static builds do not authorize deployment. Production work must follow the runbook, including independent audit, fork rehearsal, transaction simulation, source verification, Safe validation, role checks, production-origin wallet testing, monitoring and governance bootstrap.

Never use the testnet seed flow on mainnet. Mainnet treasury funding and market creation are explicit governed bootstrap actions.