Contributing

Mirrored from CONTRIBUTING.md in the repository — edit that file, not this page.

Contributions are welcome; the bar is that every change keeps the full verification battery green and does not weaken a security property. Read SECURITY.md first: never open a public issue for a vulnerability.

Setup

  • Foundry — CI pins v1.7.1; use the same locally (foundryup --install v1.7.1) so the gas snapshot check is exact. Contracts need the submodules: git submodule update --init --recursive.
  • Node 20 (CI) — npm ci in each of offchain/, packages/sdk/, packages/mcp/, subgraph/, dapp/. Build packages/sdk before packages/mcp; the MCP server imports the SDK's dist/.
  • Python 3.12 (CI; 3.9 is the floor) — cd packages/python-sdk && python -m venv .venv && .venv/bin/pip install -e .
  • mdBook 0.4.40 for the docs (mdbook build at the repo root; needs Node on PATH for the link preprocessor). scripts/devstack.sh up starts the local development network in one command.

The repo layout is in README.md; the design is in ARCHITECTURE.md.

Before you push: the battery

Run everything that your change can affect. All of it runs in CI on every push and pull request (eight jobs: contracts, offchain, packages, subgraph, verify-deploy gate, dapp, python-sdk, docs).

SurfaceCommandExpect
Contractsforge test226/226 across 11 suites
Gas regressionforge snapshot --checkno diffs against .gas-snapshot
Offchain typescd offchain && npx tsc --noEmitclean
Offchain suitesnpm run test:boundary, test:adapters, test:results, test:ha, test:billing, test:templates11, 19, 8+9, 7, 7, 6
TS SDKcd packages/sdk && npm run build && npm testartifact + results-core drift checks OK, 19/19
MCPcd packages/mcp && npm run build && npm testcompiles, 5/5
Python SDK.venv/bin/python -m unittest discover -s tests7/7
Subgraphcd subgraph && npm run codegen && npm run buildBuild completed
dAppcd dapp && npm run buildgreen
Docsmdbook buildbuilds; no dead links (see below)

The live scenarios (paid x402 loop, relay, HA failover, billing, Python interop) are scripted in docs/testing-guide.md; run the one your change touches.

Conventions that bite if skipped

  • After any contract change run cd offchain && npm run gen-abis. It regenerates offchain/src/sdk/artifacts.ts (ABIs + bytecode the deploy script uses) and the SDK's copy; packages/sdk's check:artifacts fails the build if they drift. Forgetting this deploys stale bytecode on your local development network and produces confusing reverts.
  • Gas snapshot — regenerate with forge snapshot at the repo root only, in the same commit as the contract change. Do not commit a snapshot anywhere else.
  • Pinned Merkle vectors — the evidence-format vectors are shared by three implementations (offchain ethers, packages/sdk viem, packages/python-sdk). Never change them without a format version bump; a drift in any implementation fails its suite by design.
  • Real-chain safety — nothing may fall back to the public Anvil mnemonic once REAL_CHAIN is set; verify-deploy must keep rejecting a local-development deployment (that is the CI gate's negative test). Keep it that way.
  • Docs — chapters live under docs/ and are listed in docs/SUMMARY.md. Root documents (ARCHITECTURE, SECURITY, NEXT-STEPS, this file, the CHANGELOG, package READMEs) are mirrored into the book by scripts/mdbook-repo-links.mjs; link to them with normal relative Markdown links and the preprocessor resolves them. Update the numbers you touch (test counts, defaults) — the book is meant to be exact.
  • Secrets and state — .env, node_modules, out/, book-out/, .devstack/ and CHECKPOINT-*.md are gitignored on purpose. The local development network uses the public Anvil accounts; never commit a real key.

Commits and pull requests

  • One logical change per commit, imperative subject line, body says why and what was verified (forge 226/226, demo conservation exact, and so on).
  • Note user-visible changes in CHANGELOG.md under Unreleased.
  • A pull request should say which battery rows you ran. CI must be green; the gas snapshot job is exact, so include the regenerated snapshot when gas legitimately moves.
  • Security-relevant changes (payments, staking, disputes, arbitration, account abstraction, deploy scripts) get a second reader and, where the change is economic, a note in the relevant design record under docs/design/.