BEP3: HTLC and Atomic Peg
This BEP is about introducing Hash Timer Locked Contract functions and further mechanism to handle inter-blockchain tokens peg.
HTLC has been used for Atomic Swap and cross payment channel for a few years on Bitcoin and its variant blockchains, and also Ethereum. This BEP defines native transactions to support HTLC on Binance Chain, and also proposes the standard infrastructure and procedure to use HTLC for inter-chain atomic swap to easily create and use pegged token, which is called
This BEP is under implementation.
Binance Chain serves fast transferring transactions and also high capacity asset Exchange, which have benefits a lot assets issues on it. However, there are major cases Binance Chain itself cannot satisfy:
- Assets have complicated token economies themselves, such as DeFi.
- Assets serve as native tokens on other blockchain.
For these tokens, the best way to use Binance Chain is to spread the tokens on multiple chains. One can issue or peg part of total token supply on Binance Chain to enjoy the speed, fast finality and powerful exchange, meanwhile keep other benefit and necessity on other chains. Many new requirements are imposed for such model:
- there should be an easy way for users to swap unidirectionally or bidirectionally between Binance Chain and the other chain, better in a trustless way;
- there should be restrictions and/or transparency to ensure the total supply of tokens remained the same, and no one, even the issuer cannot freely change the circulation at will;
- there should be an easy way to calculate how many tokens are in circulation on each chain of both sides.
Here new transaction and logics are required on Binance Chain, as it doesn’t support Smart Contract. Also a standard infrastructure and procedure should be proposed and used as best practice for such inter-chain communications.
The BEP is to tackle the problem, and try to pave the broadway for a practical cross chain solution to empower the decentralized economy with Binance DEX.
Atomic Peg Swap
The primary purpose of HTLC in Binance Chain is to support Atomic Peg Swap (APS). APS is proposed here as the standard way for asset/token issuers to peg or migrate part of the asset/token onto Binance Chain, so that users of the tokens can enjoy the fast transactions and pleasant trading experience.
APS is designed to support peg token from any EVM based blockchain or any one with full smart contract features. Here in order to simplify the description, Ethereum is used as the most typical example.
- Client: users who want to swap tokens from Ethereum to Binance Chain, or the other way round. Client address on Binance chain is called CB in the following sections;
- Owner: the issuers or anyone who want to peg the tokens from Ethereum to Binance Chain. In most cases, the Owner should be the issuer of the token. There expects one or multiple Owners to provide some service for one blockchain/project, depending on the size of the blockchain/project. Pegged Token Owner address on Binance chain is called OB in the following sections
- New transaction types on Binance Chain: HTLT and CHLT transactions are used to lock and claim the asset to swap. The details are covered in the following section.
- Swap smart contracts on Ethereum: the APS contract are used to lock and claim the asset to swap too. The function should be similar to the new transaction types on Binance Chain. The details of interface covered in the following section.
- Deputy process: an application run and maintained by Owner to facilitate the automatic and continuous swap activity.
- Client tooling: wallets or other tools that help Clients to monitor the blockchains to complete the claim (and maybe the lock as well).
- Owner should issue proper number of tokens on Binance Chain as the Pegged
- Owner should create one address on Binance Chain, and transfer in enough number of tokens for swap
- Owner should deploy the APS Ethereum smart contract on Ethereum, and deposit enough number of tokens for swap into a dedicated address (which both should be public announced).
- Client should have an address on both Binance Chain and Ethereum.
- For such swap, Owner should publish all their Binance Chain and APS contract address, and also the expected minimum time span, MinLockTime.
Usage Expectation and Benefits
- It is expected that each issuer of the pegged token should set up their own Deputy Process, or rely on 3rd party custodian service providers to manage one.
- Via the public balance of OB and APS contract, everyone can check the total pegged token swapped, and ensure the total supply stays clear in the same way as if the token is not pegged
- Client gets guarantee on their fund safety. They don’t need to worry too much about the availability of the Deputy process, or any cheat from issuers or swap service providers.
- It is possible for one set of infrastructure to handle swap for multiple tokens.
Client Swap Tokens from Ethereum to Binance Chain
- Client calls APS contract, with the hash of a secret, X tokens and a time span T parameters, to express his/her interest to swap X tokens. If the parameters are good (e.g. T>MinLockTime, enough tokens to swap), the call transaction is recorded on the blockchain.
- Deputy process monitors the events of the APS contract on Ethereum. If it detects the client’s call and verify good, it will sign and broadcast the HTLT transaction on Binance Chain. This will lock X (or more as bonus) number of pegged tokens on Binance Chain. Please note the time span used in this HTLT transaction should be smaller enough than T in Client’s APS call.
- Client or Client tooling monitors any transactions onto CB, if it is from OB and has the proper hash, Client or Client tooling should broadcast CHLT transaction to claim his/her requested Pegged tokens by disclosing the random number generating the hash. Binance Chain will verify the random number, if it matches the hash, it will release the locked Pegged tokens to Client address CB.
- Deputy process monitors the transactions onto OB. If there is a success CHLT, it will read the value of the random number Client disclosed, and call APS contract to claim the locked tokens by Client.
Client Swap Tokens from Binance to Ethereum
- Client sends HTLT transaction to Owner address OB with the hash of a secret, X tokens and a time span T parameters, to express his/her interest to swap X tokens. If the parameter is good, the transaction will be recorded on Binance Chain.
- Deputy Process monitors the transactions onto OB. If there is a success HTLT, it will double verify the transaction parameters (e.g. T>MinLockTime, enough tokens to swap). If all are good, it will call the APS contract on Ethereum to lock X number of tokens on Ethereum with the hash with shorter time span, expecting to be unlocked by Client address CE.
- Client or Client tooling monitors events of the APS contract on Ethereum. If it detects Deputy process’s call, it will verify and call the APS contract to claim the tokens by disclosing the random number generating the hash.
- Deputy process monitors the events from APS contract. If there is a successful claim, it will read the value of the random number Client disclosed and broadcast a CHLT transaction to claim the locked tokens by the Client via the HTLT.
Swap between several BEP2 tokens
In the following scenarios, client will need swap between several BEP2 tokens:
- Users want to swap assets that are not listed on Binance DEX.
- Users want to swap several assets with several others at the same time.
For instance, suppose a client has some
BNB token and want to swap some other BEP2 tokens which are not listed on Binance Dex, like
- Client send a HTLT transaction to an deputy address who has
DEF. In the HTLT transaction, the client locks some
BNBand expresses his expected gained
DEFamount, for example:
- Deputy process filter out the HTLT transactions in which the
toequal to deputy address and the swap ratio is reasonalbe. Then the deputy send
Deposit HTLTtransaction to lock some
DEFunder the same hash timer lock.
- Client or client tooling monitors deposit HTLT transactions. If the locked
DEFis acceptable, the client claim the HTLT with correct random number. Then the client will get locked
DEF, and the deputy will get locked
- If the locked
DEFis not acceptable for the client, the client can refuse to claim the HTLT and just refund the HTLT after expired height(Anyone can refund the HTLT after expired height). In this situation, locked
BNBwill be back to client address and the locked
DEFwill be back to deputy address.
Client Tooling is the part to help user experience. While the most commonly used tools are wallets, command line interfaces and programming SDKs, wallets are the most critical part. The wallet is expected to handle the below part to facilitate the swap, which can be challenging to the existing wallets to call the specific smart contract.
- start the request of Atomic Peg on either chain of the two, which means sign and broadcast specific transactions, or trigger smart contract with parameters;
- monitor the blockchain and automatically claim the swapped token (or automatically trigger the refund after the timeout on Ethereum and other blockchains).
- if the wallet supports multiple blockchain, e.g. both Binance Chain and Ethereum, it will be super convenient for Client to complete the whole swap process within the wallet.
New Transaction Types on Binance Chain
The below are the details for HTLT, deposit HTLT, claim HTLT and refund HTLT.
Hash Timer Locked Transfer
Hash Timer Locked Transfer (HTLT) is a new transaction type on Binance Chain, to serve as HTLC in the first step of Atomic Swap, with parameters defined as below:
|From||Address||Sender address, where the asset is from||No|
|To||Address||Receiver address, where the asset is to, if the proper condition meets.||No|
|RecipientOtherChain||bytes||a byte array, maximum 32 bytes, in any proper encoding||Yes|
|SenderOtherChain||bytes||a byte array, maximum 32 bytes, in any proper encoding||Yes|
|RandomNumberHash||32 bytes||hash of a random number and timestamp, based on SHA256||No|
|Timestamp||int64||Supposed to be the time of sending transaction, counted by second. It should be identical to the one in swap contract||No|
|OutAmount||Coins||similar to the Coins in the original Transfer defined in BEP2, assets to swap out||No|
|ExpectedIncome||string||expected gained token on the other chain, like 1000:eth||No|
|HeightSpan||int64||number of blocks to wait before the asset may be returned to From if not claimed via Random. The number must be larger than or equal to 360 (>2 minutes), and smaller than 518400 (< 48 hours)||No|
|CrossChain||bool||Specify if the HTLT is for cross chain atomic swap||No|
Before the above
To claims the transferred Coins with the correct random number that can generate the same Random Hash, the Coins will not appear as balance on
To address. The transaction is signed by private key for
CrossChain is false, then this HTLT is for single chain atomic swap which mean we can use it to swap two BEP2 tokens.
HTLT transaction is done, an atomic swap will be created and the
SwapID will be returned in the response.
SwapID equals to
sha256(swap.randomNumberHash, swap.From, swap.SenderOtherChain), If the swap is not a response to another swap on other chain,
SenderOtherChain should be nil.
Deposit Hash Timer Locked Transfer is to lock new BEP2 asset to an existed HTLT which is for single chain atomic swap.
|From||Address||Sender address, where the assets are from||No|
|OutAmount||Coins||similar to the Coins in the original transfer defined in BEP2, assets to swap out||No|
Claim Hash Timer Locked Transfer is to claim the locked asset by showing the random number value that matches the hash. Each HTLT locked asset is guaranteed to be release once.
|RandomNumber||32 bytes||random number||No|
Refund Hash Timer Locked Transfer is to refund the locked asset after timelock is expired.
APS Smart Contract Interface for Other Blockchain
- function htlt(bytes32 _randomNumberHash, uint64 _timestamp, uint256 _heightSpan, address _receiverAddr, bytes20 _bep2SwapSender, bytes20 _bep2Addr, uint256 _outAmount, uint256 _bep2Amount)
_timestampis supposed to be the time of sending transaction, counted by second. If this htlt is response to another htlt on other chain, then their timestamp should be identical.
_heightSpanis the number of blocks to wait before the asset can be refunded
_receiverAddris the Ethereum address of swap counter party
_bep2Senderthe swap sender address on Binance Chain
_bep2Recipientis the recipient address on Binance Chain.
_outAmountis the swapped out ERC20 token.
_bep2Amountis the expected received BEP2 token on Binance Chain.
- function refund(bytes32 _swapID)
sha256(swap.randomNumberHash, swap.From, swap.SenderOtherChain)
- function claim(bytes32 _swapID, bytes32 _randomNumber)
sha256(swap.randomNumberHash, swap.From, swap.SenderOtherChain)
_randomNumberis a random 32-length byte array. Client must keep it private strictly.
- function isSwapExist(bytes32 _swapID) returns (bool)
- function refundable(bytes32 _swapID) returns (bool)
- function claimable(bytes32 _swapID) returns (bool)
- function queryOpenSwap(bytes32 _swapID) returns (bytes32 _randomNumberHash, uint64 _timestamp, uint256 _expireHeight, uint256 _outAmount, address _sender, address _recipient)
- event HTLT(address indexed _msgSender, address indexed _recipientAddr, bytes32 indexed _swapID, bytes32 _randomNumberHash, uint64 _timestamp, bytes20 _bep2Addr, uint256 _index, uint256 _expireHeight, uint256 _outAmount, uint256 _bep2Amount);
- event Refunded(address indexed _msgSender, address indexed _recipientAddr, bytes32 indexed _swapID, bytes32 _randomNumberHash);
- event Claimed(address indexed _msgSender, address indexed _recipientAddr, bytes32 indexed _swapID, bytes32 _randomNumberHash, bytes32 _randomNumber);
The content is licensed under CC0.