Add local pre-broadcast outcome variant to NodeBroadcastOutcomeSchema (or split into a sibling LocalBroadcastFailureSchema)

[whoabuddy]

Context

NodeBroadcastOutcomeSchema in src/core/nonce-outcome.ts is a discriminated union covering everything stacks-core can return from a broadcast attempt: accepted, nonce_conflict, chaining_limit, nonce_too_low, fee_too_low, insufficient_funds, invalid_transaction, rate_limited, server_error, temporarily_blacklisted. decideBroadcastAction then classifies each into a (responsible, action) pair so consumers can act consistently.

The implicit assumption: every broadcast attempt makes it as far as a node response. But there's a category of failures that happens before the HTTP call, in the local @stacks/transactions library itself:

• Cannot sponsor sign a non-sponsored transaction — thrown when tx.auth.authType !== AuthType.Sponsored
• Failed to deserialize transaction — thrown on malformed hex
• Various assert / invariant style throws on bad SpendingConditionSpec, etc.

These bypass the classifier entirely and have to be handled with ad-hoc string matching in consumer catch blocks, which violates the whole point of the typed pipeline.

Production incident that motivated this

aibtcdev/x402-sponsor-relay 2026-05-19 13:00 UTC: a buggy /settle re-sponsor branch (PR aibtcdev/x402-sponsor-relay#382) enqueued a structurally-invalid hex into the bounded-broadcast queue. On every alarm tick (~5 min), the worker tried to sponsor-sign the queued tx, threw "Cannot sponsor sign a non-sponsored transaction", got caught by a generic catch block that logged the warning and incremented an error counter — and retried indefinitely.

Result: 3 wallet-0 sponsor nonces wedged for hours generating perpetual log spam until natural cleanup mechanisms (dispatch_flush_start: dispatched_entry_stuck) eventually fired.

Two stopgap fixes shipped on the relay side:

• fix(settle): gate buggy re-sponsor recovery behind ENABLE_SETTLE_RESPONSOR (default off) x402-sponsor-relay#390 — gated the buggy code path behind ENABLE_SETTLE_RESPONSOR=false (prevents new bad entries)
• fix(nonce-do): retire bounded_broadcast zombies on head-advance + structural exceptions x402-sponsor-relay#392 — added a head-advance retire guard + a string-match retire on non-sponsored transaction/failed to deserialize/malformed in the catch block (cleans up zombies)

The #392 change is the part that belongs in tx-schemas. String-matching in a catch block is not the right home for a classification decision — it should be in the discriminated-union schema, alongside the existing node outcomes.

What we need

Option A — extend NodeBroadcastOutcomeSchema

Add a new variant:

const LocalStructuralFailureSchema = z.object({
  outcome: z.literal(\"local_structural_failure\"),
  kind: z.enum([\"auth_type_mismatch\", \"deserialize_failed\", \"malformed_bytes\", \"unknown\"]),
  reason: z.string().min(1),
});

Pros: single union, callers only need to handle one discriminated type.

Cons: muddles the "this is what the node said" semantics — the name NodeBroadcastOutcomeSchema implies a node response.

Option B — sibling LocalBroadcastFailureSchema (preferred)

Keep NodeBroadcastOutcomeSchema strictly for node responses. Add a sibling:

export const LocalBroadcastFailureSchema = z.discriminatedUnion(\"kind\", [
  z.object({ kind: z.literal(\"auth_type_mismatch\"), reason: z.string() }),
  z.object({ kind: z.literal(\"deserialize_failed\"), reason: z.string() }),
  z.object({ kind: z.literal(\"malformed_bytes\"), reason: z.string() }),
  z.object({ kind: z.literal(\"unknown_local\"), reason: z.string() }),
]);
export type LocalBroadcastFailure = z.infer<typeof LocalBroadcastFailureSchema>;

And a wrapper union for full broadcast attempt outcomes:

export const BroadcastAttemptOutcomeSchema = z.discriminatedUnion(\"source\", [
  z.object({ source: z.literal(\"node\"), node: NodeBroadcastOutcomeSchema }),
  z.object({ source: z.literal(\"local\"), local: LocalBroadcastFailureSchema }),
]);

Pros: keeps node semantics clean, lets callers branch on source first.

Companion: extend decideBroadcastAction

Either way, decideBroadcastAction (src/core/... — wherever it lives) needs to gain branches that:

• Map all local_structural_failure / LocalBroadcastFailure variants to responsible: \"relay\" + action: \"retire\" (do not retry — the hex is broken, not the transient world).
• Provide a parseLocalBroadcastFailure(err: unknown) helper that takes a caught Error and classifies it (or returns null for non-structural throws that should propagate).

export function parseLocalBroadcastFailure(err: unknown): LocalBroadcastFailure | null {
  const msg = err instanceof Error ? err.message : String(err);
  if (/non-sponsored transaction/i.test(msg)) return { kind: \"auth_type_mismatch\", reason: msg };
  if (/failed to deserialize/i.test(msg)) return { kind: \"deserialize_failed\", reason: msg };
  if (/malformed/i.test(msg)) return { kind: \"malformed_bytes\", reason: msg };
  return null;
}

Consumer rewrite (relay)

Once landed, aibtcdev/x402-sponsor-relay/src/durable-objects/nonce-do.ts bounded_broadcast catch block stops doing its own regex and routes through the schema:

} catch (e) {
  const local = parseLocalBroadcastFailure(e);
  if (local) {
    const action = decideBroadcastAction({ source: \"local\", local });
    if (action.action === \"retire\") {
      this.retireQueuedEntry(entry.wallet_index, entry.sponsor_nonce, local.kind);
      this.log(\"warn\", \"bounded_broadcast_local_failure_retired\", { ...local });
      errors++;
      continue;
    }
  }
  // genuinely unexpected — keep current catch behavior
  this.log(\"warn\", \"bounded_broadcast_error\", { error: e instanceof Error ? e.message : String(e) });
  errors++;
}

Acceptance criteria

• Schema variant added (Option A or B — preference B documented above).
• decideBroadcastAction updated with new branches mapping all local failures to responsible: \"relay\" + action: \"retire\".
• parseLocalBroadcastFailure(err) helper exported and unit-tested for the three known patterns + null pass-through.
• release-please bumps minor (additive change, no breaking API).
• Relay PR follows up: replace string-match catch block with the new classifier (planned scope, no behavior change).

Out of scope

• Re-enabling ENABLE_SETTLE_RESPONSOR on the relay. That needs a separate rewrite of the re-sponsor path to bypass the dispatch queue entirely (not enqueue and sign in two steps) — tracked separately.

Refs

• Incident: 2026-05-19 13:00 UTC, aibtcdev/x402-sponsor-relay`.planning/2026-05-18-nonce-conflict-attribution/REGRESSION-NOTES.md` (private to relay repo)
• Relay stopgap PR: fix(settle): gate buggy re-sponsor recovery behind ENABLE_SETTLE_RESPONSOR (default off) x402-sponsor-relay#390
• Relay zombie cleanup PR: fix(nonce-do): retire bounded_broadcast zombies on head-advance + structural exceptions x402-sponsor-relay#392
• Original Phase 2 attribution work: /settle should re-sponsor pre-sponsored txs on ConflictingNonceInMempool instead of returning error x402-sponsor-relay#373, #381, #382

[secret-mars]

Endorsing Option B. Three refinements before landing, one out-of-scope thought.

Cross-repo context: reviewed the x402-sponsor-relay quest cluster (#378–#387) concurrent with this incident; the "string-matching in a catch block" anti-pattern @whoabuddy describes is the right thing to move out of the relay's nonce-DO bounded_broadcast loop. Sibling type beats union extension for reasons beyond clean semantics:

A wave of node:nonce_too_low and a wave of local:auth_type_mismatch deserve materially different remediation. Both retire, but the first means chain-state divergence (mempool stuck, possible reorg) and the second means a recent deploy bug. Keeping source branchable at the type level lets dashboards and on-call routes pivot on it cleanly. Option A flattens that into a single union variant; Option B preserves it.

Three refinements

1. Schema/parser variant drift in parseLocalBroadcastFailure. The proposed schema has four kind variants (auth_type_mismatch, deserialize_failed, malformed_bytes, unknown_local) but the proposed parser only emits the first three and returns null otherwise. That leaves unknown_local as a dead schema branch and bypasses the typed pipeline for the exact case where it's most useful — unrecognized errors from new @stacks/transactions versions. Suggested fix: parser always returns a LocalBroadcastFailure (drop the nullable), emits unknown_local for non-matching Error/string casts, and decideBroadcastAction routes unknown_local to a distinct action like "alert_for_review" (or "surface_for_triage") instead of "retire". Otherwise new failure shapes silently fall through to generic catch blocks — the exact regression mode this issue is trying to prevent.

2. Canonical-string sourcing, not open-ended regex. The proposed substring regex (/non-sponsored transaction/i, etc.) is durable against punctuation/case variants but fragile against legitimate refactors in @stacks/transactions. Suggest keeping the canonical messages in a top-level constants file with the package version pinned in a comment header (// canonical strings sourced from @stacks/transactions@X.Y.Z); a CI step verifies on package bump. Test coverage: one fixture per canonical string + one explicit unknown_local negative case asserting the parser doesn't silently re-classify a refactored message as a known kind.

3. decideBroadcastAction signature — additive vs breaking. Current signature presumably takes NodeBroadcastOutcome directly. Option B's wrapper means callers eventually want BroadcastAttemptOutcome. Two clean paths:

• Additive: keep decideBroadcastAction(node: NodeBroadcastOutcome) unchanged; add decideBroadcastAttempt(attempt: BroadcastAttemptOutcome) that dispatches on source. Existing relay call sites update only at the migration point. release-please stays at minor.
• Breaking: widen the existing signature to accept the union. Cleaner long-term but requires a coordinated bump in the relay + any other tx-schemas consumers.

Given the relay is the only known consumer that needs this right now, the additive path probably wins — keeps the release strictly minor and lets the relay PR migrate at its own pace.

Out-of-scope (runbook-only, not for this issue)

A fourth category of pre-broadcast failure I haven't seen captured here: wallet/signer-state errors — signing key missing in keystore, password not unlocked, hardware-wallet device disconnected, etc. Those fail at a different layer than @stacks/transactions (before reaching the tx-content classifier) and are caller-state, not tx-content. They probably belong in a separate LocalSignerError enum routed to responsible: "caller" + action: "halt_and_surface", not bundled into LocalBroadcastFailure. Surfacing for the post-fix runbook write-up rather than as scope creep on this issue.

[secret-mars]

@whoabuddy — 9-day ladder ping on this. My v459 endorsement of Option B (with 3 refinements + 1 out-of-scope thought) is the only follow-up since you filed it 5/19. Curious whether:

• (a) still planned for landing — happy to leave it sitting; or
• (b) scope-park — close-and-revisit-on-next-trigger; or
• (c) different direction since the 5/25 x402-sponsor-relay umbrella close-out (#406 + #409 + #411 + #412 all merged + deployed mainnet) — that work formalized the sender-conflict resolve paths but didn't, as far as I can see, touch NodeBroadcastOutcomeSchema itself, so the local-pre-broadcast-failure variant is still on the table as schema work. Just want to confirm before I assume it's still on your queue.

If (a), no action needed; I'll re-ladder in another 7d. If (b) or (c), happy to take a stab at the additive Option-B PR (parser unknown_local dead branch handled per refinement #1 + canonical-string sourcing per #2 + additive-signature path per #3) — let me know.