Contributing#

Practical guide for working in this repo. Read ../../CLAUDE.md (repo root) first — it's the canonical agent/contributor orientation and takes precedence over anything here if the two ever disagree.

Prerequisites#

• Rust (stable toolchain; the workspace is 2021-edition).
• Foundry (forge, anvil, cast) — installed at ~/.foundry/bin on the reference dev box. anvil must be reachable on PATH to run the live-chain end-to-end tests (crates/grantor-issuer/tests/grant_*_e2e.rs).

Environment variables used on this box (add to your shell profile or export per-session):

export PATH="$HOME/.foundry/bin:$HOME/.cargo/bin:$PATH"
export CARGO_TARGET_DIR=~/.cargo-target   # cargo builds land here, not ./target

Note: the interactive shell on this box has been observed to filter/truncate grep/ls/git ls-files stdout in some configurations. If a command's output looks suspiciously short or empty, redirect it to a file and read that file instead of trusting the terminal echo.

Build & test#

# whole Rust workspace: unit tests + Poem HTTP endpoint tests + both
# live-anvil e2e tests (needs anvil on PATH, see above)
cargo test --workspace

# Solidity: unit + invariant/fuzz tests
cd contracts && forge test

# lint — keep this clean before any review/merge
cargo clippy --workspace --all-targets

See testing.md for what each layer actually covers.

Layout#

contracts/                     # Solidity + Foundry — GrantorRegistry (trust anchor + billing)
  src/                          #   GrantorRegistry.sol
  test/                         #   unit tests + invariant/fuzz + mocks/
crates/
  grantor-verify/                 # Rust lib — JWT verify + RFC-7638 key id + TrustSource trait
  grantor-issuer/                  # Rust — the OIDC/OAuth2 issuer (Poem HTTP server)
    src/http/                    #   discovery, jwks, /authorize (+ page), /token (+ code exchange, assertion)
    src/{cache,gate,chain}.rs    #   on-chain isActive/isAgentKey reads + the fail-closed cache
    src/{config,clients,state,token,login}.rs
    tests/                       #   grant_a_e2e.rs / grant_c_e2e.rs (live-anvil)
docs/
  llms.txt / llms-full.txt       # machine-first reference (read these for the "what")
  guide/, api/                    # human guides + rendered OpenAPI
  internal/                       # this directory — contributor docs
landing/                         # the marketing/landing site (static)

Conventions#

• Test-first. Work is decomposed into bite-sized failing-test → implement → pass → commit steps. Don't write implementation ahead of a test that pins the behavior.
• Frequent, small commits. One reviewable chunk per commit; don't batch unrelated changes.
• Pristine clippy. cargo clippy --workspace --all-targets should be clean before a review or merge — this has held for every completed piece of work.
• Review before moving on. Each chunk of work is reviewed before it's considered done; Critical/Important findings get fixed in a follow-up commit before continuing, not deferred silently.
• The contract is money-handling code. Anything touching GrantorRegistry.sol gets disproportionate scrutiny: minimal owner powers, immutable treasury, checks-effects-interactions, and new invariant/fuzz coverage for anything that touches a balance.

Where to look for more#

• security-model.md — threat model + mitigations, and the tracked pre-production follow-ups.
• testing.md — full test strategy per layer and how to run each one.
• ../llms-full.txt — the complete machine-first reference (concepts, endpoints, both grant flows, configuration, errors, security summary) in one file.