Message Design Patterns

OWM

➡️

One way message Pattern [A->B]

Sender targets any contract on receiver

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 this straightforward approach by placing another _raylsSend call inside the _receiver function of the destination contract. Imagine it like a ping-pong game, 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 showcases the concept of horizontal layering, setting it apart from vertical layering by wrapping the external call in a new message format. This structure allows the application to keep certain response actions distinct from the external call.

With each layering call wrapped as its own message bundle through a specialized process, this approach is scalable to multiple sequential operations as needed by your application (e.g., B1 -> B2 -> B3, and so on).

This method proves to be highly effective for managing intricate transactions and operations on the target chain, requiring 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 proceed to interact with a decentralized finance (DeFi) protocol for lending, borrowing, liquidity provision, staking, etc., performing a variety of financial maneuvers across multiple chains.

Cross-Chain NFT Engagements: An NFT transferred to a different chain could prompt a contract to bestow a license, 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 upon by the DAO, supporting community-driven projects or public initiatives.

VT20

↔️

Vanilla Teleport ERC20

Vanilla Teleport ERC20 A simple, one-way ERC20 transfer across Privacy Nodes. Tokens are burned on the source Privacy Node and minted on the destination Privacy Node. There is no rollback mechanism — if the destination mint fails, tokens are not automatically returned.

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 A safer cross-chain ERC20 transfer with a revert mechanism. Tokens are burned on the source and locked (not immediately spendable) on the destination until the transfer is confirmed. If 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.