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

Catapult follows the **Hashed TimeLock Contract** (HTLC) protocol to create a trustless environment for the decentralized exchange of assets.

HTLC uses *hashlocks* and *timelocks* to reduce the counterparty risk.
Every participant in the exchange of assets needs to present proof (hashlock) to complete it.
Failing to do so, the locked assets are released back to each original owner after the timelock expires.

A thorough explanation of the protocol can be found on the Bitcoin Wiki.

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 tech.

Note

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

1. Alice generates a random set of bytes called `proof`

.
The proof should have a size between `10`

and `1000`

bytes.

- Alice hashes the obtained proof with one of the available algorithms to generate the
`secret`

. - 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

- Alice
**announces TX1 to the private network**and**shares with Bob the secret**. - 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

Note

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.

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

Atomic cross-chain swap between public and private chain

Trade tokens between different blockchains, without using an intermediary party in the process.

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

The maximum number of blocks the lock can lie up to is `30 days`

, being this parameter configurable per network.
If the transaction duration is reached without being proved, the locked amount goes back to the initiator of the SecretLockTransaction.

**Version**: 0x01

**EntityType**: 0x4152

**Inlines**:

Property | Type | Description |
---|---|---|

secret | Hash256 | Proof hashed. |

mosaic | UnresolvedMosaic | Locked mosaic. |

duration | BlockDuration | Number of blocks for which a lock should be valid. 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

**Inlines**:

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.

**Did you find what you were looking for?**
Give us your feedback.