ERC-7786 — Cross-Chain Messaging Gateway

Back to Infrastructure & Patterns

ERC-7786: Cross-Chain Messaging Gateway

ERC-7786 standardises the contract-side interface for sending and receiving messages across blockchains. It abstracts over the messaging provider (LayerZero, Hyperlane, Wormhole, Axelar, CCIP) so application contracts can target the gateway interface and let operators choose the underlying transport. The motivation: Solidity dApps that wanted cross-chain capabilities had to write per-provider integrations and could not switch providers without rewriting the call sites. ERC-7786 picks one shape and standardises it.

Required Interface

interface IERC7786GatewaySource {
    event MessagePosted(
        bytes32 indexed outboxId,
        string  sender,                   // CAIP-10 source identifier
        string  receiver,                 // CAIP-10 destination identifier
        bytes   payload,
        bytes[] attributes
    );

    function supportsAttribute(bytes4 selector) external view returns (bool);

    function sendMessage(
        string calldata destinationChain, // CAIP-2 chain id
        string calldata receiver,         // address on destination
        bytes  calldata payload,
        bytes[] calldata attributes
    ) external payable returns (bytes32 outboxId);
}

interface IERC7786Receiver {
    function executeMessage(
        bytes32 messageId,
        string calldata sourceChain,      // CAIP-2 source chain id
        string calldata sender,           // CAIP-10 source address
        bytes  calldata payload,
        bytes[] calldata attributes
    ) external returns (bytes4);          // returns IERC7786Receiver.executeMessage.selector
}

CAIP-2 / CAIP-10 are the chain-agnostic identifier standards (eip155:1 = Ethereum mainnet, eip155:42161 = Arbitrum, etc.). The standard is transport-agnostic: a Hyperlane-backed gateway and a LayerZero-backed gateway expose the same interface.

Neo Equivalent: Oracle + Bridge Attestation Pattern

Neo has two relevant primitives but no first-class cross-chain message bus:

1. Native Oracle service — fetch arbitrary HTTPS data via consensus. Useful as the "fetch the source-chain proof" step inside a bridge.
2. Bridge contracts — community-built bridges (Poly Network, Bywire, etc.) that maintain header relays + lock-mint contracts. Each one exposes its own interface today.

The cross-chain story for Neo is currently transport-specific, much as Ethereum was pre-7786. The mirror page documents the gap and proposes a Neo-side gateway interface that mirrors ERC-7786 so future bridge implementations can converge on a single dApp-facing shape.

ERC-7786 (Ethereum)	Proposed Neo Equivalent	Status
IERC7786GatewaySource.sendMessage(...)	IGateway.SendMessage(destChain, receiver, payload, attributes) on a per-bridge gateway contract	Per-bridge today; would be a Neo-side "ERC-7786 NEP" if formalised
IERC7786Receiver.executeMessage(...)	OnInboundMessage(messageId, sourceChain, sender, payload, attributes) callback	Per-bridge today
CAIP-2 / CAIP-10 ids	Same identifiers (chain-agnostic by design)	Direct reuse
Selector handshake (0x675b049b)	Verify-method handshake on the receiver	Same affordance
attributes array (gas limit, finality, etc.)	attributes array — same shape
Provider choice (LayerZero / Hyperlane / Axelar)	Provider choice (Poly Network / Bywire / future Neo-native bridge)

Where Neo's Native Primitives Fit

// Inside a Neo gateway contract — the SendMessage entry point posts an
// outbound message and emits an event the bridge relayer indexes.

[DisplayName("MessagePosted")]
public static event Action<ByteString, string, string, ByteString, object[]> OnMessagePosted;

public static ByteString SendMessage(
    string destinationChain,     // "eip155:1"
    string receiver,             // "eip155:1:0x…"
    ByteString payload,
    object[] attributes)
{
    if (!Runtime.CheckWitness(GetAuthorisedSender())) throw new Exception("not authorised");
    var outboxId = ComputeOutboxId(destinationChain, receiver, payload);

    // Bridge-specific: deposit fee, escrow tokens, etc.
    // ...

    OnMessagePosted(outboxId, GetSelfCAIP10(), receiver, payload, attributes);
    return outboxId;
}

// Inbound side: the bridge relayer calls this on the destination Neo contract
// after verifying the source-chain proof off-chain (or via Oracle).
public static ByteString ExecuteMessage(
    ByteString messageId,
    string sourceChain,
    string sender,
    ByteString payload,
    object[] attributes)
{
    if (Runtime.CallingScriptHash != BridgeRelayer()) throw new Exception("not relayer");
    // Process payload — application-specific.
    return (ByteString)EXECUTE_MESSAGE_SELECTOR;  // matches ERC-7786 handshake selector
}

Why This is "Pattern" Not "Direct"

Neo doesn't yet have a canonical native bridge that wraps multiple underlying transports the way ERC-7786 does for Ethereum. Each Neo bridge ships its own send/receive shape. The mirror page makes the case for a NEP-7786 convention so future bridge work converges; until that NEP exists, dApp authors writing cross-chain code on Neo should:

1. Pick a specific bridge (Poly Network is the most mature today).
2. Wrap that bridge's API in a thin adapter contract whose interface matches the proposed gateway shape above.
3. Keep the adapter swappable so a future NEP-7786 gateway can replace it without changing call sites.

Recommended Roadmap

• Short term — adopt the proposed IGateway shape in any new cross-chain dApp for forward-compatibility.
• Medium term — if Neo gets a native cross-chain primitive (rumoured for the next major NeoFS / Oracle upgrade), wrap it in the gateway interface so existing dApps need no source changes.
• Long term — propose a NEP-7786 once two or more bridges support the shape, mirroring ERC-7786's "transport-agnostic, per-provider implementation" model.

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

interface IERC7786GatewaySource {
    event MessagePosted(
        bytes32 indexed outboxId,
        string  sender,
        string  receiver,
        bytes   payload,
        bytes[] attributes
    );

    function supportsAttribute(bytes4 selector) external view returns (bool);

    function sendMessage(
        string calldata destinationChain,
        string calldata receiver,
        bytes  calldata payload,
        bytes[] calldata attributes
    ) external payable returns (bytes32 outboxId);
}

interface IERC7786Receiver {
    function executeMessage(
        bytes32 messageId,
        string calldata sourceChain,
        string calldata sender,
        bytes  calldata payload,
        bytes[] calldata attributes
    ) external returns (bytes4);
}

// Application — uses the gateway, doesn't care about the underlying provider.
contract CrossChainCounter is IERC7786Receiver {
    IERC7786GatewaySource public immutable gateway;
    mapping(string => uint256) public countsByChain;

    constructor(IERC7786GatewaySource _gateway) { gateway = _gateway; }

    function bumpRemote(string calldata destinationChain, string calldata remoteCounter) external payable {
        gateway.sendMessage{value: msg.value}(
            destinationChain, remoteCounter,
            abi.encodeWithSignature("bump()"),
            new bytes[](0)
        );
    }

    function executeMessage(
        bytes32, string calldata sourceChain, string calldata,
        bytes calldata payload, bytes[] calldata
    ) external returns (bytes4) {
        require(bytes4(payload) == bytes4(keccak256("bump()")), "unknown method");
        countsByChain[sourceChain]++;
        return IERC7786Receiver.executeMessage.selector;
    }
}

When compiled with neo-solc, this contract works against any bridge adapter that wraps a Neo-side bridge in the gateway interface (see C# tab). Until a NEP-7786 lands, the gateway address is a per-bridge deployment.

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

namespace R3E.Examples;

// Proposed gateway shape — what a Neo-side ERC-7786 mirror would look like.
// This is illustrative; until NEP-7786 lands, each bridge ships its own.

[DisplayName("CrossChainGateway")]
[ContractPermission("*", "*")]
public class CrossChainGateway : SmartContract
{
    private const byte Prefix_Outbox = 0x01;
    private static readonly UInt160 BRIDGE_RELAYER =
        (UInt160)"0x0000000000000000000000000000000000000000";

    [DisplayName("MessagePosted")]
    public static event Action<ByteString, string, string, ByteString, object[]> OnMessagePosted;

    public static ByteString SendMessage(
        string destinationChain,
        string receiver,
        ByteString payload,
        object[] attributes)
    {
        if (!Runtime.CheckWitness(Runtime.CallingScriptHash))
            throw new Exception("not authorised");

        var outboxId = (ByteString)CryptoLib.Sha256(
            ((ByteString)destinationChain)
                .Concat((ByteString)receiver)
                .Concat(payload)
                .Concat(((ByteString)Runtime.GetRandom().ToByteArray()))
        );

        Storage.Put(Storage.CurrentContext,
            new byte[] { Prefix_Outbox }.Concat(outboxId), 1);

        OnMessagePosted(outboxId, GetSelfCAIP10(), receiver, payload, attributes);
        return outboxId;
    }

    private static string GetSelfCAIP10()
    {
        // CAIP-10 for Neo: "neo:{network}:{contractHash}".
        var network = Runtime.GetNetwork();
        return "neo:" + network.ToString() + ":" + Runtime.ExecutingScriptHash.ToString();
    }
}

// Application receiver — implements the inbound side.
[DisplayName("CrossChainCounter")]
[ContractPermission("*", "*")]
public class CrossChainCounter : SmartContract
{
    private const byte Prefix_Count = 0x10;
    private static readonly UInt160 GATEWAY =
        (UInt160)"0x0000000000000000000000000000000000000000";

    public static int ExecuteMessage(
        ByteString messageId, string sourceChain, string sender,
        ByteString payload, object[] attributes)
    {
        if (Runtime.CallingScriptHash != GATEWAY) throw new Exception("not gateway");
        if (payload.Equals((ByteString)"bump"))
        {
            var key = new byte[] { Prefix_Count }.Concat((ByteString)sourceChain);
            var count = (int)(BigInteger)(Storage.Get(Storage.CurrentContext, key) ?? ByteString.Empty);
            Storage.Put(Storage.CurrentContext, key, count + 1);
        }
        return 0x675b049b;  // ERC-7786 handshake selector — kept compatible
    }
}

What Adopting This Buys

If you're building cross-chain code on Neo today, writing against the proposed gateway shape gives you:

1. Provider portability — switch from one bridge to another without touching application contracts.
2. Forward compatibility — when a NEP-7786 lands, your code already matches the canonical interface.
3. Solidity-port reuse — Solidity dApps already targeting ERC-7786 port to Neo with no API changes; just point at a Neo gateway adapter.