bip322-audit 0.12.1__tar.gz

bip322_audit-0.12.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Embedded Nation AB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bip322_audit-0.12.1/PKG-INFO

@@ -0,0 +1,268 @@
+Metadata-Version: 2.4
+Name: bip322-audit
+Version: 0.12.1
+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.12,>=0.11.1
+Provides-Extra: kernel
+Requires-Dist: bip322-core[kernel]<0.12,>=0.11.1; 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).
+* **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"
+```
+
+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-audit -w treasury snapshot --text "Annual audit {date}"      # the node wallet's own descriptor
+#   -> snapshot-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 snapshot-.../signed/
+bip322-audit finalize snapshot-2026-09-14-912345           # -> proofs.json (hand this to the auditor)
+bip322-audit verify snapshot-2026-09-14-912345 --report audit-report.json
+```
+
+`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 `proofs.json`. If coins move between the snapshot and
+the audit, re-run `finalize` before handing `proofs.json` 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 (`-w NAME`,
+`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 (the only one loaded, or `-w NAME`)
+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);
+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 bundle does not, and
+why: coins of another descriptor in the same node wallet, coins on addresses
+an earlier bundle proves. Descriptors of a kind it does not cover are named
+in `notes`. The default directory is `snapshot-<date>-<height>`, with `-2`,
+`-3` ... when that exists; `-o DIR --force` rewrites a bundle that holds no
+signed PSBTs and no `proofs.json` yet, and nothing else.
+
+`proofs.json` 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.
+
+`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 `proofs.json` 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 `proofs.json` 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 bundle 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.
+
+## Bundles over time: a ledger
+
+Keep every bundle in one directory tree and it becomes the wallet's ledger of
+proofs. Two ways to add to it:
+
+```sh
+bip322-audit -w treasury snapshot --text "Proof of control {date}" --skip-proven ledger
+#   -> ledger/snapshot-<date>-<height>/ with only the outputs no earlier bundle proves (new change, new deposits)
+bip322-audit -w treasury snapshot --text "Proof of control, audit FY2026, {date}" -o ledger/audit-2026
+#   -> 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 bundle 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 -w treasury prove bc1q...change... --text "Proof of control {date}" --ledger ledger
+#   -> a bundle 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.
+
+`--skip-proven DIR` must exist, and a `proofs.json` under it that cannot be
+read (a truncated file) is named in a warning, since it proves nothing.
+
+Sign and `finalize` each as usual. `bip322-audit verify` checks one bundle;
+[bip322-report](https://github.com/embeddednation/bip322-report) reads the
+whole ledger to produce balance reports 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 bundle (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/ledger.py     a directory tree of bundles: which addresses and outputs earlier proofs cover
+bip322audit/rpc.py        bitcoin-cli as a subprocess
+bip322audit/cli.py        the bip322-audit command
+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.

bip322_audit-0.12.1/README.md

@@ -0,0 +1,244 @@
+# 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).
+* **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"
+```
+
+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-audit -w treasury snapshot --text "Annual audit {date}"      # the node wallet's own descriptor
+#   -> snapshot-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 snapshot-.../signed/
+bip322-audit finalize snapshot-2026-09-14-912345           # -> proofs.json (hand this to the auditor)
+bip322-audit verify snapshot-2026-09-14-912345 --report audit-report.json
+```
+
+`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 `proofs.json`. If coins move between the snapshot and
+the audit, re-run `finalize` before handing `proofs.json` 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 (`-w NAME`,
+`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 (the only one loaded, or `-w NAME`)
+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);
+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 bundle does not, and
+why: coins of another descriptor in the same node wallet, coins on addresses
+an earlier bundle proves. Descriptors of a kind it does not cover are named
+in `notes`. The default directory is `snapshot-<date>-<height>`, with `-2`,
+`-3` ... when that exists; `-o DIR --force` rewrites a bundle that holds no
+signed PSBTs and no `proofs.json` yet, and nothing else.
+
+`proofs.json` 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.
+
+`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 `proofs.json` 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 `proofs.json` 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 bundle 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.
+
+## Bundles over time: a ledger
+
+Keep every bundle in one directory tree and it becomes the wallet's ledger of
+proofs. Two ways to add to it:
+
+```sh
+bip322-audit -w treasury snapshot --text "Proof of control {date}" --skip-proven ledger
+#   -> ledger/snapshot-<date>-<height>/ with only the outputs no earlier bundle proves (new change, new deposits)
+bip322-audit -w treasury snapshot --text "Proof of control, audit FY2026, {date}" -o ledger/audit-2026
+#   -> 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 bundle 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 -w treasury prove bc1q...change... --text "Proof of control {date}" --ledger ledger
+#   -> a bundle 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.
+
+`--skip-proven DIR` must exist, and a `proofs.json` under it that cannot be
+read (a truncated file) is named in a warning, since it proves nothing.
+
+Sign and `finalize` each as usual. `bip322-audit verify` checks one bundle;
+[bip322-report](https://github.com/embeddednation/bip322-report) reads the
+whole ledger to produce balance reports 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 bundle (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/ledger.py     a directory tree of bundles: which addresses and outputs earlier proofs cover
+bip322audit/rpc.py        bitcoin-cli as a subprocess
+bip322audit/cli.py        the bip322-audit command
+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.