test(bridge-sdk): live lifecycle suite over every route, back and forth

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.
ProvableHQ · iamalwaysuncomfortable · Sep 16, 2026 · Sep 16, 2026 · Sep 16, 2026 · Sep 16, 2026
commit 33aadd61c3dfe290a9496919e58c56a78baa955c
diff --git a/bridge-sdk/tests/live/cases.py b/bridge-sdk/tests/live/cases.py
@@ -34,9 +34,12 @@
 
 from .config import one_atomic_unit
 from .helpers import (LiveBenchmark, LiveCaseError, LiveState, Underfunded, ensure_secret_nonce,
-                      load_live_state, load_secret_nonce, redacted, save_live_state,
+                      load_live_state, load_secret_nonce, redacted, save_live_state, wait_for,
                       wait_for_aleo_transaction, wait_for_hyperlane_delivery)
 
+#: ERC-20 ``Transfer(address,address,uint256)``.
+_TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
+
 #: veil's per-test budget (`30 * 60_000`).
 CASE_TIMEOUT_SECONDS = 30 * 60.0
 WAIT_TIMEOUT_SECONDS = 20 * 60.0
@@ -329,11 +332,73 @@ def _select_private_record(bridge: Any, route: Route, amount_atomic: int,
     return record
 
 
+def delivery_is_a_balance_rise(route: Route, registry: Registry) -> bool:
+    """True for the Aleo→EVM xReserve withdrawal, the one leg with no delivery query anywhere.
+
+    ``lifecycle.py`` says it in as many words ("xReserve Aleo→EVM: Circle exposes no canonical
+    delivery query") and simply returns the receipt unchanged, so its status stays
+    ``DELIVERY_PENDING`` for ever and ``wait`` can only ever time out.  veil does not drive this
+    case to ``done`` either — ``aleo-xreserve.live.test.ts:146-155`` polls the recipient's ERC-20
+    balance until it rises above what it was before the burn, and that is what delivery means here.
+    """
+    if route.protocol != "xreserve":
+        return False
+    source = registry.chain(registry.asset(route.source_asset_id).chain_id).family
+    destination = registry.chain(registry.asset(route.destination_asset_id).chain_id).family
+    return source == "aleo" and destination == "evm"
+
+
+def _wait_for_balance_rise(bridge: Any, asset_id: str, before: int, *, timeout_seconds: float,
+                           poll_seconds: float, log: Callable[[str], None]) -> int:
+    """veil ``waitFor(... balanceOf > destinationBalanceBefore)``: the recipient's balance, once it rises."""
+    def read() -> Any:
+        after = read_balances(bridge).get(asset_id)
+        return after if after is not None and after > before else None
+
+    log(f"  awaiting   {asset_id} to rise above {before} atomic (no delivery query exists for this leg)")
+    return wait_for(read, timeout_seconds=timeout_seconds, poll_seconds=poll_seconds)
+
+
+def _evm_transfer_tx(bridge: Any, asset: Asset, recipient: str, amount_atomic: int,
+                     lookback_blocks: int = 5_000) -> str | None:
+    """The transaction that moved *amount_atomic* of *asset* to *recipient*, or None.
+
+    Best effort only: this is a convenience id for the report, so a public RPC that refuses the
+    log range (or returns nothing) leaves ``destinationTxId`` unset rather than failing a leg whose
+    funds have demonstrably arrived.
+    """
+    connection = getattr(bridge, "ethereum", None)
+    if connection is None or asset.locator.kind != "evm-contract":
+        return None
+    try:
+        w3 = connection.w3
+        head = w3.eth.block_number
+        entries = w3.eth.get_logs({
+            "fromBlock": max(head - lookback_blocks, 0), "toBlock": head,
+            "address": w3.to_checksum_address(asset.locator.value),
+            "topics": [_TRANSFER_TOPIC, None, "0x" + "00" * 12 + recipient[2:].lower()]})
+    except Exception:                                  # noqa: BLE001 — a missing id is not a failure
+        return None
+    for entry in reversed(list(entries)):
+        raw = entry["data"]
+        value = int(raw.hex() if hasattr(raw, "hex") else raw, 16)
+        if value == amount_atomic:
+            digest = entry["transactionHash"]
+            return "0x" + (digest.hex() if hasattr(digest, "hex") else str(digest)).removeprefix("0x")
+    return None
+
+
 def run_case(bridge: Any, case: str, route_id: str, *, state_path: Path | str, recipient: str | None = None,
              amount: str | None = None, execute: bool, benchmark: LiveBenchmark | None = None,
              wait_timeout_seconds: float = WAIT_TIMEOUT_SECONDS, wait_poll_seconds: float = WAIT_POLL_SECONDS,
-             log: Callable[[str], None] = print) -> LiveState:
-    """Run one case over one route, resuming from ``state_path``. See the module docstring for the flow."""
+             stop_after_execute: bool = False, log: Callable[[str], None] = print) -> LiveState:
+    """Run one case over one route, resuming from ``state_path``. See the module docstring for the flow.
+
+    ``stop_after_execute=True`` returns as soon as the source transaction is on chain and its
+    checkpoint is on disk, so the caller can throw the whole client away and prove that a *new*
+    ``Bridge`` finishes the transfer from the state file alone.  Calling ``run_case`` again with the
+    same ``state_path`` takes the resume branch; ``execute`` is never called twice for one transfer.
+    """
     spec = CASES[case]
     state_path = Path(state_path)
     benchmark = benchmark if benchmark is not None else LiveBenchmark(case, log=log)
@@ -394,6 +459,10 @@ def run_case(bridge: Any, case: str, route_id: str, *, state_path: Path | str, r
             # recovering, so a rejected execution is reported as itself rather than as a timeout.
             wait_for_aleo_transaction(bridge, state.source_tx_id)
             benchmark.mark("source-confirmed")
+        if stop_after_execute:
+            log(f"  handover   source={state.source_tx_id} checkpoint on disk at {state_path}; "
+                "a new client will recover it")
+            return state
     else:
         log(f"  resuming {case} {route_id} from the saved checkpoint")
 
@@ -404,6 +473,23 @@ def run_case(bridge: Any, case: str, route_id: str, *, state_path: Path | str, r
         return state
 
     progress = _recover_from_state(bridge, state, benchmark=benchmark, log=log)
+
+    if delivery_is_a_balance_rise(route, bridge.registry):
+        # No drive loop: `wait` on this leg can only time out (see delivery_is_a_balance_rise).
+        before = int(state.destination_balance_before or 0)
+        after = _wait_for_balance_rise(bridge, destination.id, before, timeout_seconds=wait_timeout_seconds,
+                                       poll_seconds=wait_poll_seconds, log=log)
+        benchmark.mark("destination-delivered")
+        state.destination_tx_id = state.destination_tx_id or _evm_transfer_tx(
+            bridge, destination, recipient, after - before)
+        log(f"  delivered  {destination.id} +{after - before} atomic (before {before}, after {after}) "
+            f"tx={state.destination_tx_id}")
+        state.completed = True
+        save_live_state(state_path, state)
+        log(f"  done       source={state.source_tx_id} destination={state.destination_tx_id}")
+        log(f"  {benchmark.summary()}")
+        return state
+
     progress = _drive(bridge, progress, state, state_path, spec=spec, secret_nonce=secret_nonce,
                       benchmark=benchmark, save=save, wait_timeout_seconds=wait_timeout_seconds,
                       wait_poll_seconds=wait_poll_seconds, log=log)
@@ -462,8 +548,8 @@ def run(bridge: Any, route_id: str, *, state_path: Path | str, recipient: str |
 
 __all__ = [
     "CASES", "CASE_NAMES", "CASE_TIMEOUT_SECONDS", "CaseSpec", "LiveCaseError", "RUNNERS", "Underfunded",
-    "asset_ref", "case_for_route", "default_amount", "default_recipient", "precheck", "print_quote",
-    "read_balances", "route_slug", "routes_for_case", "run_aleo_hyperlane", "run_aleo_xreserve",
-    "run_case", "run_evm_hyperlane", "run_evm_xreserve", "run_solana_hyperlane", "sender_for",
-    "state_name",
+    "asset_ref", "case_for_route", "default_amount", "default_recipient", "delivery_is_a_balance_rise",
+    "precheck", "print_quote", "read_balances", "route_slug", "routes_for_case", "run_aleo_hyperlane",
+    "run_aleo_xreserve", "run_case", "run_evm_hyperlane", "run_evm_xreserve", "run_solana_hyperlane",
+    "sender_for", "state_name",
 ]
diff --git a/bridge-sdk/tests/live/config.py b/bridge-sdk/tests/live/config.py
@@ -36,6 +36,31 @@
 
 ENVIRONMENTS = ("mainnet", "testnet")
 
+#: Endpoints used when the operator's shell names none. Public, read-mostly, no credentials.
+DEFAULT_ALEO_ENDPOINT = "https://edge.provable.com/api"
+DEFAULT_ETHEREUM_RPC_URL = "https://ethereum-rpc.publicnode.com"
+DEFAULT_SEPOLIA_RPC_URL = "https://ethereum-sepolia-rpc.publicnode.com"
+
+#: Key and RPC variables per environment, most specific first.  The live suite resolves connection
+#: material ONLY through these lists, so a testnet run can never pick up the mainnet Aleo key.
+ALEO_KEY_VARS = {
+    "mainnet": ("BRIDGE_PRIVATE_KEY",),
+    "testnet": ("BRIDGE_LIVE_ALEO_TESTNET_PRIVATE_KEY", "ALEO_E2E_PRIVATE_KEY"),
+}
+EVM_KEY_VARS = {
+    "mainnet": ("EVM_PRIVATE_KEY", "BRIDGE_EVM_PRIVATE_KEY"),
+    "testnet": ("BRIDGE_LIVE_EVM_TESTNET_PRIVATE_KEY", "EVM_PRIVATE_KEY", "BRIDGE_EVM_PRIVATE_KEY"),
+}
+EVM_RPC_VARS = {
+    "mainnet": ("ETHEREUM_RPC_URL", "BRIDGE_LIVE_ETHEREUM_RPC_URL"),
+    "testnet": ("SEPOLIA_RPC_URL", "BRIDGE_LIVE_SEPOLIA_RPC_URL"),
+}
+DEFAULT_EVM_RPC_URL = {"mainnet": DEFAULT_ETHEREUM_RPC_URL, "testnet": DEFAULT_SEPOLIA_RPC_URL}
+ALEO_ENDPOINT_VARS = ("BRIDGE_LIVE_ALEO_ENDPOINT", "ALEO_ENDPOINT")
+
+#: The Aleo network name each bridge environment runs on.
+ALEO_NETWORKS = {"mainnet": "mainnet", "testnet": "testnet"}
+
 #: Recipient overrides per destination-chain family; the default is our own address on that chain.
 RECIPIENT_VARS = {
     "aleo": "BRIDGE_LIVE_ALEO_MAINNET_RECIPIENT",
@@ -123,6 +148,60 @@ def case_route_override(case: str, env: Mapping[str, str] | None = None) -> str
     return value(f"BRIDGE_LIVE_{case.replace('-', '_').upper()}_ROUTE_ID", env)
 
 
+def case_amount_override(case: str, env: Mapping[str, str] | None = None) -> str | None:
+    """``BRIDGE_LIVE_<CASE>_AMOUNT``, or ``BRIDGE_LIVE_XRESERVE_AMOUNT`` for either xReserve case."""
+    specific = value(f"BRIDGE_LIVE_{case.replace('-', '_').upper()}_AMOUNT", env)
+    if specific:
+        return specific
+    return value("BRIDGE_LIVE_XRESERVE_AMOUNT", env) if case.endswith("xreserve") else None
+
+
+def _environment(environment: str) -> str:
+    if environment not in ENVIRONMENTS:
+        raise LiveConfigError(f"environment must be one of {ENVIRONMENTS}, got {environment!r}")
+    return environment
+
+
+def first_value(names: tuple[str, ...], env: Mapping[str, str] | None = None) -> tuple[str, str] | None:
+    """The first of *names* that is set, as ``(variable, value)`` — or None. Never logs the value."""
+    for name in names:
+        found = value(name, env)
+        if found:
+            return name, found
+    return None
+
+
+def aleo_private_key(environment: str, env: Mapping[str, str] | None = None) -> str:
+    """The Aleo key for *environment* (``BRIDGE_PRIVATE_KEY`` on mainnet, ``ALEO_E2E_PRIVATE_KEY``
+    — or its ``BRIDGE_LIVE_ALEO_TESTNET_PRIVATE_KEY`` alias — on testnet)."""
+    names = ALEO_KEY_VARS[_environment(environment)]
+    found = first_value(names, env)
+    if found is None:
+        raise LiveConfigError(f"Missing {' / '.join(names)}; the {environment} live case needs an Aleo key")
+    return found[1]
+
+
+def evm_private_key(environment: str, env: Mapping[str, str] | None = None) -> str:
+    """The EVM key for *environment*, normalised to ``0x…`` (the value never appears in an error)."""
+    names = EVM_KEY_VARS[_environment(environment)]
+    found = first_value(names, env)
+    if found is None:
+        raise LiveConfigError(f"Missing {' / '.join(names)}; the {environment} live case needs an EVM key")
+    return required_evm_private_key(found[0], env)
+
+
+def evm_rpc_url(environment: str, env: Mapping[str, str] | None = None) -> str:
+    """The Ethereum (mainnet) or Sepolia (testnet) RPC url, falling back to the public default."""
+    found = first_value(EVM_RPC_VARS[_environment(environment)], env)
+    return found[1] if found else DEFAULT_EVM_RPC_URL[environment]
+
+
+def aleo_endpoint(env: Mapping[str, str] | None = None) -> str:
+    """The Aleo API root, falling back to the open, credential-free edge host."""
+    found = first_value(ALEO_ENDPOINT_VARS, env)
+    return found[1] if found else DEFAULT_ALEO_ENDPOINT
+
+
 def recipient_override(family: str, env: Mapping[str, str] | None = None) -> str | None:
     """The operator's recipient override for a destination-chain *family*, or None (use our own address)."""
     try:
@@ -133,9 +212,12 @@ def recipient_override(family: str, env: Mapping[str, str] | None = None) -> str
 
 
 __all__ = [
-    "CASE_NAMES", "ENVIRONMENTS", "FUNDS_VAR", "LiveConfigError", "MAINNET_ACK", "MAINNET_ACK_VAR",
+    "ALEO_ENDPOINT_VARS", "ALEO_KEY_VARS", "ALEO_NETWORKS", "CASE_NAMES", "DEFAULT_ALEO_ENDPOINT",
+    "DEFAULT_ETHEREUM_RPC_URL", "DEFAULT_EVM_RPC_URL", "DEFAULT_SEPOLIA_RPC_URL", "ENVIRONMENTS",
+    "EVM_KEY_VARS", "EVM_RPC_VARS", "FUNDS_VAR", "LiveConfigError", "MAINNET_ACK", "MAINNET_ACK_VAR",
     "MAINNET_CASES_VAR", "MAINNET_EXECUTE_ACK", "MAINNET_EXECUTE_VAR", "RECIPIENT_VARS", "STATE_DIR_VAR",
-    "case_route_override", "live_funds_enabled", "live_state_path", "mainnet_case_enabled",
+    "aleo_endpoint", "aleo_private_key", "case_amount_override", "case_route_override", "evm_private_key",
+    "evm_rpc_url", "first_value", "live_funds_enabled", "live_state_path", "mainnet_case_enabled",
     "mainnet_execution_enabled", "one_atomic_unit", "recipient_override", "required",
     "required_evm_private_key", "state_dir", "value",
 ]