Whaleshares Logo

HTLC - What & How

ijmmaiwitnessPosted to Friends14 days ago6 min read


To be honest, when I saw the team get all excited about it, I had no idea what they were talking about. Had no clue why this was such a great feature to have. After testing HTLC with @pankso, I can see how it can help many people, but also discovered a flaw. Please read the whole post before using HTLC.

HTLC what is it?

HTLC stands for Hashed Time-Locked Contract. It is a time limited contract two parties agree on, by sharing a hashed secret phrase.


Jack wants to convert 1000 WLS into 50 BTS. Normally, he would transfer 1000 WLS from his Whaleshares account to Rudex and then sell it. Unfortunately for Jack, Rudex requirements and fees are pretty high, so he can't use that route.

On Discord, Pete mentions in general chat he wants to buy 1000 WLS and offers 50 BTS for it. He would normally also use Rudex, but experiences the same hurdles Jack experienced.

Now Jack has what Pete wants, and Pete has what Jack wants.
They should just trade, right?
But how can you trade safely? What if Jack sends his liquid WLS to Pete, and Pete doesn't send the BTS to Jack's bitshares account? Or the other way around?

Now that is where HTLC comes in. They don't send each other the crypto currency, they send it to a "contract". The contract will then, after receiving the agreed on crypto currencies from both parties, distribute the crypto currencies to each one.


Like I said I tested this with @pankso. There was some confusion, but in the end it worked. Let me walk you through step by step

I were to send WLS from my whaleshares account, to Pankso's Whaleshares account. He were to send BTS from his bitshares account, to my bitshares account. Although we never met in person, I trust him with my money, but for testing sake we used HTLC.

Step 1

Pankso started an HTLC contract on Bitshares ( couldn't find it in the menu but here is the link)


He filled out the receiver, the amount and the currency.
Then saved the two phrases.

The first one is called the preimage (the secret phrase), the second one the HASHED preimage (the public version of the secret phrase). That is what the H stands for in HTLC. The preimage and hashed preimage come in pairs, just like your private and public keys on Whaleshares do.

As you can see in the image, there is a fee charged by Bitshares for creating a HTLC.

Step 2

Pankso sent me the hashed preimage, but it also showed up in my Bitshares account

Then I created an HTLC in whaleshares wallet using that hashed preimage.
By using the same hashed preimage, the two parties are connected.

This contract shows up in Pankso's wallet in the HTLC - Received Htlcs section.

Step 3

In his wallet Pankso can now redeem the contract

  • From the Received Htlcs section he copies the contract ID
  • In the Redeem section he paste the contract ID and the preimage he saved when creating the contract on Bitshares

Step 4

Now that Pankso has used the secret phrase to redeem his side of the contract, the secret phrase is available to me too. I need to grab it from his redeem action in the explorer, and use that preimage to redeem my side of the contract on bitshares.

When you go to the explorer you will find an action similar to this one:

The preimage value is what I need, but there is a catch. The preimage value is in the wrong format. If you try to use this value on Bitshares it will not work. You can convert the value here. It will look like this:


Now all I have to do is go to my Bitshares wallet, find the contract on the HTLC page and click Redeem. The screen that pops up only needs the preimage in new format and two confirm clicks to bring this contract to a good end.


1 When you want to swap WLS for anything on Bitshares, the contract HAS TO START on Bitshares. Otherwise it won't work.

2 The contract is time-locked, this doesn't only mean the funds get returned when one of the parties doesn't create the other half of the contract, or when neither parties redeem. It also creates a risk.

When Jack starts a contract on Bitshares, and set it to 24 hours, the clock starts clicking right away. By the time the hashed preimage has been received by Pete, and Pete starts creating his side of the contract, a part of the 24 hours may already have passed. Let's say 1 hour has already passed.

If Pete also sets the time for the contract to 24 hours, it means that Pete only has 23 hours to redeem, and Jack still has 24 hours to redeem. Since Jack started the contract Pete can't do anything until Jack redeems his coins. In theory, Jack could wait till Pete's 23 hours run out, and then redeem. Jack would get his coins, and Pete would be unable to redeem.

In short, if you are the last one who creates the contract, with the hashed preimage of the first party, check how much time is left for you to redeem, and set the time on the contract a little less than that. Time is calculated in seconds.

3 There are no fees for the Whaleshares part, but Bitshares does charge a fee for creating the contract, and redeeming as well.

Use your witness votes wisely

Jump over to the Block Producer / Witness page and cast your witness votes. Simply click on the (^) up arrow next to the witness names of your choice (consider voting for "krazywitness" and "ijmmaiwitness") and supply your private active key to lock in your vote. Refresh the page in case your vote doesn't seem to stick.


Sort byOldest