ERC-2771 — Trusted Forwarder (Meta-Tx)

Back to Infrastructure & Patterns

ERC-2771: Secure Protocol for Trusted Forwarders

Meta-transactions: a relayer pays gas on behalf of users who don't have ETH. The user signs an off-chain message, the relayer wraps it in a real transaction and calls a "Forwarder" contract, which calls the target appending the original signer to calldata. Targets that opt in extract the real _msgSender() from the appended data instead of msg.sender.

Required Convention

function isTrustedForwarder(address forwarder) external view returns (bool);
function _msgSender() internal view returns (address) {
    if (msg.sender == trustedForwarder && msg.data.length >= 20) {
        return address(bytes20(msg.data[msg.data.length - 20:]));
    }
    return msg.sender;
}

Neo Equivalent: Witness Scopes (Solved at Protocol)

This entire ceremony is unnecessary on Neo. A relayer-paid transaction lists the relayer as Sender (paying the fee) and the user as a Signer with appropriate scopes. The target contract's Runtime.CheckWitness(user) succeeds because the user genuinely signed the transaction; the relayer is a separate witness paying gas. No forwarder, no _msgSender() wrapper, no calldata munging.

Live on Neo TestNet

Both implementations deployed on Neo N3 TestNet.

Implementation	TestNet Address	Contract Hash
Solidity (neo-solc)	NfiyLrGXijAAHiwq1LUGu69K92ybMu4ZS4	0x6653a8da…2c124ed9
Neo C# (nccs)	NLq6WUsRv4FAtxrqhwtTNxTeSgxAWYhG8P	0x1463ad54…a6280c0a

Checked-in snapshot verifies getNonce(deployer) == 0; the manifest now also exercises bumpNonce on both implementations. The C# port exposes named-method forwarding through Neo's witness model. docs/standards-mirror/deployments/erc-2771/.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

abstract contract ERC2771Context {
    address private immutable _trustedForwarder;

    constructor(address forwarder) { _trustedForwarder = forwarder; }

    function isTrustedForwarder(address f) public view returns (bool) {
        return f == _trustedForwarder;
    }

    function _msgSender() internal view returns (address signer) {
        if (msg.sender == _trustedForwarder && msg.data.length >= 20) {
            assembly {
                signer := shr(96, calldataload(sub(calldatasize(), 20)))
            }
        } else {
            signer = msg.sender;
        }
    }
}

contract MinimalForwarder {
    struct ForwardRequest {
        address from; address to;
        uint256 value; uint256 gas;
        uint256 nonce; bytes data;
    }
    mapping(address => uint256) public nonces;

    function execute(ForwardRequest calldata req, bytes calldata sig)
        external payable returns (bool, bytes memory)
    {
        // ... verify EIP-712 sig of req using ECDSA on `req.from` ...
        require(nonces[req.from] == req.nonce, "bad nonce");
        nonces[req.from] = req.nonce + 1;

        // Append req.from to calldata so target can extract via _msgSender()
        (bool ok, bytes memory ret) = req.to.call{ gas: req.gas, value: req.value }(
            abi.encodePacked(req.data, req.from)
        );
        require(ok, "exec failed");
        return (ok, ret);
    }
}

using System;
using System.ComponentModel;
using System.Numerics;
using Neo;
using Neo.SmartContract.Framework;
using Neo.SmartContract.Framework.Attributes;
using Neo.SmartContract.Framework.Native;
using Neo.SmartContract.Framework.Services;

namespace R3E.Examples;

[DisplayName("DemoToken")]
[SupportedStandards(NepStandard.Nep17)]
public class DemoToken : SmartContract
{
    [DisplayName("Transfer")]
    public static event Action<UInt160, UInt160, BigInteger> OnTransfer;

    /// <summary>
    /// Standard NEP-17 transfer — no special meta-tx handling. The user's
    /// witness is checked normally; the relayer pays the gas as the tx Sender.
    /// </summary>
    public static bool Transfer(UInt160 from, UInt160 to, BigInteger amount, object data)
    {
        if (!Runtime.CheckWitness(from)) throw new Exception("no authorization");
        // ... actual transfer ...
        OnTransfer(from, to, amount);
        return true;
    }
}

How a Relayed Transaction Looks on Neo

// Client (TypeScript) — user signs, relayer pays
const tx = new TransactionBuilder()
  .invoke(token, "transfer", [user, recipient, amount, "via relayer"])
  .signers([
    {
      account: relayer,
      scopes:  WitnessScope.None             // pays fee, no app authority
    },
    {
      account: user,
      scopes:  WitnessScope.CustomContracts,
      allowedContracts: [token]              // user authorises just this transfer
    }
  ])
  .build();

const userSigned    = await userWallet.signTransaction(tx);
const relayerSigned = await relayerWallet.cosignTransaction(userSigned);
await rpc.sendRawTransaction(relayerSigned);

The token contract sees Runtime.CheckWitness(user) == true because the user's signature is on the transaction. The relayer is just paying the fee.