feat(transaction)!: make max_epoch mandatory and bound the validity window

[sdbondi]

Motivation

max_epoch was optional with no upper bound, so a signed transaction stayed sequenceable forever. Two consequences:

• a wallet could never declare a transaction dead — it might still land at any point in the future;
• an aborted attempt, which consensus deliberately allows to be re-sequenced, could be retried indefinitely.

This is not about replay protection. Committed-id dedup is already permanent via the receipt-existence gate (#2381): the TransactionReceipt substate is chain state, retained regardless of epoch GC, so a committed id can never be re-sequenced. What was missing is a bounded, deterministic lifetime for every transaction.

Radix sizes the equivalent knob (max_epoch_range) at 12 * 24 * 30 — ~30 days at 5-minute epochs — for the same reason. This PR takes the same window.

Changes

Type change. max_epoch: Option<Epoch> → Epoch on UnsignedTransactionV1, its pruned mirror, the signing-domain projection (TransactionSignatureFields) and TransactionPoolRecord. The builder takes it at construction — Transaction::builder(network, max_epoch) — so every construction site chooses a window at compile time rather than silently omitting one.

Consensus constant. New ConsensusConstants::max_transaction_validity_epochs = 2160 — ~30 days at the ~20 minute epoch target — uniform across mainnet/devnet/esmeralda/testnet. It is a ceiling, not a default: wallets stamp a much shorter window for ordinary traffic, leaving the long window to callers that explicitly need it (offline or multi-party signing). A test asserts the value is identical on every network, since a divergent ceiling would mean nodes disagree on which transactions may be sequenced.

Validation. EpochRangeValidator gains the upper-bound rule and is constructed with the constant. The new MaxEpochTooFarAhead error is classified node-local, not sender fault: a node lagging by even one epoch computes a lower ceiling, so a transaction stamped at the ceiling would look too-far-ahead and graylist an honest peer. Same class as the existing CurrentEpochLessThanMinimum / CurrentEpochGreaterThanMaximum.

Enforcement. Mempool ingress now runs the epoch rules alongside the structural ones and before the gossip-acceptance verdict, so an out-of-window transaction is refused before it is admitted or re-gossiped. Consensus sequencing already routed through the same validator via TariBlockTransactionValidator.

Wallet. The daemon stamps max_epoch = current_epoch + default_transaction_validity_epochs (new config, default 3 ≈ 1 hour) when the caller does not supply one, backed by a 30-second epoch cache so a burst of builds does not make an indexer round-trip each. Building now fails if the indexer is unreachable rather than guessing a window the network may not accept. settings.get exposes current_epoch and the default window so callers that build transactions themselves — wallet CLI, traffic-sim — can pick a valid window without a new endpoint.

Ledger. SigningField::MaxEpoch now carries a bare little-endian u64 rather than a borsh Option, and the device always displays it. Field tag numbering is unchanged.

Deployment notes

Consensus-breaking and a signing-domain break. The max_epoch field encoding changes (borsh Option<Epoch> → Epoch), so pre-signed transactions do not carry over and the Ledger app + ootle-go golden vectors need the coordinated update. Belongs in the same breaking batch as the other consensus changes in this release.

The Ledger app crate (ootle-ledger-app) is out-of-workspace and needs the device toolchain — it is not built by CI here. Its changes match the type change and the in-workspace lock-step test guards the contract, but it needs a device build before release.

Verification

• 6 new EpochRangeValidator unit tests: inside-window, before min_epoch, expired, beyond the ceiling, inclusive boundary, and a saturating ceiling that admits any max_epoch.
• Consensus-constant uniformity test.
• Ledger lock-step tests green: preimage_field_tags_match_protocol plus the seal / add-signer / stealth recipe tests.
• SDK golden vectors regenerated (OOTLE_REGEN_FIXTURES=1).
• TS bindings hand-edited, bindings/package.json bumped to 1.49.0, dist rebuilt.
• cargo lints clippy --all-targets clean; cargo +nightly-2025-12-05 fmt --all applied.
• cargo nextest r -E "not package(integration_tests)" --no-fail-fast --release → 1772 passed, 0 failed.

[sdbondi]

Review

The mechanical Option<Epoch> → Epoch conversion looks consistent — no leftover Option handling, all TransactionBuilder::new/Transaction::builder call sites updated, EpochRangeValidator wired at both mempool ingress and consensus sequencing, and the ledger read_u64 matches borsh's bare-LE-u64 encoding of Epoch. Findings below.

---

1. applications/tari_walletd/src/services/auto_claim_burn_service.rs:465 — network error classified as permanent

self.claim_max_epoch().await.map_err(ClaimError::Permanent)? misclassifies a network failure. claim_max_epoch → query_current_epoch → sdk.get_network_interface().get_current_epoch() is an indexer round-trip, and ClaimError::Transient's own doc says "network unavailable, indexer unreachable" is transient (that's what MAX_RETRIES_NETWORK exists for).

Scenario: the indexer is restarting when the 30s auto-claim tick fires; get_current_epoch errors, the claim is classified Permanent, pending_claims.remove(&file_name) drops it from the queue, and the burn is never auto-claimed — manual claim required even though the next tick would have succeeded. Same at line 508 for the non-dry-run submission.

The enclosing loop already resolves current_epoch for the readiness filter; reuse it, or map to ClaimError::transient(e, MAX_RETRIES_NETWORK).

2. applications/tari_walletd/src/services/auto_claim_burn_service.rs:34 — doc comment now attached to the wrong const

The new const was inserted directly under MAX_RETRIES_NETWORK's doc comment, so /// Maximum retries for network/submission errors (indexer unreachable, tx service down). now documents CLAIM_TRANSACTION_VALIDITY_EPOCHS (line 37), and MAX_RETRIES_NETWORK (line 39) is left undocumented.

3. crates/storage/src/consensus_models/transaction_pool.rs:417 — stale #[serde(default)] inverts meaning

#[serde(default)] was left on max_epoch when its type changed from Option<Epoch> to Epoch. Epoch: Default is Epoch(0), so a payload missing the field used to mean "no expiry" and now means "expired before epoch 1". Any TransactionPoolRecord deserialized from a payload omitting max_epoch yields a record that every execution_epoch > max_epoch check treats as expired. Either drop the attribute so a missing field errors, or make the default explicit.

4. crates/transaction_validation/src/error.rs:121 — MaxEpochTooFarAhead gives spam a free pass

It is classified is_sender_fault() == false, so MempoolService::handle_new_transaction returns MessageAcceptance::Ignore, which carries no peer-score penalty. The stated justification (a node lagging one epoch computes a lower ceiling) only holds at the boundary.

Scenario: a peer floods transactions stamped max_epoch = u64::MAX; every node validates, drops, and reports Ignore, so the sender is never penalised or graylisted for traffic that is unambiguously invalid on any honest view of the epoch. A graduated rule (node-local within some slack of the ceiling, sender-fault beyond it) keeps the anti-graylist property without giving up the spam defence.

5. applications/tari_walletd/src/config.rs:107 — default_transaction_validity_epochs unvalidated

0 produces max_epoch == current_epoch, so every transaction the daemon builds must be sequenced inside the current epoch and will usually expire near a boundary. A value above max_transaction_validity_epochs (2160) makes every built transaction fail validation network-wide with MaxEpochTooFarAhead — and because that error is node-local (finding 4), it is silently Ignored rather than reported, so the operator sees transactions vanish with no diagnostic. A startup check (1..=2160) turns both into a config error.

6. utilities/traffic-sim/src/sim.rs:428 — validity window hoisted out of the loop

let max_epoch = exchange_wallet.max_epoch().await?; sits outside the for (wallet, account) in self.wallet_and_account_iter() loop, so one 10-epoch window is stamped on every transaction the loop builds. Each iteration makes several wallet-daemon round-trips; with epoch_time: 120 (the commented preset) 10 epochs is ~20 minutes, so a run over enough wallets has later transactions rejected as CurrentEpochGreaterThanMaximum. Resolving it per iteration (or per wallet) costs one cached settings call.

[sdbondi]

Re-review (through 8d4f7563)

All five walletd/storage/traffic-sim findings from the previous round are resolved. Finding 4 (MaxEpochTooFarAhead not sender-fault) stands and is restated below. Six findings on the current head:

---

1. crates/transaction_validation/src/epoch_range.rs:55 — high: the ceiling splits the verdict across nodes at an epoch boundary

The new ceiling is a consensus rule evaluated against each node's local epoch (epoch_state.epoch() at the validate_epoch/validate_full call sites in on_receive_new_transaction.rs:205-206, current_view().get_epoch() in the mempool), so the constant being uniform network-wide is not sufficient for nodes to agree.

At a boundary, node A is at E while replica B is still at E-1. A transaction stamped max_epoch = E + 2160 — exactly the ceiling, which is precisely what the long-window offline/multi-party signing case the constant exists for will use — is accepted by A and rejected by B with MaxEpochTooFarAhead.

Unlike CurrentEpochGreaterThanMaximum, whose error direction makes a lagging node more permissive, this rule makes the lagging node stricter, which is the dangerous direction: validate_new_transaction returns Ok(None), the transaction is silently never added to B's pool with no retry, and a block parked on it stays parked. Either evaluate the ceiling against a deterministic epoch, or add boundary slack (current + max_validity + epoch_end_spread-ish) so a one-epoch view difference cannot split the verdict. Classifying the error node-local addresses peer scoring, but not this.

2. applications/tari_walletd/src/handlers/transaction.rs:191 — medium: submit now needs the indexer even when it has nothing to resolve

submit_inner calls context.transaction_builder().await? and then immediately with_unsigned_transaction(req.transaction), which replaces the whole unsigned transaction and discards the max_epoch just fetched. The fetch is an indexer round-trip that can fail, so transactions.submit now errors when the indexer is unreachable even though the caller supplied a complete (possibly already-signed) transaction carrying its own max_epoch. Same pattern at lines 387 (handle_detect_inputs) and 439 (submit_dry_run_inner). These three want a builder that does not resolve an epoch.

3. applications/tari_walletd/web_ui/src/components/IndexerLivenessPill.tsx:76 — medium: pill probes while logged out

The pill is mounted in LayoutMain, the parent route element in App.tsx:238, so it renders while GuardedRoute is still showing the auth dialog. settingsGet() is an authenticated call, so on the login screen every probe throws; after two polls (30s) the pill reads "Disconnected" and the tooltip shows the auth error as if the indexer were down — and it keeps issuing failing authenticated RPCs every 15s. Gate the probe on the auth store's loggedIn.

4. crates/transaction_validation/src/error.rs:126 — low: unbounded overshoot is unpunished (carried over)

MaxEpochTooFarAhead => false makes the mempool report MessageAcceptance::Ignore, so the peer is never scored down. The one-epoch-lag argument justifies leniency for values near the ceiling; a peer gossiping a stream stamped max_epoch = u64::MAX is unambiguously at fault and gets no penalty, after every node has already paid full structural + signature validation (structural runs first, service.rs:274). Treating an overshoot larger than any plausible lag as sender fault keeps the anti-graylist property.

5. applications/tari_walletd/src/handlers/context.rs:299 — low: epoch cache survives an indexer switch

The 30s epoch cache is never invalidated when settings.set repoints the daemon at a different indexer. After switching networks (or to an indexer on a different chain), for up to 30s transaction_max_epoch() stamps a max_epoch derived from the previous network's epoch; if the two chains differ by more than max_transaction_validity_epochs, the transactions are rejected as out of range with no obvious cause. Clearing cached_epoch in the settings-set handler closes it.

6. applications/tari_walletd/src/config.rs:129 — low: boundary is off by one against the ceiling

The guard is > against a hard-copied IMPLAUSIBLE_TRANSACTION_VALIDITY_EPOCHS = 2160, so exactly 2160 passes silently — yet that value stamps max_epoch at exactly the network ceiling, i.e. the case any validator lagging one epoch refuses (finding 1). The constant also has no compile-time link to ConsensusConstants::max_transaction_validity_epochs; if the consensus ceiling is ever lowered, the wallet keeps accepting a config under which every transaction it builds is unsequenceable.

---

Checked and cleared: the MutexGuard in current_epoch() is dropped before the .await (the scrutinee temporary ends with the if statement), so no deadlock at line 307 and no !Send future; min_epoch > max_epoch is unreachable-but-harmless (rejected at every epoch, so never admitted); the ledger SigningField::MaxEpoch 8-byte read matches Epoch's borsh encoding and the field stays in both ADD_SIGNER_SEQ/SEAL_SEQ; with_unsigned_transaction's fee-builder max_epoch is never read, so the divergence with with_max_epoch is inert.