Overview

Rayls Sovereign has two routes out of the institution's own ledger, and they work differently.

The first is the Rayls Private Network route, where the institution's ledger reaches other institutions through the shared Private Network Hub. That route is covered in Connecting Rayls Sovereign to a Private Network.

The second is the Rayls Public Chain route, which is the subject of this page. It is a direct one-to-one path between a Rayls Sovereign ledger and a single public chain, it does not involve the Private Network Hub at all, and it uses a separate set of contracts and a separate relayer process.

How the two routes differ

Aspect	Private Network route	Public Chain route
Path	Rayls Sovereign ledger to the Private Network Hub to another Rayls Sovereign ledger	Rayls Sovereign ledger directly to the public chain
Relayer	The main Relayer	A separate public relayer process
Contracts	Endpoint and Teleport	The RN-prefixed contract family
Encryption	Always encrypted	Optional
Token model	Resource identifiers registered in the Hub token registry	Mirror token contracts deployed on the public chain
Asset mechanics	Burn on the source, mint on the destination	Lock or burn on the source, mint or unlock on the destination

Both routes implement the EIP-5164 cross-chain execution standard, in which context comprising the message identifier, the source chain identifier and the sender is appended to the call data.

The contracts involved

The contracts on this path all carry an RN prefix, which stands for Rayls Node.

Contract	Role
RNEndpointV1	Coordinates the one-to-one connection to the public chain and routes messages in both directions
RNMessageDispatcherV1	Implements the EIP-5164 MessageDispatcher interface for outgoing messages and emits `MessageDispatched` events
RNMessageExecutorV1	Implements the EIP-5164 MessageExecutor interface for incoming messages, with replay and reentrancy protection
RNContractFactoryV1	Deploys contracts using CREATE2, so that the same contract address is produced across chains
RNTokenGovernanceV1	Token registration and status management for public chain bridging
RNUserGovernanceV1	Manages the pairing between an address on the public chain and an address in the Rayls Sovereign ledger

On the public chain side, the counterpart endpoint is PublicRNEndpointV1, and the mirror token contracts are PublicChainERC20, PublicChainERC721 and PublicChainERC1155.

Getting a token ready to bridge

A token cannot bridge until it has been registered and activated. The sequence is as follows.

1. Deploy and register. The token owner deploys the token in the Rayls Sovereign ledger and registers it in RNTokenGovernanceV1 with its name, symbol, standard and address. It starts in INACTIVE status.

2. Activate. The owner calls updateTokenStatus to set the token ACTIVE, which emits a TokenActivated event.

3. The mirror is deployed automatically. The public relayer's private listener picks up the TokenActivated event, checks that a mirror does not already exist, and its deployer service deploys the corresponding mirror contract on the public chain.

4. The mapping is recorded. The relayer records the private-to-public address mapping through updatePublicTokenAddress on RNTokenGovernanceV1, and whitelists the new public token contract as an authorised sender on PublicRNEndpointV1.

At that point the token is bridgeable in both directions.

Bridging mechanics

Direction	Source action	Destination action
Rayls Sovereign to public chain	Lock, with the tokens held by the owner in the Rayls Sovereign ledger	Mint, creating new tokens on the public chain
Public chain to Rayls Sovereign	Burn, destroying the tokens on the public chain	Unlock, releasing the previously locked tokens

Sending to the public chain

The user calls teleportToPublicChain on the token contract in the Rayls Sovereign ledger, which locks the funds and dispatches a message. The endpoint resolves the private token address to its public counterpart, the public relayer creates the destination call data, and the mirror contract mints to the recipient on the public chain.

The signature varies by token standard:

Standard	Function
ERC-20	`teleportToPublicChain(to, value, chainId)`
ERC-721	`teleportToPublicChain(to, id, chainId)`
ERC-1155	`teleportToPublicChain(to, id, value, chainId, data)`

The call requires the caller to be registered in RNUserGovernanceV1, enforced by an onlyRegisteredUsers modifier, which is how KYC and compliance requirements are carried into the bridge itself rather than being applied alongside it. If the recipient address is the zero address, the public contract does not revert; it sends an explicit callback that unlocks the sender's tokens in the Rayls Sovereign ledger.

Receiving from the public chain

The user calls teleportToPrivacyNode on the public token contract, which burns the tokens and dispatches a message carrying both the forward payload and a revert payload. The public relayer creates the call data for the Rayls Sovereign ledger, and the private token contract unlocks the tokens and transfers them to the recipient.

The public relayer

The public relayer is a separate process from the Relayer that serves the Private Network Hub, and it operates independently of the Hub. It relays messages in both directions, deploys mirror tokens, and handles failures with automatic reverts.

Internally it runs a private listener and a public listener watching each chain for MessageDispatched events, private and public transaction generators, private and public executors that submit transactions and poll for receipts, a deployer service for mirror tokens, and a revert service.

Failure handling

Every message on this path carries a revert payload, which the generator service pre-generates and stores at the point it creates the forward transaction. The revert service polls for completed transactions on the destination, and where a transaction failed, meaning the receipt status is not equal to 1, it retrieves the stored revert signature and submits the revert payload to the source chain.

The consequence is that a failed transfer to the public chain unlocks the sender's tokens in the Rayls Sovereign ledger, and a failed transfer from the public chain mints the tokens back to the sender on the public chain. Tokens are either delivered to the destination or returned to the sender.