From e2572c61cfc6b08e360238303cc4dafc21951409 Mon Sep 17 00:00:00 2001 From: Elliot Lee Date: Wed, 5 Jun 2019 00:27:25 -0700 Subject: [PATCH] Add details about transaction fees, master keys, and multi-signing --- docs/index.md | 10 ++++++---- docs/src/transactions.md.ejs | 4 +++- src/common/schemas/objects/instructions.json | 2 +- src/common/schemas/objects/settings-plus-memos.json | 2 +- 4 files changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/index.md b/docs/index.md index 1ff640c7..ba181a12 100644 --- a/docs/index.md +++ b/docs/index.md @@ -321,17 +321,19 @@ Executing a transaction with `RippleAPI` requires the following four steps: ## Transaction Fees -Every transaction must destroy a small amount of XRP as a cost to send the transaction. This is also called a *transaction fee*. The transaction cost is designed to increase along with the load on the XRP Ledger, making it very expensive to deliberately or inadvertently overload the peer-to-peer network that powers the XRP Ledger. +Every transaction must destroy a small amount of XRP as a cost to apply the transaction to the ledger. This is also called a *transaction fee*. The transaction cost is designed to increase along with the load on the XRP Ledger, making it very expensive to deliberately or inadvertently overload the peer-to-peer network that powers the XRP Ledger. You can choose the size of the fee you want to pay or let a default be used. You can get an estimate of the fee required to be included in the next ledger closing with the [getFee](#getfee) method. +For a multi-signed transaction, ripple-lib automatically multiplies the `fee` by (1 + Number of Signatures Provided). For example, if you set `instructions.fee = '0.000020'` and `instructions.signersCount = 2`, the prepared transaction's `Fee` will be 20 drops × (1 + 2 Signatures) = 60 drops. See [Transaction Cost](https://developers.ripple.com/transaction-cost.html). + ## Transaction Instructions Transaction instructions indicate how to execute a transaction, complementary with the [transaction specification](#transaction-specifications). Name | Type | Description ---- | ---- | ----------- -fee | [value](#value) | *Optional* An exact fee to pay for the transaction. See [Transaction Fees](#transaction-fees) for more information. +fee | [value](#value) | *Optional* An exact fee to pay for the transaction, before multiplying for multi-signed transactions. See [Transaction Fees](#transaction-fees) for more information. maxFee | [value](#value) | *Optional* Deprecated: Use `maxFeeXRP` in the RippleAPI constructor instead. The maximum fee to pay for this transaction. If this exceeds `maxFeeXRP`, `maxFeeXRP` will be used instead. See [Transaction Fees](#transaction-fees) for more information. maxLedgerVersion | integer,null | *Optional* The highest ledger version that the transaction can be included in. If this option and `maxLedgerVersionOffset` are both omitted, the `maxLedgerVersion` option will default to 3 greater than the current validated ledger version (equivalent to `maxLedgerVersionOffset=3`). Use `null` to not set a maximum ledger version. If not null, this must be an integer greater than 0, or one of the following strings: 'validated', 'closed', 'current'. maxLedgerVersion | string,null | *Optional* The highest ledger version that the transaction can be included in. If this option and `maxLedgerVersionOffset` are both omitted, the `maxLedgerVersion` option will default to 3 greater than the current validated ledger version (equivalent to `maxLedgerVersionOffset=3`). Use `null` to not set a maximum ledger version. If not null, this must be an integer greater than 0, or one of the following strings: 'validated', 'closed', 'current'. @@ -519,7 +521,7 @@ Name | Type | Description ---- | ---- | ----------- defaultRipple | boolean | *Optional* Enable [rippling](https://ripple.com/build/understanding-the-noripple-flag/) on this account’s trust lines by default. (New in [rippled 0.27.3](https://github.com/ripple/rippled/releases/tag/0.27.3)) depositAuth | boolean | *Optional* Enable [Deposit Authorization](https://ripple.com/build/deposit-authorization/) on this account. If set, transactions cannot send value of any kind to this account unless the sender of those transactions is the account itself. (Requires the [DepositAuth amendment](https://ripple.com/build/known-amendments/#depositauth)) -disableMasterKey | boolean | *Optional* Disallows use of the master key to sign transactions for this account. +disableMasterKey | boolean | *Optional* Disallows use of the master key to sign transactions for this account. To disable the master key, you must authorize the transaction by signing it with the master key pair. You cannot use a regular key pair or a multi-signature. You can re-enable the master key pair using a regular key pair or multi-signature. See [AccountSet](https://developers.ripple.com/accountset.html). disallowIncomingXRP | boolean | *Optional* Indicates that client applications should not send XRP to this account. Not enforced by rippled. domain | string | *Optional* The domain that owns this account, as a hexadecimal string representing the ASCII for the domain in lowercase. emailHash | string,null | *Optional* Hash of an email address to be used for generating an avatar image. Conventionally, clients use Gravatar to display this image. Use `null` to clear. @@ -3888,7 +3890,7 @@ Name | Type | Description ---- | ---- | ----------- defaultRipple | boolean | *Optional* Enable [rippling](https://ripple.com/build/understanding-the-noripple-flag/) on this account’s trust lines by default. (New in [rippled 0.27.3](https://github.com/ripple/rippled/releases/tag/0.27.3)) depositAuth | boolean | *Optional* Enable [Deposit Authorization](https://ripple.com/build/deposit-authorization/) on this account. If set, transactions cannot send value of any kind to this account unless the sender of those transactions is the account itself. (Requires the [DepositAuth amendment](https://ripple.com/build/known-amendments/#depositauth)) -disableMasterKey | boolean | *Optional* Disallows use of the master key to sign transactions for this account. +disableMasterKey | boolean | *Optional* Disallows use of the master key to sign transactions for this account. To disable the master key, you must authorize the transaction by signing it with the master key pair. You cannot use a regular key pair or a multi-signature. You can re-enable the master key pair using a regular key pair or multi-signature. See [AccountSet](https://developers.ripple.com/accountset.html). disallowIncomingXRP | boolean | *Optional* Indicates that client applications should not send XRP to this account. Not enforced by rippled. domain | string | *Optional* The domain that owns this account, as a hexadecimal string representing the ASCII for the domain in lowercase. emailHash | string,null | *Optional* Hash of an email address to be used for generating an avatar image. Conventionally, clients use Gravatar to display this image. Use `null` to clear. diff --git a/docs/src/transactions.md.ejs b/docs/src/transactions.md.ejs index ae4c991f..566b12fc 100644 --- a/docs/src/transactions.md.ejs +++ b/docs/src/transactions.md.ejs @@ -43,10 +43,12 @@ Executing a transaction with `RippleAPI` requires the following four steps: ## Transaction Fees -Every transaction must destroy a small amount of XRP as a cost to send the transaction. This is also called a *transaction fee*. The transaction cost is designed to increase along with the load on the XRP Ledger, making it very expensive to deliberately or inadvertently overload the peer-to-peer network that powers the XRP Ledger. +Every transaction must destroy a small amount of XRP as a cost to apply the transaction to the ledger. This is also called a *transaction fee*. The transaction cost is designed to increase along with the load on the XRP Ledger, making it very expensive to deliberately or inadvertently overload the peer-to-peer network that powers the XRP Ledger. You can choose the size of the fee you want to pay or let a default be used. You can get an estimate of the fee required to be included in the next ledger closing with the [getFee](#getfee) method. +For a multi-signed transaction, ripple-lib automatically multiplies the `fee` by (1 + Number of Signatures Provided). For example, if you set `instructions.fee = '0.000020'` and `instructions.signersCount = 2`, the prepared transaction's `Fee` will be 20 drops × (1 + 2 Signatures) = 60 drops. See [Transaction Cost](https://developers.ripple.com/transaction-cost.html). + ## Transaction Instructions Transaction instructions indicate how to execute a transaction, complementary with the [transaction specification](#transaction-specifications). diff --git a/src/common/schemas/objects/instructions.json b/src/common/schemas/objects/instructions.json index e51f094c..292a1835 100644 --- a/src/common/schemas/objects/instructions.json +++ b/src/common/schemas/objects/instructions.json @@ -10,7 +10,7 @@ "$ref": "sequence" }, "fee": { - "description": "An exact fee to pay for the transaction. See [Transaction Fees](#transaction-fees) for more information.", + "description": "An exact fee to pay for the transaction, before multiplying for multi-signed transactions. See [Transaction Fees](#transaction-fees) for more information.", "$ref": "value" }, "maxFee": { diff --git a/src/common/schemas/objects/settings-plus-memos.json b/src/common/schemas/objects/settings-plus-memos.json index 1f6b6c87..c3553a1d 100644 --- a/src/common/schemas/objects/settings-plus-memos.json +++ b/src/common/schemas/objects/settings-plus-memos.json @@ -13,7 +13,7 @@ }, "disableMasterKey": { "type": "boolean", - "description": "Disallows use of the master key to sign transactions for this account." + "description": "Disallows use of the master key to sign transactions for this account. To disable the master key, you must authorize the transaction by signing it with the master key pair. You cannot use a regular key pair or a multi-signature. You can re-enable the master key pair using a regular key pair or multi-signature. See [AccountSet](https://developers.ripple.com/accountset.html)." }, "disallowIncomingXRP": { "type": "boolean",