Relayers
Understand gas submission, private fee notes, validation, and the trust boundary between a wallet and an Opertus relayer.
A relayer submits an already prepared Opertus transaction and pays its network gas. This lets a wallet transact without requiring the submitting account to be the note owner—or even to be related to the private wallet.
Relaying is a protocol pattern, not a privileged contract role. Opertus does not run a hosted relayer, a discovery network, or a quote API, and makes no availability guarantee for any relayer.
What the pool knows
The pool does not use msg.sender as spend authority. Authorization comes from
the Groth16 proof, input nullifiers, and proof-bound transaction data.
| Concern | Pool | Wallet and relayer |
|---|---|---|
| Eligibility | Accepts a valid call from any submitter | Relayer chooses whether to offer service |
| Spend authority | Verifies the proof and nullifiers; ignores msg.sender as authority | Wallet proves ownership; relayer learns no spend secret |
| Relayer identity | Has no registry, allowlist, or relayer argument | Parties identify each other through their offchain channel |
| Fee policy | Does not quote, calculate, or require a relayer fee | Parties agree the amount and token offchain |
| Compensation | Inserts the proof-bound encrypted output notes | Wallet addresses a fee note to the relayer's meta-address |
Any address can submit the same prepared call. The relayer earns compensation only when one of the three encrypted output notes was created for its Opertus meta-address.
Relayer trust boundary
The relayer never needs the sender's recovery phrase, viewing key, spend key, note openings, or Merkle-path secrets.
Submission flow
Synchronize and select
The wallet synchronizes the pool, selects notes from one Merkle tree, and obtains the current protocol fee configuration.
Request a quote
The wallet requests a quote from a relayer through an offchain channel.
Create the fee note
The wallet creates a fee note addressed to the relayer and passes it as the third output.
Build the proof-bound call
The wallet builds the witness and proof. The encrypted output notes and transaction payload are included in the external-data hash.
Send the complete call
The wallet sends the complete call object to the relayer.
Validate and broadcast
The relayer validates the chain, pool, call, fee note, and submission policy, then broadcasts the transaction.
Discover the private fee
After inclusion, the relayer scans the emitted note and later spends it like any other private note.
Fee notes
A relayer fee is denominated in the same token as the spent notes. It remains inside the pool and is private to observers, like any other output-note value. It is separate from the public deposit and unshield protocol fees that accrue to the treasury.
Both OpertusClient.consolidate and OpertusClient.withdraw take the fee as
the fee output, which is always the third output note. When nobody is paid,
pass a zero-value note there instead. The client checks that inputs equal
outputs plus the public amount before proving, so the fee must come out of
change:
import { NoteSelector } from '@opertus/core';
import { Sender } from '@opertus/wallet';
const selection = NoteSelector.select(unspent, grossAmount, BigInt(token), true);
const change = await Sender.prepareSend(myMetaAddress, BigInt(token), selection.changeAmount, domain);
const extra = await Sender.prepareSend(myMetaAddress, BigInt(token), 0n, domain);
const fee = await Sender.prepareSend(relayerMetaAddress, BigInt(token), selection.feeAmount, domain);
const call = await client.withdraw({
tree,
selectedNotes: selection.selectedNotes,
token,
circuitSize: selection.circuitSize,
amount: grossAmount,
recipient,
outputs: { change, extra, fee },
});The encrypted note's recipient meta-address alone determines who can claim the fee; there is no relayer address argument.
Fee policy
NoteSelector.select(..., includeFee: true) currently calculates:
feeAmount = requestedAmount × 5 / 1000That is a 0.5% SDK convenience policy. It is not a circuit constant, contract fee, required quote, or minimum payment. A production relayer can use another offchain policy, such as a token-denominated gas estimate, a fixed minimum, or a time-limited quote.
A quote covers at least:
| Field | Example |
|---|---|
| Network | Chain ID and pool address |
| Fee | The spent token and the fee amount the relayer wants |
| Validity | Quote expiry and acceptable gas conditions |
| Call type | Transfer, plain unshield, or external call |
| Limits | Supported targets, calldata limits, and return-token policy |
In code, a quote might look like this:
// Example shape. Opertus does not define a quote format.
type RelayerQuote = {
chainId: bigint;
pool: Address;
feeToken: Address;
feeAmount: bigint;
expiresAt: number;
maxGasPrice: bigint;
callType: 'transfer' | 'unshield' | 'external';
};What a relayer should validate
Before broadcasting, a relayer works through four questions, in order:
Is it for us?
The transaction targets the intended pool on the intended chain, and that pool and verifier deployment meet the relayer's security policy.
Will it verify?
The root is known and the call has the expected circuit width.
Does it pay us?
The third output's payload decrypts under the relayer's view key, and the decrypted token and value match the quote and the output commitment.
Is it still current?
The current unshield fee still matches the value bound into the proof, no input nullifier is spent, and the transaction hasn't already been included. The call target, calldata, public amount, clone salt, and return list are acceptable.
Decryption isn't settlement
Decrypting the fee note proves it is addressed to the relayer, not that settlement will succeed. The relayer receives the note only if the entire transaction is accepted and its commitment is emitted.
Failure and retry behavior
A relayer can refuse, delay, or fail to submit. This is an availability risk, not spend authority. The wallet can send the same proof-bound call to another submitter willing to accept its already-bound fee note, provided the root remains known, the nullifiers remain unspent, and all public data is still valid.
A proof must be rebuilt when bound data changes—for example, the target, calldata, encrypted output notes, return list, clone salt, chain, pool, or live unshield protocol fee. A successfully included transaction cannot be replayed because its nullifiers are permanently marked spent.
Security boundaries
| Relayer action | Result |
|---|---|
| Modify a fee note, recipient, target, calldata, protocol fee, return list, or clone salt | Invalidates the proof |
| Inspect public transaction data | Allowed; the relayer sees the same proof-bound public fields |
| Decline or delay a transaction | Allowed; relaying is an availability service |
| Leak calldata before broadcast | Possible unless the submission channel prevents it |
| Submit the identical prepared call first | Possible, but does not change its proof-bound effects |
| Replay an included call | Rejected because its nullifiers are already spent |
| Hide its own network or account metadata | Not guaranteed by Opertus |
Use a private submission channel when mempool exposure matters. That can reduce pre-inclusion leakage, but it does not hide the public fields eventually recorded onchain.
Continue with transactions for note construction and the core SDK for the current client interfaces.