Skip to content

grammar fixes BSIP 44 (HTLC) #112

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ryanRfox merged 7 commits into from
Jan 8, 2019
Merged

grammar fixes BSIP 44 (HTLC) #112

Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
6dda715
grammar fixes
jmjatlanta Oct 12, 2018
6efbbc2
Added some parameter limits
jmjatlanta Oct 15, 2018
57f21fa
Re-added committee parameters
jmjatlanta Oct 15, 2018
bb00710
Updated to match implementation more closely
jmjatlanta Jan 3, 2019
cf4206d
punctuation fixes and clarifications
jmjatlanta Jan 7, 2019
9664001
added comments about htlc_hash algos
jmjatlanta Jan 7, 2019
6f72b4b
better spacing in comments
jmjatlanta Jan 7, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 42 additions & 36 deletions bsip-0044.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,9 +70,9 @@ There are two competing conditions within an HTLC, the `hash lock` and the `time

The HTLC contains a `hash lock` condition, which comprise both the `preimage hash` and `preimage length`, barring the transfer of held `secured 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 `secured 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 `secured assets`. The HTLC will only evaluate transfer request from `depositor` and after `timeout threshold`, then return `secured assets` to `depositor`.
If a satisfactory `preimage` is not provided to the HTLC before the stipulated `time lock` expires, the HTLC will then return `secured assets` to `depositor`.

**Note:** we recommend the Committee the set maximum allowable `preimage length` to ensure unreasonably large submissions are rejected.
**Note:** we recommend the Committee set maximum allowable `preimage length` to ensure unreasonably large submissions are rejected.

### **Condition Evaluators**

Expand Down Expand Up @@ -100,7 +100,7 @@ To protect the `recipient`, early termination of an HTLC is not allowed by any p

### **Automatic Transfers Upon Expiry**

Upon expiry of the `timeout threshold`, the `secured assets` held within the HTLC will be queued for return to `depositor`. From this time, the HTLC will no longer evaluate the `hash lock`, preventing `recipient` from receiving the `secured assets`. No action is required by the `depositor` to receive their "locked" funds back from the contract after expiry.
Upon expiry of the `timeout threshold`, the `secured assets` held within the HTLC will be returned to `depositor`. From this time, the HTLC will no longer evaluate the `hash lock`, preventing `recipient` from receiving the `secured assets`. No action is required by the `depositor` to receive their "locked" funds back from the contract after expiry.

### **Fees**

Expand Down Expand Up @@ -172,80 +172,86 @@ Bob has now observed the `preimage` Alice used to "unlock" his HTLC, and he will
## **Objects**

```
class htlc_object : public graphene::db::abstract_object<htlc_object> {
public:
static const uint8_t space_id = implementation_ids;
static const uint8_t type_id = impl_htlc_object_type;

account_id_type depositor;
account_id_type recipient;
asset amount;
fc::time_point_sec expiration;
asset pending_fee;
vector<unsigned char> preimage_hash;
uint16_t preimage_size;
transaction_id_type preimage_tx_id;
};
typedef fc::static_variant<
htlc_algo_ripemd160,
htlc_algo_sha1,
htlc_algo_sha256
Copy link
Copy Markdown
Contributor

@pmconrad pmconrad Jan 7, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now you should mention what these three new types are... :-)

Copy link
Copy Markdown
Contributor Author

@jmjatlanta jmjatlanta Jan 7, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you think it best to put it in a descriptive note below this section or a //comment on each line? I'll give //comment a try.

> htlc_hash;

class htlc_object : public graphene::db::abstract_object<htlc_object> {
public:
static const uint8_t space_id = implementation_ids;
static const uint8_t type_id = impl_htlc_object_type;

account_id_type from;
account_id_type to;
asset amount;
fc::time_point_sec expiration;
htlc_hash preimage_hash;
Copy link
Copy Markdown
Contributor

@pmconrad pmconrad Jan 7, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

need to define htlc_hash type if you mention it here

uint16_t preimage_size;
};
```

Note 1: The preimage size must be less than the maximum number of bytes as specified by the committee.

Note 2: The initial HTLC expiration can not be more than the maximum amount of time as specified by the committee. This can be extened, but not for more than the amount of time of (extension time + maximum amount of time as specified by the committee).

## **Operations**

### **Prepare**

```
transaction_obj htlc_prepare(depositor, quantity, symbol, recipient, hash_algorithm, preimage_hash, preimage_length, timeout_threshold, htlc_preparation_fee)
Validate: HTLC signed by requisite `authority` for `depositor` account
Validate: `depositor` account has requisite `quantity` of `symbol` asset for the `guarantee`
transaction_obj htlc_create(from, to, quantity, symbol, hash_algorithm, preimage_hash, preimage_length, timeout_threshold, broadcast)
Validate: HTLC signed by requisite `authority` for `from` account
Validate: `from` account has requisite `quantity` of `symbol` asset for the `guarantee`
Validate: `timeout_threshold` < now() + GRAPHENE_HTLC_MAXIMUM_DURRATION
Calculate: `required_fee` = GRAPHENE_HTLC_OPERATION_FEE + GRAPHENE_HTLC_DAILY_FEE * count((`timeout_threshold` - now()), days)
Validate: `depositor` account has requisite `quantity` of BTS for `required_fee`
Validate: `recipient` account exists
Validate: `from` account has requisite `quantity` of BTS for `required_fee`
Validate: `to` account exists
Validate: `preimage_length` does not exceed GRAPHENE_HTLC_MAXIMUM_PREIMAGE_LENGTH
Validate: `preimage_hash` well formed
Update: BTS balance of `depositor` based on `required_fee`)
contract = new htlc_obj
Set: `contract.depositor` = `depositor`
Set: `contract.recipient` = `recipient`
Set: `contract.from` = `from`
Set: `contract.to` = `to`
Set: `contract.hash_algorithm` = `hash_algorithm`
Set: `contract.preimage_hash` = `preimage_hash`
Set: `contract.preimage_length` = `preimage_length`
Set: `contract.timeout_treshold` = `timeout_threshold`
Transfer: from `depositor` account to `contract.quantity` of `contract.symbol`
Transfer: remove `contract.quantity` of `contract.symbol` from `from` account
return results
```

### **Redeem**

```
transaction_obj htlc_redeem(fee_paying_account, id, preimage, htlc_redemption_fee)
Validate: transaction signed by requisite `authority` for `fee_paying_account` // any account may attempt to redeem
transaction_obj htlc_redeem(id, issuer, preimage, broadcast)
Validate: transaction signed by requisite `authority` for `issuer` // NOTE: any account may attempt to redeem
Get: get_htlc(id)
Validate: `fee_paying_account` account has requisite `quantity` of BTS for `htlc_redeem_fee` and `htlc_kb_fee`
Update: balance of `fee_paying_account` based on total fees
Validate: `issuer` account has requisite `quantity` of BTS for `htlc_redeem_fee` and `htlc_kb_fee`
// Evaluate: timelock
if now() < `timeout_threshold` then return error // "timeout exceeded"
// Evaluate: hashlock
if length(preimage) != `id.preimage_length` then return error // "preimage length mismatch"
Calculate: `preimage_hash` = hash(preimage)
if `preimage_hash` != `id.preimage_hash` then return error // "invalid preimage submitted"
Update: balance of `id.recipient` add asset `id.symbol` of quantity `id.quantity`
Update: balance of `id.to` add asset `id.symbol` of quantity `id.quantity`
Add: transaction to mempool
Set: `id.preimage_tx_id` = `transaction_id`
Cleanup: memory allocated to this htlc
Virtual Operation: Update account history for `depositor` to reflect redemption as by default the above operation will only appear for `redeemer`
Virtual Operation: Update account history for `from` to reflect redemption as by default the above operation will only appear for `to`

return: results
```

### **Extend Expiry**

```
transaction_obj htlc_extend_expiry(depositor, id, timeout_threshold, htlc_extention_fee)
Validate: 'depositor' = get_htlc(id).depositor
transaction_obj htlc_extend(id, issuer, timeout_threshold, broadcast)
Validate: 'issuer' = get_htlc(id).from
Validate: `timeout_threshold` < now() + GRAPHENE_HTLC_MAXIMUM_DURRATION
Calculate: `required_fee` = GRAPHENE_HTLC_DAILY_FEE * count((`timeout_threshold` - now()), days)
Validate: `depositor` account has requisite `quantity` of BTS for `required_fee`
Update: BTS balance of `depositor` based on `required_fee`)
Validate: `issuer` account has requisite `quantity` of BTS for `required_fee`
Update: BTS balance of `issuer` based on `required_fee`)
Set: `contract.timeout_treshold` = `timeout_threshold`
return results
```
Expand Down