RaylsErc1155DvpHandler

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

Inheritance: RaylsApp, ERC1155, Initializable, ReentrancyGuard, RaylsAccessManaged

See Privacy Node 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`	Privacy Node endpoint — routes messages to other Privacy Nodes via the Private Network Hub
`_raylsNodeEndpoint`	Privacy Node endpoint for the Rayls Public Chain
`_userGovernance`	RBAC contract that manages user roles and permissions within the Privacy Node
`_owner`	Address granted the Owner role

Token registration lifecycle

After deploying, call registerToken on the Privacy Node's TokenRegistryReplica system contract:

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

Once approved, the relayer calls receiveResourceId() on your contract automatically. After that, 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. Locked tokens cannot be transferred until the swap is 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,
    SharedObjects.DvpProgramability calldata _msg,
    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 buyer
`_enygmaResourceId`	Resource ID of the Enygma contract on buyer's PN
`_destChainId`	Chain ID of the buyer's Privacy Node
`_sharedId`	Unique identifier shared by both swap legs
`_msg`	Optional programmability data (custom payload after settlement)
`_validityTime`	Seconds until the swap expires (pass `0` for the contract default)

Step 3a — Swap completed (relayer-triggered)

Called automatically by the relayer when both legs succeed. Do not call this directly.

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

When executed: tokens are burned from the seller, minted on the buyer's PN, 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

Then 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, returning 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`