13 Guides

Relayer

How a claim reaches the chain without the recipient holding any ETH, what a relayer can and cannot do, and why nobody has to trust one.

#The problem it solves

A recipient who has never used the chain holds no ETH, and a transaction needs gas. Without help, the first step of receiving money would be "go and get some ETH", which defeats the point of sending a link.

#How a gasless claim works

The right to claim is a signature, not a transaction.

  1. The recipient opens the link. The page derives the claim key from the secret in the fragment.
  2. The recipient picks a wallet address to receive to. It can be new and empty.
  3. The page signs Claim(linkKey, recipient) with the claim key, in the browser. This costs nothing.
  4. The page hands (sender, id, recipient, signature) to a relayer, or submits it itself.
  5. The relayer sends claim(sender, id, recipient, signature) and pays the gas.
  6. The contract checks the signature and pays the recipient named inside it, not the relayer.

Gas of a claim is about 85k to 117k gas, see Gas and costs. At the gas price we measured on 2026-10-09 that is a few millionths of an ETH.

#What a relayer can do

  • Pay gas and submit. That is its job.
  • Delay or refuse. It can be offline, rate limit you, or decline a claim that is not worth its gas.
  • See the data in the request: the sender, the id, the recipient, and the signature.

#What a relayer cannot do

AttemptWhy it fails
Send the funds somewhere elsethe recipient is inside the signed message. A different recipient changes the digest, and the contract reverts with BadSignature
Claim a link on its ownit needs a valid signature from the claim key, which only a holder of the secret can produce
Learn the secretthe secret never leaves the browser. The relayer only receives a signature
Take a cutthe contract has no tip or relayer-fee parameter. The recipient receives the full net amount, and the only deduction is the 0.3% protocol fee
Stop you from claimingit can only refuse its own service. You can submit the same signature yourself, or use another relayer

This is the same reasoning as in The claim signature: the signature fixes the destination, so submitting it is a pure service.

#If the relayer is down

Nothing is stuck.

  • A recipient who has a little ETH can call claim directly with the signature the page produced.
  • Any third party can relay, because claim has no access control.
  • If nobody claims before the expiry, the sender gets everything back through undo or expireRefund.

#Running a relayer

A relayer is a small service with one endpoint. A sensible one:

  1. Receives (sender, id, recipient, sig).
  2. Simulates claim with eth_call. If it would revert, it answers with the error name and sends nothing, so it never pays gas for a doomed transaction.
  3. Checks the link's amount against its own gas cost and its own policy.
  4. Sends the transaction and returns the hash.
  5. Rate limits by IP and by sender, and caps the gas it will spend per hour.

The abuse to plan for is someone trying to drain the relayer's gas budget with valid but worthless claims. Simulation, a minimum amount, and a spending cap handle it.

#Status

Oopsend's own relayer is a design that is not running yet. The contract does not depend on it: everything above works with any relayer, or none. Until a relayer exists, the app asks the recipient to submit the claim themselves, which needs a small amount of ETH.