Code map
Repository
| Path | Holds |
|---|---|
src/ | The signer: one crate, a library and the binaries built on it, mapped module by module below |
tables/ | The instruction table per cluster (zink-testnet.json), generated by apps/idl-table from the programs’ IDLs, which are not checked in (IDL table). Not part of the crate yet |
config.example.toml | The annotated example config, embedded in the binary and written by config init |
skills/sa-forge-signer/ | The skill that teaches an agent to use the MCP tools (SKILL.md and references/tools.md), embedded in the binaries, served as MCP resources and written by sa-forge-signer-mcp skill install (Resources and the skill) |
apps/ | Extras a human runs beside the signer, each its own crate and workspace, kept out of the signer’s build (Building an app): apps/console/, apps/grant/ and apps/idl-table/ |
docs/ | This book (choices about the signer’s shape are in Design decisions): docs/src/ for chapters, docs/src/dev/ for working on the signer, docs/src/apps/ for the apps (Writing the docs) |
.mcp.json, scripts/dev/ | A Claude Code session’s link to the debug build: the sa-forge-signer-debug MCP server, and the script behind just mcp-dev that runs the debug service on a throwaway home in target/dev (Contributing) |
justfile | Recipes: just check (the gate), plus the docs and apps modules in docs/justfile and apps/justfile (just docs check, just apps console) |
scripts/ci/ | check.sh (the gate run by just check and CI), crate-age.sh (dependency age), docs-check.sh (just docs check), docker-toolchain.sh (the Dockerfile’s Rust matches rust-toolchain.toml) |
scripts/installer/ | install.sh: installs, updates or uninstalls the signer and the console on a host (Install and update) |
scripts/skills/ | gpui-kit.sh: installs GPUI Kit’s Claude skills at the console’s gpui-kit version (GPUI Kit skills) |
scripts/git-review/ | The local review workflow, just mr-open to just mr-approve (Local review with git-review) |
.github/workflows/ | ci.yml (the gate and a Docker build), pages.yml (publishes this book), release-plz.yml (release PRs and tags), release-binaries.yml (attested binaries for each tag) |
Dockerfile | The container image (Running in Docker) |
PLAN.md, CHANGELOG.md, CONTRIBUTING.md, SECURITY.md | Included in this book as Plan, Changelog, Contributing and Security |
Modules
One crate: a library (lib.rs, not a public API) that each binary calls into. Each module’s //! comment is the authority if this page drifts.
| Module | Owns |
|---|---|
main.rs | The sa-forge-signer binary: only calls cli::main |
cli.rs | The CLI (check, sign, halt, resume, key, token, audit, config) and exit codes |
bin/serve.rs | The sa-forge-signer-serve binary: only calls serve_cli::main |
serve_cli.rs | sa-forge-signer-serve’s command line (--config) |
bin/mcp.rs | The sa-forge-signer-mcp binary: only calls mcp_cli::main |
mcp_cli.rs | sa-forge-signer-mcp: MCP on standard input and output, forwarded to a running service’s /mcp with a bearer token; reads no key or config. Also skill print and skill install |
config.rs | Loading and validating config.toml: keys, classes, approval, limits, serve tokens, each key’s policy digest; config init and config show |
cluster.rs | Built-in cluster profiles: genesis hash, default RPC, explorer, and the programs any key may call |
payload.rs | The forge-mcp build_* payload (version 1): an instruction list, not a serialized transaction |
transfer.rs | Funding payloads: a plain System Program transfer in the same shape forge-mcp returns |
checks.rs | Structural checks on the compiled message; none decode game instructions |
policy.rs | Every check check and sign make, as one pure evaluate over the request, the key’s policy and Facts, at a stage (Check, BeforeSimulation, AfterSimulation); returns every result in order. New checks go here |
instruction_table.rs | The hash-checked instruction table from apps/idl-table, and its findings (instructions, accounts, profile) on a compiled message, without decoding anything |
facts.rs | The reads behind evaluate: the halt, the approved policy, the key’s usage from the audit log, and the RPC facts, read one at a time in check order |
engine/mod.rs | The check and sign pipeline and its report: gather facts and evaluate, simulate, the cap gate, the intent, in that order |
engine/fresh.rs | The gates that may rebuild the transaction with a fresh blockhash: approval, the stale-blockhash guard and the duplicate guard |
engine/approval.rs | The confirm prompt at the controlling terminal |
engine/send.rs | Sending, and polling until the outcome is proven or unknown |
engine/tests.rs | The pipeline’s tests, in one file because they share its fakes |
rpc.rs | The minimal Solana JSON-RPC client: only the calls the signer needs |
keystore.rs | The file key store: <key_dir>/<name>.json, 0700 directory, 0600 files; key create, import and destroy |
audit.rs | The append-only, hash-chained JSONL audit log, read back from the end for the checks (recent, walk_back), and the per-key signing lock |
halt.rs | Halts under state_dir/halts/: setting one, resume at the terminal, and the halt_after_unknown trip |
policy_approval.rs | Policy approvals under state_dir/policy/: key approve at the terminal, and the policy refusal |
trace.rs | Opt-in tracing on stderr from SA_FORGE_SIGNER_LOG: the subscriber, and what spans may never carry |
bench.rs | Test-only: just bench, timings of the audit log’s reads on synthetic logs |
serve/mod.rs | serve: the listener and its drain on shutdown, JSON over HTTP at /v1/check, /v1/sign and /v1/halt, bearer-token auth, and the Host and Origin check |
serve/mcp.rs | MCP at /mcp, revision 2026-07-28: the JSON-RPC handler, server/discover, the tools check, sign, key_show and halt, and the resources (MCP conformance) |
serve/mcp_sdk_tests.rs | Tests only: the handler’s messages read back with the Rust MCP SDK’s types |
mcp_wire.rs | What the service and the stdio relay share of that revision: its _meta keys, header names and error codes, and how a header value mirrors the body |
skill.rs | The agent skill built in from skills/sa-forge-signer/: the llms.txt and llms-full.txt texts made from it, and skill install |
url.rs | URL rules shared by the config, the service and the stdio proxy: https, or http only to a loopback host |
text.rs | Caller text (summary, intent, a halt reason): escaped and capped for a terminal, clipped for the audit log |
Checks and gates: just check runs scripts/ci/check.sh (fmt, clippy, tests, shellcheck, advisories, dependency age), the same gate as CI.