176 lines
11 KiB
Markdown
176 lines
11 KiB
Markdown
BSIP: xxxx\
|
|
Title: Hashed Time-Lock Contract\
|
|
Authors: John M. Jones, Ryan R. Fox, taconator\
|
|
Status: Draft\
|
|
Type: Informational\
|
|
Created: 2018-08-22\
|
|
Discussion: TBD\
|
|
|
|
# **Abstract**
|
|
|
|
This BSIP describes an implementation of a Hashed Time-Locked Contract (HTLC) operation.
|
|
|
|
# **Motivation**
|
|
|
|
The ability to securely hold tokenized assets within a Hashed Time-Locked Contract (HTLC) on the BitShares blockchain is a desirable feature that could be used by many persons, services, and businesses to mitigate risks between participants. HTLC implement conditional transfers, whereby a designated party (the "recipient") will reveal the preimage of a hash in order to execute the asset transfers from a second party (the "depositor"), else after time lock expiry "depositor" may retrieve their assets. No third-party escrow agent is required, rather the HTLC operation enforces execution through the BitShares consensus protocol.
|
|
|
|
# **Rational**
|
|
|
|
## **Elements of an HTLC**
|
|
|
|
An HTLC is defined to have the following components:
|
|
|
|
* Parties to the HTLC
|
|
|
|
* The depositor
|
|
|
|
* The recipient
|
|
|
|
* Escrow Asset
|
|
|
|
* Asset symbol
|
|
|
|
* Asset quantity
|
|
|
|
* Conditions
|
|
|
|
* Hash lock
|
|
|
|
* Preimage (the secret)
|
|
|
|
* Preimage hash (hash of the preimage)
|
|
|
|
* Length of the preimage hash
|
|
|
|
* Time lock
|
|
|
|
* Timeout threshold (expiry)
|
|
|
|
* Condition Evaluators
|
|
|
|
* Fee
|
|
|
|
### **Parties**
|
|
|
|
Two parties must be defined for an HTLC: one `depositor`, and one `recipient`. Note that a proposal transaction may be used for tasks such as multi-signature, but the end result at approval is still one `depositor` and one `recipient`.
|
|
|
|
### **Escrow Asset**
|
|
|
|
An HTLC involves a conditional transfer of ownership of a `quantity` of an `asset` from a designated party (the "`depositor`") to the second party (the "`recipient`"). The HTLC holds the designated `escrow assets` from `depositor` on the blockchain and will continue to enforce the specified `conditions` until one is satisfied.
|
|
|
|
### **Conditions**
|
|
|
|
There are two competing conditions within an HTLC, the `hash lock` and the `time lock`.
|
|
|
|
The HTLC contains a `hash lock` condition, which are both the `preimage hash` and its `length`, barring the transfer of held `escrow assets` unless satisfied. If a `preimage` of requisite `length` is provided to the HTLC which generates a hash matching the `preimage hash`, the `preimage` is then stored within the blockchain, and the `escrow assets` are transferred to the `recipient`.
|
|
|
|
If a satisfactory `preimage` is not provided to the HTLC before the stipulated `time lock` expires, the `depositor` may request the return of `escrow assets`. The HTLC will only evaluate transfer request from `depositor` and after `timeout threshold`, then return `escrow assets` to `depositor`.
|
|
|
|
### **Condition Evaluators**
|
|
|
|
The `preimage` can be thought of a secret key, that will eventually be shared with the `recipient`. This can be a word, a phrase, or even a random series of bytes. The `length` of the `preimage` must be shared and stored within the HTLC at creation.
|
|
|
|
Upon presentation of a `preimage`, the HTLC `condition evaluator` validates:
|
|
|
|
1. That the `timeout threshold` has not yet occurred.
|
|
|
|
2. That the `preimage length` matches the specified `length`.
|
|
|
|
3. That the `hash of the preimage` matches the specified `preimage hash`.
|
|
|
|
If all evaluations succeed, the `escrow assets` are transferred to the `recipient`. If any evaluation fails, nothing happens; the HTLC remains ready to evaluate the next `preimage`.
|
|
|
|
Upon presentation of a request from the `depositor` for return of `escrow assets`, the HTLC `condition evaluator` validates that the `timeout threshold` is now in the past. It then returns the `escrow assts` to `depositor`.
|
|
|
|
### **Timing of Condition Evaluation**
|
|
|
|
The `timeout threshold` of the contract is defined by `depositor` within the HTLC at creation. It can be any time in the future and should allow enough time for `recipient` to review the HTLC and provide the `preimage`. Further, it should not be set too far into the future to mitigate against an unresponsive `recipient` impacting `depositor`, as their `escrow assets` will be locked until `timeout threshold` expiry. The accuracy is based on when the `condition evaluator` runs, and should be considered accurate ± 15 seconds.
|
|
|
|
### **Early Termination of an Escrow Contract**
|
|
|
|
To protect the `recipient`, early termination of an HTLC is not allowed by any party. Placing a `timeout threshold` far into the future is valid. User protection from locking up funds for an extremely long period could be provided by the UI used to create the HTLC.
|
|
|
|
**TODO:** Consider adding an `Update_HTLC` operation to allow `depositor` to extend the `timeout threshold`
|
|
|
|
### **Automatic Transfers Upon Expiry**
|
|
|
|
Upon expiry of the `timeout threshold`, the `escrow assets` held within the HTLC will **not** automatically be returned to `depositor`. A separate transaction must be initiated by the `depositor` to request `escrow assets` be transferred to `depositor`.
|
|
|
|
Code _could_ be added to automate the return of funds. This could be part of block production or maintenance. However, this will cause extra load on those processes. Hence, it is felt that requiring action by the `depositor` is the best option.
|
|
|
|
### **Fee**
|
|
|
|
Creating and fulfillment are two operations that add data to the blockchain. The fees for these operations are based on the standards set for blocks, and are similar to costs of other items stored on-chain.
|
|
|
|
**TODO:** Discuss fees may be variable it is possible to store variable length preimage hash.
|
|
|
|
## **Existing Escrow Proposals**
|
|
|
|
The section describes various escrow concepts that have been proposed either for BitShares or for other blockchains or services in terms of the elements that have been defined above. This is intended to provide some background and comparison to the concepts that follow.
|
|
|
|
**TODO:** Elaborate Interledger
|
|
|
|
## **Existing Graphene Features that are Similar to What is Needed for Blockchain Escrowing**
|
|
|
|
### **BitShares Escrow**
|
|
|
|
A separate BSIP is currently being discussed that provides a more traditional escrow service. This involves parties, agents, and a more complex evaluation. HTLC shares some similarities, and could be considered a thin subset of Bitshares Escrow.
|
|
|
|
The smaller, well-defined nature of HTLC provides a major advantage for applications that want to attempt tasks such as cross chain atomic swaps.
|
|
|
|
### **BitShares Multi-Signature Account**
|
|
|
|
One of the existing features of BitShares is the ability to have an account that requires multiples signatures by differently authorized parties [cite] and even hierarchical authorizations. Using this mechanism as a form of escrow is possible. But there are many limitations. More information on escrow and multi-signatures can be found in the BitShares Escrow BSIP.
|
|
|
|
### **BitShares Proposals**
|
|
|
|
One of the existing features of BitShares is the ability to have a proposal that is recorded on the blockchain and awaits the authorization of the requisite parties (e.g. M-of-N signatures). If the required authorizations are not given by the proposal expiry then no transfer will occur. This feature also contains many limitations when compared to HTLC.
|
|
|
|
# **Specifications**
|
|
|
|
## **Possible Concepts to Implement**
|
|
|
|
The following will describe possible concepts that could be implemented in BitShares.
|
|
|
|
### **Set-Price Swap**
|
|
|
|
Two parties may agree on an asset swap at a set price, without using the exchange. Two HTLC contracts with the same hash can provide a trustless exchange of assets
|
|
|
|
#### **Business Approach**
|
|
|
|
Party A (Alice) generates an HTLC with a preimage of her choice. The contract stipulates that she will deposit 100 bitUSD into the account of Party B (Bob), if he provides the preimage that generates the stored hash before 10AM tomorrow. She then shares the contract identifier with Bob.
|
|
|
|
Bob examines the contract Alice created, being sure to examine that the receiving account, the amount, and the timeout agrees with his desires. He then generates another HTLC that will deposit 10,000 bitshares into the account of Alice, if she provides the preimage that generates the same hash before 5pm today. He then shares the contract identifier with Alice.
|
|
|
|
Alice now examines the contract Bob created, being sure to examine that the receiving account, the amount, and the timeout agrees with her desires. She also verifies that the hash matches the hash of her contract. She now uses her preimage to "unlock" Bob's contract, which puts 10,000 bitshares into her account. This also posts the preimage on the BitShares blockchain. NOTE: She must do this before 5PM. Otherwise, Bob may (and should) reclaim the funds in the contract he created.
|
|
|
|
Bob can now see the preimage that Alice used to receive her bitshares, and he can use the same preimage to "unlock" the contract Alice created, and receive the 100 bitUSD. NOTE: He must do this before 10AM tomorrow. Otherwise, Alice may (and should) reclaim the funds in the contract she created.
|
|
|
|
### **Cross-Chain Swap**
|
|
|
|
The set-price swap mentioned above works the same across chains that support HTLC. Bitcoin, as an example, supports HTLC.
|
|
|
|
#### **Business Approach**
|
|
|
|
Alice generates an HTLC on the BitShares blockchain with a preimage of her choice. The contract stipulates that she will deposit 1 bitBTC into the account of Bob, if he provides the preimage that generates the stored hash before 10AM tomorrow. She then shares the contract identifier with Bob.
|
|
|
|
Bob examines the contract Alice created, being sure to examine that the receiving account, the amount, and the timeout agrees with his desires. He then generates an HTLC that will deposit 1 BTC into the Bitcoin address of Alice, if she provides the preimage that generates the same hash before 5pm today. He then shares the Bitcoin transaction identifier with Alice.
|
|
|
|
Alice now examines the contract Bob created, being sure to examine that the receiving account, the amount, and the timeout agrees with her desires. She also verifies that the hash matches the hash of her contract. She now uses her preimage to "unlock" Bob's contract, which puts 1 BTC into her Bitcoin wallet. This also posts the preimage on the Bitcoin blockchain. NOTE: She must do this before 5PM. Otherwise, Bob may (and should) reclaim the funds in the contract he created.
|
|
|
|
Bob can now see the preimage that Alice used to receive her Bitcoin, and he can use the same preimage to "unlock" the contract Alice created, and receive the 1 bitBTC. NOTE: He must do this before 10AM tomorrow. Otherwise, Alice may (and should) reclaim the funds in the contract she created.
|
|
|
|
# **Discussion**
|
|
|
|
# **Summary for Shareholders**
|
|
|
|
TBD
|
|
|
|
# **Copyright**
|
|
|
|
This document is placed in the public domain.
|
|
|
|
# **See Also**
|
|
|
|
A description of [Hashed Timelock Contracts](https://en.bitcoinwiki.org/wiki/Hashed_Timelock_Contracts)
|