Add typed error classes for transaction lifecycle with error classification

[marshacb]

Summary

Adds typed error classes for the execute lifecycle so users can programmatically distinguish between broadcast failures, proving errors, confirmation timeouts, finalize reverts, and duplicate transactions. Replaces generic Error throws throughout the execute path.

try {
  await contract.execute.mint_card({ inputs: [...] })
} catch (e) {
  if (e instanceof FinalizeRevertError) {
    // Finalize reverted on-chain - fee consumed, public state unchanged
  } else if (e instanceof TransactionTimeoutError) {
    // May still confirm - check e.transactionId before resubmitting
  } else if (e instanceof DuplicateTransactionError) {
    // Already on-chain - safe to treat as success
  } else if (e instanceof RecordAlreadyUsedError) {
    // Record spent - refresh with requestRecords() and retry
  }
}

Addresses #19 and PR #9 review comments 13, 14, 15.

New error classes (all extend BaseError)

Class	Trigger
InvalidTransactionError	Malformed transaction, fee verification failure, bad ID
DuplicateTransactionError	Transaction already exists in the ledger
RecordAlreadyUsedError	Record UTXO already consumed (duplicate Output ID, serial number, etc.)
BroadcastError	Network congestion (429/503) or unrecognized broadcast failure
TransactionTimeoutError	Confirmation polling exceeded timeout
FinalizeRevertError	Confirmed transaction with status: "rejected" (finalize reverted, fee consumed)
ProvingError	Proof generation or DPS submission failure
SimulateNotSupportedError	simulateContract called on RPC (wallet) account

Error classifiers

Two functions that parse raw SDK errors into typed Veil errors:

• classifyBroadcastError(error, txId?) - regex-based classification for submitTransaction errors (SDK doesn't preserve HTTP status)
• classifyProvingError(error) - delegates broadcast-like messages, wraps rest as ProvingError

Execute lifecycle changes

• waitForConfirmation now uses getConfirmedTransaction (returns status) instead of getTransaction — detects finalize reverts via status === "rejected"
• Delegated path: provingRequest + submitProvingRequest wrapped → classifyProvingError
• Local path: buildExecutionTransaction → ProvingError, submitTransaction → classifyBroadcastError
• All catch blocks re-throw BaseError instances to avoid double-wrapping

Files

• packages/core/src/errors/errors.ts - 8 error classes + 2 classifier functions
• packages/core/src/index.ts - exports
• packages/core/src/actions/wallet/simulateContract.ts - SimulateNotSupportedError
• packages/provable/src/index.ts - execute lifecycle wrapping + getConfirmedTransaction fix
• packages/core/test/errors/errors.test.ts - 25 new tests

Test plan

• 614 tests pass (25 new, 0 regressions)
• Error classes: constructor, .name, instanceof BaseError, domain properties, cause chain
• Classifiers: all SnarkOS error message patterns correctly classified
• SimulateNotSupportedError thrown for RPC accounts

[vercel]

@marshacb must be a member of the Provable team on Vercel to deploy.
- Click here to add @marshacb to the team.
- If you initiated this build, request access.
- If you're already a member of the Provable team, make sure that your Vercel account is connected to your GitHub account.

Learn more about collaboration on Vercel and other options here.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
veil-loyalty-dapp	Error		May 6, 2026 8:42pm

[iamalwaysuncomfortable]

A few things worth tightening before merge.

1. waitForConfirmation swallows polling errors silently

packages/provable/src/index.ts:379-385 — the bare catch (e) discards every non-FinalizeRevertError exception (network failure, RPC down, malformed response) and keeps polling. After the timeout the caller sees TransactionTimeoutError with no hint that the actual problem was the network.

Capture the last error and attach as cause:

let lastError: unknown
while (Date.now() - startTime < timeout) {
  try {
    const confirmed = await pollingClient.getConfirmedTransaction(txId)
    if (confirmed) {
      if (confirmed.status === 'rejected') throw new FinalizeRevertError(txId)
      return confirmed.transaction
    }
  } catch (e) {
    if (e instanceof FinalizeRevertError) throw e
    lastError = e
  }
  await new Promise((r) => setTimeout(r, 5_000))
}
throw new TransactionTimeoutError(txId, timeout, { cause: lastError as Error | undefined })

Requires extending TransactionTimeoutError's constructor at errors.ts:134 to accept an options?: ErrorOptions arg.

2. Constructor signatures are inconsistent

errors.ts mixes (message, options?), (transactionId?, options?), (transactionId, timeoutMs, options?), and (message, statusCode?, options?) across the eight classes. Callers have to remember which class takes what in which order.

Viem's pattern — a single options bag ({ shortMessage, metaMessages, cause }) with all fields named — is what most modern SDK error hierarchies converge to. Worth adopting before public-API commitment; renaming constructor signatures after release is a breaking change.

3. (error as any)?.status casts in the classifiers

errors.ts:204 and errors.ts:239. Works because SnarkOS attaches .status on broadcast errors, but the assumption is undocumented. Replace with:

function getStatus(e: unknown): number | undefined {
  return typeof e === 'object' && e !== null && 'status' in e && typeof e.status === 'number'
    ? e.status
    : undefined
}

Reads cleaner, removes the cast, no behavior change.

4. RecordAlreadyUsedError conflates two distinct cases

errors.ts:108. The classifier regex matches both "duplicate output id" (collision in a newly-created record — basically a bug, never user-recoverable) and "duplicate serial number" (double-spend — user tried to spend the same record twice). The message says "Record already consumed," which is wrong for the output-id case.

Either broaden the message to cover both, or split into RecordSpentError (serial number) and OutputIdCollisionError (output id) since the recovery paths differ.

5. ProvingError is overloaded

provable/src/index.ts:389 ('Delegated execution requires proverUrl') and provable/src/index.ts:417 ('DPS response did not contain a transaction ID') throw ProvingError, but neither is a proof failure — the first is user config error (no proving attempted), the second is a DPS protocol violation. Suggest:

• ConfigurationError (or MissingConfigError) for the proverUrl case.
• DelegatedProvingError for the DPS protocol case (or keep ProvingError but add a kind: 'protocol' | 'computation' discriminant).

6. Integration tests against a real devnet

The classifiers (errors.ts:199, errors.ts:235) match SnarkOS internal error message strings. The 25 unit tests assert against the strings the classifier expects — they pass even if SnarkOS has rephrased any of them. A SnarkOS upgrade that turns "duplicate output id" into "output identifier conflict" silently degrades RecordAlreadyUsedError to BroadcastError, and instanceof RecordAlreadyUsedError checks start returning false without warning.

Worth a separate integration harness: submit known-bad transactions to a local snarkOS devnet (or replay captured broadcast responses) and assert each typed error class fires. Pure-string unit tests can't catch error-vocabulary drift; only a real devnet (or a periodically-refreshed fixture pulled from one) can.

[iamalwaysuncomfortable]

The other options for waitForTransaction is to make our own functionality for it that has richer errors and NOT use the SDK's funciton.

[marshacb]

A few things worth tightening before merge.

1. waitForConfirmation swallows polling errors silently

packages/provable/src/index.ts:379-385 — the bare catch (e) discards every non-FinalizeRevertError exception (network failure, RPC down, malformed response) and keeps polling. After the timeout the caller sees TransactionTimeoutError with no hint that the actual problem was the network.

Capture the last error and attach as cause:

let lastError: unknown
while (Date.now() - startTime < timeout) {
  try {
    const confirmed = await pollingClient.getConfirmedTransaction(txId)
    if (confirmed) {
      if (confirmed.status === 'rejected') throw new FinalizeRevertError(txId)
      return confirmed.transaction
    }
  } catch (e) {
    if (e instanceof FinalizeRevertError) throw e
    lastError = e
  }
  await new Promise((r) => setTimeout(r, 5_000))
}
throw new TransactionTimeoutError(txId, timeout, { cause: lastError as Error | undefined })

Requires extending TransactionTimeoutError's constructor at errors.ts:134 to accept an options?: ErrorOptions arg.

2. Constructor signatures are inconsistent

errors.ts mixes (message, options?), (transactionId?, options?), (transactionId, timeoutMs, options?), and (message, statusCode?, options?) across the eight classes. Callers have to remember which class takes what in which order.

Viem's pattern — a single options bag ({ shortMessage, metaMessages, cause }) with all fields named — is what most modern SDK error hierarchies converge to. Worth adopting before public-API commitment; renaming constructor signatures after release is a breaking change.

3. (error as any)?.status casts in the classifiers

errors.ts:204 and errors.ts:239. Works because SnarkOS attaches .status on broadcast errors, but the assumption is undocumented. Replace with:

function getStatus(e: unknown): number | undefined {
  return typeof e === 'object' && e !== null && 'status' in e && typeof e.status === 'number'
    ? e.status
    : undefined
}

Reads cleaner, removes the cast, no behavior change.

4. RecordAlreadyUsedError conflates two distinct cases

errors.ts:108. The classifier regex matches both "duplicate output id" (collision in a newly-created record — basically a bug, never user-recoverable) and "duplicate serial number" (double-spend — user tried to spend the same record twice). The message says "Record already consumed," which is wrong for the output-id case.

Either broaden the message to cover both, or split into RecordSpentError (serial number) and OutputIdCollisionError (output id) since the recovery paths differ.

5. ProvingError is overloaded

provable/src/index.ts:389 ('Delegated execution requires proverUrl') and provable/src/index.ts:417 ('DPS response did not contain a transaction ID') throw ProvingError, but neither is a proof failure — the first is user config error (no proving attempted), the second is a DPS protocol violation. Suggest:

• ConfigurationError (or MissingConfigError) for the proverUrl case.
• DelegatedProvingError for the DPS protocol case (or keep ProvingError but add a kind: 'protocol' | 'computation' discriminant).

6. Integration tests against a real devnet

The classifiers (errors.ts:199, errors.ts:235) match SnarkOS internal error message strings. The 25 unit tests assert against the strings the classifier expects — they pass even if SnarkOS has rephrased any of them. A SnarkOS upgrade that turns "duplicate output id" into "output identifier conflict" silently degrades RecordAlreadyUsedError to BroadcastError, and instanceof RecordAlreadyUsedError checks start returning false without warning.

Worth a separate integration harness: submit known-bad transactions to a local snarkOS devnet (or replay captured broadcast responses) and assert each typed error class fires. Pure-string unit tests can't catch error-vocabulary drift; only a real devnet (or a periodically-refreshed fixture pulled from one) can.

All six addressed, pushed:

• lastError tracking: waitForConfirmation captures the last polling error and attaches it as cause on TransactionTimeoutError.

• Options bag constructors: BroadcastError, TransactionTimeoutError, and ProvingError now take { message, statusCode?, cause? } instead of positional args.

• getStatus() helper: Replaces (error as any)?.status casts with typed extraction.

• Split RecordAlreadyUsedError → RecordSpentError (serial number double-spend, user-recoverable) + OutputIdCollisionError (output ID collision, program-level bug).

• ConfigurationError: Replaces ProvingError for missing proverUrl and DPS protocol issues.

• Devnet test harness: Opened a follow-up PR (Add devnet test harness with Leo devnode and GitHub Actions CI #53) that spawns a local Leo devnode and feeds real SnarkOS error responses through classifyBroadcastError to validate our regex patterns against actual error vocabulary. Also adds the first GitHub Actions CI workflow for the repo.