Where a Nullark flow can fail

Start with the first check that failed. That check stays failed even if something later looks successful.

Stage matrix

Stage	Example failure	Stop action	Next step
Runtime	Unknown network, wrong chain, pool mismatch	Block reads, proving, and submission	Re-select bundled runtime; verify RPC chain
Recovery	Parse, checksum, context, or commitment mismatch	Do not count note	Preserve original bytes; locate matching runtime or backup
Membership	Missing leaf, invalid path, expired root	Do not prove	Refresh events and path from configured deployment
Spent state	RPC unavailable or nullifier already recorded	Do not mark available	Retry read; reconcile prior withdrawal
Artifacts	Missing pin, hash mismatch, oversize bytes, wrong verifier or order	Do not buffer further or prove	Restore trusted bundled configuration and exact artifacts
Witness	Amount, fee, payload, or context mismatch	Do not call prover	Rebuild intent from current state
Proof	Local verification fails	Do not preflight	Discard package; investigate witness and artifacts
Preflight	Revert, stale fee, spent nullifier, wrong chain	Do not submit	Resolve state drift; generate fresh proof when needed
Transport	Wallet or relayer result unknown	Do not switch path or nonce	Preserve identity; reconcile chain outcome
Settlement	Receipt lacks expected pool event	Do not mark the child spent or available	Inspect target, receipt, `Withdrawal`, and nullifier state

Know when the outcome is uncertain

Signal	Classification
Wallet rejected before returning a hash	Definitive no submission from that request
Receipt status reverted on intended chain	Definitive failed transaction
Timeout after signature or relay acceptance	Uncertain submission
RPC network error	Unknown chain state
Nullifier recorded	Definitive spent state for configured pool
Expected commitment event found	Definitive insertion evidence for that pool transaction

Treat an unknown outcome as pending. Retrying it as failed can create a duplicate deposit or withdrawal.

What to record

Preserve public diagnostics only:

Runtime name, chain ID, pool, and deployment block
Transaction hash or relayer request identity
Block number, receipt status, log index, and event names
Artifact role and expected/actual public digest, never proving secrets
Exact error stage and timestamp

Never include recovery exports, note secrets, wallet unlock signatures, Merkle witnesses, private keys, or raw proof witnesses.

Before you retry

Reads are safe to retry because they move no value. Retry proving only after refreshing its inputs. Retry a value-moving submission only after the original outcome is definitely failed and the runtime, fee, root, nullifier, and nonce are current again. For symptom-led help, see Troubleshooting. For report handling, see Report a vulnerability.

Workflows

Setup and recovery

Reference

Where a Nullark flow can fail

Stage matrix

Know when the outcome is uncertain

What to record

Before you retry

​Stage matrix

​Know when the outcome is uncertain

​What to record

​Before you retry

Stage matrix

Know when the outcome is uncertain

What to record

Before you retry