RaylsErc1155Handler

RaylsErc1155Handler is the abstract base contract for ERC1155 (multi-token) tokens in the Rayls Sovereign ledger. Extend it to create a multi-token contract supporting both fungible and non-fungible tokens that can be minted, burned and teleported cross-chain.

Inheritance: RaylsApp, ERC1155, ERC1155Holder, Initializable, ReentrancyGuard, RaylsAccessManaged

Minimal implementation

// SPDX-License-Identifier: MIT
pragma solidity 0.8.24;

import "@rayls/contracts/tokens/RaylsErc1155Handler.sol";

contract MyToken1155 is RaylsErc1155Handler {
    constructor(
        string memory _uri,
        string memory _name,
        address _endpoint,
        address _raylsNodeEndpoint,
        address _userGovernance,
        address _owner
    )
        RaylsErc1155Handler(
            _uri,
            _name,
            _endpoint,
            _raylsNodeEndpoint,
            _userGovernance,
            _owner,
            false
        )
    {}
}

Constructor parameters

Parameter	Description
`_uri`	Base URI for token metadata
`_name`	Collection name
`_endpoint`	Rayls Sovereign endpoint, which routes messages to other Rayls Nodes through the Private Network Hub
`_raylsNodeEndpoint`	Rayls Sovereign endpoint for the Rayls Public Chain
`_userGovernance`	RBAC contract that manages user roles and permissions within the Rayls Sovereign ledger
`_owner`	Address granted the Owner role (mint, burn, submitTokenUpdate)

The last parameter (false) marks this as a standard token. Pass true only if you are overriding the default transfer behaviour.

Token registration lifecycle

After deploying your token, call registerToken on the TokenRegistryReplica system contract in the Rayls Sovereign ledger:

TokenRegistryReplica.registerToken(tokenAddress, SharedObjects.ErcStandard.ERC1155, false)

Once the Private Network Operator approves the registration, the relayer calls receiveResourceId() on your contract automatically:

// Called by the relayer (MESSAGE_EXECUTOR role) after approval — do NOT call manually
function receiveResourceId(bytes32 _resourceId) public virtual restricted

Your token then holds a resourceId and is ready for cross-chain teleports.

Mint and burn

// Owner role only
function mint(address to, uint256 id, uint256 value, bytes memory data) public virtual restricted nonReentrant

// Owner role only
function burn(address from, uint256 id, uint256 value) public virtual restricted nonReentrant

Both functions report the change automatically to the TokenRegistry on the Private Network Hub, using _submitTokenUpdate.

Balance updates

// Owner role only
function submitTokenUpdate(
    SharedObjects.BalanceUpdateType updateType,
    uint256 id,
    uint256 amount
) public virtual restricted

BalanceUpdateType is an enum with the values MINT and BURN. You rarely need to call this function directly, because mint and burn call it internally.

Teleport functions

Vanilla teleport

This is a simple burn and mint with no revert mechanism.

function teleport(
    address to,
    uint256 id,
    uint256 value,
    uint256 chainId,
    bytes memory data
) public virtual nonReentrant returns (bool)

Atomic teleport

Tokens are locked on the destination until the transfer is confirmed, and if the destination fails, the relayer reverts the operation.

function teleportAtomic(
    address to,
    uint256 id,
    uint256 value,
    uint256 chainId,
    bytes memory data
) public virtual nonReentrant returns (bool)

Teleport to Public Chain

This sends tokens from the Rayls Sovereign ledger to an address on the Rayls Public Chain, and the caller must be a registered user.

function teleportToPublicChain(
    address to,
    uint256 id,
    uint256 value,
    uint256 destinationChainId,
    bytes memory data
) public virtual onlyRegisteredUsers nonReentrant returns (bool)

Token locking

ERC1155 tokens lock amounts per (address, tokenId):

// Returns locked amount for a specific token ID held by an account
function getLockedAmount(address account, uint256 id) public view returns (uint256)

Receive functions (called by the relayer)

Function	Trigger
`receiveTeleport(address to, uint256 id, uint256 value, bytes data)`	Vanilla teleport arrived, so tokens are minted
`receiveTeleportAtomic(address to, uint256 id, uint256 value, bytes data)`	Atomic teleport arrived, so tokens are minted and locked
`receiveTeleportFromPublicChain(address to, uint256 id, uint256 amount)`	Transfer from the Public Chain into the Rayls Sovereign ledger arrived, so tokens are unlocked
`revertTeleportMint(address to, uint256 id, uint256 value, bytes data)`	Atomic teleport reverted on the source chain, so tokens are re-minted
`revertTeleportBurn(address to, uint256 id, uint256 value)`	Atomic teleport reverted on the destination chain, so tokens are unlocked and burned
`revertTeleportToPublicChain(address from, uint256 id, uint256 amount)`	Public Chain mint failed, so tokens are unlocked
`unlock(address to, uint256 id, uint256 amount, bytes data)`	Atomic teleport confirmed, so locked tokens are released

All of these functions are restricted to MESSAGE_EXECUTOR.

Access control summary

Role	Functions
Owner	`mint`, `burn`, `submitTokenUpdate`
MESSAGE_EXECUTOR	`receiveTeleport`, `receiveTeleportAtomic`, `receiveTeleportFromPublicChain`, `revertTeleportMint`, `revertTeleportBurn`, `revertTeleportToPublicChain`, `unlock`, `receiveResourceId`
Any address	`teleport`, `teleportAtomic`, `teleportToPublicChain`*

teleportToPublicChain additionally requires onlyRegisteredUsers.