bridge-sdk: aleo-bridge-sdk Python package (lifecycle verbs, agent tools, live suite) - #71

…payload and hook data

…s) with typed views and validation

…lasses

…t all types

…nd fake facade fixtures

…nfirmation timeouts

…d delivery read

…mported modules

del sys.modules[...] permanently replaced aleo_bridge's module/class objects for
the rest of the pytest session, breaking isinstance checks in any test file that
runs later alphabetically and compares against classes imported at collection
time. Use monkeypatch.delitem so the original modules are restored at teardown.

…estation client, nullifier read

…onError

…ecord selection

…eo-only profile, CLI entry point

…o and verify the root on chain

…d nullifier reads, registry drift) and README

Add checkpoint.py: Checkpoint (frozen dataclass with to_dict/to_json and
from_dict/from_json round-tripping), create_checkpoint(plan, receipt, registry)
reducing a Receipt to the documented recovery allowlist (intent, route,
source/destination transaction ids, delivery verification) while excluding
keys, record plaintext, secretNonce, attestation bodies, payloads, message
hashes, nonces and quote internals, CheckpointStore protocol, and
FileCheckpointStore (one 0600 file per sanitized receipt id, atomic
temp+os.replace writes).

Export Checkpoint/CheckpointStore/FileCheckpointStore/create_checkpoint from
__init__.py. Update the two test_client.py cases that were placeholders for
plan 4's checkpoint wiring (BRIDGE_CHECKPOINT_DIR, Profile.checkpoint_dir) now
that checkpoint.py exists and client.py's lazy imports resolve.

…e JSON-RPC web3 double

Adds aleo_bridge.eth.Ethereum (rpc_url+private_key, w3+signer, or bare w3
read-only/default-account forms), cached chain_id, send_transaction (local
signer or default-account path), wait_for_receipt/get_receipt, and
Ethereum.from_env. web3/eth_account stay lazily imported so the package
still imports without the evm extra.

Adds tests/fakes/fake_web3.py: a real Web3 over a hand-rolled JSON-RPC
provider so tests exercise real signing/calldata against fake transport
state, reusing tests.conftest.FakeAleo rather than a second Aleo fake.

Updates the two plan-1 placeholder assertions in test_client.py that
anticipated this change (Bridge.eth / Bridge.from_env now construct a
real Ethereum connection instead of raising MissingExtraError).

…ABI fragments, _plan_for

private_burn's record plaintext (input 0) and private_mint's secret nonce
(input 3) could end up in logs via repr(). Print only the input count;
.inputs stays the explicit accessor for callers that need the values.

… ConfigurationError

Receipt.replace() forwarded protocol_state/next_action straight to
dataclasses.replace() unless the caller overrode them, so a replace() copy
aliased the original's dicts and mutating one leaked into the other.
setdefault() a shallow copy of each first.

to_progress()'s missing-routeId check raised a bare ValueError; every other
failure in this package is a BridgeError subclass, so make this one
ConfigurationError too (same message).

_verified_tree() previously fell back to an unverified (possibly empty)
Merkle proof whenever the on-chain freeze_list_root was unreadable, which
would silently hand out a proof against the wrong tree. Raise
ConfigurationError instead and tell the caller to pass merkle_proof=
explicitly.

freeze_list_program()'s import-lookup also narrowed its except clause from
bare Exception to (ProgramNotFound, AleoError), so a transient RPC failure
of another type propagates instead of silently falling back to the static
freeze-list table.

Updated every fake facade setup that expects a proof to seed
usdcx_freezelist.aleo/freeze_list_root[1u8] with the matching root
(EMPTY_TREE_ROOT for an empty list), and added tests for the unreadable-root
and unrelated-exception-propagates cases.

…e 0700

Profile.load_or_create()'s first-write path used a tmp-file-plus-rename,
which is atomic but not exclusive: two processes racing a fresh
$ALEO_BRIDGE_HOME could each "win", the second silently overwriting the
first's already-in-use key. Open profile.json with O_EXCL instead; on
FileExistsError, load whichever profile got there first instead of
clobbering it. The home directory is now created (or healed) at mode 0700,
matching the file's existing 0600.

…tate

burn() silently ignored record=/merkle_proof= for public/public-as-signer
modes instead of rejecting them, and an unknown mode wasn't caught until
deep inside build_burn_inputs (after route/amount/chain work already ran).
Validate mode first, and reject record=/merkle_proof= for any non-private
mode with a ConfigurationError.

Also de-duplicated the Aleo-chain lookup: XReserveModule._aleo_chain_id()
and HyperlaneModule._aleo_chain() were exact copies of Bridge.aleo_chain();
both modules now call the client's version instead of keeping their own.

- units._DECIMAL_RE: \d -> [0-9] (Python's \d matches any Unicode decimal
  digit, not just ASCII).
- encoding.xreserve_deposit_nonce: bound source_domain to uint32 before
  encoding it, consistent with the payload's remote_domain check.
- registry.Asset.matches_address: re.fullmatch instead of re.search, so a
  trailing newline can no longer sneak past a "$"-anchored regex.
- encoding's hex/shape/width checks (hex_to_bytes, bytes32_to_u128_limbs,
  solana_address_to_hyperlane_recipient, xreserve_deposit_payload's
  per-field width check) now raise InvalidRecipientError, and _uint_be
  raises InvalidAmountError, instead of bare ValueError — all BridgeError
  subclasses, same remedy messages. Updated the callers (circle.py,
  hyperlane.py, xreserve.py) that caught the old ValueError type, and the
  tests that asserted on it. xreserve.get_attestation("nope") now raises a
  BridgeError instead of a naked one.
- client.checkpoints_from_env: removed the dead ImportError branch (and its
  "plan 4" wording) now that checkpoint.py always exists.
- client.balance_program: one-line comment recording that arc20_<sym>.aleo's
  balances mapping is verified to be what the warp/xreserve programs'
  mint_public/burn_public spend.
- hyperlane.py: removed the unused Callable import.

…and checkpoint-before-poll ordering

- fake_web3._decode_raw now keeps nonce/gas/gasPrice/maxFeePerGas/maxPriorityFeePerGas from the
  signed raw tx instead of discarding them, so tests can assert send_transaction's exact fee-filling
  arithmetic (gas = estimate * 1.2; EIP-1559 maxFeePerGas = baseFee * 2 + tip).
- FakeRpcProvider gains a legacy=True knob that omits baseFeePerGas from eth_getBlockByNumber,
  exercising eth.py's previously-unreachable legacy gasPrice branch.
- FakeRpcProvider gains receipt_delay/receipt_poll_counts so a receipt can stay pending for N polls
  per hash; test_evm_call's ordering test now proves each checkpoint fires with zero receipt polls
  for its own hash, that polling only starts after, and that approvals fully confirm before the
  main call is broadcast.

No production code changes: eth.py's fee formula and _calls.py's checkpoint-before-poll ordering
were both already correct; the gap was in test strength only.

…e split and chain assert

…m __exit__

_AsyncClientAdapter.close() now awaits the wrapped client's own close() on the private loop
before stopping it — solana-py's AsyncClient owns an aiohttp session that can only be closed
from its own loop — and closes the loop only once the thread has actually exited, instead of
raising on a loop that is still running.

SolanaRpcClient gains close(), so Solana.close() releases the HTTP pool of the DEFAULT
transport too, and Solana.__exit__ swallows whatever close() raises so releasing a transport
cannot replace the caller's own exception.

… at build, accept a plan alone

M7: keypair_from_private_key raises its ConfigurationError outside the except block on both
the JSON and base58 paths, so neither __cause__ nor __context__ survives — a chained
JSONDecodeError carries the whole document in .doc, which IS the private key.

M8: _build_transaction re-resolves the route through outbound_route() instead of the one
snapshotted when transfer_remote() was called, and refuses a route that no longer matches the
quoted plan; the instruction can no longer be compiled against a stale deployment.

M11: recipient is optional on quote_transfer_remote/transfer_remote — a plan supplies it
along with the amount and sender. Neither plan nor recipient raises InvalidRecipientError,
plan with sender= or a differing amount raises ValueError (an identical amount is tolerated),
mirroring EthModule's rule.

…arations

README lists BRIDGE_SOLANA_PRIVATE_KEY / BRIDGE_LIVE_SOLANA_RPC_URL as aliases with the same
caveat as the Ethereum pair: they are not live-test-only, so an exported alias points every
from_env() call at that endpoint.

Removes _sealevel.ALEO_MAINNET_HYPERLANE_DOMAIN (nothing imported it; the domain comes from
the route metadata) and the unused decimals parameter of SolModule._make_plan.

…unk_blocks on assignment

Without plan=, eth.quote_transfer_remote/transfer_remote/quote_deposit_usdc/deposit_usdc
now raise InvalidRecipientError instead of letting recipient=None reach _recipient_bytes32
as an opaque TypeError (deposit_usdc did not fail until send()).

log_scan_chunk_blocks becomes a validating property so eth.log_scan_chunk_blocks = 0 cannot
make _scan_logs spin forever; the constructor runs through the same check.

…gs and EVM/Solana dispatch

execute() commits the source-chain legs of a prepared Plan and returns Progress. Aleo legs
prove (DPS or local), checkpoint the exact prepared transaction BEFORE broadcasting it, submit
with wait=False and checkpoint the id; EVM and Solana legs go through the modules' own plan=
surface so the route, registry version, sender and every plan field are re-validated where the
transaction is built.

A private xReserve mint now requires its own secret_nonce (never the 0scalar default), the
Hyperlane hook payment is re-quoted at the last moment unless pinned, and a destination-balance
baseline is captured only when the destination connection is the recipient.

_Emitter feeds both checkpoint channels: a module's already-reduced Checkpoint and execute()'s
own post-send emission reduce to the same value, so the caller sees each boundary once and the
bound store keeps exactly one record per transfer, superseding the id it replaces.

The write-side fakes gain the real plan= signatures, and lifecycle.quote now calls
bridge.sol.quote_transfer_remote(plan=plan) without the positional recipient workaround.

… adapter close survives a raising client

R1: a node that echoes a different hash still ANSWERED, so the signed bytes may sit in its
mempool under the hash we computed — the same ambiguity as a lost response. The mismatch branch
now carries broadcast_id, so EvmCall refuses a resend instead of signing a second transfer.

R2: _AsyncClientAdapter.close() bounds the wrapped client's close() by the timeout, swallows its
failure and stops the loop in a finally, setting _closed only once that stop is issued — a
third-party transport that cannot close no longer leaves the private loop thread running with a
second close() turned into a no-op.

R3: comments the default-account path, where the hash is not knowable until the node answers, so
none of these protections apply; a local signer is the right choice for funds-moving calls.

…ound xReserve and balance-diff fallback

…connected address, and make destination-balance reads best-effort

Task 4 review carry-overs: _persist now saves (or drops, if terminal) the new
checkpoint before deleting the id it supersedes, never the reverse, so a crash
between the two steps can't leave the store holding neither. A module-emitted
checkpoint's supersede is deferred on the _Emitter (_pending_supersede) until
the module has actually saved it -- flushed at the next emission or via
execute()'s new finalize() call.

Aleo hyperlane/xreserve legs now call _assert_sender against a guarded
bridge.aleo_address() before proving, refusing a plan built for a different
account. _read_destination_balance wraps its RPC read in try/except so an
advisory baseline read never blocks funds movement.

…or tolerance and timeout-as-not-failure

Polls get_status() to a caller boundary (types.CALLER_BOUNDARIES, extendable
via until=) or a terminal state, tracking observed changes into the bound
checkpoint store and firing on_update only when the receipt actually changed.
A transient read error (flaky RPC/HTTP transport) is retried with the normal
poll interval up to max_consecutive_errors (default 5) before the last one is
re-raised; on_error lets callers log the retries. Everything else propagates
on the first attempt. Hitting timeout_seconds raises PollingTimeoutError
carrying the last status/progress -- a timeout is not a failure, the transfer
is still in flight.

…swallowing a missing Solana connection

_message_id no longer falls back to receipt.id when it equals receipt.source_tx_id (an EVM
Hyperlane receipt whose DispatchId log was unreadable carries the tx hash as its id, not a
message id). get_status's Solana message-id fill-in now resolves the sol module outside the
log-read try, so a missing Solana connection raises ConfigurationError instead of being
swallowed as "still unavailable". Also adds the carried "delivered wins" regression test for
get_status's inbound xReserve nullifier-first check on ATTESTATION_PENDING.

…t signing

Appends recover(bridge, checkpoint) plus its helpers (_coerce_checkpoint,
_plan_from_intent, _assert_prepared_id, _finish) to lifecycle.py. Accepts a
Checkpoint, its dict, or its JSON; rebuilds the Plan via prepare() against the
live registry and validates route id + registry version before touching any
chain. Branches on source-chain family: Aleo (prepared-but-unbroadcast resumes
with no network read; submitted gets one get_status refresh), Solana
(validates the blockhash pair and reads source_status once), EVM Hyperlane
(delegates to eth.recover_source(plan, cp, required=False)), and inbound
xReserve (delegates to eth.recover_source, then layers a submitted or
prepared private-mint destination leg on top). Checkpoint deletion on a
terminal outcome is keyed on the checkpoint's own id, never the receipt's
(they diverge once a source tx confirms into a message id).

Adds tests/test_recover.py (8 tests) covering checkpoint validation, all
three source-chain families, xReserve destination recovery paths, unsupported
routes, terminal checkpoint cleanup, and a round-trip check that a plan
rebuilt from a checkpoint is field-identical to the plan that produced it for
an EVM, a Solana, and an Aleo-origin route.

The best-effort try/except lived inside _read_destination_balance, so a flaky
RPC looked identical to 'no reader configured' in get_status branch 6 - the
delivery signal degraded to 'not delivered yet' forever instead of being
retried by wait()'s transient classifier.

Move the swallow to _delivery_verification, the one caller that genuinely must
not raise (execute's advisory pre-broadcast baseline).

…rivate mint

resume() finishes the source leg an interruption left unsubmitted. An Aleo leg
rebroadcasts the checkpointed bytes byte-for-byte after checking the serialized
payload's own id, and treats the node's duplicate answer as success (plan 1's
is_duplicate_submission, re-exported as is_duplicate_broadcast_error rather than
reimplemented) - so the transfer can only ever exist once on chain. An EVM leg
re-scans source history with recover_source(required=True) and authorizes only
the step the scan proves is still missing, keeping veil's two guards: the
re-quoted hook data must equal the checkpointed approval's hook, and the
allowance must still cover the deposit. Solana legs have no resumable state and
say so instead of guessing.

complete() submits the one user-signed Aleo transaction a private USDCx mint
needs: it rebroadcasts an already-proved destination transaction, or builds the
mint (the module re-verifies that (recipient, secret_nonce) opens the attested
commitment, so a wrong nonce never reaches proving), proves it, checkpoints the
exact bytes BEFORE broadcast, then broadcasts.

secret_nonce is mandatory for a private resume/complete and is refused before
any RPC; it is never written to a receipt, a checkpoint or a Progress.

… cleans up by checkpoint id

…ackage exports

…lete never persists secrets (store-level test)

The hook-equality guard in resume's xReserve branch only ran when protocol_state
carried a hookData string, so a receipt without one passed it vacuously and the
deposit could be re-hooked to a freshly derived commitment. Require the hook to
be present and a 65-byte 0x hex string (encoding.HOOK_DATA_BYTES, the same shape
EthModule._recover_xreserve enforces) in the pre-RPC block, before the history
scan, so a transfer resume() cannot finish is not even scanned; the equality
guard below is now unconditional.

Every receipt recover() produces already carries hookData, so this only refuses
hand-built, truncated or legacy ones.

Also: assert at the store level that complete() writes neither the secret nonce,
Circle's attestation nor the committed hook into any checkpoint file, and say in
resume's docstring that a SOURCE_APPROVAL_PENDING receipt needs recover() first.

…ated writes

bridge_tools() returns the six read and five write tools in the Claude API
tools= shape; dispatch_tool() runs one and returns JSON-serializable data.
Reads are open; every write needs confirm=true and otherwise returns the quote
(or recovered progress / built call) plus how_to_confirm, having moved nothing.
bridge_execute takes the quote inputs, never a plan, and re-quotes internally;
confirmed writes hand back {progress, checkpoint} so the model can feed the
checkpoint to bridge_get_progress / bridge_resume / bridge_complete later.

Three safety rules on top of the plain surface:
- a private mint never gets a defaulted secret: mint_mode=private without a
  secret_nonce (and bridge_complete without one, unless the mint is already
  proved) is a structured error that quotes nothing and moves nothing;
- secrets never leave the process: rendered receipts drop the private-mint
  secret, record plaintext, the Circle attestation body and the proved
  transaction bytes, and no tool echoes its own arguments back;
- BridgeErrors come back as {error, error_type, how_to_fix} instead of
  crashing the model's loop - unconfigured Ethereum/Solana connections are
  probed up front, and an ambiguous source send also carries next="recover"
  with the last checkpoint, since these calls are single-use.

EvmXReserveQuote renders a synthetic "xReserve max fee" fee entry from
max_fee_atomic, which its empty fees tuple would otherwise hide.

Also lands the exports task 9 deferred: bridge_tools, dispatch_tool and
agent_guide() (the packaged AGENTS.md, or a pointer at codegen/gen_context.py
until task 12 generates it), with the export-pinning test extended.

… controls

…cord previews, copy schemas, guide recovery on write errors

…bridge prints the guide

…the hermetic mirror

Ports veil's test/integration/live/config.ts and helpers.ts: the read-only gate
functions (BRIDGE_LIVE_FUNDS + BRIDGE_LIVE_STATE_DIR, the mainnet acknowledgement
and case list, the separate execution acknowledgement), one_atomic_unit, the
namespaced state path, and the state/benchmark/polling/explorer helpers.

The private-mint secret nonce is new relative to veil: it is generated once per
case, written to <state>.secret with O_CREAT|O_EXCL and mode 0600, and the state
JSON records only secretNoncePresent, so a state file can be shared without
leaking the commitment secret.

tests/test_live_helpers.py mirrors veil's helpers.test.ts (gating truth table,
state round-trip and fail-closed cases, one-atomic-unit formatting, bytea hashes,
rejected Aleo transactions) and adds the secret-file mode/exclusivity checks and
the explorer 429/5xx tolerance.

… verbs

tests/live/cases.py ports veil's five mainnet cases as functions the pytest
suite (13b) and the operator CLI both call, so the two cannot drift. Each case
loads its route-qualified state file, quotes, prints the route/amount/fee table,
prechecks balances (Underfunded carries the shortfall so callers can skip),
and — only when the caller passes execute=True — executes once, drops the
in-memory progress, recovers from the checkpoint on disk and drives
wait/resume/complete to done. execute is never retried after a broadcast.

Case parametrization covers every registry route per case, in both directions,
with non-active routes reported as skipped-by-registry rather than dropped.
veil's literals are kept: '2' USDC for the private mint, '2.000001' USDCx for
the private burn, one atomic unit elsewhere, signer mode for Aleo Hyperlane.
The Aleo Hyperlane IGP payment comes from our own quote rather than veil's
operator-supplied fee variable.

scripts/rehearse.py runs one case over its routes with --case/--route/
--quote-only/--recover/--report and exits 0/1/2 (ok/failed/pending). It only
reads the acknowledgement variables, prints no line that would set one, and
prints the --recover command for anything left pending.

Documents the three gates and that nothing in the repository sets them, the
state and secret files, the five cases with their routes and veil amounts, the
funding each run needs (from the read-only mainnet quote sweep), and how to
rehearse, run and recover through scripts/rehearse.py.

…, marks, balance delta

Aleo-origin cases confirm the source transaction on chain before recovering
(veil aleo-hyperlane:153, aleo-xreserve:136), so a rejected execution is
reported as a rejection rather than as a delivery timeout. Adds the
plan-prepared and clients-created benchmark marks veil records, logs the
destination balance delta once a case is done, and looks the checkpoint up in
the bound store once instead of twice.

One `live`-marked test per veil case, parametrized from an enumeration of
DEFAULT_REGISTRY rather than a hand-written route list: a route no case covers
raises at import, and a `metadata-required` route is parametrized and skipped
with `registry:metadata-required` instead of disappearing. Plus the testnet
deposit (3 USDC, the amount that clears the 2 USDCx withdrawal fee) and — beyond
veil — the testnet RETURN burn, so "all the routes back and forth" holds on
testnet too.

Every funded test crosses a real process boundary: phase one quotes, prechecks
and calls `execute` once, then returns; that client is dropped and a brand-new
Bridge over the same FileCheckpointStore finishes the transfer through
`pending()` → `recover()` → `wait`/`resume`/`complete`. `execute` is never
called twice for one transfer. Underfunded is a skip with the shortfall (also
when a quote refuses first), a timeout is pending with the resume command.

Harness changes the first real runs forced:

* `cases.run_case(stop_after_execute=...)` — the handover point above.
* Aleo→EVM xReserve delivery is a balance rise, not a drive loop. lifecycle.py
  says Circle exposes no delivery query for that direction and leaves the
  receipt in DELIVERY_PENDING, so `wait` could only ever time out (it did, for
  20 minutes, on a leg whose funds had already landed). veil polls the ERC-20
  balance instead; so do we now, and we recover the withdrawal tx id from the
  Transfer log.
* config: per-environment key/RPC resolution (testnet Aleo key, Sepolia RPC,
  public defaults) and `BRIDGE_LIVE_XRESERVE_AMOUNT`.
* Delivery is asserted as "at least what was quoted", never equality — the
  testnet return delivered 0.996501 USDC against a quoted 0.000001, because the
  live withdrawal fee was 1.0035 USDC, not the registry's 2.

README: the exact invocations for quote-only, testnet and mainnet execution
(the acknowledgement values shown only as `<see tests/live/config.py>`, never
copy-pasteable), the metadata-required and testnet routes, and the two-phase
recovery the suite performs.

pyproject: PyNaCl moves into the base dependencies. Delegated proving is the
default path, and the proving request is sealed with a NaCl box before it
leaves the machine — without PyNaCl the first testnet private mint raised
ImportError *after* the Sepolia deposit was already on chain. That is not an
optional extra.

…P surface and live evidence

Reorganizes README.md around quote/execute/wait/recover/resume/complete, connections,
routes, shield/unshield, Tier 2 modules, agent tools and MCP, keeping every existing
fact (aliases, single-use calls, timeout-is-not-failure, checkpoint-before-poll,
Solana.close(), the full live-tests gates/cases/funding tables). Adds the 2026-09-18
testnet round trip evidence and the registry-vs-live xReserve fee discrepancy.
Extends tests/test_package.py with version/extras lockstep, AGENTS.md packaging and
README-coverage assertions.

Mirrors build-shield-swap/release-shield-swap: builds the pure-Python wheel against
the built aleo-sdk wheel, runs the hermetic suite only (pytest -q -m "not live" —
no key, no live RPC), checks AGENTS.md via gen_context.py --check, and smoke-tests
the wheel both with every extra and without any (MissingExtraError only at point of
use, never at import). release-bridge is tag-triggered, reuses the trusted-publishing
pattern, and gates on build-bridge like the other release jobs; adds bridge-sdk/** to
the push/pull_request path triggers.