> ## Documentation Index
> Fetch the complete documentation index at: https://docs.algovoi.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# AVM Proofpack: Algorand State Proof Verification in Python

> Verify an Algorand or Voi transaction offline in pure Python: avm-proofpack recomputes every hash and Merkle link from raw bytes up to the chain's state proof commitment. Zero dependencies.

**avm-proofpack** is a pure-Python, zero-dependency library and CLI for
**Algorand state proof verification**: it captures a confirmed transaction as a
single portable JSON bundle, then re-verifies it **offline**, with no node, no
SDK, and no network, by recomputing every hash and Merkle link from raw
canonical bytes up to the chain's stake-signed state proof commitment.

* **PyPI**: [`pip install avm-proofpack`](https://pypi.org/project/avm-proofpack/)
* **Source**: [github.com/chopmob-cloud/avm-proofpack](https://github.com/chopmob-cloud/avm-proofpack) (Apache-2.0)
* Works unchanged on any AVM chain that generates state proofs; verified live
  against Algorand mainnet and Voi mainnet.

## Why it exists

Payment processors, custodians and auditors routinely assert "transaction X
settled on chain Y" backed by nothing but their own signature. Algorand and Voi
commit, every 256 rounds, to a stake-signed vector commitment over their block
headers. That makes settlement claims falsifiable: evidence can be checked
against consensus itself rather than against the claimant.

Two constraints shape the design:

1. **Public nodes prune.** Non-archival nodes serve proof material for roughly
   the most recent 1,000 rounds. Evidence must be captured near settlement time
   and stored; it cannot be fetched years later on demand.
2. **Verification must not trust the capturer.** A bundle carries raw canonical
   bytes, not quoted values. The verifier recomputes everything itself.

## Verify a transaction offline

```bash theme={null}
# capture near settlement time (any algod endpoint)
avm-proofpack capture \
  --node https://mainnet-api.algonode.cloud \
  --txid KOERHNGJPLUUQK4WJ4YPY5OC3BOINDH2J4E6HM2RYARSJ5R3FAYA \
  --round 63604900 \
  -o evidence.json

# verify later, fully offline
avm-proofpack verify evidence.json --corroborate
```

The offline verification chain runs from the transaction ID, through the
transaction leaf and the block's `txn256` vector commitment, to the block hash,
the light block header, and finally membership in the state proof message's
block headers commitment. Every domain separator and commitment shape follows
the go-algorand reference implementation.

## Trust model, stated plainly

Offline verification proves internal consistency down to one trust root: the
bundle's own state proof message. Offline alone does not prove that message was
produced by the chain's consensus stake. Raising the trust root is explicit:
`--corroborate` compares the message across independent nodes (do this near
capture time, inside the prune window, or against an archival node). Falcon
signature verification of the state proof itself is the planned next tier. The
CLI refuses to report a bare pass without `--corroborate` or an explicit
`--accept-unattested` flag.

## x402 settlement evidence

For agentic payments, the bundle binds chain settlement to the receipt layer:
an optional, additive `chain_binding` on [verifiable x402
receipts](/verifiable-x402-receipt) carries the proofpack evidence, so an
[offline-verifiable receipt](/offline-verifiable-receipts) and its on-chain
settlement can be checked together, years later, from files alone. Disclosure
is opt-in for privacy. See the repo's `docs/INTEGRATION.md` for the receipt
integration path and [SPEC.md](https://github.com/chopmob-cloud/avm-proofpack/blob/main/SPEC.md)
for the bundle format.