Module X402::BSV::NetworkVisibility ¶
Centralised "is this txid visible on the BSV network via ARC?" check.
Used by gateway settle paths to enforce that the client actually broadcast the payment transaction before we mutate wallet / replay state. A valid-looking BEEF is not proof of broadcast; ARC observation is. This helper absorbs propagation lag with a bounded retry loop, caches positive outcomes for a short TTL to protect ARC from duplicate-submission bursts, and classifies failures cleanly:
* non-visible status (or 404 "unknown txid") → client fault → 402
* 5xx / SocketError / Timeout → ARC outage → 503
Negative results are NEVER cached: propagation can flip UNKNOWN to SEEN_ON_NETWORK at any moment, and a cached negative would delay legitimate payments.
Constants¶
DEFAULT_SLEEPER ¶
Not documented.
KNOWN_NON_VISIBLE ¶
Non-visible statuses the SDK may surface. Logged at WARN if a response falls outside this plus VISIBLE_STATUSES — surfaces ARC enum drift without failing the request.
NOT_VISIBLE_MESSAGE ¶
Not documented.
OUTAGE_MESSAGE ¶
Not documented.
RETRY_DELAYS_SECONDS ¶
Backoff schedule between ARC polls. One immediate attempt plus three retries → 4 attempts total, absorbing ~1.75 s of propagation lag. Mirrors ProofGateway#check_mempool! timing.
VISIBLE_STATUSES ¶
ARC statuses that indicate the client successfully broadcast. Kept deliberately tight (2 values) — distinct from ProofGateway's 8-value "is my server's broadcast propagating?" whitelist. SEEN_ON_NETWORK is the first ARC status confirming a different node has observed the tx (not just ARC-side ingestion); MINED confirms it landed in a block.
Public Class Methods¶
verify!(arc_client:, txid:, cache:, logger: = nil, visible_statuses: = VISIBLE_STATUSES, sleeper: = DEFAULT_SLEEPER) ¶
Verify that txid is visible on the BSV network via arc_client.
Returns the observed status string on success. Raises X402::VerificationError with +status: 402+ on exhaustion with a non-visible status, or +status: 503+ on ARC outage / network fault. - @param arc_client [#status] ARC client responding to +#status(txid)+ - @param txid [String] hex transaction id to check - @param cache [Cache] per-gateway positive-only TTL cache - @param logger [#warn, nil] optional logger for unknown-status warnings - @param visible_statuses [Arraysleeper [#call] injectable sleep lambda (for tests) - @raise [X402::VerificationError] 402 on non-visible; 503 on outage - @return [String] the visible status that satisfied the check