Cross-Chain Swaps

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


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.


Alice and Bob want to exchange 10 alice tokens for 10 bob tokens. The problem is that they are not in the same blockchain: alice token is defined in Catapult’s public chain, whereas bob token is only present in a private chain using Catapult technology.


Catapult’s private and future public chain share the SDK. You could implement atomic cross-chain swap between blockchains that use different technologies if they permit the secret lock/proof mechanism.

sequenceDiagram participant Alice participant Private Chain participant Public Chain participant Bob Note over Alice: proof = 'random' Note over Alice: h = sha_256() Note over Alice: secret = h(proof) Alice ->> Private Chain: announces TX1(secret) Note right of Alice: TX1 waits for proof Alice -->> Bob: tells secret Bob ->> Public Chain: announces TX2(secret) Note left of Bob: TX2 waits for proof Alice ->> Public Chain: announces TX3(proof, secret) Note left of Public Chain: proof becomes public Note left of Bob: TX2 executes Note left of Bob: Alice receives funds Bob ->> Private Chain: announces TX4(proof, secret) Note right of Alice: TX1 executes Note right of Alice: Bob receives funds

Atomic cross-chain swap sequence diagram

  1. Alice generates a random set of bytes called proof. The proof should have a size between 10 and 1000 bytes.
  2. Alice hashes the obtained proof with one of the available algorithms to generate the secret.
  3. Alice defines the SecretLockTransaction TX1:
  • Mosaic: 10 alice token
  • Recipient: Bob’s address (Private Chain)
  • Algorithm: h
  • Secret: h(proof)
  • Duration: 96h
  • Network: Private Chain
  1. Alice announces TX1 to the private network and shares with Bob the secret.
  2. Bob defines announces the following SecretLockTransaction TX2 to the public network:
  • Mosaic: 10 bob token
  • Recipient: Alice’s address (Public Chain)
  • Algorithm: h
  • Secret: h(proof)
  • Duration: 84h
  • Network: Public Chain


The amount of time in which funds can be unlocked should be a smaller time frame than TX1’s. Alice knows the secret, so Bob must be sure he will have some time left after Alice releases the secret.

  1. Alice announces the SecretProofTransaction TX3 to the public network. This transaction defines the encrypting algorithm used, the original proof and the secret.
  2. Once TX3 is confirmed, the proof is revealed. TX2 transaction is unlocked and Alice receives the locked funds.
  3. Bob picks the proof and announces the SecretProofTransaction TX4 to the private network, receiving the locked funds from TX1.


Transaction schemas


Use a SecretLockTransaction to transfer mosaics between two accounts. The specified mosaics remain locked until a valid SecretProofTransaction unlocks them.

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

Version: 0x01

EntityType: 0x4152


Property Type Description
secret Hash256 Proof hashed.
mosaic UnresolvedMosaic Locked mosaic.
duration BlockDuration Number of blocks for which a lock should be valid. Duration is allowed to lie up to 30 days. If reached, the mosaics will be returned to the initiator.
hashAlgorithm LockHashAlgorithm Algorithm used to hash the proof.
recipientAddress UnresolvedAddress Address that receives the funds once unlocked.


Use a SecretProofTransaction to unlock SecretLockTransactions.

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

Version: 0x01

EntityType: 0x4252


Property Type Description
secret Hash256 Proof hashed.
proofSize uint16 Proof size in bytes.
hashAlgorithm LockHashAlgorithm Algorithm used to hash the proof.
recipientAddress UnresolvedAddress Address that receives the funds once unlocked.
proof array(byte, proofSize) Original random set of bytes.


The list of supported hashing algorithms.

Enumeration: uint8

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

Continue: Cryptography.