Cross-Chain Swaps

A cross-chain swap enables trading tokens across different blockchains, without using an intermediary party (eg. an exchange service) in the process.

../_images/cross-chain-swap.png

Atomic cross-chain swap between public and private network

In order to create a trustless environment for an exchange, a specific transaction type is required that is commonly referred to as Hashed TimeLock Contract (HTLC). Two additional components characterize this transaction type: hashlocks and timelocks. A thorough explanation can be found on the Bitcoin Wiki.

In other words, to reduce counterparty risk, the receiver of a payment needs to present a proof for the transaction to execute. Failing to do so, the locked funds are released after the deadline is reached, even if just one actor does not agree. The figure below illustrates the cross-chain swap protocol.

../_images/cross-chain-swap-cycle.png

Atomic cross-chain swap sequence diagram

When talking about tokens in NEM, we are actually referring to mosaics. Catapult enables atomic swaps through secret lock / secret proof transaction mechanism.

Guides

Schemas

Note

Configuration parameters are editable . Public network configuration may differ.

SecretLockTransaction

Use a secret lock transaction to start the cross-chain swap:

  1. Define the mosaic units you want to transfer to a determined account.
  2. Generate a random set of bytes called proof.
  3. Hash the obtained proof with one of the available algorithms to generate the secret.
  4. Select during how much time the mosaics will be locked and announce the transaction.

The specified mosaics remain locked until a valid Secret Proof Transaction unlocks them.

If the transaction duration is reached without being proved, the locked amount goes back to the initiator of the secret lock transaction.

Version: 0x01

Entity type: 0x4152

Inlines:

Property Type Description
mosaic Mosaic Locked mosaic.
duration uint64 The lock duration. If reached, the mosaics will be returned to the initiator.
hashAlgorithm LockHashAlgorithm The algorithm used to hash the proof.
secret 64 bytes (binary) The proof hashed.
recipient 25 bytes (binary) The address who will receive the funds once unlocked.

SecretProofTransaction

Use a secret proof transaction to unlock secret lock transactions.

The transaction must prove that it knows the proof that unlocks the mosaics.

Version: 0x01

Entity type: 0x4252

Inlines:

Property Type Description
hashAlgorithm LockHashAlgorithm The algorithm used to hash the proof.
secret 64 bytes (binary) The proof hashed.
proofSize uint16 The proof size in bytes.
proof array(byte, proofSize) The original proof.

LockHashAlgorithm

Enumeration: uint8

Id Description
0 (Op_Sha3_256) Input is hashed using sha3 256.
1 (Op_Keccak_256) Input is hashed using Keccak (ETH compatibility).
2 (Op_Hash_160) Input is hashed twice: first with Sha-256 and then with RIPEMD-160 (bitcoin’s OP_HASH160).
3 (Op_Hash_256) Input is hashed twice with Sha-256 (bitcoin’s OP_HASH256).