Relayers
A relayer is a MultiversX wallet that holds EGLD and does exactly one thing: it co-signs other people's transactions so that its EGLD pays their fees. It has no authority over anything else.
The fleet
The registry is committed to this repository as public data — addresses, shards and states, no
keys — in wallets/registry.public.json:
| Relayer wallets | 30 |
| Per shard | 10 (shards 0, 1, 2) |
| Marked active at launch | 9 — three per shard |
| Held as cold spares | 21 |
The spares are not warm standbys. Their keys are on no server at all; they exist on chain with zero weight, and activating one is a deliberate, owner-signed act. That is the difference between "we have capacity" and "a machine that is compromised gives up 30 keys".
Why several per shard
Three active relayers per shard, rather than one, buys three things:
- Exposure headroom. Every transaction in flight reserves its worst-case fee against the relayer that will pay it. One relayer has one balance; three have three.
- A failure that is not an outage. If a relayer has to be drained, the shard keeps serving.
- Room for weights. The registry stores a weight per relayer, so traffic can be shifted without removing anybody.
How a relayer is funded
Relayers hold a small working float — enough to pay fees, never enough to be worth attacking. The float is topped up from revenue and swept back down when it grows past its ceiling; the sweep destination is a cold reserve wallet whose key is on no server.
The float target is deliberately low. The money a relayer holds is CoRelayer's own working capital, not customer funds: a customer's USDC goes to the contract, and the contract never sends anything to a relayer wallet as custody. The worst case of a compromised signing host is the loss of the active relayer floats and the work of replacing those wallets from spares — not the loss of anybody's plan, credits or tokens.
States, and how a relayer leaves
| State | Assigned to new senders | Co-signs transactions already promised |
|---|---|---|
registered | no | no |
active | yes | yes |
draining | no | yes |
retired | no | no |
Two rules make this safe:
- A relayer is never retired while a transaction it co-signed is still in flight. Retiring one early would strand a transaction that is perfectly valid and waiting for a block.
- A relayer that was ever handed out by the compatibility endpoint drains for a full month. That endpoint exists for clients which cache one relayer address and never look again; there is no way to tell them to refresh, so the only honest option is to keep the address working long enough for a human to notice.
The registry is on chain
Everything above is contract state, not a configuration file of ours:
| View | Answers |
|---|---|
getActiveRelayers | Which addresses are serving right now. |
getRelayerState | The state of one address. |
getRegistryVersion | A number that changes whenever the set changes — a cache key. |
getShardWeights | How traffic is distributed inside a shard. |
This is the point. A client should never have to trust an API response about which address is a
legitimate relayer, because that is exactly the claim an attacker would want to make. Verify the
address you were given against the contract, through a node that is not ours, and refuse if it is
not active. Each CoRelayer SDK does this for you when you give its relay flow a relayer verifier.
The verifier asks a gateway you choose, before anything is built or signed.
Verify a relayer has the procedure and the code.
Who may change what
| Action | Who | Note |
|---|---|---|
addRelayers | owner only | New addresses can only ever be introduced by the cold key. |
activateRelayers, drainRelayers, retireRelayers | operator or owner | Incident response has to be fast. |
setRelayerWeights | operator or owner | Shifts traffic without changing membership. |
A stolen operator key can take relayers out of service — which is a denial of service, and visible — but it cannot introduce an address of its own, because every address it can activate was added by the owner first. The contract enforces that ordering.
Revenue
Relayers are not a cost centre paid out of a treasury by hand. Of every payment that enters the contract, a fixed share is swapped into EGLD and accrues to the relayer pool, and the rest goes to the treasury. The split is on chain and so is the accounting. (Where the money goes)
What relayers deliberately do not have
- No guardian. The protocol does not allow a guarded relayer, and the contract refuses to register one.
- No role overlap. A relayer address may not also be the owner, operator, reporter or treasury. The contract checks this, and the signer refuses to start with a key bundle that violates it.
- No authority over accounts. A relayer cannot grant entitlement, change a plan, move credits or settle usage. Its only verb is "co-sign".