Private DvP with Enygma

Enygma's delivery-versus-payment (DvP) lets two participants exchange Enygma tokens for a tokenised asset in a single settlement on the Private Network Hub, the Hyperledger Besu chain at the centre of every Rayls Private Network. For DvP across a Private Network in general, see DvP on Rayls Private Networks. Either both legs settle or neither does, and the trade terms are encrypted for the counterparty.

What you can exchange

The Private Network operator decides which assets can be swapped for which, by registering asset groups and the pairs of groups that may settle against each other.

How DvP holds assets

DvP doesn't use the account balances of Enygma payments. Assets in DvP are held as coins in vaults on the Hub, one vault per asset type:

• each coin is a commitment, a Poseidon hash of the owner's public spend key, a random salt, the amount or token ID, and the asset, stored as a leaf in a Merkle tree;
• spending a coin needs a zero-knowledge proof that you own a coin in the tree, plus a nullifier, which marks that coin as spent without revealing which one it was;
• a swap spends the input coins and creates new coins for the new owners.

This is a UTXO-style (unspent transaction output) model, which suits swapping discrete assets.

A swap, step by step

Alice, on chain A, buys NFT #42 from Bob, on chain B, for 100 Enygma tokens:

1. Agree. Alice and Bob agree the terms off-chain, including a shared swap ID (sharedId).
2. Deposit. Each side moves its asset into DvP:
   • Alice calls depositToDvp on the Enygma token. Her relayer moves 100 tokens from her participant's Enygma balance on the Hub into a new coin in the Enygma vault, using a zero-knowledge proof, so the amount stays hidden.
   • Bob calls depositIntoDvp on the NFT token. NFT #42 moves into the ERC-721 vault on the Hub, and a coin is created for Bob.
3. Initiate. Both sides call their token's swap function with the same sharedId: swapWithDvpForERC721 on the Enygma side, swapWithDvpForEnygma on the NFT side. Whichever relayer reaches the Hub first becomes the initiator. It encrypts the terms for the counterparty and calls initiateSwap with its proof and a validity time. The contract locks the initiator's coin and records the swap as pending.
4. Complete. The counterparty's relayer decrypts the terms, checks them and calls completeSwap with its own proof. The contract checks that the two sides' messages match, that the asset pair is allowed and that both proofs are valid. It then spends both input coins and creates the new coins in one transaction: Alice now owns a coin for NFT #42, and Bob a coin for 100 Enygma tokens.
5. Withdraw. Each side takes its new asset back to its own chain. Bob calls callWithdrawFromDvp on the Enygma token, and the 100 tokens return to his Enygma balance. Alice calls withdrawFromDvp on the NFT token, and NFT #42 is delivered to her on chain A.

If a swap doesn't complete

• Cancel. Either side can cancel a pending swap through its token. On the Enygma token the functions are cancelERC721Swap and cancelERC1155Swap, and the caller must hold a balance of the token. On the NFT token the function is cancelSwap. The relayer then calls cancelSwap on the Hub.
• Expire. Every swap has a validity time: two days by default, and always more than 5 hours and less than 14 days. After it passes, expireSwap closes the swap.

In both cases, the initiator's locked coin is marked spent and replaced by a new coin of the same value. The initiator committed to the replacement coin when it initiated the swap, so the initiator gets its asset back in DvP and can withdraw it.

Many small deposits

A single DvP proof can spend at most 10 coins. If a participant holds more small Enygma coins than that, its relayer automatically merges them into a larger coin first (mixFunds).

What DvP reveals

• NFT deposits and withdrawals are visible. An ERC-721 token moves into and out of the vault on the Hub, so observers see which token entered and later left DvP.
• Enygma amounts are hidden. Enygma deposits and withdrawals use the same proofs as transfers, and coins hide their amounts.
• The terms are encrypted for the counterparty. The key is agreed with ML-KEM against the counterparty's view key, and the terms are encrypted with AES-256-GCM. Since the Private Network operator holds every participant's view key, it can read swap terms too. See Who sees what.
• Swap events are public. The Hub emits events when a swap is initiated, completed, cancelled or expired, each tagged with its sharedId.

For the function signatures, see RaylsEnygmaHandler.