Receipt timeout after a broadcast transferWithAuthorization becomes SettleResponse::Failure with no transaction hash — and the resulting 402 induces a fresh-nonce second charge

[aurumflux20]

Good to be back in a qntx repo (we spoke on x402-openai-python#34). A few things here are better than most facilitators I've read: verify.rs checks authorizationState before ever settling, the nonce manager resets on failure instead of drifting, and the error taxonomy in r402-core is genuinely clean. This report is about one path where that taxonomy has no room for the outcome that actually happens.

The path

Eip155ChainProvider::send_transaction (crates/r402-evm/src/chain/provider.rs) does the right two-step: broadcast, then wait for the receipt.

let pending_tx = match self.inner.send_transaction(txr).await { Ok(pending) => pending, Err(e) => { ...reset_nonce...; return Err(Transport(e)) } };
let watcher = pending_tx.with_required_confirmations(tx.confirmations).with_timeout(Some(timeout));
match watcher.get_receipt().await {
    Ok(receipt) => Ok(receipt),
    Err(e) => {
        // Receipt fetch failed (timeout or other error) - reset nonce to force requery
        self.nonce_manager.reset_nonce(from_address).await;
        Err(MetaTransactionSendError::PendingTransaction(e))
    }
}

The first arm is a definitive failure — nothing left the process. The second is not: by the time get_receipt times out, the transferWithAuthorization is in the mempool. The facilitator's receipt_timeout_secs defaults to 20 (with the note that it "must finish inside the 30 s HTTP client budget"), and Base under load routinely takes longer than that to hand back a receipt. So this arm fires on ordinary congestion, for a transfer that lands seconds later.

Both arms return Err, and from there the two indistinguishable outcomes take one road:

• settle_payment propagates it with ? as Eip155ExactError
• error.rs:220 maps Timeout => ErrorReason::UnexpectedSettleError
• rpc.rs:481 builds SettleResponse::Failure { reason, message, payer: None, network, extensions }

Failure has no transaction field — only Success does. So the caller receives success:false, unexpected_settle_error and the hash of a payment that very likely landed is dropped entirely. Nobody downstream can find, reconcile, or refund it.

Why the authorizationState check doesn't cover this

It's the right guard and I'm glad it's there — but it protects against replaying the same authorization. That isn't the retry this failure induces.

Under x402, a resource server that gets success:false from /settle does not serve the resource; it returns 402 with fresh requirements. A conforming client treats that as "payment required" and signs a new authorization with a new nonce. That nonce has never been seen, so authorizationState is false, verify passes, and the facilitator settles it — a second real transferWithAuthorization for the same purchase. The first one, meanwhile, has confirmed on chain with no record on your side that it exists.

So the payer is charged twice, and the only response they ever saw for the first charge was "unexpected settle error."

One secondary thing worth checking rather than asserting: reset_nonce on the timeout arm forces a requery, and the timed-out transfer is still pending. Whether the requeried nonce collides with that in-flight transaction depends on which block tag the nonce manager queries; if it's latest, the next settlement (a different payer's) could reuse the nonce and replace the pending transfer. I haven't traced the nonce manager far enough to claim it — flagging it because the timeout arm is exactly where it would bite.

The fix — the outcome needs a name

The taxonomy is one variant short. Timeout should not be UnexpectedSettleError; it's a third state between success and failure, and the code already holds the one thing needed to make it useful — pending_tx.tx_hash().

• In send_transaction, on the receipt-timeout arm, return a distinct variant carrying the hash (e.g. SettlementPending { tx_hash }) instead of folding it into PendingTransaction alongside definitive failures.
• Give SettleResponse a shape for it — an ambiguous/pending result that carries transaction, rather than Failure — so a resource server can tell "your payment was rejected" from "the chain hasn't answered yet." Those must never look the same on the wire, because only the first should ever become a 402.
• On the pending shape, the resource server should hold and reconcile rather than re-challenge: you have two authoritative reads for free — get_transaction_receipt(hash) and the authorizationState(nonce) you already call. Either resolves pending → settled/not-settled before anyone is asked to pay again.

This is the piece the current taxonomy can't express: an outcome that is terminal-for-now but not a failure. Once it has a name, everything downstream — the nonce reset, the 402 decision, the receipt the payer gets — can branch on it correctly.

Scope, honestly: this is a line-by-line read of main across facilitator and r402, not a live reproduction — I haven't driven a receipt timeout against a real facilitator and watched two transfers land. The control flow and the wire mapping are verified; the double-charge is the consequence that follows from them under x402's client behaviour.

For context on the general shape: the rule that an ambiguous outcome must stay distinct and never be collapsed into "did not happen" is §4.3 of the MCP retry-safety proposal I've been co-authoring with @YoadElkayam (https://github.com/YoadElkayam/mcp-fuse/tree/main/sep) — a working draft with no sponsor yet, not an adopted standard. Your authorizationState pre-check is already the reconciliation read it describes; this is about giving its result somewhere to go on the timeout path.

Happy to send a PR for the pending variant plus a test that times out get_receipt and asserts the hash survives to the wire — your call entirely.

[aurumflux20]

Turned this into a failing test against main, and confirmed the shape of a fix that makes it pass.

Red on main — crates/r402-core/tests/settlement_pending_hash.rs, run with cargo test -p r402-core --all-features:

test post_broadcast_failure_carries_the_tx_hash ... FAILED
test failure_can_express_a_transaction_like_success_can ... FAILED

assertion failed: a broadcast that may have landed was reported with no
recoverable transaction hash: the caller cannot reconcile, so a retry mints
a fresh nonce and pays twice
  left: String("")
 right: String("")

test result: FAILED. 0 passed; 2 failed

The assertion is deliberately on the property, not a wire shape: after a post-broadcast failure the hash must be recoverable from the response somewhere — top-level transaction, an extension, anything. The helper scans all of them. On main there is no path that puts it anywhere, because SettleResponse::Failure has no field for it and send_transaction discards it: Err(MetaTransactionSendError::PendingTransaction(e)) at crates/r402-evm/src/chain/provider.rs:344 carries no hash, though pending_tx held one two lines earlier.

What makes it green. The failure needs an error variant that can carry the hash — e.g. SettlementError::Pending { transaction } — mapped to errorReason: "settlement_pending" with the hash attached. On a branch with that variant the equivalent assertion passes:

test wire::rpc::response_tests::settle_pending_failure_carries_the_transaction_hash_on_the_wire ... ok

I went the extensions route rather than adding a field to Failure, because a new field on that variant touches roughly forty construction sites across the chain crates; an extension entry is additive and costs nothing to ignore. That is a design call, not part of the finding — the test above passes either way.

Scope, stated honestly: this is a unit-level proof of the structural claim — that a post-broadcast failure cannot carry its hash. It is not a live reproduction against a running facilitator; I have not driven a receipt timeout on a real chain and watched two transfers land. The control flow at provider.rs:337-346 and the absence of any hash-bearing path on the failure side are verified from source and pinned by the test.

settlement_pending_hash.rs — drop into crates/r402-core/tests/

//! Regression test for issue #73 — RED on main.
//!
//! `Eip155ChainProvider::send_transaction` (crates/r402-evm/src/chain/provider.rs)
//! broadcasts, then waits for a receipt. When that wait fails *after* a successful
//! broadcast, the transaction is in the mempool and likely to land — but the error
//! it produces (`MetaTransactionSendError::PendingTransaction`) carries no hash,
//! and the `SettleResponse::Failure` it becomes has no field that could carry one.
//! The caller is told "failed" and handed nothing to reconcile against, so a retry
//! mints a fresh nonce and pays a second time.
//!
//! The assertion is on the *property*, not on a particular wire shape: after a
//! post-broadcast failure, the hash must be recoverable from the response
//! somewhere — a top-level `transaction`, an extension, anything. Which of those
//! is the right home is the maintainers' call.

use compact_str::CompactString;
use r402_core::error::{ErrorReason, FacilitatorError};
use r402_core::wire::SettleResponse;

/// Recover a broadcast hash from a settle response, whatever shape carries it.
fn recoverable_hash(json: &serde_json::Value) -> Option<String> {
    if let Some(t) = json.get("transaction").and_then(|v| v.as_str())
        && !t.is_empty()
    {
        return Some(t.to_owned());
    }
    // Any extension that names a transaction is equally good evidence.
    let ext = json.get("extensions")?.as_object()?;
    for (_name, entry) in ext {
        if let Some(t) = entry
            .pointer("/info/transaction")
            .or_else(|| entry.get("transaction"))
            .and_then(|v| v.as_str())
            && !t.is_empty()
        {
            return Some(t.to_owned());
        }
    }
    None
}

/// A settlement that was broadcast but whose receipt could not be read must still
/// name the transaction, so the caller can reconcile instead of re-paying.
#[test]
fn post_broadcast_failure_carries_the_tx_hash() {
    let err = FacilitatorError::internal("receipt wait timed out after a successful broadcast");
    let resp = SettleResponse::from_facilitator_error(&err, "eip155:8453");
    let json = serde_json::to_value(&resp).expect("serialise");

    assert_eq!(json["success"], serde_json::json!(false));
    assert!(
        recoverable_hash(&json).is_some(),
        "a broadcast that may have landed was reported with no recoverable transaction \
         hash: the caller cannot reconcile, so a retry mints a fresh nonce and pays twice.\n\
         response was: {json}"
    );
}

/// The asymmetry the issue is about: `Success` can name the transaction, a
/// post-broadcast `Failure` cannot — even though that is exactly the case where
/// the hash is the only evidence that exists.
#[test]
fn failure_can_express_a_transaction_like_success_can() {
    let ok = SettleResponse::Success {
        payer: CompactString::from("0xpayer"),
        transaction: CompactString::from("0xdeadbeef"),
        network: CompactString::from("eip155:8453"),
        amount: None,
        extensions: Default::default(),
    };
    let ok_json = serde_json::to_value(&ok).expect("serialise");
    assert_eq!(recoverable_hash(&ok_json).as_deref(), Some("0xdeadbeef"));

    let failure = SettleResponse::Failure {
        reason: ErrorReason::UnexpectedSettleError,
        message: Some(CompactString::from("receipt unavailable after broadcast")),
        payer: None,
        network: CompactString::from("eip155:8453"),
        extensions: Default::default(),
    };
    let failure_json = serde_json::to_value(&failure).expect("serialise");
    assert!(
        recoverable_hash(&failure_json).is_some(),
        "Failure offers no way to carry the hash of a transaction already in the mempool"
    );
}

[aurumflux20]

Following up once, because the surface area changed since this was filed rather than the defect.

Between 2 and 8 September this repo composed exact facilitators for NEAR, XRPL, Hedera, AVM, Aptos, Keeta, TVM, Stellar and Concordium, plus experimental TRON, and cut 0.7.0 and 0.7.1. That is nine more rails, and the failing test in this issue sits in r402-core — the settle path they all compose over. So this is not nine separate bugs to argue about; it is one branch that each new family inherits the moment it ships.

The question I would want answered in your position, and I genuinely do not know the answer from outside: is the post-broadcast failure path chain-specific, or does every family share the one SettleResponse::Failure construction that drops the hash? If it is shared, every rail added this week widened the same window, and the fix is one place. If each family builds its own failure response, then this issue understates the problem and there are ten of them.

Nothing else from me on this thread. The report, the failing test and the shape of the fix are all above and stay free to use however you like — no attribution needed, and no reply expected if the answer is "we know, it is scheduled."