diff --git a/bsip-0044.md b/bsip-0044.md index 994e243..e8ad2d8 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** @@ -172,67 +172,73 @@ 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; - }; + 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_hash; + + 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 from; + account_id_type to; + asset amount; + fc::time_point_sec expiration; + htlc_hash preimage_hash; + 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 ``` @@ -240,12 +246,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 ```