RaylsErc1155DvpHandler

RaylsErc1155DvpHandler is the abstract base contract for ERC1155 tokens that participate in cross-chain Delivery vs. Payment (DvP) swaps in the Rayls Sovereign ledger. The seller deposits tokens and initiates a swap offering them in exchange for Enygma tokens from a buyer on a different Rayls Node.

Inheritance: RaylsApp, ERC1155Supply, Initializable, ReentrancyGuard, RaylsAccessManaged

See Rayls Sovereign internal DvP for the full cross-chain DvP flow overview.

Minimal implementation

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

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

contract MyDvpToken1155 is RaylsErc1155DvpHandler {
    constructor(
        string memory _uri,
        string memory _name,
        address _endpoint,
        address _raylsNodeEndpoint,
        address _userGovernance,
        address _owner
    )
        RaylsErc1155DvpHandler(
            _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
`_isCustom`	True for the custom-token issuer flow, false for the standard template path

Token registration lifecycle

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

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

Once the registration is approved, the relayer calls receiveResourceId() on your contract automatically, after which the token can participate in DvP swaps.

DvP flow

Step 1 — Deposit tokens

The seller locks their tokens into the DvP contract before initiating a swap.

function depositIntoDvp(uint256 _tokenId, uint256 _value, bytes memory _data) public virtual nonReentrant

After this call, lockedForDvp[msg.sender][_tokenId] increases by _value, and the locked tokens cannot be transferred until the swap is either completed or cancelled.

Step 2 — Initiate the cross-chain swap

function swapWithDvpForEnygma(
    uint256 _tokenId,
    uint256 _tokenValue,
    bytes memory tokenDataParam,
    uint256 _enygmaAmount,
    bytes32 _enygmaResourceId,
    uint256 _destChainId,
    bytes32 _sharedId,
    uint64 _validityTime
) public virtual nonReentrant

Parameter	Description
`_tokenId`	ID of the token to offer
`_tokenValue`	Amount of tokens to swap
`tokenDataParam`	Optional extra data
`_enygmaAmount`	Amount of Enygma tokens requested from the buyer
`_enygmaResourceId`	Resource ID of the Enygma contract on the buyer's Sovereign ledger
`_destChainId`	Chain ID of the buyer's Rayls Node
`_sharedId`	Unique identifier shared by both swap legs
`_validityTime`	Seconds until the swap expires (pass `0` for the contract default)

Step 3a — Swap completed (relayer-triggered)

The relayer calls this function automatically once both legs of the swap succeed, so you should not call it yourself.

// restricted — RELAYER role only
function dvpSwapCompleted(
    SharedObjects.DvpSwapCompletedParams memory params,
    address from,
    uint256 _value,
    bytes memory data
) public virtual restricted nonReentrant

When it executes, the tokens are burned from the seller, minted on the buyer's Sovereign ledger, and the Enygma payment is released.

Step 3b — Cancel the swap

Call cancelSwap if the swap has expired or the counterparty did not respond.

function cancelSwap(
    bytes32 _sharedId,
    uint256 _toChainId,
    uint256 _tokenId,
    uint256 _tokenValue,
    bytes32 _enygmaResourceId,
    uint256 _enygmaAmount
) public virtual nonReentrant

Once the cancellation is registered, call withdrawFromDvp to recover the locked tokens:

function withdrawFromDvp(uint256 _tokenId, uint256 _value, bytes memory data) public virtual nonReentrant

The relayer finalises the unlock by calling unlockFromDvp, which returns the tokens to the seller's available balance.

Mint and burn

// Owner role only
function mint(
    address _to,
    uint256 _id,
    uint256 value,
    bytes memory data,
    SharedObjects.Dvp1155ExtraData[] memory _extraDatas
) public virtual restricted nonReentrant

// Owner role only
function burn(address _from, uint256 _id, uint256 _value) public virtual restricted nonReentrant

Swap validity time

// Owner role only
function setSwapValidityTime(uint64 _validityTime) public virtual restricted

Access control summary

Role	Functions
Owner	`mint`, `burn`, `submitTokenUpdate`, `setSwapValidityTime`
RELAYER	`dvpSwapCompleted`, `unlockFromDvp`, `notifySenderWithPNCommunicator`, `notifySenderAndReceiverWithPNCommunicator`
MESSAGE_EXECUTOR	`unlock`, `receiveResourceId`, `MintFromSwapDvp`
Any address	`depositIntoDvp`, `swapWithDvpForEnygma`, `cancelSwap`, `withdrawFromDvp`