Using a secret lock transaction for an atomic cross-chain swap - NEM Catapult 101


@gimer shared a very interesting forum post on the JP side of Catapult demonstrating the use of the new secret lock transaction for an atomic, cross-chain swap:

I found this quite interesting. I found it even interesting that there weren’t many posts in this forum. In response to that I have decided to start a series of posts called Catapult 101, where I break down various Catapult concepts for the layman to understand :slight_smile:

I don’t only want to discuss it, but demonstrate it using NEM2.

Here is the first installment from the aforementioned article, in proper English so we can discuss it!

Thanks to @memario for clearing up a few things that were misrepresented in this article :slight_smile:

Using secret lock transactions for atomic cross-chain swap.


Suppose you have two different MIJIN_TEST chains. A "Public Chain" (i.e NEM) and a "Private Chain" (i.e crackTheCode Chain), respectively. Let's refer to the private chain as `A` and the public chain as `B`

Bob wants to send XEM to Alice from her A chain, and Alice wants to send Bob a mosaic from his B chain.

In short, they want to perform a cross-chain transaction, exchanging XEM for a mosaic (or vice versa)

Now, if Alice and Bob both trust each other with no problems, then they can simply peform a transfer transaction on each chain.

In our scenario, however, they don’t trust each other. This is where secret lock transactions come into play!

Secret lock and proof transactions

This is where the secret lock and proof transactions come into play in a trustless environment as stated here, where mosaics are locked, or unlocked, with a secret value only shared between Bob and Alice.

There is no trust because Bob could take off with Alice’s mosaic without sending his. The secret transaction essentially holds it in escrow until both secrets are entered in their respective chains. If the secret is never entered, the funds get returned to their owners.

Like a transfer transaction, a secret lock transaction can send mosaics. The difference, however, is that it has to be unlocked via a secret proof transaction.

A secret lock transaction has a hash of a secret value embedded within it, similar to a message. If you can prove that you know the secret value via a secret proof transaction, you can receive the mosaic being sent.

It requires the common secret shared between the two parties (Bob and Alice) to unlock.

Here is how an atomic transfer might go:

  • Alice creates a secret lock transaction on the private chain that sends a mosaic to Bob’s address. A secret is included in this transaction

  • Bob receives the transaction and the secret. He now announces a secret lock transaction with XEM with on the public chain. This transaction uses the same secret that Alice sent to him.

  • Now that we have a secret lock transaction on each network, they must be proven by each party. Alice sends a secret proof transaction to Bob on the public network where she wants to receive her XEM. Bob does the same on the private network where he wants Alice’s mosaic. Once this occurs, and everyone has sent their transactions in due time and nothing has timed out, the transaction is concluded!

  • With the transaction concluded, Alice has her XEM on the public chain and Bob has his mosaic on the private chain!

As you can see, this type of cross-chain exchange is possible. In total four transactions are required to make this transfer. Secret lock transactions help to avoid fraud if one or more parties do not trust each other.

The possibilities - not just currency exchange

While here a cross-chain exchange was performed, this method can be used to communicate between chains through sending messages, or even for holding funds in escrow between a private chain and public NEM chain for a house purchase until the deal is closed! There are many ways this can be utilized :smile:

Now see how you can try it out yourself!
Coming soon

NEM Community fund for little projects

Hi, is atomic transfer requires secret lock transaction or a simple aggregate transaction is more than enough… As per catapult doc, aggregate transaction is used for atomic swaps… Could you please clarify


aggregate is only good on the same chain. You need the secret lock for x-chain tx.


Ok… But in that case other chain say ethereum should also have similar functionality for this transaction to succeed… Right??


Most chains do. In Eth you’d probably have to write a smart contract.
All you really need is a way to lock funds until a certain secret is revealed.


@crackTheCode Great idea to start doing Catapult 101 series of post! I like how you explained the guide and @planethouki figures.

We could add value to the current docs as well while creating this series of post. nem2-docs is open-source and can be improved a lot from the community.

Current guide:



Thank you! I thought it would be a good thing to do for the community and for myself! @planethouki did an amazing job explaining this.

I am writing up this code example only with more screenshots so even a beginner developer can try this out. Good to know the docs are open-source! I would love to improve parts of it as I learn :slight_smile:


Thank you for explaining that :+1:


The last part in the documentation (Is it atomic) is somewhat confusing:

Alice signs and announces Tx3, receiving Bob’s funds. Bob will have time 
to sign Tx4, as Tx1 validity is longer than Tx2.Alice signs and announces 
Tx3, receiving Bob’s funds. Bob will have time to sign Tx4, as Tx1 validity 
is longer than Tx2.

With this description, I understand that Alice gets Bob’s funds as soon as she sends Tx3. Which leads to non-atomicity as she could have given a false proof value to Bob, which then would never get his funds. I suppose the wording in that part that can be improved. My understanding was that Alice and Bob get their respective funds once both Tx3 and Tx4 are signed. Can someone confirm?


Alice announced Tx3, so Bob can check in the private network the transaction and get the secret.

Bob, or any other person, even Alice, can unlock Tx2 funds by sending Tx4. It doesn’t matter who sends the last secret proof transaction, the funds will be transfered to Bob, as defined in Tx1.

It will be even more evident if Bob started the atomic swap, and Tx3 is announced to the public network instead, ensuring the secret it is visible to everyone.


From the links I assume, two transactions are independent per se it is the users/actors in this case Alice and Bob make it an atomic swap… Is my assumption correct??


Yes, pretty sure you are.


Now that I’ve actually read your documentation (lol, sorry) I don’t think it’s entirely correct.
You make it sound like Alice and Bob create different secrets which I don’t think is the case.

The docmentation uses poor nomenclature as the secret isn’t actually secret but the proof is. I’m going to stick to calling what’s secret, secret and use the word proof for the process of revealing that secret.

Alice or Bob can create a screet and then lock funds with the hashed secret.
Then the other party locks their funds with that same hash (which they got from the original tx).
At this point only the party that created the original (unhashed) secret can unlock their funds but they can’t do that without revealing that secret to the other party (via the proof-tx). So once they do, the other party can also claim their funds. If the original party does not claim their funds the lock times-out and everyone get’s their stuff back.

If they did it like you’re suggesting then they’d have a big problem: Who sends the proof first and how do you guarantee that the other party plays along ? You write:

They send each other the secrets required to unlock the funds.

That’s the whole problem that this is trying to solve and if they create seperate secret’s it isn’t being solved. Does Bob send first or Alice ? What if the other party doesn’t send their’s in return ?


Thank you for that, yes I believe I did misrepresent it by saying two secrets are involved, In reality, just one is and is used throughout the entire transaction. I have made an edit, please let me know if you have any problems with it, thanks!


nice sharing!!