Metadata-Version: 2.4
Name: bip322-audit
Version: 0.16.0
Summary: Proof of control of a wallet's coins at a block: BIP-322 proofs per funded address plus the on-chain checks an auditor runs on their own node
Author: Embedded Nation AB
License-Expression: MIT
Project-URL: Homepage, https://github.com/embeddednation/bip322-audit
Project-URL: Changelog, https://github.com/embeddednation/bip322-audit/blob/main/CHANGELOG.md
Keywords: bitcoin,bip322,proof of control,audit,multisig,psbt
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Office/Business :: Financial :: Accounting
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: bip322-core<0.13,>=0.12.0
Provides-Extra: kernel
Requires-Dist: bip322-core[kernel]<0.13,>=0.12.0; extra == "kernel"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# bip322-audit

Proof of control of a wallet's coins at a block: one BIP-322 proof per funded
address, a block stamp inside the signed message, and the on-chain checks an
auditor runs on their own node. Built on
[bip322-core](https://github.com/embeddednation/bip322-core), which does the
BIP-322 work and never talks to a node; everything that does lives here, and
only through `bitcoin-cli`.

Two roles:

* **Owner**: `snapshot` (or `prove`, for given addresses), sign on the
  cosigners' devices, `finalize`. Needs a node with the wallet loaded
  (watch-only is enough). Everything lands under `<wallet>/snapshots/` in the directory `bip322 init` made.
* **Auditor**: `verify`, against any node that has the chain; `holdings` to
  look up single outputs or addresses. No wallet, no index, no key material,
  and nothing about the owner's wallet beyond the proven addresses.

The commands: `stamp`, `snapshot`, `prove`, `finalize`, `verify`, `holdings`,
`help`. With bip322-core installed they are also reachable as `bip322 audit ...`.

## Install

One line, into a fresh venv, with bip322-core pulled in:

```sh
python3 -m venv ~/.bip322 && ~/.bip322/bin/pip install "bip322-audit[kernel]"
export PATH="$HOME/.bip322/bin:$PATH"
```

Python 3.11 or newer (on Ubuntu 22.04: `apt install python3.12 python3.12-venv`
from the deadsnakes PPA, then `python3.12 -m venv ~/.bip322`); leave out
`[kernel]` on anything but CPython 3.12 / Linux x86_64.

For a reproducible, hash-pinned install (what an auditor should do), clone and use the setup script:

```sh
git clone https://github.com/embeddednation/bip322-audit.git && cd bip322-audit
./setup.sh                          # venv, hash-pinned dependencies, bip322-core at the pinned tag, tests
export PATH="$PWD/.venv/bin:$PATH"
```

`setup.sh` installs `bip322-core` from its git repository at the tag named
by `CORE_REF` in the script. `./setup.sh --core ../bip322-core` installs a local
checkout instead, which is the development setup and also the auditor's: clone both
repositories at the tags the owner names, check the commit hashes out of
band, and run `verify`.

The whole yearly flow across the three packages is in bip322-report's [handbook](https://github.com/embeddednation/bip322-report/blob/main/bip322report/handbook.md).

## Workflow

For "we controlled these coins as of block N", repeatable whenever coins move:

```sh
bip322 init -w treasury               # once: this directory holds the wallets (bip322.toml)
bip322 audit snapshot                 # the node wallet's own descriptor
#   -> treasury/snapshots/2026-09-14-912345/: snapshot.json, message.txt, to_sign/to_sign-01.psbt ... one per funded address
#   sign every PSBT on the cosigners' devices, put the results into its signed/
bip322 audit finalize                 # the newest snapshot -> treasury-2026-09-14-912345-proofs.json (hand this to the auditor)
bip322 audit verify --report audit-report.json
```

The wallet is `-w NAME`, else the wallet directory the command runs in, else
`wallet` in `bip322.toml`, else the node's one loaded wallet; `finalize` and `verify` take a snapshot's name
(`finalize 2026-09-14-912345`) or a path when the newest is not the one
meant, and `verify` a proofs file. `-o DIR` writes a snapshot elsewhere.
See [Where everything lives](#where-everything-lives).

`finalize` also asks the node wallet the coins came from (recorded in
`snapshot.json`) which listed outputs have been spent since, and records the
spending transactions in the proofs file. If coins move between the snapshot and
the audit, re-run `finalize` before handing the proofs file over; the proofs
themselves do not change. `--offline` skips that step and keeps the spends an
earlier run recorded. A PSBT that cannot be used is reported with its address
and file names, and files in `to_sign/` and `signed/` that were not used are
listed.

The node is reached with `--cli CMD` (default `bitcoin-cli`). `CMD` is split
like a shell command line, so a path with spaces is quoted inside it:
`--cli "'/opt/my node/bitcoin-cli' -signet"`. `--timeout SECONDS` bounds every
node call (default 600); a UTXO-set scan the tool gave up on keeps running on
the node. Chains: `main`, `test`, `testnet4`, `signet`, `regtest`.

`snapshot` reads the wallet's descriptor from the node wallet
(`listdescriptors`; `--descriptor FILE` overrides and is cross-checked against
the node), takes the block six behind the tip (`--depth`) as the stamp *and*
the snapshot height: the message ends with `block: HEIGHT HASH TIME` taken
from that block, and only outputs confirmed at that block are listed. Coins
come from `listunspent` on the node wallet or, when the node has no wallet, from a
`scantxoutset` of the descriptor (minutes on mainnet; the command says so
before it starts; `--source` forces either). The stamp, the coins, their
heights and block hashes are read under one tip: if a block arrives
meanwhile, they are read again. The template accepts `{date}`, `{time}`,
`{height}`, `{hash}` (date and time are the stamp block's header time, UTC;
`text` in `bip322.toml` sets the default); anything else in braces is refused, as is a template with a `block:` line of
its own, and the message is checked against hardware signers' message rules.

`snapshot` covers one descriptor (`wsh(multi/sortedmulti)` or `wpkh`). Its
summary and `snapshot.json` say which (`descriptor`), and under `left_out`
how many outputs and how much the node listed that the snapshot does not, and
why: coins of another descriptor in the same node wallet, coins on addresses
an earlier snapshot proves. Descriptors of a kind it does not cover are named
in `notes`. The snapshot's directory is `<date>-<height>` under the wallet's
`snapshots/`, with `-2`, `-3` ... when that exists; `-o DIR --force` rewrites
a snapshot that holds no signed PSBTs and no proofs file yet, and nothing else.

The proofs file names addresses, not a wallet: the message, the stamp, and per
address the proof and its outputs, plus the policy string (`2 of 3`). It is
built from a fixed list of fields (`tool`, `chain`, `stamp`, `message`,
`message_hex`, `policy`, `finalized_utc`, `total_sat`, `total_btc`, `spends`,
`spends_utc`, and per proof `address`, `signature`, `variant`, `total_sat`
and the outputs' `txid`, `vout`, `amount_sat`, `height`, `blockhash`), with
the proofs in address order and only `smp` proofs. No
descriptor, no xpubs, no derivation paths and no node wallet name go in. The
proofs stand per address, and the xpubs would let the auditor derive every
address of the wallet, past and future, which no check of the claim needs.
`snapshot.json`, the owner's copy, keeps all of it. The file's name,
`<wallet>-<date>-<height>-proofs.json`, says what it is wherever it ends up,
and it keeps that name in the snapshot, beside a statement and at the auditor's.

`verify` re-checks everything on the auditor's node: each BIP-322 signature,
the stamp block (`getblockheader`: height, time, in main chain), that the
document is consistent with the signed message, and each listed output.
An output still unspent is checked with `gettxout` (amount, address,
creation height at or before the stamp), which also shows it was unspent at
the stamp. An output spent since is fetched by the block hash the snapshot
recorded (no `-txindex` needed): that shows it existed at the stamp with the
claimed amount and address. Whether it was still *unspent* at the stamp needs
the spending transaction, which only an address index or the owner's wallet
knows; `finalize` records it in the proofs file from the node wallet's history
(`listsinceblock` from the stamp block), and `verify` checks that it really
spends the output and was confirmed after the stamp block. A spend at or
before the stamp is a contradiction (`spent_before_snapshot`). A spent output
with no recorded spend, or with one the node cannot find or whose block left
the main chain, is `spent_time_unknown`: it existed, and nothing shows when
it was spent, so it is not counted as held. The report's rows are built from
what the node answered; nothing else in the proofs file is copied into them.
Totals are computed from the listed outputs: `claimed`, `held at the stamp`
(shown by the node) and `unspent now`. A `total_sat` that disagrees, an
output or an address listed twice, a recorded spend that does not spend its
output, and a document with no proofs are problems of the document.

The result is one of three:

* **OK**: the signatures and the stamp check out, the document is consistent,
  and every listed output is shown held at the stamp block (unspent now, or
  spent after the stamp by a checked spend).
* **INCOMPLETE**: nothing failed and nothing is contradicted, but some listed
  output is not shown held at the stamp block. The owner re-runs `finalize`
  on the node wallet to record the spends.
* **FAILED**: a signature, the stamp or the document does not check out, or
  the node contradicts a listed output.

In the JSON report the verdict is `result` (`ok`, `incomplete`, `failed`).
The key `ok` is true only for `ok`; `totals.held_at_stamp_sat` is what the node
showed held.

`--offline` verifies signatures and the document only.

## Exit codes

| command | 0 | 1 | 2 | 3 |
|---|---|---|---|---|
| `verify` | result OK | result FAILED | could not run | result INCOMPLETE |
| `stamp`, `snapshot`, `prove`, `finalize`, `holdings`, `help` | done | not used | could not run | not used |

"Could not run" is bad input (an unknown placeholder, a file that is not a
proofs document, a directory that exists), a node that cannot be reached or
answers something that is not JSON, or a snapshot that cannot be finalized;
the message is one line on stderr starting with `error:`.

Completeness (that the listed addresses are all the holdings in scope) is not
something a key or a scan can establish, since nothing rules out a second
wallet. It comes from the audited party's representation and from
reconciling one year's spends to the next year's proofs, which the recorded
spends make possible.

`examples/audit_walkthrough.sh [DIR]` runs the whole thing on a throwaway
regtest node, including spending a coin after the snapshot (INCOMPLETE until
`finalize` is re-run). It writes into a new directory and refuses one that
exists and is not empty.

## Checking holdings on chain

```sh
bip322 audit holdings 7a1b...:0 3c9d...:1 --at 912345    # by output: a direct lookup, instant
bip322 audit holdings bc1q... --at 912345                 # by address: a UTXO-set scan, minutes on mainnet
```

For each output: the scriptPubKey it is locked to, its amount, and whether
it is unspent; with `--at`, whether it was held at that block (an output
confirmed at or before the block and unspent now was; `gettxout` only finds
unspent outputs). The JSON adds the address and the confirmation block and
time. This is how a reader of a statement checks its closing holdings. Coins spent since cannot
show; the owner's records name them and `verify` checks those. A bech32
address may be given in upper case.

## Where everything lives

A directory of your choice, made with `bip322 init` (the same as
`bip322 audit init`): it writes `bip322.toml`, the file that marks the
directory and holds the defaults, and from then on every command run in that
directory or below finds it, as git finds its repository. There is no default
place; `--dir DIR` or `BIP322_DIR` name it from elsewhere.

```sh
mkdir ~/bip322 && cd ~/bip322
bip322 init -w treasury               # -> bip322.toml: wallet = "treasury", every other key a comment to switch on
```

```
~/bip322/
  bip322.toml
  treasury/
    snapshots/
      2026-03-02-880412/                  # a prove during the year
      2026-09-14-912345/                  # a full snapshot
        snapshot.json  message.txt  to_sign/  signed/
        treasury-2026-09-14-912345-proofs.json
    statements/                           # bip322-report's
```

`-w NAME` names the wallet: its directory, and the node wallet of the same
name (or the one `node` names in its `[wallets.NAME]` table of
`bip322.toml`, for a node wallet whose name is long or no directory name).
Without `-w`, the wallet directory the command runs in names it, else
`wallet` in `bip322.toml`, else the node's one loaded wallet does; inside a
snapshot's directory, `finalize` and `verify` mean that snapshot. A second
wallet is a second directory, created when first written to. The snapshots
hold the PSBTs, which carry the wallet's xpubs: they stay with the holder.

In `bip322.toml`, top-level keys are defaults for every wallet, a
`[wallets.NAME]` table is for one, and the command line beats both:

```toml
wallet = "treasury"
text = "Proof of control {date}"
cli = "bitcoin-cli -rpcconnect=10.0.0.5"

[wallets.treasury]
node = "treasury-2of3-main"
```

`init` writes the file with every key the tools read as a comment to switch
on, and `-w NAME` switches `wallet = NAME` and its table on. An existing file
is left alone.

Keys this package reads: `wallet`, `cli`, `timeout`, `text`, and `node` per
wallet; bip322-report reads more.

Over the years the snapshots accumulate, and their proofs files are what
`--skip-proven` reads:

```sh
bip322 audit snapshot --skip-proven
#   -> snapshots/<date>-<height>/ with only the outputs no earlier snapshot of the wallet proves (new change, new deposits)
bip322 audit snapshot --text "Proof of control, audit FY2026, {date}"
#   -> every output the wallet holds, after the period's end, under a message that names the audit
```

The block stamp in every message is the timestamp an audit needs: it shows
the proof was made after that block, it can be checked on any node at any
later date, and it cannot pass for another year. The auditor's request is
therefore simply "a full snapshot with a stamp after the period's last block";
their engagement reference may go in the text if they want it in their file.

A third way, for an address that holds nothing yet:

```sh
bip322 audit prove bc1q...change...
#   -> a snapshot for exactly that address; refused if it is not the wallet's
```

That is the check to run on the change address of a spend before broadcasting
it: sign, `finalize`, and a valid proof means the quorum controls where the
change goes. A proof is about an address, so every output paid to it later
is covered too, and `--skip-proven` skips addresses proven that way.

A proofs file under the wallet's snapshots that cannot be read (a truncated
file) is named in a warning, since it proves nothing. A file still named
`proofs.json` (earlier versions) is read as well.

Sign and `finalize` each as usual. `bip322 audit verify` checks one proofs file;
[bip322-report](https://github.com/embeddednation/bip322-report) reads the
whole of the wallet's snapshots to produce the statement of a period, in
which every output is backed by a verified proof.

## Layout

```
bip322audit/stamp.py      the block stamp: fetch, parse, compose the message, check
bip322audit/snapshot.py   coins at the stamp block (listunspent / scantxoutset), PSBT per address, the snapshot on disk (snapshot, prove)
bip322audit/audit.py      finalize (combine, finalize, self-verify, record spends) and verify (the report)
bip322audit/holdings.py   what outputs or addresses hold now, and at a block (holdings)
bip322audit/proofs.py     the proofs files in a directory tree: which addresses and outputs earlier proofs cover
bip322audit/datadir.py    the data directory: bip322.toml, finding it from below, the wallet directories, snapshot and proofs file names
bip322audit/rpc.py        bitcoin-cli as a subprocess
bip322audit/cli.py        the bip322-audit command, and bip322-init (what bip322 init runs)
bip322audit/testing.py    a throwaway regtest node for the regtest test and the walkthrough
tests/                    fake-node tests (test_audit.py, test_review_fixes.py), the pin test, and an end-to-end test on a real regtest Bitcoin Core
examples/audit_walkthrough.sh   the whole flow on a throwaway regtest node
```

The regtest test and the walkthrough need a Bitcoin Core binary: set
`BITCOIN_CORE_DIR`, or run `refcheck/fetch.sh` in the bip322-core checkout
the venv was set up from. Without one the test skips.

CI checks out bip322-core at the pinned tag.
