bsips/bsip-0000.md

BSIP: xxxx
Title: Hashed Time-Locked 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 on the BitShares blockchain is a desirable feature that could be used by many persons, services, and businesses to mitigate risks between participants during asset transfer. 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 conditions, evaluations and transfers through the BitShares consensus protocol.

Rational

Elements of a Hashed Time-Locked Contract (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

  • Time lock

    • Timeout threshold (expiry)

• Condition Evaluators

• Fee

Parties

Two parties must be defined within each HTLC: the depositor and the recipient. The depositor will escrow their assets within the HTLC and designate the recipient to receive them. Note that a proposal transaction may be used for tasks such as multi-signature, but the end result at approval remains a single depositor and a single recipient.

Escrow Asset

An HTLC involves a conditional transfer of the defined asset symbol in the amount of assets quantity from the depositor to the recipient. The HTLC holds these 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 comprise both the preimage hash and length of the preimage, 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 specified 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 length of the preimage matches the specified preimage 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 fee for each operation is based on the standards set for blocks, and is similar to costs of other items stored on-chain.

TODO: Discuss fees may be variable, as it is possible to store a variable length preimage hash.

Existing Escrow Proposals

This 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 [cite] 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 within the BitShares protocol.

Set-Price Swap

Two parties may agree on a swap of two distinct escrow assets at a set price (defined exchange ratio), without using an exchange such as the BitShares DEX. This will require two (2) HTLC contracts containing the identical preimage hash within each to "link" them together and facilitate the execution of an "atomic swap" of these "locked" escrow assets between the party's accounts resulting in a trustless value exchange.

Business Approach

Alice begins by generating a distinct preimage of her choosing, notes the preimage length and calculates the preimage hash. She retains the preimage in secret, then creates a new HTLC stipulating that the depositor account "alice" will transfer quantity "100" "bitUSD" asset into the recipient account "bob" if a preimage is presented matching the preimage hash before the timelock threshold of 10AM tomorrow. Upon consensus validation of the HTLC, the 100 bitUSD escrow assets are transferred from Alice's depositor account into the HTLC where they remain locked by the preimage hash and timelock threshold. She then shares the resulting contract identifier with Bob.

Bob queries the blockchain for the contract identifier Alice provided. He examines to ensure it contains his desired recipient account, asset symbol, asset quantity, preimage length, and timelock threshold. Bob now creates his own HTLC that will deposit quantity "10,000" "BTS" symbol into the recipient account "alice" from depositor account "bob", if a preimage that generates the preimage hash Bob copied from Alice's HTLC before the timelock threshold of 5pm today. Upon consensus validation of Bob's HTLC, his 10,000 BTS escrow assets are transferred from his depositor account and "locked" into the contract. He then shares the resulting contract identifier with Alice. Notice Bob specified a timelock threshold much shorter than Alice defined in her contract. This ensures Bob will have enough time to observe and use the preimage Alice will publish to the blockchain next.

Alice now examines the HTLC Bob created, ensuring the preimage hash and preimage length both match the original values she used within her contract. She also verifies her desired recipient account "alice", the quantity, symbol, and the timelock threshold agree with her intentions. She now uses her preimage to "unlock" Bob's contract. Once consensus validation occurs, the HTLC will transfer the escrow assets 10,000 BTS into her recipient account "alice". This reveals the preimage on the BitShares blockchain for Bob to use next. NOTE: She must do this before 5PM. Otherwise, Bob may (and should) reclaim the funds in the contract he created.

Bob can now observe the preimage Alice used to "unlock" his HTLC, and he will use it to "unlock" her HTLC to receive the 100 bitUSD escrow assets into his recipient account "bob". NOTE: He must do this before 10AM tomorrow. Otherwise, Alice may (and should) reclaim the funds in the contract she created.

Cross-Chain Swap

Similar to the set-price swap mentioned above, two parties may exchange tokens between distinct blockchains when both implement HTLC support. Bitcoin, Litecoin and many others support HTLC [cite].

Business Approach

Alice and Bob intend to swap BTC (bitcoin token) and BTS (BitShares token). This will require both parties to define both a BTC deposit address and BTS deposit account. These addresses/accounts will be exchanged between the parties.

Alice will initiate the first leg of the swap on the BitShares Network with her HTLC and Bob will follow up on the Bitcoin Network with his HTLC. Allice generates a distinct preimage of her choosing, notes the preimage length and calculates the preimage hash. She retains the preimage in secret, then creates a new HTLC stipulating that the depositor account "alice" will transfer quantity "10,000" "bitUSD" asset into the recipient account "bob" if a preimage is presented matching the preimage hash before the timelock threshold of 10AM tomorrow. Upon consensus validation of the HTLC on the BitShares Network, the 10,000 bitUSD escrow assets are transferred from Alice's depositor account into the HTLC where they remain locked by the preimage hash and timelock threshold. She then shares the resulting contract identifier with Bob.

Bob queries the BitShares Network for the contract identifier Alice provided. He examines to ensure it contains his desired recipient account, asset symbol, asset quantity, preimage length, and timelock threshold. Bob now creates and funds his own HTLC on the Bitcoin Network that will spend the UTXO of this contract to the recipient address Alice provided during their setup phase, of amount 1 BTC if a preimage that generates the preimage hash Bob copied from Alice's HTLC before the timelock threshold of 5pm today. Upon consensus validation of Bob's HTLC on the Bitcoin Network, 1 BTC he controlled are spent into the contract and "locked". He then shares the resulting contract identifier with Alice. Notice Bob specified a timelock threshold much shorter than Alice defined in her contract. This ensures Bob will have enough time to observe and use the preimage Alice will publish to the blockchain next.

Alice now examines the HTLC Bob created on the Bitcoin Network, ensuring the preimage hash and preimage length both match the original values she used within her contract. She also verifies her desired recipient address, quantity, and timelock threshold agree with her intentions. She now uses her preimage to "unlock" Bob's contract. Once consensus validation occurs on the Bitcoin Network, the HTLC will spend 1 BTC to Alice's recipient address. This reveals the preimage on the Bitcoin Network for Bob to use next. NOTE: She must do this before 5PM. Otherwise, Bob may (and should) reclaim the funds in the contract he created.

Bob has now observed the preimage Alice used to "unlock" his HTLC, and he will use it to "unlock" her HTLC to receive the 10,000 bitUSD escrow assets into his recipient account "bob". 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