Transaction Relaying

The relay action enables co-signed transaction execution, where the XOXNO relayer adds its signature to transactions before broadcasting. This supports gasless transactions and meta-transaction patterns using MultiversX Relayer V3 format.

Overview

Transaction relaying allows:

• Gasless transactions - Users sign, relayer pays gas

• Meta-transactions - Execute on behalf of users

• Relayer V3 format - Native MultiversX relayer support

Relayer Addresses

Critical: You must use the correct relayer address based on the sender's shard. Each shard has a dedicated relayer wallet.

Shard	Relayer Address
0	erd1l0x0n5yxsfcy93gm0vyvx9m9f7cte9h9vuq4am33ugpw3d5r3hvqx6f59h
1	erd12yxd5phejzw83gn8qh6jfz6q9a0ekyyhkfd3c49r03mxw25l3a5swq3nf7
2	erd13jxp0yjh7gjvzgrg5mj7e8rzhn5lzcye45l0p6e5996d543r7vrq9e50za

How It Works

1. Determine sender shard - Calculate which shard the sender address belongs to

2. Select relayer address - Use the relayer address for that shard

3. Build transaction with relayer field - Include the relayer address in the transaction

4. User signs transaction - User signs the complete transaction (including relayer field)

5. Send to relayer - Submit via WebSocket relay action

6. Relayer adds signature - Backend appends relayerSignature

7. Broadcast - Transaction sent to P2P network

Shard Calculation

The sender's shard is determined by the last byte of their address:

function getShardFromAddress(bech32Address) {
  // Decode bech32 to get public key bytes
  const pubKeyHex = bech32ToHex(bech32Address);
  const lastByte = parseInt(pubKeyHex.slice(-2), 16);
  
  // Shard = lastByte % numShards
  return lastByte % 3;
}

// Relayer addresses by shard
const RELAYER_ADDRESSES = {
  0: 'erd1l0x0n5yxsfcy93gm0vyvx9m9f7cte9h9vuq4am33ugpw3d5r3hvqx6f59h',
  1: 'erd12yxd5phejzw83gn8qh6jfz6q9a0ekyyhkfd3c49r03mxw25l3a5swq3nf7',
  2: 'erd13jxp0yjh7gjvzgrg5mj7e8rzhn5lzcye45l0p6e5996d543r7vrq9e50za'
};

function getRelayerForSender(senderAddress) {
  const shard = getShardFromAddress(senderAddress);
  return RELAYER_ADDRESSES[shard];
}

Relay Request

The relayer field is mandatory - you must include the correct relayer address:

ws.send(JSON.stringify({
  action: 'relay',
  requestId: 'relay-001',
  tx: {
    nonce: 42,
    value: '0',
    receiver: 'erd1qqqqqqqqqqqqqpgq...',
    sender: 'erd1user...',
    gasPrice: 1000000000,
    gasLimit: 50000000,
    data: 'swapExactAmountIn@...',
    chainID: '1',
    version: 2,
    signature: 'user-signature-hex...',
    relayer: 'erd1l0x0n5yxsfcy93gm0vyvx9m9f7cte9h9vuq4am33ugpw3d5r3hvqx6f59h' // Required!
  }
}));

Transaction Fields

Field	Type	Required	Description
nonce	number	Yes	Sender's transaction counter
value	string	Yes	EGLD value in atomic units
receiver	string	Yes	Receiver's bech32 address
sender	string	Yes	Sender's bech32 address
gasPrice	number	Yes	Gas price in atomic units
gasLimit	number	Yes	Maximum gas units
data	string	No	Transaction data payload
chainID	string	Yes	Chain identifier
version	number	Yes	Transaction version
signature	string	Yes	User's signature (hex)
relayer	string	Yes	Relayer address for sender's shard

The user must sign the transaction including the relayer field. The backend only appends relayerSignature.

Batch Relay

ws.send(JSON.stringify({
  action: 'relay',
  requestId: 'relay-batch-001',
  txs: [
    {
      nonce: 42,
      value: '0',
      receiver: 'erd1contract...',
      sender: 'erd1user...',
      gasPrice: 1000000000,
      gasLimit: 50000000,
      data: 'tx1data',
      chainID: '1',
      version: 2,
      signature: 'sig1...',
      relayer: 'erd1l0x0n5yxsfcy93gm0vyvx9m9f7cte9h9vuq4am33ugpw3d5r3hvqx6f59h'
    },
    {
      nonce: 43,
      value: '0',
      receiver: 'erd1contract...',
      sender: 'erd1user...',
      gasPrice: 1000000000,
      gasLimit: 50000000,
      data: 'tx2data',
      chainID: '1',
      version: 2,
      signature: 'sig2...',
      relayer: 'erd1l0x0n5yxsfcy93gm0vyvx9m9f7cte9h9vuq4am33ugpw3d5r3hvqx6f59h'
    }
  ]
}));

Response

Success

{
  "action": "relay",
  "status": "completed",
  "requestId": "relay-001",
  "hashes": [
    "abc123def456..."
  ],
  "failed": []
}

Partial Success

{
  "action": "relay",
  "status": "partial",
  "requestId": "relay-batch-001",
  "hashes": [
    "hash1..."
  ],
  "failed": [
    {
      "index": 1,
      "reason": "invalid user signature"
    }
  ]
}

Complete Integration Example

import { Address, Transaction, TransactionPayload } from '@multiversx/sdk-core';
import { UserSigner } from '@multiversx/sdk-wallet';
import bech32 from 'bech32';

// Relayer addresses by shard (mainnet)
const RELAYER_ADDRESSES = {
  0: 'erd1l0x0n5yxsfcy93gm0vyvx9m9f7cte9h9vuq4am33ugpw3d5r3hvqx6f59h',
  1: 'erd12yxd5phejzw83gn8qh6jfz6q9a0ekyyhkfd3c49r03mxw25l3a5swq3nf7',
  2: 'erd13jxp0yjh7gjvzgrg5mj7e8rzhn5lzcye45l0p6e5996d543r7vrq9e50za'
};

class GaslessRelayClient {
  constructor(wsUrl) {
    this.ws = new WebSocket(wsUrl);
    this.pending = new Map();
    this.counter = 0;
    
    this.ws.onmessage = (event) => {
      const msg = JSON.parse(event.data);
      if (msg.action === 'relay' && msg.requestId) {
        const resolver = this.pending.get(msg.requestId);
        if (resolver) {
          this.pending.delete(msg.requestId);
          resolver(msg);
        }
      }
    };
  }

  /**
   * Calculate shard from bech32 address
   */
  getShardFromAddress(bech32Address) {
    const decoded = bech32.decode(bech32Address);
    const pubKeyBytes = bech32.fromWords(decoded.words);
    const lastByte = pubKeyBytes[pubKeyBytes.length - 1];
    return lastByte % 3;
  }

  /**
   * Get the correct relayer address for a sender
   */
  getRelayerForSender(senderAddress) {
    const shard = this.getShardFromAddress(senderAddress);
    const relayer = RELAYER_ADDRESSES[shard];
    
    if (!relayer) {
      throw new Error(`No relayer configured for shard ${shard}`);
    }
    
    return relayer;
  }

  /**
   * Submit a relay request
   */
  async relay(transaction) {
    const requestId = `relay-${++this.counter}`;
    
    return new Promise((resolve, reject) => {
      const timeout = setTimeout(() => {
        this.pending.delete(requestId);
        reject(new Error('Relay timeout'));
      }, 30000);
      
      this.pending.set(requestId, (result) => {
        clearTimeout(timeout);
        resolve(result);
      });
      
      this.ws.send(JSON.stringify({
        action: 'relay',
        requestId,
        tx: transaction
      }));
    });
  }

  /**
   * Execute a gasless swap
   */
  async executeGaslessSwap(swapParams, userWallet, accountNonce) {
    const senderAddress = userWallet.address;
    
    // Step 1: Determine the correct relayer for sender's shard
    const relayerAddress = this.getRelayerForSender(senderAddress);
    console.log(`Sender shard: ${this.getShardFromAddress(senderAddress)}`);
    console.log(`Using relayer: ${relayerAddress}`);

    // Step 2: Build transaction WITH relayer field
    const tx = {
      nonce: accountNonce,
      value: '0',
      receiver: AGGREGATOR_CONTRACT,
      sender: senderAddress,
      gasPrice: 1000000000,
      gasLimit: 50000000,
      data: swapParams.txData,
      chainID: '1',
      version: 2,
      relayer: relayerAddress  // Must include before signing!
    };

    // Step 3: User signs the transaction (including relayer field)
    const signedTx = await userWallet.signTransaction(tx);
    tx.signature = signedTx.signature;

    // Step 4: Submit to relayer (backend adds relayerSignature)
    const result = await this.relay(tx);
    
    if (result.status === 'failed') {
      throw new Error(result.failed[0]?.reason || 'Relay failed');
    }
    
    return result.hashes[0];
  }
}

// Usage
const client = new GaslessRelayClient('wss://relayer.xoxno.com/ws');

await new Promise(r => { client.ws.onopen = r; });

const txHash = await client.executeGaslessSwap(
  { txData: 'swapExactAmountIn@...' },
  userWallet,
  42
);

console.log(`Gasless swap executed: ${txHash}`);

Transaction Signing Flow

The user must sign the complete transaction including the relayer field:

// What the user signs (serialized for signing):
{
  "nonce": 42,
  "value": "0",
  "receiver": "erd1contract...",
  "sender": "erd1user...",
  "gasPrice": 1000000000,
  "gasLimit": 50000000,
  "data": "c3dhcA==",
  "chainID": "1",
  "version": 2,
  "relayer": "erd1l0x0n5yxsfcy93gm0vyvx9m9f7cte9h9vuq4am33ugpw3d5r3hvqx6f59h"
}

// What the relayer broadcasts (after adding relayerSignature):
{
  "nonce": 42,
  "value": "0",
  "receiver": "erd1contract...",
  "sender": "erd1user...",
  "gasPrice": 1000000000,
  "gasLimit": 50000000,
  "data": "c3dhcA==",
  "chainID": "1",
  "version": 2,
  "signature": "user-signature...",
  "relayer": "erd1l0x0n5yxsfcy93gm0vyvx9m9f7cte9h9vuq4am33ugpw3d5r3hvqx6f59h",
  "relayerSignature": "relayer-signature..."  // Added by backend
}

Error Handling

async function safeRelay(client, tx) {
  // Validate relayer address before sending
  const expectedRelayer = client.getRelayerForSender(tx.sender);
  if (tx.relayer !== expectedRelayer) {
    throw new Error(`Wrong relayer. Expected ${expectedRelayer} for sender's shard`);
  }

  try {
    const result = await client.relay(tx);
    
    switch (result.status) {
      case 'completed':
        return { success: true, hash: result.hashes[0] };
      case 'partial':
        return {
          success: false,
          partial: true,
          hashes: result.hashes,
          errors: result.failed
        };
      case 'failed':
        return {
          success: false,
          error: result.failed[0]?.reason || 'Unknown error'
        };
    }
  } catch (error) {
    return { success: false, error: error.message };
  }
}

Common Errors

Error	Cause	Solution
invalid relayer address	Wrong relayer for sender's shard	Use correct relayer from table above
relayer field missing	Transaction missing relayer	Include relayer in transaction
invalid user signature	User didn't sign with relayer field	Re-sign including relayer
nonce too low	Transaction already processed	Get fresh nonce

Relay vs Broadcast

Aspect	Relay	Broadcast
relayer field	Required	Not needed
User signs	With relayer field	Without relayer field
Backend adds	relayerSignature	Nothing
Gas payer	Relayer	User
Use case	Gasless, meta-tx	Standard tx

Rate Limits

Limit	Value
Relay requests per second	100
Max batch size	100 transactions
Pending relays per sender	10

Always verify you're using the correct relayer address for the sender's shard. Using the wrong relayer will cause the transaction to fail.