# 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):

```bash
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

```bash
# 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`](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`](security-model.md) — threat model + mitigations, and
  the tracked pre-production follow-ups.
- [`testing.md`](testing.md) — full test strategy per layer and how to run
  each one.
- [`../llms-full.txt`](../llms-full.txt) — the complete machine-first
  reference (concepts, endpoints, both grant flows, configuration, errors,
  security summary) in one file.