Message Design Patterns

OWM

➡️### One way message Pattern [A->B]

Sender targets any contract on receiver

The sender needs to know the smart contract address on the destination network.

BFM

🔄### Back-and-forth message Pattern [A->B->A]

Sender targets any contract on receiver, receiver replies the sender....

The back-and-forth message pattern builds on the one-way approach by placing another raylsSend call inside the receiver function of the destination contract. It behaves like a game of ping-pong, where a call is sent to a destination chain and then bounced back to the original source, creating a back-and-forth flow (A -> B -> A).

LMP

🔃### Layering message Pattern [A->B->BA->BB]

Sender targets a specific contract on receiver, receiver calls another contract and reply the sender....

This approach applies horizontal layering, which differs from vertical layering because the external call is wrapped in a new message format. That structure lets the application keep certain response actions distinct from the external call itself.

Each layering call is wrapped as its own message bundle through a specialised process, so the approach scales to as many sequential operations as an application needs (for example, B1 -> B2 -> B3, and so on).

The method suits complex transactions and operations on the target chain that require separate stages of contract logic, such as:

Multi-Chain Finance Operations: A smart contract could initiate a token move on the target chain and then interact with a decentralised finance (DeFi) protocol for lending, borrowing, liquidity provision or staking, carrying out a range of financial operations across several chains.

Cross-Chain NFT Engagements: An NFT transferred to a different chain could prompt a contract to grant a licence, record a domain, or start a subscription service that reflects the NFT's ownership.

Inter-Chain DAO Actions: A DAO might transfer funds to a contract on another chain and send a structured message to carry out particular investments or fund initiatives agreed by the DAO, supporting community-driven projects or public initiatives.

VT20

↔️### Vanilla Teleport ERC20

Vanilla Teleport ERC20 is a simple, one-way ERC20 transfer between institutions. Tokens are burned in the source Rayls Sovereign ledger and minted in the destination Rayls Sovereign ledger. There is no rollback mechanism, so if the destination mint fails the tokens are not returned automatically.

Use teleport() (self-initiated) or teleportFrom() (third-party with prior approval) on any RaylsErc20Handler-based token.

// Self-initiated: burn from msg.sender, mint on destination
function teleport(address to, uint256 value, uint256 chainId) public virtual returns (bool)

// Third-party: requires prior approval from 'from'
function teleportFrom(address from, address to, uint256 value, uint256 chainId) public virtual returns (bool)

AT20

🔀### Atomic Teleport ERC20

Atomic Teleport ERC20 is the safer cross-chain ERC20 transfer, because it carries a revert mechanism. Tokens are burned on the source and locked on the destination, meaning they are not immediately spendable, until the transfer is confirmed. Where the destination fails, the relayer can revert the operation and return the tokens to the sender.

Use teleportAtomic() (self-initiated) or teleportAtomicFrom() (third-party with prior approval) on any RaylsErc20Handler-based token.

// Self-initiated atomic teleport
function teleportAtomic(address to, uint256 value, uint256 destinationChainId) public virtual returns (bool)

// Third-party atomic teleport: requires prior approval from `from`
function teleportAtomicFrom(address from, address to, uint256 value, uint256 destinationChainId) public virtual returns (bool)

Prefer AT20 over VT20 for production transfers where loss of funds on a destination failure is unacceptable.