TRC-7786: Cross-Chain Messaging Gateway

[yanghang8612]

tip: 7786
title: Cross-Chain Messaging Gateway
description: An interface for contracts to send and receive cross-chain messages containing arbitrary data.
author: yanghang8612@gmail.com
discussions-to: https://github.com/tronprotocol/tips/issues/902
status: Draft
type: Standards Track
category: TRC
created: 2026-07-02

Simple Summary

A standard interface, and corresponding workflow, for smart contracts to send and receive arbitrary data across chains through cross-chain messaging protocols (bridges).

Abstract

This proposal describes an interface, and the corresponding workflow, for smart contracts to send arbitrary data through cross-chain messaging protocols. The end goal is to have all such messaging protocols accessible via this interface (natively or using "adapters") to improve their composability and interoperability. That would allow a new class of cross-chain native smart contracts to emerge while reducing vendor lock-in. This proposal is modular by design, allowing users to leverage bridge-specific features through attributes (structured metadata) while providing simple "universal" access to the simple feature of "just getting a simple message through". Sender and recipient accounts are expressed as chain-agnostic Interoperable Addresses, so the same interface covers TRON, other EVM chains, and non-EVM chains.

Motivation

Cross-chain messaging protocols (or bridges) allow communication between smart contracts deployed on different blockchains. There is a large diversity of such protocols with multiple degrees of decentralization, different architectures, implementing different interfaces, and providing different guarantees to users.

Because almost every protocol implements a different workflow using a specific interface, portability between bridges is currently basically impossible. This also prevents the development of generic contracts that rely on cross-chain communication.

The objective of this TRC is to provide a standard interface, and a corresponding workflow, for performing cross-chain communication between contracts. Existing cross-chain communication protocols that do not natively implement this interface should be able to adopt it using adapter gateway contracts. TRON hosts a large share of the industry's stablecoin liquidity, so standardized, auditable messaging rails between TRON and other chains are particularly valuable; a bridge-agnostic interface lets a TRON contract switch or layer providers without rewriting its integration.

Compared to previous work in this area, this proposal offers compatibility with chains outside of the Ethereum/EVM ecosystem, and it is extensible to support the different feature sets of various protocols while offering a shared core of standard functionality.

Specification

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.

Message Field Encoding

A cross-chain message consists of a sender, recipient, payload, value (native token), and list of attributes.

Sender and Recipient

The sender account (in the source chain) and recipient account (in the destination chain) MUST be input in an Interoperable Address binary format, specified in ERC-7930, which MUST be serialized according to CAIP-350. The recipient field MAY be omitted or zeroed (contain an Interoperable Address with all fields set to zero) to indicate an unspecified destination, such as when a broadcast mode is employed and the final recipients are determined by the protocol itself.

TRON is not an eip155 chain and its Interoperable Address encoding is TRON-specific:

• Chain identity. TRON identifies a chain by its genesis block id; TIP-712 already uses the low 4 bytes of block.chainid (0x2b6653dc on Mainnet), matching the CAIP-2 form tron:0x2b6653dc used by wallet ecosystems. A tron CAIP namespace and its CAIP-350 binary serialization MUST be agreed (and, ideally, registered upstream) so that TRON gateways interoperate with counterparts on other chains. Distinct chain references MUST be used for Mainnet, Nile, and Shasta to prevent cross-network delivery.
• Address bytes. A TRON account is canonically the 20-byte body obtained by stripping the 0x41 prefix (consistent with TIP-712 and TIP-2612); Base58Check is a display concern only. Because two encodings of the same account would silently break matching, gateways MUST use this canonical 20-byte form in the ERC-7930 Address field and reject non-canonical encodings (see Security Considerations).

Payload

The payload is an opaque bytes value.

Attributes

An attribute is a key-value pair, where the key determines the type and encoding of the value, as well as its meaning and behavior in the gateway.

The set of valid attributes is extensible. It is RECOMMENDED to standardize them and their characteristics by publishing them as TIPs. A gateway MAY support any set of standard or custom attributes.

An attribute key is a 4-byte value (bytes4). It is RECOMMENDED to define a key as the function selector for a function signature according to Solidity ABI (for example, minGasLimit(uint256) resulting in the key 39f87ba1), so as to give the key a human-readable name and a standard value encoding corresponding to the ABI-encoding of the function arguments.

An attribute value is a byte array (bytes).

The list of attributes MUST be encoded as bytes[] (an array of bytes) where each element is the concatenation of a key and a value. (Note that in the case of keys defined as Solidity function selectors, each element of the array can be encoded by abi.encodeWithSignature.)

A message with no attributes (an empty attributes list) MUST be considered a valid message.

Because attribute keys are permissionless selectors, TRON-specific attributes (for example an energy fee-limit hint) can be introduced without any change to this interface. Standard gas-denominated attributes such as minGasLimit(uint256) MUST be interpreted by a TRON destination gateway in terms of the TVM energy model (destination execution is metered in energy under a fee-limit cap), and the interpretation SHOULD be documented by the gateway.

Sending Procedure

A Source Gateway is a contract that offers a protocol to send a message to a recipient on another chain. It MUST implement ITRC7786GatewaySource.

interface ITRC7786GatewaySource {
    event MessageSent(
        bytes32 indexed sendId,
        bytes sender,    // Binary Interoperable Address
        bytes recipient, // Binary Interoperable Address
        bytes payload,
        uint256 value,
        bytes[] attributes
    );

    error UnsupportedAttribute(bytes4 selector);

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

    function sendMessage(
        bytes calldata recipient, // Binary Interoperable Address
        bytes calldata payload,
        bytes[] calldata attributes
    ) external payable returns (bytes32 sendId);
}

supportsAttribute

Returns a boolean indicating whether an attribute (identified by its key) is supported by the gateway.

A gateway MAY be upgraded with support for additional attributes. Once present, support for an attribute SHOULD NOT be removed to preserve backwards compatibility with users of the gateway.

sendMessage

Initiates the sending of a message.

Further action MAY be required by the gateway to make the sending of the message effective, such as providing payment for gas/energy. See Post-processing.

MUST revert with UnsupportedAttribute if an unsupported attribute is included. MAY revert if an attribute value is not valid for the key.

MAY accept call value (native token) to be sent with the message. On TRON the native value slot maps to TRX call_value; TRC-10 (call_token_value/token_id) is out of scope and MUST be wrapped into a TRC-20 representation first, while TRC-20 transfers are ordinary calldata and unaffected. MUST revert if call value is included but it is not a feature supported by the gateway. It is unspecified how this value is represented on the destination.

MAY generate and return a unique non-zero send identifier, otherwise returning zero. This identifier can be used to track the lifecycle of the message in the source gateway in events and for post-processing. Note that this identifier MAY be different from the receiveId that is delivered to the recipient, since that identifier may preferably consist of values like transaction id and log index that are not available in the execution environment.

MUST emit a MessageSent event, including the optional send identifier that is returned by the function.

MessageSent

This event signals that a would-be sender has requested a message to be sent.

If sendId is present, post-processing MAY be required to send the message through the cross-chain channel.

Post-processing

After a sender has invoked sendMessage, further action MAY be required by the gateways to make the message effective. This is called post-processing. For example, some payment is typically required to cover the energy of executing the message at the destination.

The exact interface for any such action is out of scope of this TRC.

Reception Procedure

A Destination Gateway is a contract that implements a protocol to validate messages sent on other chains. The interface of the destination gateway and how it is invoked is out of scope of this TRC.

The protocol MUST ensure delivery of a sent message to its recipient using the ITRC7786Recipient interface (specified below), which the recipient MUST implement.

Once the message can be safely delivered (see Properties), the gateway MUST invoke receiveMessage with the message identifier and contents, unless the sender or the recipient explicitly requested otherwise.

The receiveId MUST be either empty or unique (for the calling gateway) to the message being relayed. The format of this identifier is not specified, and the gateway can use it at its own discretion. For example it can be an identifier of the event that created the message.

The gateway MUST verify that receiveMessage returns the correct value, and MUST revert otherwise.

interface ITRC7786Recipient {
    function receiveMessage(
        bytes32 receiveId,     // Unique identifier
        bytes calldata sender, // Binary Interoperable Address
        bytes calldata payload
    ) external payable returns (bytes4);
}

receiveMessage

Delivery of a message sent from another chain.

The recipient MUST validate that the caller of this function is a known gateway, i.e., one whose underlying cross-chain messaging protocol it trusts.

MUST return ITRC7786Recipient.receiveMessage.selector (0x2432ef26).

Properties

The protocol underlying a pair of gateways is expected to guarantee a series of properties:

• The protocol MUST guarantee Safety: A message is delivered at the destination if and only if it was sent at the source. The delivery process must ensure a message is only delivered once the sending transaction is finalized, and not delivered more than once. Note that there can be multiple messages with identical parameters that must be delivered separately.
• The protocol MUST guarantee Liveness: A sent message is eventually delivered to the destination, assuming Liveness and censorship-resistance of the source and destination chains and that any protocol costs are paid.
• The protocol SHOULD guarantee Timeliness: A sent message is delivered at the destination within a bounded delivery time, which should be documented.
• The above properties SHOULD NOT rely on trust in some centralized actor. For example, safety should be guaranteed by some trustless mechanism such as a light client proof or attestations by an open, decentralized validator set. Relaying should be decentralized or permissionless to ensure liveness; a centralized relayer can fail and thus halt the protocol.

On TRON, the practical finality gate for the Safety property is the solidified block (a block confirmed by more than two thirds of the 27 Super Representatives). A source-side gateway or relayer SHOULD NOT act on a MessageSent event before the emitting block is solidified, otherwise a chain reorganization could cause a phantom or double delivery.

Rationale

Attributes are designed so that gateways can expose any specific features the bridge offers without having to use a proprietary interface. This should allow contracts to change the gateway they use while continuing to express messages the same way. This portability offers many advantages:

• A contract that relies on a specific gateway for sending messages is vulnerable to the gateway being paused, deprecated, or simply breaking. If the communication between the contract and the gateway is standard, an admin of the contract could update the address (in storage) of the gateway to use. In particular, this allows senders to update to the new gateway when a new version is available.
• Bridge layering is made easier. In particular, this interface should allow for gateways that route the message through multiple independent bridges. Delivery of the message could require one or multiple of these independent bridges depending on whether improved liveness or safety is desired.

As some cross-chain communication protocols require additional parameters beyond the destination and the payload, and because we want to send messages through those bridges without any knowledge of these additional parameters, a post-processing of the message MAY be required (after sendMessage is called, and before the message is delivered). The additional parameters MAY be supported through attributes, which would remove the need for a post-processing step. If these additional parameters are not provided through attributes, an additional call to the gateway is REQUIRED for the message to be sent. If possible, the gateway SHOULD be designed so that anyone with an incentive for the message to be delivered can jump in. A malicious actor providing invalid parameters SHOULD NOT prevent the message from being successfully relayed by someone else.

Some protocol gateways support doing arbitrary direct calls on the recipient. In that case, the recipient must detect that it is being called by the gateway to properly identify cross-chain messages. Getters are available on the gateway to figure out where the cross-chain message comes from (source chain and sender address). This approach has the downside that it allows anyone to trigger any call from the gateway to any contract. This is dangerous if the gateway ever holds any assets (TRC-20 or similar). The use of a dedicated receiveMessage function on the recipient protects any assets or permissions held by the gateway against such attacks. If the ability to perform direct calls is desired, this can be implemented as a wrapper on top of any gateway that implements this TRC.

Backwards Compatibility

Existing cross-chain messaging protocols implement proprietary interfaces. We recommend that protocols natively implement the standard interface defined here, and propose the development of standard adapters for those that don't. On TRON, adapter gateways can wrap existing infrastructure (for example the BTTC bridge or LayerZero deployments), so no protocol change is required to expose the standard interface; reference gateway adapters written against this interface on other chains port to TVM with only address and chain-id adjustments.

Security Considerations

Handling addresses

Interoperable Addresses (ERC-7930) rely on CAIP-350 serialization. Using non-canonical encodings can lead to silent delivery failures. Gateways SHOULD reject non-canonical encodings and MAY normalize them before emission. On TRON this specifically means using the canonical 20-byte (0x41-stripped) account body rather than the 21-byte prefixed form or a Base58Check string.

Recipient authentication

Because receiveMessage grants the caller the ability to deliver a message under an arbitrary sender, a recipient MUST authenticate msg.sender as a known, trusted destination gateway before acting on the payload, MUST deduplicate by receiveId, and SHOULD treat the decoded sender Interoperable Address as untrusted input until validated. When a delivery fans out into further calls, implementers should account for the TVM 63/64 energy-forwarding rule (TIP-272) and for reentrancy.

Copyright

Copyright and related rights waived via CC0.

[lily309]

We've already got BTTC, LayerZero endpoints and the usual exchange rails on TRON. What does a standard gateway interface really add on top of that? Trying to work out whether this solves an actual portability problem or just adds another layer to maintain.

[TonyStank911]

This leans on ERC-7930 for the address format, but that's still in Review and there's no tron entry in CAIP-350 as far as I can tell. Doesn't that block any two TRON gateways from being interoperable until it's sorted out? How are you thinking of handling it in the meantime?

[yanghang8612]

@lily309 This isn't trying to replace BTTC or LayerZero, it's a common interface sitting on top of them. The point is you're not married to one bridge anymore — if a gateway gets paused or deprecated you swap an address in storage instead of rewriting your integration, and you can route through several if you want. Both of those can just be wrapped as adapters, nothing underneath has to change.

[yanghang8612]

@TonyStank911 Yeah, the 7930 dependency is honestly the part I most want feedback on. It's still in Review upstream and there's no tron namespace in CAIP-350 yet, so until someone pins down how TRON serializes as an interoperable address (the ChainType + chain-reference bytes) and ideally gets it registered, two gateways can't really talk. For now I'd fix a specific 7930 version and a provisional TRON assignment in the TIP so nobody's implementation drifts — but if you see a cleaner path, that's the open one.