From 6dda7150d6c0a2ee57808f57ede6d96c52e26bb6 Mon Sep 17 00:00:00 2001 From: John Jones Date: Fri, 12 Oct 2018 17:05:30 -0500 Subject: [PATCH 1/7] grammar fixes --- bsip-0044.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/bsip-0044.md b/bsip-0044.md index 994e243..6b9dcf7 100644 --- a/bsip-0044.md +++ b/bsip-0044.md @@ -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** @@ -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** From 6efbbc2f7d6f7c990f1da48379289d6691ac9204 Mon Sep 17 00:00:00 2001 From: John Jones Date: Mon, 15 Oct 2018 06:34:52 -0500 Subject: [PATCH 2/7] Added some parameter limits --- bsip-0044.md | 34 ++++++++++++++++++++-------------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/bsip-0044.md b/bsip-0044.md index 6b9dcf7..4b7c71e 100644 --- a/bsip-0044.md +++ b/bsip-0044.md @@ -172,22 +172,28 @@ Bob has now observed the `preimage` Alice used to "unlock" his HTLC, and he will ## **Objects** ``` - class htlc_object : public graphene::db::abstract_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 preimage_hash; - uint16_t preimage_size; - transaction_id_type preimage_tx_id; - }; + class htlc_object : public graphene::db::abstract_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 preimage_hash; + fc::enum_type preimage_hash_algorithm; + uint16_t preimage_size; + }; ``` +Note 1: The preimage hash algorithm must be speceified as either ``SHA256``, ``RIPEMD160``, or ``SHA1``. The use of ``SHA1`` is added for compatibility to other chains, but its use is discouraged. + +Note 2: The preimage size must be less than 65536 bytes. + +Note 3: The initial HTLC expiration can not be more than 2 years from the HTLC creation. This can be extened, but not for more than 2 years beyond each extension. + ## **Operations** ### **Prepare** From 57f21fa876b4cd16e05baff1c042f2a8492fde7d Mon Sep 17 00:00:00 2001 From: John Jones Date: Mon, 15 Oct 2018 08:16:07 -0500 Subject: [PATCH 3/7] Re-added committee parameters --- bsip-0044.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/bsip-0044.md b/bsip-0044.md index 4b7c71e..c456060 100644 --- a/bsip-0044.md +++ b/bsip-0044.md @@ -190,9 +190,9 @@ Bob has now observed the `preimage` Alice used to "unlock" his HTLC, and he will Note 1: The preimage hash algorithm must be speceified as either ``SHA256``, ``RIPEMD160``, or ``SHA1``. The use of ``SHA1`` is added for compatibility to other chains, but its use is discouraged. -Note 2: The preimage size must be less than 65536 bytes. +Note 2: The preimage size must be less than the maximum number of bytes as specified by the committee. -Note 3: The initial HTLC expiration can not be more than 2 years from the HTLC creation. This can be extened, but not for more than 2 years beyond each extension. +Note 3: 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** From bb0071069029da6ecd02b76386e321120f7ed96e Mon Sep 17 00:00:00 2001 From: John Jones Date: Thu, 3 Jan 2019 14:54:26 -0500 Subject: [PATCH 4/7] Updated to match implementation more closely --- bsip-0044.md | 44 ++++++++++++++++++++------------------------ 1 file changed, 20 insertions(+), 24 deletions(-) diff --git a/bsip-0044.md b/bsip-0044.md index c456060..3e7dd3e 100644 --- a/bsip-0044.md +++ b/bsip-0044.md @@ -177,13 +177,11 @@ Bob has now observed the `preimage` Alice used to "unlock" his HTLC, and he will 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; + account_id_type from; + account_id_type to; asset amount; fc::time_point_sec expiration; - asset pending_fee; - vector preimage_hash; - fc::enum_type preimage_hash_algorithm; + htlc_hash preimage_hash; uint16_t preimage_size; }; ``` @@ -199,46 +197,44 @@ Note 3: The initial HTLC expiration can not be more than the maximum amount of t ### **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 ``` @@ -246,12 +242,12 @@ transaction_obj htlc_redeem(fee_paying_account, id, preimage, htlc_redemption_fe ### **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 ``` From cf4206d2b18d2982c6434aa20f49cfcec798a4bc Mon Sep 17 00:00:00 2001 From: John Jones Date: Mon, 7 Jan 2019 15:05:00 -0500 Subject: [PATCH 5/7] punctuation fixes and clarifications --- bsip-0044.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/bsip-0044.md b/bsip-0044.md index 3e7dd3e..a67ab67 100644 --- a/bsip-0044.md +++ b/bsip-0044.md @@ -172,6 +172,12 @@ Bob has now observed the `preimage` Alice used to "unlock" his HTLC, and he will ## **Objects** ``` + typedef fc::static_variant< + htlc_algo_ripemd160, + htlc_algo_sha1, + htlc_algo_sha256 + > htlc_hash; + class htlc_object : public graphene::db::abstract_object { public: static const uint8_t space_id = implementation_ids; @@ -186,11 +192,9 @@ Bob has now observed the `preimage` Alice used to "unlock" his HTLC, and he will }; ``` -Note 1: The preimage hash algorithm must be speceified as either ``SHA256``, ``RIPEMD160``, or ``SHA1``. The use of ``SHA1`` is added for compatibility to other chains, but its use is discouraged. - -Note 2: The preimage size must be less than the maximum number of bytes as specified by the committee. +Note 1: The preimage size must be less than the maximum number of bytes as specified by the committee. -Note 3: 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). +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** @@ -213,7 +217,7 @@ transaction_obj htlc_create(from, to, quantity, symbol, hash_algorithm, preimage Set: `contract.preimage_hash` = `preimage_hash` Set: `contract.preimage_length` = `preimage_length` Set: `contract.timeout_treshold` = `timeout_threshold` - Transfer: remove `contract.quantity` of `contract.symbol` from from` account + Transfer: remove `contract.quantity` of `contract.symbol` from `from` account return results ``` From 966400130bf519499340f57cb712efb5e3ede1b5 Mon Sep 17 00:00:00 2001 From: John Jones Date: Mon, 7 Jan 2019 15:22:13 -0500 Subject: [PATCH 6/7] added comments about htlc_hash algos --- bsip-0044.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/bsip-0044.md b/bsip-0044.md index a67ab67..90a3a1a 100644 --- a/bsip-0044.md +++ b/bsip-0044.md @@ -173,9 +173,9 @@ Bob has now observed the `preimage` Alice used to "unlock" his HTLC, and he will ``` typedef fc::static_variant< - htlc_algo_ripemd160, - htlc_algo_sha1, - htlc_algo_sha256 + htlc_algo_ripemd160, // preimage_hash using RIPEMD160 algorithm + htlc_algo_sha1, // preimage_hash using SHA1 algorithm + htlc_algo_sha256 // preimage_hash using SHA256 algorithm > htlc_hash; class htlc_object : public graphene::db::abstract_object { From 6f72b4bf88a077752a9719bcd9cc231e6476b7b7 Mon Sep 17 00:00:00 2001 From: John Jones Date: Mon, 7 Jan 2019 15:24:54 -0500 Subject: [PATCH 7/7] better spacing in comments --- bsip-0044.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/bsip-0044.md b/bsip-0044.md index 90a3a1a..e8ad2d8 100644 --- a/bsip-0044.md +++ b/bsip-0044.md @@ -174,8 +174,8 @@ Bob has now observed the `preimage` Alice used to "unlock" his HTLC, and he will ``` typedef fc::static_variant< htlc_algo_ripemd160, // preimage_hash using RIPEMD160 algorithm - htlc_algo_sha1, // preimage_hash using SHA1 algorithm - htlc_algo_sha256 // preimage_hash using SHA256 algorithm + htlc_algo_sha1, // preimage_hash using SHA1 algorithm + htlc_algo_sha256 // preimage_hash using SHA256 algorithm > htlc_hash; class htlc_object : public graphene::db::abstract_object {