From f491d09605a3e817914529e0fd7fef5367cfa045 Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa Date: Thu, 24 Jan 2019 09:27:45 -0800 Subject: [PATCH] doc multisignreserve changes --- .../accounts/reserves.md | 2 +- .../ledger-object-types/signerlist.md | 44 ++++++++++++------- .../transaction-types/signerlistset.md | 2 + .../set-up-multi-signing.md | 4 +- 4 files changed, 34 insertions(+), 18 deletions(-) diff --git a/content/concepts/payment-system-basics/accounts/reserves.md b/content/concepts/payment-system-basics/accounts/reserves.md index d6975001ff..1a7899cebe 100644 --- a/content/concepts/payment-system-basics/accounts/reserves.md +++ b/content/concepts/payment-system-basics/accounts/reserves.md @@ -21,7 +21,7 @@ Many objects in the ledger are owned by a particular address, and count toward t - [Offers](offer.html) are owned by the address that placed them. Transaction processing automatically removes Offers that are fully consumed or found to be unfunded. Alternatively, the owner can cancel an Offer by sending an [OfferCancel transaction][], or by sending an [OfferCreate transaction][] that contains an `OfferSequence` parameter. - [Trust lines](ripplestate.html) are shared between two addresses. The owner reserve can apply to one or both of the addresses, depending on whether the fields that address controls are in their default state. See [Contributing to the Owner Reserve](ripplestate.html#contributing-to-the-owner-reserve) for details. -- A single [SignerList](signerlist.html) counts as 3 to 10 objects for purposes of the owner reserve, depending on how many members it has. See also: [SignerLists and Reserves](signerlist.html#signerlists-and-reserves). +- Without the [MultiSignReserve amendment](known-amendments.html#multisignreserve), a single [SignerList](signerlist.html) counts as 3 to 10 objects for purposes of the owner reserve, depending on how many members it has. With the [MultiSignReserve amendment](known-amendments.html#multisignreserve) enabled, a single SignerList counts as 1 object for purposes of the owner reserve, regardless of the number of members it has. See also: [SignerLists and Reserves](signerlist.html#signerlists-and-reserves). - [Held Payments (Escrow)](escrow-object.html) are owned by the address that placed them. - [Payment Channels](use-payment-channels.html) are owned by the address that created them. - [Owner directories](directorynode.html) list all the ledger objects that contribute to an address's owner reserve. However, the owner directory itself does not count towards the reserve. diff --git a/content/references/rippled-api/ledger-data-formats/ledger-object-types/signerlist.md b/content/references/rippled-api/ledger-data-formats/ledger-object-types/signerlist.md index 914d7c5ef3..12aef9519a 100644 --- a/content/references/rippled-api/ledger-data-formats/ledger-object-types/signerlist.md +++ b/content/references/rippled-api/ledger-data-formats/ledger-object-types/signerlist.md @@ -42,16 +42,16 @@ The `SignerList` object type represents a list of parties that, as a group, are A `SignerList` object has the following fields: -| Name | JSON Type | Internal Type | Description | -|-----------------|-----------|---------------|-------------| -| `LedgerEntryType` | String | UInt16 | The value `0x0053`, mapped to the string `SignerList`, indicates that this object is a SignerList object. | -| `Flags` | Number | UInt32 | A bit-map of boolean flags. No flags are defined for the SignerList type, so this value is always `0`. | -| `PreviousTxnID` | String | Hash256 | The identifying hash of the transaction that most recently modified this object. | -| `PreviousTxnLgrSeq` | Number | UInt32 | The [index of the ledger][Ledger Index] that contains the transaction that most recently modified this object. | -| `OwnerNode` | String | UInt64 | A hint indicating which page of the owner directory links to this object, in case the directory consists of multiple pages. | -| `SignerEntries` | Array | Array | An array of SignerEntry objects representing the parties who are part of this signer list. | -| `SignerListID` | Number | UInt32 | An ID for this signer list. Currently always set to `0`. If a future [amendment](amendments.html) allows multiple signer lists for an account, this may change. | -| `SignerQuorum` | Number | UInt32 | A target number for signer weights. To produce a valid signature for the owner of this SignerList, the signers must provide valid signatures whose weights sum to this value or more. | +| Name | JSON Type | Internal Type | Description | +|:--------------------|:----------|:--------------|:---------------------------| +| `LedgerEntryType` | String | UInt16 | The value `0x0053`, mapped to the string `SignerList`, indicates that this object is a SignerList object. | +| `Flags` | Number | UInt32 | A bit-map of boolean flags. Without the [MultiSignReserve amendment](known-amendments.html#multisignreserve), no flags are defined for the SignerList type, so this value is always 0. With the [MultiSignReserve amendment](known-amendments.html#multisignreserve) enabled, a flag is defined for the SignerList type, so this value can be bit-map of a boolean flag enabled for this account. | +| `PreviousTxnID` | String | Hash256 | The identifying hash of the transaction that most recently modified this object. | +| `PreviousTxnLgrSeq` | Number | UInt32 | The [index of the ledger][Ledger Index] that contains the transaction that most recently modified this object. | +| `OwnerNode` | String | UInt64 | A hint indicating which page of the owner directory links to this object, in case the directory consists of multiple pages. | +| `SignerEntries` | Array | Array | An array of SignerEntry objects representing the parties who are part of this signer list. | +| `SignerListID` | Number | UInt32 | An ID for this signer list. Currently always set to `0`. If a future [amendment](amendments.html) allows multiple signer lists for an account, this may change. | +| `SignerQuorum` | Number | UInt32 | A target number for signer weights. To produce a valid signature for the owner of this SignerList, the signers must provide valid signatures whose weights sum to this value or more. | The `SignerEntries` may be any combination of funded and unfunded addresses that use either secp256k1 or ed25519 keys. @@ -59,16 +59,30 @@ The `SignerEntries` may be any combination of funded and unfunded addresses that Each member of the `SignerEntries` field is an object that describes that signer in the list. A SignerEntry has the following fields: -| Name | JSON Type | Internal Type | Description | -|-----------------|-----------|---------------|-------------| -| `Account` | String | AccountID | An XRP Ledger address whose signature contributes to the multi-signature. It does not need to be a funded address in the ledger. | -| `SignerWeight` | Number | UInt16 | The weight of a signature from this signer. A multi-signature is only valid if the sum weight of the signatures provided meets or exceeds the SignerList's `SignerQuorum` value. | +| Name | JSON Type | Internal Type | Description | +|:---------------|:----------|:--------------|:--------------------------------| +| `Account` | String | AccountID | An XRP Ledger address whose signature contributes to the multi-signature. It does not need to be a funded address in the ledger. | +| `SignerWeight` | Number | UInt16 | The weight of a signature from this signer. A multi-signature is only valid if the sum weight of the signatures provided meets or exceeds the SignerList's `SignerQuorum` value. | When processing a multi-signed transaction, the server dereferences the `Account` values with respect to the ledger at the time of transaction execution. If the address _does not_ correspond to a funded [AccountRoot object](accountroot.html), then only the master secret associated with that address can be used to produce a valid signature. If the account _does_ exist in the ledger, then it depends on the state of that account. If the account has a Regular Key configured, the Regular Key can be used. The account's master key can only be used if it is not disabled. A multi-signature cannot be used as part of another multi-signature. +## {{currentpage.name}} Flag + +_Requires the [MultiSignReserve Amendment](known-amendments.html#multisignreserve)._ + +SignerList objects can have the following flag value: + +| Flag Name | Hex Value | Decimal Value | Description | +|:-----------------|:-----------|:--------------|:-------------------------------| +| lsfOneOwnerCount | 0x00010000 | 65536 | This flag is set by the [SignerListSet transaction](signerlistset.html) when you create a new SignerList, or replace or remove a SignerList that was created before the MultiSignReserve amendment was enabled. Setting this flag enables the XRP Ledger to lower the [`OwnerCount`](accountroot.html#accountroot-fields) and [owner reserve](reserves.html#owner-reserves) for a SignerList as provided by the MultiSignReserve amendment. For example, when you create a SignerList after the MultiSignReserve amendment is enabled, this flag is set, your `OwnerCount` is increased by 1, and your owner reserve is increased by 5 XRP. When you replace a SignerList that was created before the MultiSignReserve amendment was enabled, this flag is set, your `OwnerCount` and owner reserve for the replaced SignerList are removed, your `OwnerCount` is increased by 1, and your owner reserve is increased by 5 XRP. When you remove a SignerList that was created before the MultiSignReserve amendment was enabled, this flag is set and your `OwnerCount` and owner reserve for the SignerList you removed are removed. | + ## SignerLists and Reserves -A SignerList contributes to its owner's [reserve requirement](reserves.html). The SignerList itself counts as two objects, and each member of the list counts as one. As a result, the total owner reserve associated with a SignerList is anywhere from 3 times to 10 times the reserve required by a single trust line ([RippleState](ripplestate.html)) or [Offer](offer.html) object in the ledger. +A SignerList contributes to its owner's [reserve requirement](reserves.html). + +Without the [MultiSignReserve Amendment](known-amendments.html#multisignreserve), the SignerList itself counts as two objects, and each member of the list counts as one. As a result, the total owner reserve associated with a SignerList is anywhere from 3 times to 10 times the reserve required by a single trust line ([RippleState](ripplestate.html)) or [Offer](offer.html) object in the ledger. + +With the [MultiSignReserve Amendment](known-amendments.html#multisignreserve) enabled, the SignerList counts as one object, regardless of how many members it has. As a result, the owner reserve associated with a SignerList is 5 XRP, regardless of how many members it has. ## SignerList ID Format diff --git a/content/references/rippled-api/transaction-formats/transaction-types/signerlistset.md b/content/references/rippled-api/transaction-formats/transaction-types/signerlistset.md index 8006ef5730..d927ffdb49 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/signerlistset.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/signerlistset.md @@ -51,6 +51,8 @@ You can create, update, or remove a SignerList using the master key, regular key You cannot remove the last method of signing transactions from an account. If an account's master key is disabled (it has the [`lsfDisableMaster` flag](accountroot.html#accountroot-flags) enabled) and the account does not have a [Regular Key](cryptographic-keys.html) configured, then you cannot delete the SignerList from the account. Instead, the transaction fails with the error [`tecNO_ALTERNATIVE_KEY`](tec-codes.html). +With the [MultiSignReserve Amendment](known-amendments.html#multisignreserve) enabled, creating a SignerList, or replacing or removing a SignerList that was created before the MultiSignReserve amendment was enabled, sets the lsfOneOwnerCount flag on the SignerList object. When this flag is set, the XRP Ledger is able to lower the [`OwnerCount`](accountroot.html#accountroot-fields) and [owner reserve](reserves.html#owner-reserves) for a SignerList as provided by the MultiSignReserve amendment. For more information, see [SignerList Flag](signerlist.html#signerlist-flag). + {% include '_snippets/rippled-api-links.md' %} {% include '_snippets/tx-type-links.md' %} diff --git a/content/tutorials/manage-account-settings/set-up-multi-signing.md b/content/tutorials/manage-account-settings/set-up-multi-signing.md index e2775e6a29..e20436f29c 100644 --- a/content/tutorials/manage-account-settings/set-up-multi-signing.md +++ b/content/tutorials/manage-account-settings/set-up-multi-signing.md @@ -16,7 +16,7 @@ This tutorial demonstrates how to enable multi-signing for an address. ## 1. Prepare a funded address -You need an XRP Ledger address that can send transactions, and has enough XRP available. Multi-signing requires more than the usual amount of XRP for the [account reserve](reserves.html) and [transaction cost](transaction-cost.html), increasing with the number of signers and signatures you use. +You need an XRP Ledger address that can send transactions, and has enough XRP available. Multi-signing requires more than the usual amount of XRP for the [account reserve](reserves.html) and [transaction cost](transaction-cost.html), increasing with the number of signers and signatures you use. ***TODO: jha figure out how to fix this text - the reserve is 5 XRP - is that considered to be more than the usual amount - what is the usual amount? The transaction cost remains the same.*** If you started `rippled` in [stand-alone mode](rippled-server-modes.html#reasons-to-run-a-rippled-server-in-stand-alone-mode) with a new genesis ledger, you must: @@ -129,7 +129,7 @@ In this example, the SignerList has 3 members, with the weights and quorum set u Make sure that the [Transaction Result](transaction-results.html) is [**tesSUCCESS**](tes-success.html). Otherwise, the transaction failed. If you have a problem in stand-alone mode or a non-production network, check that [multi-sign is enabled](start-a-new-genesis-ledger-in-stand-alone-mode.html#settings-in-new-genesis-ledgers). -**Note:** The more members in the SignerList, the more XRP your address must have for purposes of the [owner reserve](reserves.html#owner-reserves). If your address does not have enough XRP, the transaction fails with [tecINSUFFICIENT_RESERVE](tec-codes.html). See also: [SignerLists and Reserves](signerlist.html#signerlists-and-reserves). +**Note:** Without the [MultiSignReserve Amendment](known-amendments.html#multisignreserve), the more members in the SignerList, the more XRP your address must have for purposes of the [owner reserve](reserves.html#owner-reserves). If your address does not have enough XRP, the transaction fails with [tecINSUFFICIENT_RESERVE](tec-codes.html). With the [MultiSignReserve Amendment](known-amendments.html#multisignreserve) enabled, the XRP your address must have for purposes of the [owner reserve](reserves.html#owner-reserves) is 5 XRP, regardless of the number of members in the SignerList. See also: [SignerLists and Reserves](signerlist.html#signerlists-and-reserves). ## 4. Close the ledger