Opertus

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.

ConcernPoolWallet and relayer
EligibilityAccepts a valid call from any submitterRelayer chooses whether to offer service
Spend authorityVerifies the proof and nullifiers; ignores msg.sender as authorityWallet proves ownership; relayer learns no spend secret
Relayer identityHas no registry, allowlist, or relayer argumentParties identify each other through their offchain channel
Fee policyDoes not quote, calculate, or require a relayer feeParties agree the amount and token offchain
CompensationInserts the proof-bound encrypted output notesWallet 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 / 1000

That 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:

FieldExample
NetworkChain ID and pool address
FeeThe spent token and the fee amount the relayer wants
ValidityQuote expiry and acceptable gas conditions
Call typeTransfer, plain unshield, or external call
LimitsSupported 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 actionResult
Modify a fee note, recipient, target, calldata, protocol fee, return list, or clone saltInvalidates the proof
Inspect public transaction dataAllowed; the relayer sees the same proof-bound public fields
Decline or delay a transactionAllowed; relaying is an availability service
Leak calldata before broadcastPossible unless the submission channel prevents it
Submit the identical prepared call firstPossible, but does not change its proof-bound effects
Replay an included callRejected because its nullifiers are already spent
Hide its own network or account metadataNot 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.

On this page