Skip to main content

Relayed v3

Relayed v3 is the MultiversX protocol feature CoRelayer is built on. It is not a wrapper, a meta-transaction format or a contract trick: it is two extra fields on an ordinary transaction, and the node treats the result as one transaction with two signatures.

It is also what makes a transaction gasless for its sender. The relayer, not the sender, pays the network fee in EGLD, so the sender needs no EGLD at all. CoRelayer runs those relayers, and you pay for them with a plan in USDC.

The two fields​

An ordinary transaction becomes a relayed one by setting:

FieldWhat it is
relayerThe bech32 address of the account that will pay the fee.
relayerSignatureThat account's Ed25519 signature over the same bytes the sender signed.

Both are part of the transaction. Neither is a header, a side channel or an off-chain agreement.

What this means, exactly​

Four consequences follow, and everything else about the service follows from them.

The sender signs the relayer​

relayer is inside the bytes the sender signs. So the relayer cannot be changed after you signed: swapping it invalidates your signature, and the network will not accept the result. You know, before you approve anything, which account is going to pay for your transaction.

Only the sender's nonce is consumed​

The relayer's own nonce is untouched. That is what lets one relayer serve many senders at once, and it is what lets the same relayer key co-sign on more than one host without the two hosts having to agree on a counter.

A co-signed transaction has no expiry​

Once a relayer signature exists, the transaction is executable until the sender's nonce moves past it. There is no time-to-live. Anyone holding the bytes can broadcast them. This is why the moment the relayer signature leaves our signer is a hard boundary in our design: before it, an error is still possible; after it, the transaction exists in the world and the only honest answer is a state, never a failure. (Delivery guarantees)

Without the relayer signature it is inert​

A transaction that names a relayer but carries no relayer signature is invalid. It cannot execute, cannot be repaired by anyone else, and costs nobody anything. A signed payload that we never co-signed is a dead letter.

The shape of one relayed transaction​

A relayed v3 transaction, as the API takes it
{
  "nonce": 41,
  "value": "0",
  "receiver": "erd1…",
  "sender": "erd1…",
  "gasPrice": 1000000000,
  "gasLimit": 150000,
  "data": "…base64…",
  "chainID": "1",
  "version": 2,
  "relayer": "erd1…",
  "signature": "…hex…"
}

You send that to POST /v1/relay without relayerSignature. The service adds it. A body that tries to supply one is rejected with RELAYER_SIGNATURE_PRESENT: a co-signature is not something a client can bring.

The extra gas​

Relaying is not free for the network either. Every relayed transaction pays a fixed surcharge on top of the usual cost of moving a transaction, and a guarded transaction pays a second one. The assignment response gives you both numbers so you do not have to guess:

From the assignmentMeaning
extraGasRelayedGas the protocol adds because the transaction is relayed. Always applies.
extraGasGuardedGas the protocol adds when the sender uses a guardian. Applies only then.
minGasPrice, maxGasPriceThe band your gasPrice must fall in to be accepted.

Getting the gas limit right matters for you, because the Relay Unit count is computed from the transaction's worst case, not from the gas it ends up using. (Relay Units)

The full exchange​

Everything that can go wrong is on the left of the commit point. That is a deliberate property, not an accident of implementation: it is what lets a client treat any error it receives as "nothing was sent". (Delivery guarantees)

What we verify before co-signing​

The list is long on purpose, because every item is a way for a relayed transaction to cost us a fee and give the sender nothing:

  • the signature is valid and the bytes name one of our relayers, in the right shard;
  • the lease is ours, unexpired and for this sender;
  • the nonce is in the window the network will accept, and no other transaction of ours occupies the same slot;
  • gasPrice is inside the admitted band and gasLimit is above the true movement cost and below the class ceiling;
  • the sender can actually pay any value the transaction moves — a transaction that fails for lack of funds still costs the relayer the whole fee;
  • the account has entitlement, and the reservation fits inside the relayer's funded exposure;
  • optionally, a simulation says the call would not revert for a reason we could have seen.

Each of these has its own error code, and each error page says whether re-sending the same bytes can ever help. Start at the error catalogue.

The facts this rests on​

These are properties of the MultiversX protocol, not of CoRelayer. They are what make the design above sound, and they are worth checking against the protocol documentation rather than taking from us:

  1. Sender, guardian and relayer sign the same bytes, and those bytes contain relayer.
  2. Relayed v3 consumes only the sender's nonce.
  3. A co-signed transaction has no TTL; without a relayer signature it is invalid.
  4. At most one transaction per (sender, nonce) executes; identical bytes re-broadcast are the same transaction.
  5. Among transactions with the same nonce, the mempool prefers the higher gas price, then the lower hash. There is no minimum bump.
  6. A not-executable outcome charges no fee and does not move the nonce. A failed execution charges the relayer the full gas limit.

Next​

On this page