Offline, read-only PSBT intent verifier. psbt-guard checks whether a Partially Signed Bitcoin Transaction (PSBT, BIP 174) matches a payment intent you declare — recipients, amounts, fee limits — and highlights conditions that deserve review before you sign.
Status: MVP complete through milestone M3.
inspectreports structural findings PG101-PG105;verifyvalidates TOML/JSON intent manifests and runs absolute-fee, recipient, amount, undeclared-output and fee-ceiling rules PG201 and PG301-PG304;explainprovides the stable catalogue entry for every implemented code. SeePLAN.md.
Bitcoin Core already decodes PSBTs structurally. psbt-guard answers a different question: "does this transaction do what I think it does?" You declare intent in a small manifest; the tool compares the PSBT against it and reports structured, plain-language findings — unexpected recipients, amount mismatches, undeclared outputs, excessive fees, non-standard sighashes, missing UTXO data.
psbt-guard never:
- requests, loads, generates or stores private keys;
- signs a transaction;
- broadcasts a transaction;
- makes network requests.
It operates entirely on PSBT data, public wallet information and your declared intent. Its verdict is advisory review guidance — not a guarantee of safety. A clean report means none of its rules fired, nothing more.
psbt-guard inspect <PSBT> # structural findings, no intent needed
psbt-guard verify <PSBT> --intent intent.toml # verify against declared intent
psbt-guard explain PG301 # explain a finding code<PSBT> may be a file path, a base64 string, or - for stdin. Add --format json
to inspect or verify for deterministic machine-readable output. Intent manifests
are TOML (primary) or JSON selected by the .json extension — see
examples/intent.toml. Finding codes are case-insensitive
when passed to explain.
M2 can allow a declared count of outputs that are not recipients as change
candidates. It cannot prove those outputs return to your wallet. Keep
max_change_outputs as low as possible and independently review every output;
descriptor-based change ownership verification is planned for M4.
| Code | Meaning |
|---|---|
0 |
Analysis completed with no policy violations |
1 |
Policy violations or critical findings |
2 |
Malformed input or operational error |
cargo build --workspace
cargo run -p psbt-guard-cli -- --helpRequires Rust 1.74+. The workspace contains psbt-guard-core (reusable analysis
library, no I/O) and psbt-guard-cli (the psbt-guard binary).
macOS/Homebrew note: if
cargo/rustcare "not found", Rust was likely installed viabrew install rustup(keg-only). Runexport PATH="/opt/homebrew/opt/rustup/bin:$PATH"(and consider adding it to your shell profile) before building.
PLAN.md— problem statement, architecture, milestonesdocs/rule-catalogue.md— stable finding codesdocs/threat-model.md— what it does and doesn't defend againstdocs/learning-journal.md— Rust/Bitcoin concepts log
Dual-licensed under MIT or Apache-2.0, at your option. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work shall be dual-licensed as above, without additional terms.