Opertus

Troubleshooting

Diagnose note scanning, witness generation, proof verification, deposits, and unshield failures.

Find what you're seeing below:

Every contract error is listed in the contract reference.

A revert is safe to retry

A reverted transaction consumes no notes and inserts nothing. Fix the cause, rebuild the call, and send it again.

A note does not appear

Check the chain ID and pool address used to create and scan the encrypted note. Both are authenticated with the ciphertext, so a note prepared for another domain is intentionally ignored.

Then check:

  • Did sync include the event? Look for the NoteCommitted or ReturnShielded log that created the note.
  • Is the commitment the pool's? The scanner needs the commitment the pool emitted, not one you computed.
  • Is it the right view key? It has to belong to the meta-address the note was sent to.
  • Is the payload intact? Ciphertext, ephemerals, view tag, and nonce must match what was emitted.

Synchronization fails or is slow

A single getLogs call from block zero can exceed an RPC provider's block-range or response-size limit. Pass fromBlock as the pool's deployment block and set blockRange to a value your provider accepts. Persist lastBlock and pass the previous result back as previous on the next sync. See sync incrementally.

Sync incomplete

After rebuilding the tree, getLogs asks the pool whether the root is known at lastBlock. Sync incomplete means it is not: the RPC dropped a log, a chunk was skipped, or previous came from a different pool or chain. Sync again from the deploy block, with a smaller blockRange if the provider truncates responses. A reorg below lastBlock has the same effect; sync a few blocks behind the head.

No spendable note is selected

A view key can decrypt notes and calculate their nullifiers, but it cannot derive the one-time spend secret. Make sure the spending key is available at spend time and that the derived secret opens the note's ownerPubKey.

Selection also requires enough value in at most eight notes of the token. Supported circuit widths are 1, 2, 4, and 8; unused input slots are represented by zero-value padding inputs.

The SDK rejects the call before proving

OpertusClient validates a spend before it calls the prover:

Error messageCause
Value is not conservedOutput values plus the public amount do not equal the selected inputs
Output "…" must be a real stealth noteAn output is missing; all three outputs are required
Output "…" is for a different tokenAn output note was prepared for another token
Selected note has no ownerSecretThe spend secret was not derived with KeyManager.computeStealthSecret
… notes do not fit a …-input circuitMore notes were selected than circuitSize allows

The Merkle root is unknown

Rebuild the pool's one tree from events in leaf-index order. getLogs throws when a leaf index is missing, because a LeanIMT built over a gap has a different root. Use the root recorded after the transaction's final insertion. An empty pool has root 0, which is never known.

Old roots do not expire, so an honestly emitted historical root should remain known. Common causes are skipped logs, inserting a ciphertext instead of its commitment, building a tree from an incremental sync without the earlier leaves, or computing intermediate roots that the pool never committed.

The deposit reverts

Map the reported error before rebuilding the transaction:

ErrorMeaningWhat to verify
InvalidPublicAmountTransfer or note value is zero or out of bounds, or native value does not matchGross amount, note bound, and exact msg.value for native deposits
NoteValueMismatchMeasured arrival minus the deposit fee differs from the prepared noteToken transfer behavior, live fee, and predicted net note value
CommitmentMismatchSubmitted commitment does not match its declared openingToken, value, owner public key, randomness, and blind
InvalidCommitmentA field is invalid, the owner key is zero, or the commitment already existsField ranges, nonzero owner key, and fresh opening data

For ERC-20 deposits, also check allowance and token transfer behavior. Predict the note from the actual net accounting, not merely the requested transfer.

The proof is invalid

An InvalidProof usually means a public signal differs from the proof that was generated. Recheck each group of proof inputs:

GroupFields
CircuitWidth and nullifier count
Tree and tokenRoot, token, public amount, and clone salt
DomainChain ID and pool address
OutputsAll three encrypted output notes
Unshield onlyTarget, calldata, current protocol fee, and the complete return list

Changing any bound field after proving invalidates the proof. A transfer uses public amount zero and salt zero. An unshield uses the gross public amount, and a nonzero salt must have the correct spend-scalar and diversifier preimage. If you pass unshieldFeeBps explicitly, make sure it is the pool's live rate.

Also verify that the prover was created with artifacts for the selected width. Missing artifacts fail before a valid proof can be produced.

A nullifier or commitment is rejected

NullifierAlreadySpent means an input note was already consumed. Refresh pool events and remove it from local spendable state.

Within one call, the outputs must be distinct, and return commitments must differ from all three outputs and from earlier returns; otherwise the pool reverts with InvalidCommitment. A commitment that is already in the tree from an earlier call is accepted, but it shares the first copy's nullifier, so only one copy can be spent. The SDK flags later copies duplicate and refuses to spend them. Sender.prepareSend uses fresh opening data for every note, so this only happens when opening data is reused.

The unshield or external call reverts

For a plain public payout, calldata and the return list must both be empty and salt must be zero, or the pool reverts with InvalidPublicAmount. A zero target reverts with InvalidRecipient.

For a composed call, match the error to its check:

CheckError
No more than four return tokens are listedTooManyReturns
No token appears twiceDuplicateReturn
Every measured return meets its minValueSlippageExceeded
The target is not the pool or executorInvalidRecipient
The target is not another protocol addressForbiddenTarget
The live fee rate matches the one used while provingInvalidProof
The external call itself succeedsCallFailed
The clone received the full net, which a fee-on-transfer token does notCloneUnderpaid

Returned assets that aren't named in the list don't cause a revert; they stay on the clone instead of becoming notes.

External call data is public; see the privacy model.

Still stuck?

Work from the outside in, and stop at the first thing that doesn't match: the chain ID and pool address, then the synced events, then your note state (decryption, nullifiers, tree ID), then the proof inputs, and finally the contract's token accounting and fees.

On this page