The Amendments system provides a means of introducing new features to the decentralized Ripple consensus network without causing disruptions. The amendments system works by utilizing the core consensus process of the network to approve any changes by showing continuous support before those changes go into effect. An amendment normally requires 80% support for two weeks before it can apply.
+
When an Amendment has been enabled, it applies permanently to all ledger versions after the one that included it. You cannot disable an Amendment, unless you introduce a new Amendment to do so.
+
Background
+
Any changes to transaction processing could cause servers to build a different ledger with the same set of transactions. If only a portion of validators (rippled servers participating in consensus) have upgraded to a new version of the software, this could cause anything from minor inconveniences to full outages. In the minor case, a minority of servers spend more time and bandwidth fetching the actual consensus ledger because they cannot build it using the transaction processing rules they already know. In the worst case, the consensus process might be unable to validate new ledger versions because servers with different rules could not reach a consensus on the exact ledger to build.
+
Amendments provide a solution to this problem, so that new features can be enabled only when enough validators support those features.
+
Users and businesses who rely on the Ripple Consensus Ledger can also use Amendments to provide advance notice of changes in transaction processing that might affect their business. However, API changes that do not impact transaction processing or the consensus process do not require Amendments.
+
About Amendments
+
An amendment is a fully-functional feature or change, waiting to be enabled by the peer-to-peer network as a part of the consensus process. A rippled server that wants to use an amendment has code for two modes: without the amendment (previous behavior) and with the amendment (new behavior).
+
Every amendment has a unique identifying hex value and a short name. The short name is for human use, and is not used in the amendment process. Two servers can support the same amendment ID while using different names to describe it. An amendment's name is not guaranteed to be unique.
Every 256th ledger is called a "flag" ledger. The process of approving an amendment starts in the ledger version immediately before the flag ledger. When rippled validator servers send validation messages for that ledger, those servers also submit votes in favor of specific amendments. (Fee Voting also occurs around flag ledgers.)
+
The flag ledger itself has no special contents. However, during that time, the servers look at the votes of the validators they trust, and decide whether to insert an EnableAmendment pseudo-transaction into the following ledger. The flags of an EnableAmendment pseudo-transaction indicate what the server thinks happened:
+
+
The tfGotMajority flag means that support for the amendment has increased to at least 80% of trusted validators.
+
The tfLostMajority flag means that support for the amendment has decreased to less than 80% of trusted validators.
+
An EnableAmendment pseudo-transaction with no flags means that support for the amendment has been enabled. (The change in transaction processing applies to every ledger after this one.)
+
+
A server only inserts the pseudo-transaction to enable an amendment if all of the following conditions are met:
+
+
The amendment has not already been enabled.
+
A previous ledger includes an EnableAmendment pseudo-transaction for this amendment with the tfGotMajority flag enabled.
+
The previous ledger in question is an ancestor of the current ledger.
+
The previous ledger in question has a close time that is at least two weeks before the close time of the latest flag ledger.
+
There are no EnableAmendment pseudo-transactions for this amendment with the tfLostMajority flag enabled in the consensus ledgers between the tfGotMajority pseudo-transaction and the current ledger.
+
+
It is theoretically possible (but extremely unlikely) that a tfLostMajority EnableAmendment pseudo-transaction could be included in the same ledger as the pseudo-transaction to enable an amendment. In this case, the pseudo-transaction with the tfLostMajority pseudo-transaction has no effect.
+
Amendment Voting
+
Operators of rippled validators can choose which amendments to support or reject using the feature command. This decides which amendments the validator votes for in the amendment process. By default, rippled votes in favor of every amendment it knows about.
+
The operator of a rippled validator can "veto" an amendment. In this case, that validator never sends a vote in favor of the amendment. If enough servers veto an amendment, that prevents it from reaching consistent 80% support, so the amendment does not apply.
+
As with all aspects of the consensus process, amendment votes are only taken into account by servers that trust the validators sending those votes. Currently, Ripple (the company) recommends only trusting the 5 default validators that Ripple (the company) operates. For now, trusting only those validators is sufficient to coordinate with Ripple (the company) on releasing new features.
+
Configuring Amendment Voting
+
You can temporarily configure an amendment using the feature command. To make a persistent change to your server's support for an amendment, modify your server's rippled.cfg file.
+
Use the [veto_amendments] stanza to list amendments you do not want the server to vote for. Each line should contain one amendment's unique ID, optionally followed by the short name for the amendment. For example:
Use the [amendments] stanza to list amendments you want to vote for. (Even if you do not list them here, by default a server votes for all the amendments it knows how to apply.) Each line should contain one amendment's unique ID, optionally followed by the short name for the amendment. For example:
If you want to see how rippled behaves with an amendment enabled, before that amendment gets enabled on the production network, you can run use rippled's configuration file to forcibly enable a feature. This is intended for development purposes only.
+
Because other members of the consensus network probably do not have the feature enabled, you should not use this feature while connecting to the production network. While testing with features forcibly enabled, you should run rippled in Stand-Alone Mode.
+
To forcibly enable a feature, add a [features] stanza to your rippled.cfg file. In this stanza, add the short names of the features to enable, one per line. For example:
+
[features]
+MultiSign
+TrustSetAuth
+
+
Known Amendments
+
The following is a comprehensive list of all known amendments and their status on the production Ripple Consensus Ledger:
Note: In many cases, an incomplete version of the code for an amendment is present in previous versions of the software. The "Introduced" version in the table above is the first stable version.
Changes the way the transaction cost applies to proposed transactions. Modifies the consensus process to prioritize transactions that pay a higher transaction cost.
+
This amendment introduces a fixed-size transaction queue for transactions that were not able to be included in the previous consensus round. If the rippled servers in the consensus network are under heavy load, they queue the transactions with the lowest transaction cost for later ledgers. Each consensus round prioritizes transactions from the queue with the largest transaction cost (Fee value), and includes as many transactions as the consensus network can process. If the transaction queue is full, transactions drop from the queue entirely, starting with the ones that have the lowest transaction cost.
+
While the consensus network is under heavy load, legitimate users can pay a higher transaction cost to make sure their transactions get processed. The situation persists until the entire backlog of cheap transactions is processed or discarded.
+
A transaction remains in the queue until one of the following happens:
+
+
It gets applied to a validated ledger (regardless of success or failure)
+
It becomes invalid (for example, the LastLedgerSequence causes it to expire)
+
It gets dropped because there are too many transactions in the queue with a higher transaction cost.
This amendment allows addresses to have a list of signers who can authorize transactions from that address in a multi-signature. The list has a quorum and 1 to 8 weighted signers. This allows various configurations, such as "any 3-of-5" or "signature from A plus any other two signatures."
+
Signers can be funded or unfunded addresses. Funded addresses in a signer list can sign using a regular key (if defined) or master key (unless disabled). Unfunded addresses can sign with a master key. Multi-signed transactions have the same permissions as transactions signed with a regular key.
+
An address with a SignerList can disable the master key even if a regular key is not defined. An address with a SignerList can also remove a regular key even if the master key is disabled. Therefore, the tecMASTER_DISABLED transaction result code is renamed tecNO_ALTERNATIVE_KEY. The tecNO_REGULAR_KEY transaction result is retired and replaced with tecNO_ALTERNATIVE_KEY. Additionally, this amendment adds the following new transaction result codes:
Provides "Suspended Payments" for XRP as a means of escrow within the Ripple Consensus Ledger. Creates the SuspendedPayment ledger node type and the new transaction types SuspendedPaymentCreate, SuspendedPaymentFinish, and SuspendedPaymentCancel.
+
This amendment is still in development. The current version is enabled on the Ripple Test Net.
Introduces Tickets as a way to reserve a transaction sequence number for later execution. Creates the Ticket ledger node type and the transaction types TicketCreate and TicketCancel.
Offers are owned by the account that placed them. An Offer can be automatically removed from the ledger if it is fully consumed or if it is found unfunded during transaction processing. 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 are shared between two accounts. The owner reserve can apply to one or both of the accounts, depending on whether the fields that account controls are in their default state. See Contributing to the Owner Reserve for details.
+
A single SignerList counts as 3 to 10 objects for purposes of the owner reserve, depending on how many members it has. See also: SignerLists and Reserves.
Owner directories list all the ledger nodes that contribute to an account's owner reserve. However, the owner directory itself does not count towards the reserve.
You can run rippled in stand-alone mode without a consensus of trusted servers. In stand-alone mode, rippled does not communicate with any other servers in the Ripple peer-to-peer network, but you can do most of the same actions on your local server only. Stand-alone provides a method for testing rippled behavior without being tied to the live network. For example, you can test the effects of Amendments before those Amendments have gone into effect across the decentralized network.
+
When you run rippled in stand-alone mode, you have to tell it what ledger version to start from:
In stand-alone mode, you can have rippled create a new genesis ledger. This provides a known state, with none of the ledger history from the production Ripple Consensus Ledger. (This is very useful for unit tests, among other things.)
+
+
To start rippled in stand-alone mode with a new genesis ledger, use the -a and --start options:
+
+
rippled -a --start --conf=/path/to/rippled.cfg
+
+
In a genesis ledger, the genesis address holds all 100 billion XRP. The keys of the genesis address are hardcoded as follows:
Caution: If you create a new genesis ledger, the hard-coded default Reserve is 200 XRP minimum for funding a new address, with an increment of 50 XRP per object in the ledger. These values are higher than the current reserve requirements of the production network. (See also: Fee Voting)
+
Load Saved Ledger
+
You can start with a ledger version that was saved to disk if your rippled server was previously synced with the Ripple peer-to-peer network (either the production network or the Test Net).
+
1. Start rippled normally.
+
To load an existing ledger, you must first retrieve that ledger from the network. Start rippled in networked mode as normal:
+
rippled --conf=/path/to/rippled.cfg
+
+
2. Wait until rippled is synced.
+
Use the server_info command to check the state of your server relative to the network. Your server is synced when the server_state value shows any of the following values:
+
+
full
+
proposing
+
validating.
+
+
3. (Optional) Retrieve specific ledger versions.
+
If you only want the most recent ledger, you can skip this step.
+
If you want to load a specific historical ledger version, use the ledger_request command to make rippled fetch it. If rippled does not already have the ledger version, you may have to run the ledger_request command multiple times until it has finished retrieving the ledger.
+
If you want to replay a specific historical ledger version, you must fetch both the ledger version to replay and the ledger version immediately before it.
To load the most recent ledger version, you can use the -a and --load options when starting the server:
+
rippled -a --load --conf=/path/to/rippled.cfg
+
+
To instead load a specific historical ledger, use the --load parameter along with the --ledger parameter, providing the ledger index or identifying hash of the ledger version to load:
+
rippled -a --load --ledger 19860944 --conf=/path/to/rippled.cfg
+
+
6. Manually advance the ledger.
+
When you load a ledger with --ledger in stand-alone mode, it goes to the current open ledger, so you must manually advance the ledger:
In stand-alone mode, rippled does not communicate to other members of the peer-to-peer network or participate in a consensus process. Instead, you must manually advance the ledger index using the ledger_accept command:
In stand-alone mode, rippled makes no distinction between a "closed" ledger version and a "validated" ledger version. (For more information about the difference, see The Ripple Ledger Consensus Process.)
+
Whenever rippled closes a ledger, it reorders the transactions according to a deterministic but hard-to-game algorithm. (This is an important part of consensus, since transactions may arrive at different parts of the network in different order.) When using rippled in stand-alone mode, you should manually advance the ledger before submitting a transaction that depends on the result of a previous transaction. Otherwise, the second transaction might be executed before the first transaction when you manually advance the ledger. Note: You can safely submit multiple transactions from a single address to a single ledger, because rippled sorts transactions from the same address in ascending order by Sequence number.
In order to protect the Ripple Consensus Ledger from being disrupted by spam and denial-of-service attacks, each transaction must destroy a small amount of XRP. This transaction cost is designed to increase along with the load on the network, making it very expensive to deliberately or inadvertently overload the network.
The current transaction cost required by the network is typically 0.01 XRP (10,000 drops), although it sometimes increases due to network load.
+
The current transaction cost required by the network for a standard transaction is typically 0.01 XRP (10,000 drops), although it sometimes increases due to network load.
The transaction cost is not paid to any party: the XRP is irrevocably destroyed. Since no new XRP can ever be created, this makes XRP more scarce, and consequently benefits all holders of XRP by making XRP more valuable.
-
Load Scaling
-
Each rippled server independently scales the transaction cost based on its current load. If you submit a transaction with a Fee value that is lower than current load-based transaction cost of the rippled server, that server neither applies nor relays the transaction. (Note: If you submit a transaction through an admin connection, the server applies and relays the transaction as long as the transaction cost meets the overall minimum.) A transaction is very unlikely to survive the consensus process unless its Fee value meets the requirements of a majority of servers.
+
Load Cost and Open Ledger Cost
+
When the FeeEscalation amendment is enabled, there are two thresholds for the transaction cost:
+
+
If the transaction cost does not meet a rippled server's load-based transaction cost threshold, the server ignores the transaction completely. (This logic is essentially unchanged with or without the amendment.)
+
If the transaction cost does not meet a rippled server's open ledger cost threshold, the server queues the transaction for a later ledger.
+
+
This divides transactions into roughly three categories:
+
+
Transactions that specify a transaction cost so low that they get rejected by the load-based transaction cost.
+
Transactions that specify a transaction cost high enough to be included in the current open ledger.
Each rippled server maintains a cost threshold based on its current load. If you submit a transaction with a Fee value that is lower than current load-based transaction cost of the rippled server, that server neither applies nor relays the transaction. (Note: If you submit a transaction through an admin connection, the server applies and relays the transaction as long as the transaction cost meets the overall minimum.) A transaction is very unlikely to survive the consensus process unless its Fee value meets the requirements of a majority of servers.
+
Open Ledger Cost
+
A rippled server with the FeeEscalation amendment enabled has a second mechanism for enforcing the transaction cost, called the open ledger cost. The open ledger cost starts out equal to the minimum transaction cost, but increases exponentially when an in-progress ledger has more transactions than the previous one. Only transactions which pay more than the open ledger cost can be included in the current open ledger.
+Transactions that do not meet the open ledger cost are queued for a following ledger instead.
+
The open ledger cost requirement is proportional to the normal cost of the transaction, not the absolute transaction cost. Transaction types that have a higher-than-normal requirement, such as multi-signed transactions must pay more to meet the open ledger cost than transactions which have minimum transaction cost requirements.
When rippled receives a transaction that meet the server's local load cost but not the open ledger cost, the server checks the transaction to see if it is "likely to be included" in a later ledger. If so, the server adds the transaction to the transaction queue and relays the transaction to other members of the network. Otherwise, the server discards the transaction. The server tries minimize the amount of network load caused by transactions that would not pay a transaction cost, since the transaction cost only applies when a transaction is included in a validated ledger.
+
The rippled server uses a variety of heuristics to determine which transactions are "likely to be included in a ledger." Most importantly, those transactions must be properly-formed and authorized with valid signatures.
+
When the current open ledger closes and the server starts a new open ledger, the server starts taking transactions from the queue to include in the new open ledger. The transaction queue is sorted with the transactions that would pay the highest transaction cost first, proportional to the un-scaled cost of those transactions. Transactions that pay the same transaction cost are queued in the order the server receives them.
+
Note: As of rippledversion 0.31.0, the transaction queue supports at most 1 transaction per sending address. This is expected to change in later versions.
+
Caution: The current implementation does not allow transactions with an AccountTxnID field in the transaction queue.
Querying the Transaction Cost
-
The rippled APIs have two ways to query the transaction cost: the server_info command (intended for humans) and the server_state command (intended for machines).
+
The rippled APIs have two ways to query the local load-based transaction cost: the server_info command (intended for humans) and the server_state command (intended for machines).
The server_info command reports the unscaled minimum XRP cost, as of the previous ledger, as validated_ledger.base_fee_xrp, in the form of decimal XRP. The actual cost necessary to relay a transaction is scaled by multiplying that base_fee_xrp value by the load_factor parameter in the same response, which represents the server's current load level. In other words:
Current Transaction Cost in XRP = base_fee_xrp × load_factor
@@ -156,10 +210,11 @@
You do not know in advance exactly what value you are signing for the Fee field.
-
If you are using rippled, you can also use the fee_mult_max parameter of the sign command to set a limit to the load scaling you are willing to sign.
+
If you are using rippled, you can also use the fee_mult_max and fee_div_max parameters of the sign command to set a limit to the load scaling you are willing to sign.
You cannot look up the current transaction cost from an offline machine.
+
You cannot automatically specify the transaction cost when multi-signing.
Transaction Costs and Failed Transactions
Since the purpose of the transaction cost is to protect the peer-to-peer Ripple network from excessive load, it should apply to any transaction that gets distributed to the network, regardless of whether or not that transaction succeeds. However, in order to affect the shared global ledger, a transaction must be included in a validated ledger. Thus, rippled servers attempt to include failed transactions in ledgers, with tec status codes ("tec" stands for "Transaction Engine - Claimed fee only").
@@ -172,6 +227,7 @@
As a special case, an account can send a SetRegularKey transaction with a transaction cost of 0, as long as the account's lsfPasswordSpent flag is disabled. This transaction must be signed by the account's master key. Sending this transaction enables the lsfPasswordSpent flag.
This feature is designed to allow you to recover an account if the regular key is compromised, without worrying about whether the compromised account has any XRP available. This way, you can regain control of the account before you send additional XRP to it.
The lsfPasswordSpent flag starts out disabled. If enabled, it gets disabled again when the account receives a Payment of XRP.
+
When the FeeEscalation amendment is enabled, rippled prioritizes key reset transactions above other transactions even though the nominal transaction cost of a key reset transaction is zero.
Changing the Transaction Cost
In addition to short-term scaling to account for load, the Ripple Consensus Ledger has a mechanism for changing the minimum transaction cost in order to account for long-term changes in the value of XRP. Any changes have to be approved by the consensus process. See Fee Voting for more information.
diff --git a/content/concept-amendments.md b/content/concept-amendments.md
new file mode 100644
index 0000000000..5598a11146
--- /dev/null
+++ b/content/concept-amendments.md
@@ -0,0 +1,174 @@
+# Amendments #
+
+_(New in [version 0.31.0](https://wiki.ripple.com/Rippled-0.31.0))_
+
+The Amendments system provides a means of introducing new features to the decentralized Ripple consensus network without causing disruptions. The amendments system works by utilizing the core consensus process of the network to approve any changes by showing continuous support before those changes go into effect. An amendment normally requires **80% support for two weeks** before it can apply.
+
+When an Amendment has been enabled, it applies permanently to all ledger versions after the one that included it. You cannot disable an Amendment, unless you introduce a new Amendment to do so.
+
+
+## Background ##
+
+Any changes to transaction processing could cause servers to build a different ledger with the same set of transactions. If only a portion of _validators_ (`rippled` servers [participating in consensus](tutorial-rippled-setup.html#reasons-to-run-a-validator)) have upgraded to a new version of the software, this could cause anything from minor inconveniences to full outages. In the minor case, a minority of servers spend more time and bandwidth fetching the actual consensus ledger because they cannot build it using the transaction processing rules they already know. In the worst case, [the consensus process](https://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/) might be unable to validate new ledger versions because servers with different rules could not reach a consensus on the exact ledger to build.
+
+Amendments provide a solution to this problem, so that new features can be enabled only when enough validators support those features.
+
+Users and businesses who rely on the Ripple Consensus Ledger can also use Amendments to provide advance notice of changes in transaction processing that might affect their business. However, API changes that do not impact transaction processing or [the consensus process](https://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/) do not require Amendments.
+
+
+## About Amendments ##
+
+An amendment is a fully-functional feature or change, waiting to be enabled by the peer-to-peer network as a part of the consensus process. A `rippled` server that wants to use an amendment has code for two modes: without the amendment (previous behavior) and with the amendment (new behavior).
+
+Every amendment has a unique identifying hex value and a short name. The short name is for human use, and is not used in the amendment process. Two servers can support the same amendment ID while using different names to describe it. An amendment's name is not guaranteed to be unique.
+
+See also: [Known Amendments](#known-amendments)
+
+## Amendment Process ##
+
+Every 256th ledger is called a "flag" ledger. The process of approving an amendment starts in the ledger version immediately before the flag ledger. When `rippled` validator servers send validation messages for that ledger, those servers also submit votes in favor of specific amendments. ([Fee Voting](concept-fee-voting.html) also occurs around flag ledgers.)
+
+The flag ledger itself has no special contents. However, during that time, the servers look at the votes of the validators they trust, and decide whether to insert an [`EnableAmendment` pseudo-transaction](reference-transaction-format.html#enableamendment) into the following ledger. The flags of an EnableAmendment pseudo-transaction indicate what the server thinks happened:
+
+* The `tfGotMajority` flag means that support for the amendment has increased to at least 80% of trusted validators.
+* The `tfLostMajority` flag means that support for the amendment has decreased to less than 80% of trusted validators.
+* An EnableAmendment pseudo-transaction with no flags means that support for the amendment has been enabled. (The change in transaction processing applies to every ledger after this one.)
+
+A server only inserts the pseudo-transaction to enable an amendment if all of the following conditions are met:
+
+* The amendment has not already been enabled.
+* A previous ledger includes an EnableAmendment pseudo-transaction for this amendment with the `tfGotMajority` flag enabled.
+* The previous ledger in question is an ancestor of the current ledger.
+* The previous ledger in question has a close time that is at least **two weeks** before the close time of the latest flag ledger.
+* There are no EnableAmendment pseudo-transactions for this amendment with the `tfLostMajority` flag enabled in the consensus ledgers between the `tfGotMajority` pseudo-transaction and the current ledger.
+
+It is theoretically possible (but extremely unlikely) that a `tfLostMajority` EnableAmendment pseudo-transaction could be included in the same ledger as the pseudo-transaction to enable an amendment. In this case, the pseudo-transaction with the `tfLostMajority` pseudo-transaction has no effect.
+
+## Amendment Voting ##
+
+Operators of `rippled` validators can choose which amendments to support or reject using the [`feature` command](reference-rippled.html#feature). This decides which amendments the validator votes for in the [amendment process](#amendment-process). By default, `rippled` votes in favor of every amendment it knows about.
+
+The operator of a `rippled` validator can "veto" an amendment. In this case, that validator never sends a vote in favor of the amendment. If enough servers veto an amendment, that prevents it from reaching consistent 80% support, so the amendment does not apply.
+
+As with all aspects of the consensus process, amendment votes are only taken into account by servers that trust the validators sending those votes. Currently, Ripple (the company) recommends only trusting the 5 default validators that Ripple (the company) operates. For now, trusting only those validators is sufficient to coordinate with Ripple (the company) on releasing new features.
+
+### Configuring Amendment Voting ###
+
+You can temporarily configure an amendment using the [`feature` command](reference-rippled.html#feature). To make a persistent change to your server's support for an amendment, modify your server's `rippled.cfg` file.
+
+Use the `[veto_amendments]` stanza to list amendments you do not want the server to vote for. Each line should contain one amendment's unique ID, optionally followed by the short name for the amendment. For example:
+
+```
+[veto_amendments]
+C1B8D934087225F509BEB5A8EC24447854713EE447D277F69545ABFA0E0FD490 Tickets
+DA1BD556B42D85EA9C84066D028D355B52416734D3283F85E216EA5DA6DB7E13 SusPay
+```
+
+Use the `[amendments]` stanza to list amendments you want to vote for. (Even if you do not list them here, by default a server votes for all the amendments it knows how to apply.) Each line should contain one amendment's unique ID, optionally followed by the short name for the amendment. For example:
+
+```
+[amendments]
+4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373 MultiSign
+42426C4D4F1009EE67080A9B7965B44656D7714D104A72F9B4369F97ABF044EE FeeEscalation
+```
+
+
+## Testing Amendments ##
+
+If you want to see how `rippled` behaves with an amendment enabled, before that amendment gets enabled on the production network, you can run use `rippled`'s configuration file to forcibly enable a feature. This is intended for development purposes only.
+
+Because other members of the consensus network probably do not have the feature enabled, you should not use this feature while connecting to the production network. While testing with features forcibly enabled, you should run `rippled` in [Stand-Alone Mode](concept-stand-alone-mode.html).
+
+To forcibly enable a feature, add a `[features]` stanza to your `rippled.cfg` file. In this stanza, add the short names of the features to enable, one per line. For example:
+
+```
+[features]
+MultiSign
+TrustSetAuth
+```
+
+
+
+# Known Amendments #
+
+The following is a comprehensive list of all known amendments and their status on the production Ripple Consensus Ledger:
+
+| Name | Introduced | Enabled |
+|---------------------------------|------------|---------|
+| [Tickets](#tickets) | v0.31.0 | TBD |
+| [SusPay](#suspay) | v0.31.0 | TBD |
+| [TrustSetAuth](#trustsetauth) | v0.30.0 | TBD |
+| [MultiSign](#multisign) | v0.31.0 | TBD |
+| [FeeEscalation](#feeescalation) | v0.31.0 | TBD |
+
+**Note:** In many cases, an incomplete version of the code for an amendment is present in previous versions of the software. The "Introduced" version in the table above is the first stable version.
+
+## FeeEscalation ##
+
+| Amendment ID |
+|--------------|
+| 42426C4D4F1009EE67080A9B7965B44656D7714D104A72F9B4369F97ABF044EE |
+
+Changes the way the [transaction cost](concept-transaction-cost.html) applies to proposed transactions. Modifies the consensus process to prioritize transactions that pay a higher transaction cost.
+
+This amendment introduces a fixed-size transaction queue for transactions that were not able to be included in the previous consensus round. If the `rippled` servers in the consensus network are under heavy load, they queue the transactions with the lowest transaction cost for later ledgers. Each consensus round prioritizes transactions from the queue with the largest transaction cost (`Fee` value), and includes as many transactions as the consensus network can process. If the transaction queue is full, transactions drop from the queue entirely, starting with the ones that have the lowest transaction cost.
+
+While the consensus network is under heavy load, legitimate users can pay a higher transaction cost to make sure their transactions get processed. The situation persists until the entire backlog of cheap transactions is processed or discarded.
+
+A transaction remains in the queue until one of the following happens:
+
+* It gets applied to a validated ledger (regardless of success or failure)
+* It becomes invalid (for example, the [`LastLedgerSequence`](reference-transaction-format.html#lastledgersequence) causes it to expire)
+* It gets dropped because there are too many transactions in the queue with a higher transaction cost.
+
+## MultiSign ##
+
+| Amendment ID |
+|--------------|
+| 4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373 |
+
+Introduces simple [multi-signing](reference-transaction-format.html#multi-signing) as a way to authorize transactions. Creates the [`SignerList` ledger node type](reference-ledger-format.html#signerlist) and the [`SignerListSet` transaction type](reference-transaction-format.html#signerlistset). Adds the optional `Signers` field to all transaction types. Modifies some transaction result codes.
+
+This amendment allows addresses to have a list of signers who can authorize transactions from that address in a multi-signature. The list has a quorum and 1 to 8 weighted signers. This allows various configurations, such as "any 3-of-5" or "signature from A plus any other two signatures."
+
+Signers can be funded or unfunded addresses. Funded addresses in a signer list can sign using a regular key (if defined) or master key (unless disabled). Unfunded addresses can sign with a master key. Multi-signed transactions have the same permissions as transactions signed with a regular key.
+
+An address with a SignerList can disable the master key even if a regular key is not defined. An address with a SignerList can also remove a regular key even if the master key is disabled. Therefore, the `tecMASTER_DISABLED` transaction result code is renamed `tecNO_ALTERNATIVE_KEY`. The `tecNO_REGULAR_KEY` transaction result is retired and replaced with `tecNO_ALTERNATIVE_KEY`. Additionally, this amendment adds the following new [transaction result codes](reference-transaction-format.html#result-categories):
+
+* `temBAD_SIGNER`
+* `temBAD_QUORUM`
+* `temBAD_WEIGHT`
+* `tefBAD_SIGNATURE`
+* `tefBAD_QUORUM`
+* `tefNOT_MULTI_SIGNING`
+* `tefBAD_AUTH_MASTER`
+
+## SusPay ##
+
+| Amendment ID |
+|--------------|
+| DA1BD556B42D85EA9C84066D028D355B52416734D3283F85E216EA5DA6DB7E13 |
+
+Provides "Suspended Payments" for XRP as a means of escrow within the Ripple Consensus Ledger. Creates the `SuspendedPayment` ledger node type and the new transaction types `SuspendedPaymentCreate`, `SuspendedPaymentFinish`, and `SuspendedPaymentCancel`.
+
+This amendment is still in development. The current version is enabled on the [Ripple Test Net](https://ripple.com/build/ripple-test-net/).
+
+## TrustSetAuth ##
+
+| Amendment ID |
+|--------------|
+| 6781F8368C4771B83E8B821D88F580202BCB4228075297B19E4FDC5233F1EFDC |
+
+Allows pre-authorization of accounting relationships (zero-balance trust lines) when using [Authorized Accounts](tutorial-gateway-guide.html#authorized-accounts).
+
+With this amendment enabled, a `TrustSet` transaction with [`tfSetfAuth` enabled](reference-transaction-format.html#trustset-flags) can create a new [`RippleState` ledger node](reference-ledger-format.html#ripplestate) even if it keeps all the other values of the `RippleState` node in their default state. The new `RippleState` node has the [`lsfLowAuth` or `lsfHighAuth` flag](reference-ledger-format.html#ripplestate-flags) enabled accordingly. The sender of the transaction must have [`lsfRequireAuth` enabled](reference-ledger-format.html#accountroot-flags).
+
+## Tickets ##
+
+| Amendment ID |
+|--------------|
+| C1B8D934087225F509BEB5A8EC24447854713EE447D277F69545ABFA0E0FD490 |
+
+Introduces Tickets as a way to reserve a transaction sequence number for later execution. Creates the `Ticket` ledger node type and the transaction types `TicketCreate` and `TicketCancel`.
+
+This amendment is still in development.
diff --git a/content/concept-freeze.md b/content/concept-freeze.md
index dfbcf5124c..bf3025deb7 100644
--- a/content/concept-freeze.md
+++ b/content/concept-freeze.md
@@ -82,7 +82,7 @@ To enable or disable Individual Freeze on a specific trust line, send a `TrustSe
| LimitAmount.value | String | The amount of currency you trust this counterparty to issue to you, as a quoted number. From the perspective of a gateway, this is typically `"0"`. |
| Flags | Number | To enable a freeze, use a value with the bit `0x00100000` (tfSetFreeze) enabled. To disable a freeze, use a value with the bit `0x00200000` (tfClearFreeze) enabled instead. |
-Set the `Fee`, `Sequence`, and `LastLedgerSequence` parameters [in the typical way](reference-transaction-format.html#signing-and-sending-transactions).
+Set the `Fee`, `Sequence`, and `LastLedgerSequence` parameters [in the typical way](reference-transaction-format.html#signing-and-submitting-transactions).
Example of submitting a TrustSet transaction to enable an individual freeze using the [WebSocket API](reference-rippled.html#websocket-api):
diff --git a/content/concept-reserves.md b/content/concept-reserves.md
index fee741cc24..9f4297f0c6 100644
--- a/content/concept-reserves.md
+++ b/content/concept-reserves.md
@@ -21,6 +21,7 @@ Many objects in the ledger are owned by a particular account, and therefore coun
* [Offers](reference-ledger-format.html#offer) are owned by the account that placed them. An Offer can be automatically removed from the ledger if it is fully consumed or if it is found unfunded during transaction processing. Alternatively, the owner can cancel an offer by sending an [OfferCancel transaction](reference-transaction-format.html#offercancel), or by sending an [OfferCreate transaction](reference-transaction-format.html#offercreate) that contains an `OfferSequence` parameter.
* [Trust lines](reference-ledger-format.html#ripplestate) are shared between two accounts. The owner reserve can apply to one or both of the accounts, depending on whether the fields that account controls are in their default state. See [Contributing to the Owner Reserve](reference-ledger-format.html#contributing-to-the-owner-reserve) for details.
+* A single [SignerList](reference-ledger-format.html#signerlist) counts as 3 to 10 objects for purposes of the owner reserve, depending on how many members it has. See also: [SignerLists and Reserves](reference-ledger-format.html#signerlists-and-reserves).
* [Owner directories](reference-ledger-format.html#directorynode) list all the ledger nodes that contribute to an account's owner reserve. However, the owner directory itself does not count towards the reserve.
#### Owner Reserve Edge Cases ####
@@ -40,4 +41,3 @@ When an account has less XRP than its current reserve requirement, it cannot sen
## Changing the Reserve Requirements ##
The Ripple Consensus Ledger has a mechanism for changing the reserve requirements in order to account for long-term changes in the value of XRP. Any changes have to be approved by the consensus process. See [Fee Voting](concept-fee-voting.html) for more information.
-
diff --git a/content/concept-stand-alone-mode.md b/content/concept-stand-alone-mode.md
new file mode 100644
index 0000000000..f7ed2c06e8
--- /dev/null
+++ b/content/concept-stand-alone-mode.md
@@ -0,0 +1,103 @@
+Stand-Alone Mode
+===============================================================================
+
+You can run `rippled` in stand-alone mode without a consensus of trusted servers. In stand-alone mode, `rippled` does not communicate with any other servers in the Ripple peer-to-peer network, but you can do most of the same actions on your local server only. Stand-alone provides a method for testing `rippled` behavior without being tied to the live network. For example, you can [test the effects of Amendments](concept-amendments.html#testing-amendments) before those Amendments have gone into effect across the decentralized network.
+
+When you run `rippled` in stand-alone mode, you have to tell it what ledger version to start from:
+
+* Create a [new genesis ledger](#new-genesis-ledger) from scratch.
+* [Load an existing ledger version](#load-saved-ledger) from disk.
+
+**Caution:** In stand-alone mode, you must [manually advance the ledger](#advancing-ledgers-in-stand-alone-mode).
+
+New Genesis Ledger
+-------------------------------------------------------------------------------
+In stand-alone mode, you can have `rippled` create a new genesis ledger. This provides a known state, with none of the ledger history from the production Ripple Consensus Ledger. (This is very useful for unit tests, among other things.)
+
+* To start `rippled` in stand-alone mode with a new genesis ledger, use the `-a` and `--start` options:
+
+```
+rippled -a --start --conf=/path/to/rippled.cfg
+```
+
+In a genesis ledger, the [genesis address](reference-rippled.html#special-addresses) holds all 100 billion XRP. The keys of the genesis address are [hardcoded](https://github.com/ripple/rippled/blob/94ed5b3a53077d815ad0dd65d490c8d37a147361/src/ripple/app/ledger/Ledger.cpp#L184) as follows:
+
+**Address:** `rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh`
+
+**Secret:** `snoPBrXtMeMyMHUVTgbuqAfg1SUTb` ("masterpassphrase")
+
+**Caution:** If you create a new genesis ledger, the hard-coded default [Reserve](concept-reserves.html) is **200 XRP** minimum for funding a new address, with an increment of **50 XRP** per object in the ledger. These values are higher than the current reserve requirements of the production network. (See also: [Fee Voting](concept-fee-voting.html))
+
+
+
+Load Saved Ledger
+-------------------------------------------------------------------------------
+You can start with a ledger version that was saved to disk if your `rippled` server was previously synced with the Ripple peer-to-peer network (either the production network or the [Test Net](tutorial-rippled-setup.html#parallel-networks)).
+
+### 1. Start `rippled` normally. ###
+
+To load an existing ledger, you must first retrieve that ledger from the network. Start `rippled` in networked mode as normal:
+
+```
+rippled --conf=/path/to/rippled.cfg
+```
+
+### 2. Wait until `rippled` is synced. ###
+
+Use the [`server_info` command](reference-rippled.html#server-info) to check the state of your server relative to the network. Your server is synced when the `server_state` value shows any of the following values:
+
+* `full`
+* `proposing`
+* `validating`.
+
+### 3. (Optional) Retrieve specific ledger versions. ###
+
+If you only want the most recent ledger, you can skip this step.
+
+If you want to load a specific historical ledger version, use the [`ledger_request` command](reference-rippled.html#ledger-request) to make `rippled` fetch it. If `rippled` does not already have the ledger version, you may have to run the `ledger_request` command multiple times until it has finished retrieving the ledger.
+
+If you want to replay a specific historical ledger version, you must fetch both the ledger version to replay and the ledger version immediately before it.
+
+### 4. Shut down `rippled`. ###
+
+Use the [`stop` command](reference-rippled.html#stop):
+
+```
+rippled stop --conf=/path/to/rippled.cfg
+```
+
+### 5. Start `rippled` in stand-alone mode. ###
+
+To load the most recent ledger version, you can use the `-a` and `--load` options when starting the server:
+
+```
+rippled -a --load --conf=/path/to/rippled.cfg
+```
+
+To instead load a specific historical ledger, use the `--load` parameter along with the `--ledger` parameter, providing the ledger index or identifying hash of the ledger version to load:
+
+```
+rippled -a --load --ledger 19860944 --conf=/path/to/rippled.cfg
+```
+
+### 6. Manually advance the ledger. ###
+
+When you load a ledger with `--ledger` in stand-alone mode, it goes to the current open ledger, so you must [manually advance the ledger](#advancing-ledgers-in-stand-alone-mode):
+
+```
+rippled ledger_accept --conf=/path/to/rippled.cfg
+```
+
+
+Advancing Ledgers in Stand-Alone Mode
+-------------------------------------------------------------------------------
+
+In stand-alone mode, `rippled` does not communicate to other members of the peer-to-peer network or participate in a consensus process. Instead, you must manually advance the ledger index using the [`ledger_accept` command](reference-rippled.html#ledger-accept):
+
+```
+rippled ledger_accept --conf=/path/to/rippled.cfg
+```
+
+In stand-alone mode, `rippled` makes no distinction between a "closed" ledger version and a "validated" ledger version. (For more information about the difference, see [The Ripple Ledger Consensus Process](https://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/).)
+
+Whenever `rippled` closes a ledger, it reorders the transactions according to a deterministic but hard-to-game algorithm. (This is an important part of consensus, since transactions may arrive at different parts of the network in different order.) When using `rippled` in stand-alone mode, you should manually advance the ledger before submitting a transaction that depends on the result of a previous transaction. Otherwise, the second transaction might be executed before the first transaction when you manually advance the ledger. **Note:** You can safely submit multiple transactions from a single address to a single ledger, because `rippled` sorts transactions from the same address in ascending order by `Sequence` number.
diff --git a/content/concept-transaction-cost.md b/content/concept-transaction-cost.md
index cbd5971cf1..35831eec2b 100644
--- a/content/concept-transaction-cost.md
+++ b/content/concept-transaction-cost.md
@@ -7,24 +7,74 @@ Every transaction must [specify how much XRP it will destroy](#specifying-the-tr
## Current Transaction Cost ##
-The current transaction cost required by the network is typically **0.01 XRP** (10,000 drops), although it sometimes increases due to network load.
+The current transaction cost required by the network for a standard transaction is typically **0.01 XRP** (10,000 drops), although it sometimes increases due to network load.
You can also [query `rippled` for the current transaction cost](#querying-the-transaction-cost).
+### Special Transaction Costs ###
+
+Some transactions have different transaction costs:
+
+| Transaction | Cost Before Load Scaling |
+|-----------------------|--------------------------|
+| Reference Transaction (Standard cost of most transactions) | 10 drops |
+| [Key Reset Transaction](#key-reset-transaction) | 0 |
+| [Multi-signed transaction](reference-transaction-format.html#multi-signing) | 10 drops × (1 + Number of Signatures Provided) |
+
## Beneficiaries of the Transaction Cost ##
The transaction cost is not paid to any party: the XRP is irrevocably destroyed. Since no new XRP can ever be created, this makes XRP more scarce, and consequently benefits all holders of XRP by making XRP more valuable.
-## Load Scaling ##
+## Load Cost and Open Ledger Cost ##
+
+When the [FeeEscalation amendment](concept-amendments.html#feeescalation) is enabled, there are two thresholds for the transaction cost:
+
+* If the transaction cost does not meet a `rippled` server's [load-based transaction cost threshold](#local-load-cost), the server ignores the transaction completely. (This logic is essentially unchanged with or without the amendment.)
+* If the transaction cost does not meet a `rippled` server's [open ledger cost threshold](#open-ledger-cost), the server queues the transaction for a later ledger.
+
+This divides transactions into roughly three categories:
+
+* Transactions that specify a transaction cost so low that they get rejected by the load-based transaction cost.
+* Transactions that specify a transaction cost high enough to be included in the current open ledger.
+* Transactions in between, which get [queued for a later ledger version](#queued-transactions).
+
+
+## Local Load Cost ##
+
+Each `rippled` server maintains a cost threshold based on its current load. If you submit a transaction with a `Fee` value that is lower than current load-based transaction cost of the `rippled` server, that server neither applies nor relays the transaction. (**Note:** If you submit a transaction through an [admin connection](reference-rippled.html#connecting-to-rippled), the server applies and relays the transaction as long as the transaction cost meets the overall minimum.) A transaction is very unlikely to survive [the consensus process](https://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/) unless its `Fee` value meets the requirements of a majority of servers.
+
+## Open Ledger Cost ##
+
+A `rippled` server with the [FeeEscalation amendment](concept-amendments.html#feeescalation) enabled has a second mechanism for enforcing the transaction cost, called the _open ledger cost_. The open ledger cost starts out equal to the minimum transaction cost, but increases exponentially when an in-progress ledger has more transactions than the previous one. Only transactions which pay more than the open ledger cost can be included in the current open ledger.
+Transactions that do not meet the open ledger cost are [queued for a following ledger](#queued-transactions) instead.
+
+The open ledger cost requirement is proportional to the normal cost of the transaction, not the absolute transaction cost. Transaction types that have a higher-than-normal requirement, such as [multi-signed transactions](reference-transaction-format.html#multi-signing) must pay more to meet the open ledger cost than transactions which have minimum transaction cost requirements.
+
+See also: [Fee Escalation explanation in `rippled` repository](https://github.com/ripple/rippled/blob/release/src/ripple/app/misc/FeeEscalation.md).
+
+### Queued Transactions ###
+
+(Requires the [FeeEscalation amendment](concept-amendments.html#feeescalation))
+
+When `rippled` receives a transaction that meet the server's local load cost but not the open ledger cost, the server checks the transaction to see if it is "likely to be included" in a later ledger. If so, the server adds the transaction to the transaction queue and relays the transaction to other members of the network. Otherwise, the server discards the transaction. The server tries minimize the amount of network load caused by transactions that would not pay a transaction cost, since [the transaction cost only applies when a transaction is included in a validated ledger](#transaction-costs-and-failed-transactions).
+
+ The `rippled` server uses a variety of heuristics to determine which transactions are "likely to be included in a ledger." Most importantly, those transactions must be properly-formed and [authorized](reference-transaction-format.html#authorizing-transactions) with valid signatures.
+
+When the current open ledger closes and the server starts a new open ledger, the server starts taking transactions from the queue to include in the new open ledger. The transaction queue is sorted with the transactions that would pay the highest transaction cost first, proportional to the un-scaled cost of those transactions. Transactions that pay the same transaction cost are queued in the order the server receives them.
+
+**Note:** As of `rippled` **version 0.31.0**, the transaction queue supports at most 1 transaction per sending address. This is expected to change in later versions.
+
+**Caution:** The current implementation does not allow transactions with an `AccountTxnID` field in the transaction queue.
-Each `rippled` server independently scales the transaction cost based on its current load. If you submit a transaction with a `Fee` value that is lower than current load-based transaction cost of the `rippled` server, that server neither applies nor relays the transaction. (**Note:** If you submit a transaction through an [admin connection](reference-rippled.html#connecting-to-rippled), the server applies and relays the transaction as long as the transaction cost meets the overall minimum.) A transaction is very unlikely to survive [the consensus process](https://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/) unless its `Fee` value meets the requirements of a majority of servers.
## Querying the Transaction Cost ##
-The `rippled` APIs have two ways to query the transaction cost: the `server_info` command (intended for humans) and the `server_state` command (intended for machines).
+The `rippled` APIs have two ways to query the local load-based transaction cost: the `server_info` command (intended for humans) and the `server_state` command (intended for machines).
+
+If the [FeeEscalation amendment](concept-amendments.html#feeescalation) is enabled, you can use the [`fee` command](reference-rippled.html#fee) to check the open ledger cost.
### server_info ###
@@ -57,8 +107,9 @@ When you sign a transaction online, you can omit the `Fee` field. In this case,
* If the network's transaction cost goes up between signing and distributing the transaction, the transaction may not be confirmed.
* In the worst case, the transaction may be stuck in a state of being neither definitively confirmed or rejected, unless it included a `LastLedgerSequence` parameter or until you cancel it with a new transaction that uses the same `Sequence` number. See [reliable transaction submission](tutorial-reliable-transaction-submission.html) for best practices.
* You do not know in advance exactly what value you are signing for the `Fee` field.
- * If you are using `rippled`, you can also use the `fee_mult_max` parameter of the [`sign` command](reference-rippled.html#sign) to set a limit to the load scaling you are willing to sign.
+ * If you are using `rippled`, you can also use the `fee_mult_max` and `fee_div_max` parameters of the [`sign` command](reference-rippled.html#sign) to set a limit to the load scaling you are willing to sign.
* You cannot look up the current transaction cost from an offline machine.
+* You cannot automatically specify the transaction cost when [multi-signing](reference-transaction-format.html#multi-signing).
@@ -85,6 +136,8 @@ This feature is designed to allow you to recover an account if the regular key i
The [lsfPasswordSpent flag](reference-ledger-format.html#accountroot-flags) starts out disabled. If enabled, it gets disabled again when the account receives a [Payment](reference-transaction-format.html#payment) of XRP.
+When the [FeeEscalation amendment](concept-amendments.html#feeescalation) is enabled, `rippled` prioritizes key reset transactions above other transactions even though the nominal transaction cost of a key reset transaction is zero.
+
## Changing the Transaction Cost ##
diff --git a/content/reference-ledger-format.md b/content/reference-ledger-format.md
index 2898ed3b61..4ec642e406 100644
--- a/content/reference-ledger-format.md
+++ b/content/reference-ledger-format.md
@@ -4,20 +4,20 @@ The point of the Ripple software is to maintain a shared, global ledger that is
-The shared global ledger is actually a series of individual ledgers, or ledger versions, which `rippled` keeps in its internal database. Every ledger version has a sequence number (also called a ledger index), starting at 1 and incrementing with each new version. Every closed ledger also has an identifying hash value, which uniquely identifies the contents of that ledger. At any given time, a `rippled` instance has an in-progress "current" open ledger, plus some number of closed ledgers that have not yet been approved by consensus, and any number of historical ledgers that have been validated by consensus. Only the validated ledgers are certain to be accurate and immutable.
+The shared global ledger is actually a series of individual ledgers, or ledger versions, which `rippled` keeps in its internal database. Every ledger version has a [ledger index](#ledger-index) which identifies the order in which ledgers occur. Each closed ledger version also has an identifying hash value, which uniquely identifies the contents of that ledger. At any given time, a `rippled` instance has an in-progress "current" open ledger, plus some number of closed ledgers that have not yet been approved by consensus, and any number of historical ledgers that have been validated by consensus. Only the validated ledgers are certain to be accurate and immutable.
A single ledger version consists of several components:
-* A **header** - The ledger's unique index (sequence number), hashes of the other contents, and other metadata.
+* A **header** - The [ledger index](#ledger-index), hashes of its other contents, and other metadata.
* A **transaction tree** - The [transactions](reference-transaction-format.html) that were applied to the previous ledger to make this one. Transactions are the _only_ way to modify the ledger.
* A **state tree** - All the [ledger nodes](#ledger-node-types) that contain the settings, balances, and objects in the ledger as of this version.
## Tree Format ##
-As its name might suggest, a ledger's state tree is a tree data structure, with each node identified by a 256-bit value called an `index`. In JSON, a ledger node's index value is represented as a 64-character hexadecimal string like `"193C591BF62482468422313F9D3274B5927CA80B4DD3707E42015DD609E39C94"`. Every node in the state tree has an index that you can use as a key to look up the node in the state tree; every transaction has an indentifying hash that you can use to look up the transaction in the transaction tree. Do not confuse the `index` (key) of a ledger node with the `ledger_index` (sequence number) of a ledger.
+As its name might suggest, a ledger's state tree is a tree data structure, with each node identified by a 256-bit value called an `index`. In JSON, a ledger node's index value is represented as a 64-character hexadecimal string like `"193C591BF62482468422313F9D3274B5927CA80B4DD3707E42015DD609E39C94"`. Every node in the state tree has an index that you can use as a key to look up the node in the state tree; every transaction has an indentifying hash that you can use to look up the transaction in the transaction tree. Do not confuse the `index` (key) of a ledger node with the [`ledger_index` (sequence number) of a ledger](#ledger-index).
In the case of transactions, the identifying hash is based on the signed transaction instructions, but the contents of the transaction object when you look it up also contain the results and metadata of the transaction, which are not taken into account when generating the hash.
@@ -33,19 +33,24 @@ Every ledger version has a unique header that describes the contents. You can lo
| Field | JSON Type | [Internal Type][] | Description |
|-----------------|-----------|-------------------|-------------|
-| ledger\_index | String | UInt32 | The sequence number of the ledger. Some API methods display this as a quoted integer; some display it as a native JSON number. |
+| [ledger\_index](#ledger-index) | String | UInt32 | The sequence number of the ledger. Some API methods display this as a quoted integer; some display it as a native JSON number. |
| ledger\_hash | String | Hash256 | The SHA-512Half of the ledger header, excluding the `ledger_hash` itself. This serves as a unique identifier for this ledger and all its contents. |
| account\_hash | String | Hash256 | The SHA-512Half of this ledger's state tree information. |
| close\_time | Number | UInt32 | The approximate time this ledger closed, as the number of seconds since the Ripple Epoch of 2000-01-01 00:00:00. This value is rounded based on the `close_time_resolution`, so it is possible for subsequent ledgers to have the same value. |
| closed | Boolean | bool | If true, this transaction is no longer accepting new transactions. (However, unless this ledger is validated, it might be replaced by a different ledger with a different set of transactions.) |
-| parent\_hash | String | Hash256 | The `ledger_hash` value of the previous ledger that was used to build this one. If there are different versions of the previous ledger by sequence number, this indicates from which one the ledger was derived. |
+| parent\_hash | String | Hash256 | The `ledger_hash` value of the previous ledger that was used to build this one. If there are different versions of the previous ledger index, this indicates from which one the ledger was derived. |
| total\_coins | String | UInt64 | The total number of drops of XRP owned by accounts in the ledger. This subtracts XRP that has been destroyed by transaction fees. The actual amount of XRP in circulation is lower because some accounts are "black holes" whose keys are not known by anyone. |
| transaction\_hash | String | Hash256 | The SHA-512Half of the transactions included in this ledger. |
| close\_time\_resolution | Number | Uint8 | An integer in the range \[2,120\] indicating the maximum number of seconds by which the `close_time` could be rounded. |
-| closeFlags | (Omitted) | UInt8 | A bit-map of flags relating to the closing of this ledger. |
+| [closeFlags](#close-flags) | (Omitted) | UInt8 | A bit-map of flags relating to the closing of this ledger. |
[Internal Type]: https://wiki.ripple.com/Binary_Format
+
+### Ledger Index ###
+{% include 'data_types/ledger_index.md' %}
+[Hash]: reference-rippled.html#hashes
+
### Close Flags ###
Currently, the ledger has only one flag defined for closeFlags: **sLCF_NoConsensusTime** (value `1`). If this flag is enabled, it means that validators were in conflict regarding the correct close time for the ledger, but built otherwise the same ledger, so they declared consensus while "agreeing to disagree" on the close time. In this case, the consensus ledger contains a `close_time` value that is 1 second after that of the previous ledger. (In this case, there is no official close time, but the actual real-world close time is probably 3-6 seconds later than the specified `close_time`.)
@@ -100,7 +105,7 @@ The `AccountRoot` node has the following fields:
| Balance | String | Amount | The account's current XRP balance in drops, represented as a string. |
| OwnerCount | Number | UInt32 | The number of objects this account owns in the ledger, which contributes to its owner reserve. |
| PreviousTxnID | String | Hash256 | The identifying hash of the transaction that most recently modified this node. |
-| PreviousTxnLgrSeq | Number | UInt32 | The sequence number (`ledger_index`) of the ledger that contains the transaction that most recently modified this node. |
+| PreviousTxnLgrSeq | Number | UInt32 | The [index of the ledger](#ledger-index) that contains the transaction that most recently modified this node. |
| AccountTxnID | String | Hash256 | (Optional) The identifying hash of the transaction most recently submitted by this account. |
| RegularKey | String | AccountID | (Optional) The address of a keypair that can be used to sign transactions for this account instead of the master key. Use a [SetRegularKey transaction](reference-transaction-format.html#setregularkey) to change this value. |
| EmailHash | String | Hash128 | (Optional) The md5 hash of an email address. Clients can use this to look up an avatar through services such as [Gravatar](https://en.gravatar.com/). |
@@ -127,7 +132,7 @@ AccountRoot nodes can have the following flag values:
| lsfGlobalFreeze | 0x00400000 | 4194304 | All assets issued by this account are frozen. | asfGlobalFreeze |
| lsfDefaultRipple | 0x00800000 | 8388608 | Enable [rippling](https://ripple.com/knowledge_center/understanding-the-noripple-flag/) on this account's trust lines by default. Required for gateways; discouraged for other accounts. | asfDefaultRipple |
-### AccountRoot index format ###
+### AccountRoot Index Format ###
The `index` of an AccountRoot node is the SHA-512Half of the following values put together:
@@ -201,7 +206,7 @@ Example Directories:
| TakerGetsCurrency | String | Hash160 | (Offer Directories only) The currency code of the TakerGets amount from the offers in this directory. |
| TakerGetsIssuer | String | Hash160 | (Offer Directories only) The issuer of the TakerGets amount from the offers in this directory. |
-### Directory index formats ###
+### Directory Index Formats ###
There are three different formulas for creating the index of a DirectoryNode, depending on whether the DirectoryNode represents:
@@ -275,7 +280,7 @@ An Offer node has the following fields:
| BookNode | String | UInt64 | A hint indicating which page of the offer directory links to this node, in case the directory consists of multiple nodes. |
| OwnerNode | String | UInt64 | A hint indicating which page of the owner directory links to this node, in case the directory consists of multiple nodes. **Note:** The offer does not contain a direct link to the owner directory containing it, since that value can be derived from the `Account`. |
| PreviousTxnID | String | Hash256 | The identifying hash of the transaction that most recently modified this node. |
-| PreviousTxnLgrSeq | Number | UInt32 | The sequence number (`ledger_index`) of the ledger that contains the transaction that most recently modified this node. |
+| PreviousTxnLgrSeq | Number | UInt32 | The [index of the ledger](#ledger-index) that contains the transaction that most recently modified this node. |
| Expiration | Number | UInt32 | (Optional) Indicates the time after which this offer will be considered unfunded. See [Specifying Time](reference-rippled.html#specifying-time) for details. |
### Offer Flags ###
@@ -289,7 +294,7 @@ Offer nodes can have the following flag values:
| lsfPassive | 0x00010000 | 65536 | The node was placed as a passive offer. This has no effect on the node in the ledger. | tfPassive |
| lsfSell | 0x00020000 | 131072 | The node was placed as a sell offer. This has no effect on the node in the ledger (because tfSell only matters if you get a better rate than you asked for, which cannot happen after the node enters the ledger). | tfSell |
-### Offer index format ###
+### Offer Index Format ###
The `index` of an Offer node is the SHA-512Half of the following values put together:
@@ -344,7 +349,7 @@ A RippleState node has the following fields:
| LowLimit | Object | Amount | The limit that the low account has set on the trust line. The `issuer` is the address of the low account that set this limit. |
| HighLimit | Object | Amount | The limit that the high account has set on the trust line. The `issuer` is the address of the high account that set this limit. |
| PreviousTxnID | String | Hash256 | The identifying hash of the transaction that most recently modified this node. |
-| PreviousTxnLgrSeq | Number | UInt32 | The sequence number (`ledger_index`) of the ledger that contains the transaction that most recently modified this node. |
+| PreviousTxnLgrSeq | Number | UInt32 | The [index of the ledger](#ledger-index) that contains the transaction that most recently modified this node. |
| LowNode | String | UInt64 | (Omitted in some historical ledgers) A hint indicating which page of the low account's owner directory links to this node, in case the directory consists of multiple nodes. |
| HighNode | String | UInt64 | (Omitted in some historical ledgers) A hint indicating which page of the high account's owner directory links to this node, in case the directory consists of multiple nodes. |
| LowQualityIn | Number | UInt32 | (Optional) The inbound quality set by the low account, as an integer in the implied ratio LowQualityIn:1,000,000,000. The value 0 is equivalent to 1 billion, or face value. |
@@ -390,7 +395,7 @@ The default state of the two NoRipple flags depends on the state of the [lsfDefa
Fortunately, `rippled` uses lazy evaluation to calculate the owner reserve. This means that even if an account changes the default state of all its trust lines by changing the DefaultRipple flag, that account's reserve stays the same initially. If an account modifies a trust line, `rippled` re-evaluates whether that individual trust line is in its default state and should contribute the owner reserve.
-### RippleState index format ###
+### RippleState Index Format ###
The `index` of a RippleState node is the SHA-512Half of the following values put together:
@@ -398,3 +403,72 @@ The `index` of a RippleState node is the SHA-512Half of the following values put
* The AccountID of the low account
* The AccountID of the high account
* The 160-bit currency code of the trust line(s)
+
+
+## SignerList ##
+[[Source] ](https://github.com/ripple/rippled/blob/6d2e3da30696bd10e3bb11a5ff6d45d2c4dae90f/src/ripple/protocol/impl/LedgerFormats.cpp#L127 "Source")
+
+The `SignerList` node type represents a list of parties that, as a group, are authorized to sign a transaction in place of an individual account. You can create, replace, or remove a SignerList using the [SignerListSet transaction type](reference-transaction-format.html#signerlistset) This node type is introduced by the [MultiSign amendment](concept-amendments.html#multisign). _(New in [version 0.31.0][])_
+
+Example SignerList node:
+
+```
+{
+ "Flags": 0,
+ "LedgerEntryType": "SignerList",
+ "OwnerNode": "0000000000000000",
+ "PreviousTxnID": "5904C0DC72C58A83AEFED2FFC5386356AA83FCA6A88C89D00646E51E687CDBE4",
+ "PreviousTxnLgrSeq": 16061435,
+ "SignerEntries": [
+ {
+ "SignerEntry": {
+ "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
+ "SignerWeight": 2
+ }
+ },
+ {
+ "SignerEntry": {
+ "Account": "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
+ "SignerWeight": 1
+ }
+ },
+ {
+ "SignerEntry": {
+ "Account": "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
+ "SignerWeight": 1
+ }
+ }
+ ],
+ "SignerListID": 0,
+ "SignerQuorum": 3,
+ "index": "A9C28A28B85CD533217F5C0A0C7767666B093FA58A0F2D80026FCC4CD932DDC7"
+}
+```
+
+A SignerList node has the following fields:
+
+| Name | JSON Type | Internal Type | Description |
+|-----------------|-----------|---------------|-------------|
+| OwnerNode | String | UInt64 | A hint indicating which page of the owner directory links to this node, in case the directory consists of multiple nodes. |
+| 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. |
+| 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](concept-amendments.html) allows multiple signer lists for an account, this may change. |
+| PreviousTxnID | String | Hash256 | The identifying hash of the transaction that most recently modified this node. |
+| PreviousTxnLgrSeq | Number | UInt32 | The [index of the ledger](#ledger-index) that contains the transaction that most recently modified this node. |
+
+The `SignerEntries` may be any combination of funded and unfunded addresses that use either secp256k1 or ed25519 keys.
+
+### SignerEntry Object ###
+
+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 | A Ripple 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 node](#accountroot), 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 a component of another multi-signature.
+
+### SignerLists and Reserves ###
+
+A SignerList contributes to its owner's [reserve requirement](concept-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)) or [Offer](#offer) node in the ledger.
diff --git a/content/reference-rippled.md b/content/reference-rippled.md
old mode 100644
new mode 100755
index 4b628ccd16..f89e309979
--- a/content/reference-rippled.md
+++ b/content/reference-rippled.md
@@ -171,6 +171,7 @@ rippled account_info r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 validated true
```
*JSON-RPC*
+
```
HTTP Status: 200 OK
{
@@ -192,6 +193,7 @@ HTTP Status: 200 OK
}
```
*Commandline*
+
```
{
"result": {
@@ -299,6 +301,7 @@ HTTP Status: 200 OK
#### JSON-RPC API Error Response Format ####
Some JSON-RPC requests will respond with an error code on the HTTP layer. In these cases, the response is a plain-text explanation in the response body. For example, if you forgot to specify the command in the `method` parameter, the response is like this:
+
```
HTTP Status: 400 Bad Request
Null method
@@ -322,7 +325,7 @@ When your request results in an error, the entire request is copied back as part
All methods can potentially return any of the following values for the `error` code:
* `unknownCmd` - The request does not contain a [command](#api-methods) that the `rippled` server recognizes.
-* `jsonInvalid1 - (WebSocket only) The request is not a proper JSON object.
+* `jsonInvalid` - (WebSocket only) The request is not a proper JSON object.
* JSON-RPC returns a 400 Bad Request HTTP error in this case instead.
* `missingCommand` - (WebSocket only) The request did not specify a `command` field.
* JSON-RPC returns a 400 Bad Request HTTP error in this case instead.
@@ -330,7 +333,7 @@ All methods can potentially return any of the following values for the `error` c
* `noNetwork` - The server is having trouble connecting to the rest of the Ripple Network (and is not running in stand-alone mode).
* `noCurrent` - The server does not know what the current ledger is, due to high load, network problems, validator failures, incorrect configuration, or some other problem.
* `noClosed` - The server does not have a closed ledger, typically because it has not finished starting up.
-* `wsTextRequired` - (WebSocket only) The request's [opcode](https://tools.ietf.org/html/rfc6455#section-5.2) is not text.
+* `wsTextRequired` - (WebSocket only) The request's [opcode](https://tools.ietf.org/html/rfc6455#section-5.2) is not text.
## Formatting Conventions ##
@@ -377,12 +380,12 @@ Each closed *Ledger* has a [Ledger Index][] and a [Hash][] value. When [Specifyi
Many API methods require you to specify an instance of the ledger, with the data retrieved being considered accurate and up-to-date as of that particular version of the shared ledger. The commands that accept a ledger version all work the same way. There are three ways you can specify which ledger you want to use:
1. Specify a ledger by its [Ledger Index][] in the `ledger_index` parameter. Each closed ledger has an identifying sequence number that is 1 higher than the previously-validated ledger. (The Genesis Ledger has sequence number 0)
-2. Specify a ledger by its [Hash][] value in the `ledger_hash` parameter.
+2. Specify a ledger by its [Hash][] value in the `ledger_hash` parameter.
3. Specify a ledger by one of the following shortcuts, in the `ledger_index` parameter:
- * `validated` for the most recent ledger that has been validated by the whole network
- * `closed` for the most recent ledger that has been closed for modifications and proposed for validation by the node
- * `current` for the node's current working version of the ledger.
-
+ * `validated` for the most recent ledger that has been validated by the whole network
+ * `closed` for the most recent ledger that has been closed for modifications and proposed for validation by the node
+ * `current` for the node's current working version of the ledger.
+
There is also a deprecated `ledger` parameter which accepts any of the above three formats. *Do not* use this parameter; it may be removed without further notice.
If you do not specify a ledger, the `current` (in-progress) ledger will be chosen by default. If you provide more than one field specifying ledgers, the deprecated `ledger` field will be used first if it exists, falling back to `ledger_hash`. The `ledger_index` field is ignored unless neither of the other two are present. __*Note:*__ Do not rely on this default behavior; it is subject to change. Instead, you should always specify a ledger version in each call.
@@ -432,9 +435,9 @@ For example, to represent $153.75 US dollars issued by account `r9cZA1mLK5R5Am25
```
{
- "currency": "USD",
- "value": "153.75",
- "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59"
+ "currency": "USD",
+ "value": "153.75",
+ "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59"
}
```
@@ -520,7 +523,9 @@ API methods for the Websocket and JSON-RPC APIs are defined by command names, an
* [`server_info` - Retrieve status of the server in human-readable format](#server-info)
* [`server_state` - Retrieve status of the server in machine-readable format](#server-state)
* [`sign` - Cryptographically sign a transaction](#sign)
+* [`sign_for` - Contribute to a multi-signature](#sign-for)
* [`submit` - Send a transaction to the network](#submit)
+* [`submit_multisigned` - Send a multi-signed transaction to the network](#submit-multisigned)
* [`subscribe` - Listen for updates about a particular subject](#subscribe)
* [`transaction_entry` - Retrieve info about a transaction from a particular ledger version](#transaction-entry)
* [`tx` - Retrieve info about a transaction from all the ledgers on hand](#tx)
@@ -534,6 +539,7 @@ The `owner_info` command is deprecated. Use [`account_objects`](#account-objects
* [`can_delete` - Allow online deletion of ledgers up to a specific ledger](#can-delete)
* [`connect` - Force the rippled server to connect to a specific peer](#connect)
* [`consensus_info` - Get information about the state of consensus as it happens](#consensus-info)
+* [`feature` - Get information about protocol amendments](#feature)
* [`fetch_info` - Get information about the server's sync with the network](#fetch-info)
* [`get_counts` - Get statistics about the server's internals and memory usage](#get-counts)
* [`ledger_accept` - Close and advance the ledger in stand-alone mode](#ledger-accept)
@@ -548,7 +554,7 @@ The `owner_info` command is deprecated. Use [`account_objects`](#account-objects
* [`validation_seed` - Temporarily set key to be used for validating](#validation-seed)
* [`wallet_propose` - Generate keys for a new account](#wallet-propose)
-The following admin commands are deprecated and may be removed without further notice:
+The following admin commands are deprecated and may be removed without further notice:
* `ledger_header` - Use the [`ledger` command](#ledger) instead.
* `unl_add`, `unl_delete`, `unl_list`, `unl_load`, `unl_network`, `unl_reset`, `unl_score` - Use the configuration file for UNL management instead.
@@ -564,7 +570,7 @@ The `rippled` application, in addition to acting as a server, can be run (as a s
# Account Information #
-Accounts are the core unit of authentication in the Ripple Network. Each account can hold balances in multiple currencies, and all transactions must be signed by an account's secret key. In order for an account to exist in a validated ledger version, it must hold a minimum reserve amount of XRP. (The [reserve for an account](concept-reserves.html) increases with the amount of data it is responsible for in the shared ledger.) It is expected that accounts will correspond loosely to individual users.
+Accounts are the core unit of authentication in the Ripple Network. Each account can hold balances in multiple currencies, and all transactions must be signed by an account's secret key. In order for an account to exist in a validated ledger version, it must hold a minimum reserve amount of XRP. (The [reserve for an account](concept-reserves.html) increases with the amount of data it is responsible for in the shared ledger.) It is expected that accounts will correspond loosely to individual users.
## account_currencies ##
@@ -721,7 +727,7 @@ The response follows the [standard format](#response-formatting), with a success
## account_info ##
[[Source] ](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/AccountInfo.cpp "Source")
-The `account_info` command retrieves information about an account, its activity, and its XRP balance. All information retrieved is relative to a particular version of the ledger.
+The `account_info` command retrieves information about an account, its activity, and its XRP balance. All information retrieved is relative to a particular version of the ledger.
#### Request Format ####
@@ -1108,9 +1114,9 @@ An example of a successful response:
"value": "0.01886995237307572"
}
},
-
+
...
-
+
],
"validated": false
}
@@ -1122,47 +1128,47 @@ An example of a successful response:
```
200 OK
{
- "result": {
- "account": "rpP2JgiMyTF5jR5hLG3xHCPi1knBb1v9cM",
- "ledger_current_index": 18539596,
- "offers": [{
- "flags": 0,
- "quality": "0.000000007599140009999998",
- "seq": 6578020,
- "taker_gets": "29740867287",
- "taker_pays": {
- "currency": "USD",
- "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
- "value": "226.0050145327418"
- }
- }, {
- "flags": 0,
- "quality": "7989247009094510e-27",
- "seq": 6572128,
- "taker_gets": "2361918758",
- "taker_pays": {
- "currency": "XAU",
- "issuer": "rrh7rf1gV2pXAoqA8oYbpHd8TKv5ZQeo67",
- "value": "0.01886995237307572"
- }
- }, {
- "flags": 0,
- "quality": "0.00000004059594001318974",
- "seq": 6576905,
- "taker_gets": "3892952574",
- "taker_pays": {
- "currency": "CNY",
- "issuer": "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y",
- "value": "158.0380691682966"
- }
- },
-
- ...
-
- ],
- "status": "success",
- "validated": false
- }
+ "result": {
+ "account": "rpP2JgiMyTF5jR5hLG3xHCPi1knBb1v9cM",
+ "ledger_current_index": 18539596,
+ "offers": [{
+ "flags": 0,
+ "quality": "0.000000007599140009999998",
+ "seq": 6578020,
+ "taker_gets": "29740867287",
+ "taker_pays": {
+ "currency": "USD",
+ "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
+ "value": "226.0050145327418"
+ }
+ }, {
+ "flags": 0,
+ "quality": "7989247009094510e-27",
+ "seq": 6572128,
+ "taker_gets": "2361918758",
+ "taker_pays": {
+ "currency": "XAU",
+ "issuer": "rrh7rf1gV2pXAoqA8oYbpHd8TKv5ZQeo67",
+ "value": "0.01886995237307572"
+ }
+ }, {
+ "flags": 0,
+ "quality": "0.00000004059594001318974",
+ "seq": 6576905,
+ "taker_gets": "3892952574",
+ "taker_pays": {
+ "currency": "CNY",
+ "issuer": "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y",
+ "value": "158.0380691682966"
+ }
+ },
+
+ ...
+
+ ],
+ "status": "success",
+ "validated": false
+ }
}
```
@@ -1203,7 +1209,7 @@ Each offer object contains the following fields:
## account_objects ##
[[Source] ](https://github.com/ripple/rippled/blob/399c43cae6e90a428e9ce6a988123972b0f03c99/src/ripple/rpc/handlers/AccountObjects.cpp "Source")
-The `account_objects` command returns the raw [ledger format][] for all objects owned by an account, such as [outstanding offers](reference-transaction-format.html#lifecycle-of-an-offer), trust lines in non-default state, and tickets (which are part of forthcoming multi-sign code). For getting the balance of an account's trust lines, we recommend [`account_lines`](#account-lines) instead.
+The `account_objects` command returns the raw [ledger format][] for all objects owned by an account, such as [outstanding offers](reference-transaction-format.html#lifecycle-of-an-offer), trust lines in non-default state, and [signer lists](reference-transaction-format.html#multi-signing). For getting the balance of an account's trust lines, we recommend [`account_lines`](#account-lines) instead.
[ledger format]: reference-ledger-format.html
@@ -1871,7 +1877,7 @@ The request includes the following parameters:
| Field | Type | Description |
|-------|------|-------------|
-| account | String | A unique identifier for the account, most commonly the account's address. |
+| account | String | A unique identifier for the account, most commonly the account's address. |
| ledger\_index\_min | Integer | Use to specify the earliest ledger to include transactions from. A value of `-1` instructs the server to use the earliest validated ledger version available. |
| ledger\_index\_max | Integer | Use to specify the most recent ledger to include transactions from. A value of `-1` instructs the server to use the most recent validated ledger version available. |
| ledger\_hash | String | (Optional) Use instead of ledger\_index\_min and ledger\_index\_max to look for transactions from a single ledger only. (See [Specifying a Ledger](#specifying-ledgers)) |
@@ -3013,30 +3019,30 @@ An example of a successful response:
```
200 OK
{
- "result": {
- "ledger": {
- "accepted": true,
- "account_hash": "B089E7CD4F5167249951611AAEC863D4BF84FF098500E9CB50561F1A89EED825",
- "close_flags": 0,
- "close_time": 508541222,
- "close_time_human": "2016-Feb-11 21:27:02",
- "close_time_resolution": 10,
- "closed": true,
- "hash": "85E6D422F1A3AE0BEA315C4F09CD0B45022312A4BBF0D308246E901536B61157",
- "ledger_hash": "85E6D422F1A3AE0BEA315C4F09CD0B45022312A4BBF0D308246E901536B61157",
- "ledger_index": "18851543",
- "parent_close_time": 508541221,
- "parent_hash": "C382DB117F2D5AAECFBFB43EA509F8E56D6E1D1297CE00C0D02A3EE695ABB78F",
- "seqNum": "18851543",
- "totalCoins": "99998102795090646",
- "total_coins": "99998102795090646",
- "transaction_hash": "BEC71A3CAD11BFC4E4013CD109F220E0850E9A3808B15FAA6DAE4D898970EFAF"
- },
- "ledger_hash": "85E6D422F1A3AE0BEA315C4F09CD0B45022312A4BBF0D308246E901536B61157",
- "ledger_index": 18851543,
- "status": "success",
- "validated": true
- }
+ "result": {
+ "ledger": {
+ "accepted": true,
+ "account_hash": "B089E7CD4F5167249951611AAEC863D4BF84FF098500E9CB50561F1A89EED825",
+ "close_flags": 0,
+ "close_time": 508541222,
+ "close_time_human": "2016-Feb-11 21:27:02",
+ "close_time_resolution": 10,
+ "closed": true,
+ "hash": "85E6D422F1A3AE0BEA315C4F09CD0B45022312A4BBF0D308246E901536B61157",
+ "ledger_hash": "85E6D422F1A3AE0BEA315C4F09CD0B45022312A4BBF0D308246E901536B61157",
+ "ledger_index": "18851543",
+ "parent_close_time": 508541221,
+ "parent_hash": "C382DB117F2D5AAECFBFB43EA509F8E56D6E1D1297CE00C0D02A3EE695ABB78F",
+ "seqNum": "18851543",
+ "totalCoins": "99998102795090646",
+ "total_coins": "99998102795090646",
+ "transaction_hash": "BEC71A3CAD11BFC4E4013CD109F220E0850E9A3808B15FAA6DAE4D898970EFAF"
+ },
+ "ledger_hash": "85E6D422F1A3AE0BEA315C4F09CD0B45022312A4BBF0D308246E901536B61157",
+ "ledger_index": 18851543,
+ "status": "success",
+ "validated": true
+ }
}
```
@@ -3895,7 +3901,7 @@ There are several sources of complication in transactions. Unlike traditional ba
## tx ##
[[Source] ](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/Tx.cpp "Source")
-The `tx` method retrieves information on a single transaction.
+The `tx` method retrieves information on a single transaction.
#### Request Format ####
@@ -4098,7 +4104,7 @@ The response follows the [standard format](#response-formatting), with a success
## transaction_entry ##
[[Source] ](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/TransactionEntry.cpp "Source")
-The `transaction_entry` method retrieves information on a single transaction from a specific ledger version. (The [`tx`](#tx) command, by contrast, searches all ledgers for the specified transaction. We recommend using that method instead.)
+The `transaction_entry` method retrieves information on a single transaction from a specific ledger version. (The [`tx`](#tx) command, by contrast, searches all ledgers for the specified transaction. We recommend using that method instead.)
#### Request Format ####
@@ -4150,7 +4156,7 @@ The request includes the following parameters:
| ledger_index | String or Unsigned Integer| (Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying a Ledger](#specifying-ledgers)) |
| tx_hash | String | Unique hash of the transaction you are looking up |
-__*Note:*__ This method does not support retrieving information from the current in-progress ledger. You must specify a ledger version in either `ledger_index` or `ledger_hash`.
+__*Note:*__ This method does not support retrieving information from the current in-progress ledger. You must specify a ledger version in either `ledger_index` or `ledger_hash`.
#### Response Format ####
@@ -5209,11 +5215,11 @@ The fields included in each transaction object vary slightly depending on the ty
## path_find ##
[[Source] ](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/PathFind.cpp "Source")
-*WebSocket API only!* The `path_find` method searches for a [path](concept-paths.html) along which a transaction can possibly be made, and periodically sends updates when the path changes over time. For a simpler version that is supported by JSON-RPC, see [`ripple_path_find`](#ripple-path-find). For payments occurring strictly in XRP, it is not necessary to find a path, because XRP can be sent directly to any account.
+*WebSocket API only!* The `path_find` method searches for a [path](concept-paths.html) along which a transaction can possibly be made, and periodically sends updates when the path changes over time. For a simpler version that is supported by JSON-RPC, see [`ripple_path_find`](#ripple-path-find). For payments occurring strictly in XRP, it is not necessary to find a path, because XRP can be sent directly to any account.
There are three different modes, or sub-commands, of the path_find command. Specify which one you want with the `subcommand` parameter:
-* `create` - Start sending pathfinding information
+* `create` - Start sending pathfinding information
* `close` - Stop sending pathfinding information
* `status` - Get the information of the currently-open pathfinding request
@@ -6146,7 +6152,7 @@ An example of the request format:
"TransactionType" : "Payment",
"Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
- "Amount" : {
+ "Amount" : {
"currency" : "USD",
"value" : "1",
"issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
@@ -6206,7 +6212,7 @@ The server automatically attempts to fill in certain fields from the `tx_json` o
* `Sequence` - The server automatically uses the next Sequence number from the sender's account information. Be careful: the next sequence number for the account is not incremented until this transaction is applied. If you sign multiple transactions without submitting and waiting for the response to each one, you must provide the correct sequence numbers in the request. Automatically filled unless `offline` is true.
* `Fee` - If you omit the `Fee` parameter, the server [automatically provides an appropriate transaction cost](concept-transaction-cost.html#automatically-specifying-the-transaction-cost) unless you specified `offline` as true. If you specify `offline` as true, you must fill in the transaction cost in the `Fee` parameter. Be careful: a malicious server can specify an excessively high transaction cost.
* If `fee_mult_max` is included, and the automatically provided `Fee` value is greater than the long-term base transaction cost times `fee_mult_max`, then the transaction fails with the error `rpcHIGH_FEE`. This way, you can let the server fill in the current minimum `Fee` value as long as the current load-based transaction cost is not too high.
-* `Paths` - For Payment-type transactions (excluding XRP-to-XRP transfers), the Paths field can be automatically filled, as if you did a [ripple_path_find](#ripple-path-find). Only filled if `build_path` is provided.
+* `Paths` - For Payment-type transactions (excluding XRP-to-XRP transfers), the Paths field can be automatically filled, as if you did a [ripple_path_find](#ripple-path-find). Only filled if `build_path` is provided.
#### Response Format ####
@@ -6293,17 +6299,249 @@ __*Caution:*__ If this command results in an error messages, the message can con
* `noPath` - The transaction did not include paths, and the server was unable to find a path by which this payment can occur.
+## sign_for ##
+[[Source] ](https://github.com/ripple/rippled/blob/release/src/ripple/rpc/handlers/SignFor.cpp "Source")
+
+The `sign_for` command provides one signature for a [multi-signed transaction](reference-transaction-format.html#multi-signing).
+
+This command requires the [MultiSign amendment](concept-amendments.html#multisign) to be enabled. _(New in [version 0.31.0][])_
+
+#### Request Format ####
+An example of the request format:
+
+
+
+*WebSocket*
+
+```
+{
+ "id": "sign_for_example",
+ "command": "sign_for",
+ "account": "rLFd1FzHMScFhLsXeaxStzv3UC97QHGAbM",
+ "seed": "s████████████████████████████",
+ "key_type": "ed25519",
+ "tx_json": {
+ "TransactionType": "TrustSet",
+ "Account": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
+ "Flags": 262144,
+ "LimitAmount": {
+ "currency": "USD",
+ "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
+ "value": "100"
+ },
+ "Sequence": 2,
+ "SigningPubKey": "",
+ "Fee": "30000"
+ }
+}
+```
+
+*JSON-RPC*
+
+```
+POST http://localhost:5005/
+{
+ "method": "sign_for",
+ "params": [{
+ "account": "rLFd1FzHMScFhLsXeaxStzv3UC97QHGAbM",
+ "seed": "s████████████████████████████",
+ "key_type": "ed25519",
+ "tx_json": {
+ "TransactionType": "TrustSet",
+ "Account": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
+ "Flags": 262144,
+ "LimitAmount": {
+ "currency": "USD",
+ "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
+ "value": "100"
+ },
+ "Sequence": 2,
+ "SigningPubKey": "",
+ "Fee": "30000"
+ }
+ }]
+}
+```
+
+*Commandline*
+
+```
+#Syntax: rippled sign_for [offline]
+rippled sign_for rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW s████████████████████████████ '{
+ "TransactionType": "TrustSet",
+ "Account": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
+ "Flags": 262144,
+ "LimitAmount": {
+ "currency": "USD",
+ "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
+ "value": "100"
+ },
+ "Sequence": 2,
+ "SigningPubKey": "",
+ "Fee": "30000"
+}'
+```
+
+
+
+The request includes the following parameters:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| account | String - [Address][] | The address which is providing the signature. |
+| tx\_json | Object | The [Transaction](reference-transaction-format.html) to sign. Unlike using the [`sign` command](#sign), all fields of the transaction must be provided, including `Fee` and `Sequence`. The transaction must include the field `SigningPubKey` with an empty string as the value. The object may optionally contain a `Signers` array with previously-collected signatures. |
+| secret | String | (Optional) The secret key to sign with. (Cannot be used with `key_type`.) |
+| passphrase | String | (Optional) A passphrase to use as the secret key to sign with. |
+| seed | String | (Optional) A base-58-encoded secret key to sign with. |
+| seed\_hex | String | (Optional) A hexadecimal secret key to sign with. |
+| key\_type | String | (Optional) The type of key to use for signing. This can be `secp256k1` or `ed25519`. (Ed25519 support is experimental.) |
+
+You must provide exactly 1 field with the secret key. You can use any of the following fields: `secret`, `passphrase`, `seed`, or `seed_hex`.
+
+#### Response Format ####
+
+An example of a successful response:
+
+
+
+*WebSocket*
+
+```
+{
+ "id": "sign_for_example",
+ "status": "success",
+ "type": "response",
+ "result": {
+ "tx_blob": "1200142200040000240000000263D5038D7EA4C680000000000000000000000000005553440000000000B5F762798A53D543A014CAF8B297CFF8F2F937E868400000000000753073008114A3780F5CB5A44D366520FC44055E8ED44D9A2270F3E0107321EDDF4ECB8F34A168143B928D48EFE625501FB8552403BBBD3FC038A5788951D7707440C3DCA3FEDE6D785398EEAB10A46B44047FF1B0863FC4313051FB292C991D1E3A9878FABB301128FE4F86F3D8BE4706D53FA97F5536DBD31AF14CD83A5ACDEB068114D96CB910955AB40A0E987EEE82BB3CEDD4441AAAE1F1",
+ "tx_json": {
+ "Account": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
+ "Fee": "30000",
+ "Flags": 262144,
+ "LimitAmount": {
+ "currency": "USD",
+ "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
+ "value": "100"
+ },
+ "Sequence": 2,
+ "Signers": [
+ {
+ "Signer": {
+ "Account": "rLFd1FzHMScFhLsXeaxStzv3UC97QHGAbM",
+ "SigningPubKey": "EDDF4ECB8F34A168143B928D48EFE625501FB8552403BBBD3FC038A5788951D770",
+ "TxnSignature": "C3DCA3FEDE6D785398EEAB10A46B44047FF1B0863FC4313051FB292C991D1E3A9878FABB301128FE4F86F3D8BE4706D53FA97F5536DBD31AF14CD83A5ACDEB06"
+ }
+ }
+ ],
+ "SigningPubKey": "",
+ "TransactionType": "TrustSet",
+ "hash": "5216A13A3E3CF662352F0B430C7D82B7450415B6883DD428B5EC1DF1DE45DD8C"
+ }
+ }
+}
+```
+
+*JSON-RPC*
+
+```
+200 OK
+{
+ "result" : {
+ "status" : "success",
+ "tx_blob" : "1200142200040000240000000263D5038D7EA4C680000000000000000000000000005553440000000000B5F762798A53D543A014CAF8B297CFF8F2F937E868400000000000753073008114A3780F5CB5A44D366520FC44055E8ED44D9A2270F3E010732102B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF744730450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E58114204288D2E47F8EF6C99BCC457966320D12409711E1F1",
+ "tx_json" : {
+ "Account" : "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
+ "Fee" : "30000",
+ "Flags" : 262144,
+ "LimitAmount" : {
+ "currency" : "USD",
+ "issuer" : "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
+ "value" : "100"
+ },
+ "Sequence" : 2,
+ "Signers" : [
+ {
+ "Signer" : {
+ "Account" : "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
+ "SigningPubKey" : "02B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF",
+ "TxnSignature" : "30450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E5"
+ }
+ }
+ ],
+ "SigningPubKey" : "",
+ "TransactionType" : "TrustSet",
+ "hash" : "A94A6417D1A7AAB059822B894E13D322ED3712F7212CE9257801F96DE6C3F6AE"
+ }
+ }
+}
+```
+
+*Commandline*
+
+```
+Loading: "/etc/rippled.cfg"
+Connecting to 127.0.0.1:5005
+{
+ "result" : {
+ "status" : "success",
+ "tx_blob" : "1200142200040000240000000263D5038D7EA4C680000000000000000000000000005553440000000000B5F762798A53D543A014CAF8B297CFF8F2F937E868400000000000753073008114A3780F5CB5A44D366520FC44055E8ED44D9A2270F3E010732102B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF744730450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E58114204288D2E47F8EF6C99BCC457966320D12409711E1F1",
+ "tx_json" : {
+ "Account" : "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
+ "Fee" : "30000",
+ "Flags" : 262144,
+ "LimitAmount" : {
+ "currency" : "USD",
+ "issuer" : "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
+ "value" : "100"
+ },
+ "Sequence" : 2,
+ "Signers" : [
+ {
+ "Signer" : {
+ "Account" : "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
+ "SigningPubKey" : "02B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF",
+ "TxnSignature" : "30450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E5"
+ }
+ }
+ ],
+ "SigningPubKey" : "",
+ "TransactionType" : "TrustSet",
+ "hash" : "A94A6417D1A7AAB059822B894E13D322ED3712F7212CE9257801F96DE6C3F6AE"
+ }
+ }
+}
+```
+
+
+
+The response follows the [standard format](#response-formatting), with a successful result containing the following fields:
+
+| Field | Type | Description |
+|----------|------|-------------|
+| tx\_blob | String | Hexadecimal representation of the signed transaction, including the newly-added signature. If it has enough signatures, you can [submit this string using the `submit` command](#submit-only-mode). |
+| tx\_json | Object | The [transaction specification](reference-transaction-format.html) in JSON format, with the newly-added signature in the `Signers` array. If it has enough signatures, you can submit this object using the [`submit_multisigned` command](#submit-multisigned). |
+
+#### Possible Errors ####
+
+* Any of the [universal error types](#universal-errors).
+* `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
+* `srcActNotFound` - If the `Account` from the transaction is not a funded address in the ledger.
+* `srcActMalformed` - If the signing address (`account` field) from the request is not validly formed.
+* `badSeed` - The seed value supplied was invalidly-formatted.
+* `badSecret` - The secret value supplied was invalidly-formatted.
+
+
+
## submit ##
[[Source] ](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/Submit.cpp "Source")
-The `submit` method sends a [transaction](reference-transaction-format.html) to the network to be confirmed and included in future ledgers.
+The `submit` method applies a [transaction](reference-transaction-format.html) and sends it to the network to be confirmed and included in future ledgers.
This command has two modes:
* Submit-only mode takes a signed, serialized transaction as a binary blob, and submits it to the network as-is. Since signed transaction objects are immutable, no portion of the transaction can be modified or automatically filled in after submission.
* Sign-and-submit mode takes a JSON-formatted Transaction object, completes and signs the transaction in the same manner as the [sign command](#sign), and then submits the signed transaction. We recommend only using this mode for testing and development.
-To send a transaction as robustly as possible, you should construct and [`sign`](#sign) it in advance, persist it somewhere that you can access even after a power outage, then `submit` it as a `tx_blob`. After submission, monitor the network with the [`tx`](#tx) command to see if the transaction was successfully applied; if a restart or other problem occurs, you can safely re-submit the `tx_blob` transaction: it won't be applied twice since it has the same sequence number as the old transaction.
+To send a transaction as robustly as possible, you should construct and [`sign`](#sign) it in advance, persist it somewhere that you can access even after a power outage, then `submit` it as a `tx_blob`. After submission, monitor the network with the [`tx`](#tx) command to see if the transaction was successfully applied; if a restart or other problem occurs, you can safely re-submit the `tx_blob` transaction: it won't be applied twice since it has the same sequence number as the old transaction.
### Submit-Only Mode ###
@@ -6381,7 +6619,7 @@ An example of the request format:
"TransactionType" : "Payment",
"Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
- "Amount" : {
+ "Amount" : {
"currency" : "USD",
"value" : "1",
"issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
@@ -6495,13 +6733,13 @@ The response follows the [standard format](#response-formatting), with a success
| Field | Type | Description |
|-------|------|-------------|
-| engine_result | String | Code indicating the status of the transaction, for example `tesSUCCESS` |
-| engine_result_code | Integer | Numeric code indicating the status of the transaction, directly correlated to `engine_result` |
-| engine_result_message | String | Human-readable explanation of the status of the transaction |
+| engine_result | String | Code indicating the preliminary result of the transaction, for example `tesSUCCESS` |
+| engine_result_code | Integer | Numeric code indicating the preliminary result of the transaction, directly correlated to `engine_result` |
+| engine_result_message | String | Human-readable explanation of the transaction's preliminary result |
| tx_blob | String | The complete transaction in hex string format |
| tx_json | Object | The complete transaction in JSON format |
-__*Caution:*__ Even if the WebSocket response has `"status":"success"`, indicating that the command was successfully received, that does not necessarily indicate that the transaction has taken place. There are many cases that can prevent a transaction from processing successfully, such as a lack of trust lines connecting the two accounts in a payment, or changes in the state of the network since the time the transaction was constructed. Even if nothing is wrong, it may take several seconds to close and validate the ledger version that includes the transaction. See the [full list of transaction responses](reference-transaction-format.html#full-transaction-response-list) for details, and do not consider the transaction's results final until they appear in a validated ledger version.
+__*Caution:*__ Even if the WebSocket response has `"status":"success"`, indicating that the command was successfully received, that does _not_ indicate that the transaction executed successfully. Many situations can prevent a transaction from processing successfully, such as a lack of trust lines connecting the two accounts in a payment, or changes in the state of the ledger since the time the transaction was constructed. Even if nothing is wrong, it may take several seconds to close and validate the ledger version that includes the transaction. See the [full list of transaction responses](reference-transaction-format.html#full-transaction-response-list) for details, and do not consider the transaction's results final until they appear in a validated ledger version.
__*Caution:*__ If this command results in an error messages, the message can contain an account secret, if one was provided in the request. (This is not a problem if the request contained a signed tx_blob instead.) Make sure that these errors are not visible to others, including:
@@ -6523,6 +6761,259 @@ __*Caution:*__ If this command results in an error messages, the message can con
* `internalJson` - An internal error occurred when serializing the transaction to JSON. This could be caused by many aspects of the transaction, including a bad signature or some fields being malformed.
+## submit_multisigned ##
+[[Source] ](https://github.com/ripple/rippled/blob/release/src/ripple/rpc/handlers/SubmitMultiSigned.cpp "Source")
+
+The `submit_multisigned` command applies a [multi-signed](reference-transaction-format.html#multi-signing) transaction and sends it to the network to be included in future ledgers. (You can also submit multi-signed transactions in binary form using the [`submit` command in submit-only mode](#submit-only-mode).)
+
+This command requires the [MultiSign amendment](concept-amendments.html#multisign) to be enabled. _(New in [version 0.31.0][])_
+
+#### Request Format ####
+An example of the request format:
+
+
+
+*WebSocket*
+
+```
+{
+ "id": "submit_multisigned_example"
+ "command": "submit_multisigned",
+ "tx_json": {
+ "Account": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
+ "Fee": "30000",
+ "Flags": 262144,
+ "LimitAmount": {
+ "currency": "USD",
+ "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
+ "value": "100"
+ },
+ "Sequence": 2,
+ "Signers": [{
+ "Signer": {
+ "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
+ "SigningPubKey": "02B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF",
+ "TxnSignature": "30450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E5"
+ }
+ }, {
+ "Signer": {
+ "Account": "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
+ "SigningPubKey": "028FFB276505F9AC3F57E8D5242B386A597EF6C40A7999F37F1948636FD484E25B",
+ "TxnSignature": "30440220680BBD745004E9CFB6B13A137F505FB92298AD309071D16C7B982825188FD1AE022004200B1F7E4A6A84BB0E4FC09E1E3BA2B66EBD32F0E6D121A34BA3B04AD99BC1"
+ }
+ }],
+ "SigningPubKey": "",
+ "TransactionType": "TrustSet",
+ "hash": "BD636194C48FD7A100DE4C972336534C8E710FD008C0F3CF7BC5BF34DAF3C3E6"
+ }
+}
+```
+
+*JSON-RPC*
+
+```
+{
+ "method": "submit_multisigned",
+ "params": [
+ {
+ "tx_json": {
+ "Account": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
+ "Fee": "30000",
+ "Flags": 262144,
+ "LimitAmount": {
+ "currency": "USD",
+ "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
+ "value": "0"
+ },
+ "Sequence": 4,
+ "Signers": [
+ {
+ "Signer": {
+ "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
+ "SigningPubKey": "02B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF",
+ "TxnSignature": "3045022100CC9C56DF51251CB04BB047E5F3B5EF01A0F4A8A549D7A20A7402BF54BA744064022061EF8EF1BCCBF144F480B32508B1D10FD4271831D5303F920DE41C64671CB5B7"
+ }
+ },
+ {
+ "Signer": {
+ "Account": "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
+ "SigningPubKey": "03398A4EDAE8EE009A5879113EAA5BA15C7BB0F612A87F4103E793AC919BD1E3C1",
+ "TxnSignature": "3045022100FEE8D8FA2D06CE49E9124567DCA265A21A9F5465F4A9279F075E4CE27E4430DE022042D5305777DA1A7801446780308897699412E4EDF0E1AEFDF3C8A0532BDE4D08"
+ }
+ }
+ ],
+ "SigningPubKey": "",
+ "TransactionType": "TrustSet",
+ "hash": "81A477E2A362D171BB16BE17B4120D9F809A327FA00242ABCA867283BEA2F4F8"
+ }
+ }
+ ]
+}
+```
+
+*Commandline*
+
+```
+#Syntax: submit_multisigned
+rippled submit_multisigned '{
+ "Account": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
+ "Fee": "30000",
+ "Flags": 262144,
+ "LimitAmount": {
+ "currency": "USD",
+ "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
+ "value": "0"
+ },
+ "Sequence": 4,
+ "Signers": [
+ {
+ "Signer": {
+ "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
+ "SigningPubKey": "02B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF",
+ "TxnSignature": "3045022100CC9C56DF51251CB04BB047E5F3B5EF01A0F4A8A549D7A20A7402BF54BA744064022061EF8EF1BCCBF144F480B32508B1D10FD4271831D5303F920DE41C64671CB5B7"
+ }
+ },
+ {
+ "Signer": {
+ "Account": "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
+ "SigningPubKey": "03398A4EDAE8EE009A5879113EAA5BA15C7BB0F612A87F4103E793AC919BD1E3C1",
+ "TxnSignature": "3045022100FEE8D8FA2D06CE49E9124567DCA265A21A9F5465F4A9279F075E4CE27E4430DE022042D5305777DA1A7801446780308897699412E4EDF0E1AEFDF3C8A0532BDE4D08"
+ }
+ }
+ ],
+ "SigningPubKey": "",
+ "TransactionType": "TrustSet",
+ "hash": "81A477E2A362D171BB16BE17B4120D9F809A327FA00242ABCA867283BEA2F4F8"
+}'
+```
+
+
+
+The request includes the following parameters:
+
+| Field | Type | Description |
+|----------|--------|-------------|
+| tx\_json | Object | [Transaction in JSON format](reference-transaction-format.html) with an array of `Signers`. To be successful, the weights of the signatures must be equal or higher than the quorum of the [SignerList](reference-ledger-format.html#signerlist). |
+| fail\_hard | Boolean | (Optional, defaults to false) If true, and the transaction fails locally, do not retry or relay the transaction to other servers. |
+
+#### Response Format ####
+
+An example of a successful response:
+
+
+
+*WebSocket*
+
+```
+{
+ "id": "submit_multisigned_example",
+ "status": "success",
+ "type": "response",
+ "result": {
+ "engine_result": "tesSUCCESS",
+ "engine_result_code": 0,
+ "engine_result_message": "The transaction was applied. Only final in a validated ledger.",
+ "tx_blob": "1200142200040000240000000263D5038D7EA4C680000000000000000000000000005553440000000000B5F762798A53D543A014CAF8B297CFF8F2F937E868400000000000753073008114A3780F5CB5A44D366520FC44055E8ED44D9A2270F3E010732102B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF744730450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E58114204288D2E47F8EF6C99BCC457966320D12409711E1E0107321028FFB276505F9AC3F57E8D5242B386A597EF6C40A7999F37F1948636FD484E25B744630440220680BBD745004E9CFB6B13A137F505FB92298AD309071D16C7B982825188FD1AE022004200B1F7E4A6A84BB0E4FC09E1E3BA2B66EBD32F0E6D121A34BA3B04AD99BC181147908A7F0EDD48EA896C3580A399F0EE78611C8E3E1F1",
+ "tx_json": {
+ "Account": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
+ "Fee": "30000",
+ "Flags": 262144,
+ "LimitAmount": {
+ "currency": "USD",
+ "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
+ "value": "100"
+ },
+ "Sequence": 2,
+ "Signers": [
+ {
+ "Signer": {
+ "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
+ "SigningPubKey": "02B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF",
+ "TxnSignature": "30450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E5"
+ }
+ },
+ {
+ "Signer": {
+ "Account": "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
+ "SigningPubKey": "028FFB276505F9AC3F57E8D5242B386A597EF6C40A7999F37F1948636FD484E25B",
+ "TxnSignature": "30440220680BBD745004E9CFB6B13A137F505FB92298AD309071D16C7B982825188FD1AE022004200B1F7E4A6A84BB0E4FC09E1E3BA2B66EBD32F0E6D121A34BA3B04AD99BC1"
+ }
+ }
+ ],
+ "SigningPubKey": "",
+ "TransactionType": "TrustSet",
+ "hash": "BD636194C48FD7A100DE4C972336534C8E710FD008C0F3CF7BC5BF34DAF3C3E6"
+ }
+ }
+}
+```
+
+*JSON-RPC*
+
+```
+200 OK
+{
+ "result": {
+ "engine_result": "tesSUCCESS",
+ "engine_result_code": 0,
+ "engine_result_message": "The transaction was applied. Only final in a validated ledger.",
+ "status": "success",
+ "tx_blob": "120014220004000024000000046380000000000000000000000000000000000000005553440000000000B5F762798A53D543A014CAF8B297CFF8F2F937E868400000000000753073008114A3780F5CB5A44D366520FC44055E8ED44D9A2270F3E010732102B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF74473045022100CC9C56DF51251CB04BB047E5F3B5EF01A0F4A8A549D7A20A7402BF54BA744064022061EF8EF1BCCBF144F480B32508B1D10FD4271831D5303F920DE41C64671CB5B78114204288D2E47F8EF6C99BCC457966320D12409711E1E010732103398A4EDAE8EE009A5879113EAA5BA15C7BB0F612A87F4103E793AC919BD1E3C174473045022100FEE8D8FA2D06CE49E9124567DCA265A21A9F5465F4A9279F075E4CE27E4430DE022042D5305777DA1A7801446780308897699412E4EDF0E1AEFDF3C8A0532BDE4D0881143A4C02EA95AD6AC3BED92FA036E0BBFB712C030CE1F1",
+ "tx_json": {
+ "Account": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
+ "Fee": "30000",
+ "Flags": 262144,
+ "LimitAmount": {
+ "currency": "USD",
+ "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
+ "value": "0"
+ },
+ "Sequence": 4,
+ "Signers": [
+ {
+ "Signer": {
+ "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
+ "SigningPubKey": "02B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF",
+ "TxnSignature": "3045022100CC9C56DF51251CB04BB047E5F3B5EF01A0F4A8A549D7A20A7402BF54BA744064022061EF8EF1BCCBF144F480B32508B1D10FD4271831D5303F920DE41C64671CB5B7"
+ }
+ },
+ {
+ "Signer": {
+ "Account": "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
+ "SigningPubKey": "03398A4EDAE8EE009A5879113EAA5BA15C7BB0F612A87F4103E793AC919BD1E3C1",
+ "TxnSignature": "3045022100FEE8D8FA2D06CE49E9124567DCA265A21A9F5465F4A9279F075E4CE27E4430DE022042D5305777DA1A7801446780308897699412E4EDF0E1AEFDF3C8A0532BDE4D08"
+ }
+ }
+ ],
+ "SigningPubKey": "",
+ "TransactionType": "TrustSet",
+ "hash": "81A477E2A362D171BB16BE17B4120D9F809A327FA00242ABCA867283BEA2F4F8"
+ }
+ }
+}
+```
+
+
+
+The response follows the [standard format](#response-formatting), with a successful result containing the following fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| engine\_result | String | Code indicating the preliminary result of the transaction, for example `tesSUCCESS` |
+| engine\_result\_code | Integer | Numeric code indicating the preliminary result of the transaction, directly correlated to `engine_result` |
+| engine\_result\_message | String | Human-readable explanation of the preliminary transaction result |
+| tx\_blob | String | The complete [transaction](reference-transaction-format.html) in hex string format |
+| tx\_json | Object | The complete [transaction](reference-transaction-format.html) in JSON format |
+
+#### Possible Errors ####
+
+* Any of the [universal error types](#universal-errors).
+* `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
+* `srcActMalformed` - The `Account` field from the `tx_json` was invalid or missing.
+* `internal` - An internal error occurred. This includes the case where a signature is not valid for the transaction JSON provided.
+
+
+
## book_offers ##
[[Source] ](https://github.com/ripple/rippled/blob/develop/src/ripple/rpc/handlers/BookOffers.cpp "Source")
@@ -6717,7 +7208,7 @@ JSON-RPC support for subscription callbacks is deprecated and may not work as ex
## subscribe ##
[[Source] ](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/Subscribe.cpp "Source")
-The `subscribe` method requests periodic notifications from the server when certain events happen.
+The `subscribe` method requests periodic notifications from the server when certain events happen.
#### Request Format ####
An example of the request format:
@@ -6823,7 +7314,7 @@ An example of a successful response:
The response follows the [standard format](#response-formatting). The fields contained in the response vary depending on what subscriptions were included in the request.
* `accounts` and `accounts_proposed` - No fields returned
-* *Stream: server* - Information about the server status, such as `load_base` (the current load level of the server), `random` (a randomly-generated value), and others, subject to change.
+* *Stream: server* - Information about the server status, such as `load_base` (the current load level of the server), `random` (a randomly-generated value), and others, subject to change.
* *Stream: transactions*, *Stream: transactions_proposed*, and *Stream: validations* - No fields returned
* *Stream: ledger* - Information about the ledgers on hand and current fee schedule, such as `fee_base` (current base fee for transactions in XRP), `fee_ref` (current base fee for transactions in fee units), `ledger_hash` (hash of the latest validated ledger), `reserve_base` (minimum reserve for accounts), and more.
* `books` - No fields returned by default. If `"snapshot": true` is set in the request, returns `offers` (an array of offer definition objects defining the order book)
@@ -7030,12 +7521,12 @@ Transaction stream messages have the following fields:
| Field | Type | Description |
|-------|------|-------------|
| type | String | `transaction` indicates this is the notification of a transaction, which could come from several possible streams. |
-| engine_result | String | String [Transaction result code](reference-transaction-format.html#result-categories) |
-| engine_result_code | Number | Numeric [transaction response code](reference-transaction-format.html#result-categories), if applicable. |
-| engine_result_message | String | Human-readable explanation for the transaction response |
-| ledger_current_index | Unsigned Integer | (Omitted for validated transactions) Sequence number of the current ledger version for which this transaction is currently proposed |
-| ledger_hash | String | (Omitted for unvalidated transactions) Unique hash of the ledger version that includes this transaction, as hex |
-| ledger_index | Unsigned Integer | (Omitted for unvalidated transactions) Sequence number of the ledger version that includes this transaction |
+| engine\_result | String | String [Transaction result code](reference-transaction-format.html#result-categories) |
+| engine\_result\_code | Number | Numeric [transaction response code](reference-transaction-format.html#result-categories), if applicable. |
+| engine\_result\_message | String | Human-readable explanation for the transaction response |
+| ledger\_current\_index | Unsigned Integer | (Omitted for validated transactions) Sequence number of the current ledger version for which this transaction is currently proposed |
+| ledger\_hash | String | (Omitted for unvalidated transactions) Unique hash of the ledger version that includes this transaction, as hex |
+| ledger\_index | Unsigned Integer | (Omitted for unvalidated transactions) Sequence number of the ledger version that includes this transaction |
| meta | Object | (Omitted for unvalidated transactions) Various metadata about the transaction, including which ledger entries it affected |
| transaction | Object | The [definition of the transaction](reference-transaction-format.html) in JSON format |
| validated | Boolean | If true, this transaction is included in a validated ledger. Responses from the `transaction` stream should always be validated. |
@@ -7049,13 +7540,13 @@ Example of a Peer Status stream message:
```
{
- "action": "CLOSING_LEDGER",
- "date": 508546525,
- "ledger_hash": "4D4CD9CD543F0C1EF023CC457F5BEFEA59EEF73E4552542D40E7C4FA08D3C320",
- "ledger_index": 18853106,
- "ledger_index_max": 18853106,
- "ledger_index_min": 18852082,
- "type": "peerStatusChange"
+ "action": "CLOSING_LEDGER",
+ "date": 508546525,
+ "ledger_hash": "4D4CD9CD543F0C1EF023CC457F5BEFEA59EEF73E4552542D40E7C4FA08D3C320",
+ "ledger_index": 18853106,
+ "ledger_index_max": 18853106,
+ "ledger_index_min": 18852082,
+ "type": "peerStatusChange"
}
```
@@ -7085,132 +7576,132 @@ The `action` field of a Peer Status stream message can have the following values
### Order Book Streams ###
-When you subscribe to one or more order books with the `books` field, you get back any transactions that affect those order books.
+When you subscribe to one or more order books with the `books` field, you get back any transactions that affect those order books.
Example order book stream message:
```
{
- "engine_result": "tesSUCCESS",
- "engine_result_code": 0,
- "engine_result_message": "The transaction was applied. Only final in a validated ledger.",
- "ledger_hash": "08547DD866F099CCB3666F113116B7AA2DF520FA2E3011DD1FF9C9C04A6C7C3E",
- "ledger_index": 18852105,
- "meta": {
- "AffectedNodes": [{
- "ModifiedNode": {
- "FinalFields": {
- "Account": "rfCFLzNJYvvnoGHWQYACmJpTgkLUaugLEw",
- "AccountTxnID": "D295E2BE50E3B78AED24790D7B9096996DAF43F095BF17DB83EEACC283D14050",
- "Balance": "3070332374272",
- "Flags": 0,
- "OwnerCount": 23,
- "RegularKey": "r9S56zu6QeJD5d8A7QMfLAeYavgB9dhaX4",
- "Sequence": 12142921
- },
- "LedgerEntryType": "AccountRoot",
- "LedgerIndex": "2880A9B4FB90A306B576C2D532BFE390AB3904642647DCF739492AA244EF46D1",
- "PreviousFields": {
- "AccountTxnID": "3CA3422B0E42D76A7A677B0BA0BE72DFCD93676E0C80F8D2EB27C04BD8457A0F",
- "Balance": "3070332385272",
- "Sequence": 12142920
- },
- "PreviousTxnID": "3CA3422B0E42D76A7A677B0BA0BE72DFCD93676E0C80F8D2EB27C04BD8457A0F",
- "PreviousTxnLgrSeq": 18852102
- }
- }, {
- "ModifiedNode": {
- "FinalFields": {
- "Flags": 0,
- "IndexPrevious": "00000000000022D2",
- "Owner": "rfCFLzNJYvvnoGHWQYACmJpTgkLUaugLEw",
- "RootIndex": "F435FBBEC9654204D7151A01E686BAA8CB325A472D7B61C7916EA58B59355767"
- },
- "LedgerEntryType": "DirectoryNode",
- "LedgerIndex": "29A543B6681AD7FC8AFBD1386DAE7385F02F9B8C4756A467DF6834AB54BBC9DB"
- }
- }, {
- "ModifiedNode": {
- "FinalFields": {
- "ExchangeRate": "4C1BA999A513EF78",
- "Flags": 0,
- "RootIndex": "79C54A4EBD69AB2EADCE313042F36092BE432423CC6A4F784C1BA999A513EF78",
- "TakerGetsCurrency": "0000000000000000000000000000000000000000",
- "TakerGetsIssuer": "0000000000000000000000000000000000000000",
- "TakerPaysCurrency": "0000000000000000000000005553440000000000",
- "TakerPaysIssuer": "2ADB0B3959D60A6E6991F729E1918B7163925230"
- },
- "LedgerEntryType": "DirectoryNode",
- "LedgerIndex": "79C54A4EBD69AB2EADCE313042F36092BE432423CC6A4F784C1BA999A513EF78"
- }
- }, {
- "CreatedNode": {
- "LedgerEntryType": "Offer",
- "LedgerIndex": "92E235EE80D2B28A89BEE2C905D4545C2A004FD5D4097679C8A3FB25507FD9EB",
- "NewFields": {
- "Account": "rfCFLzNJYvvnoGHWQYACmJpTgkLUaugLEw",
- "BookDirectory": "79C54A4EBD69AB2EADCE313042F36092BE432423CC6A4F784C1BA999A513EF78",
- "Expiration": 508543674,
- "OwnerNode": "00000000000022F4",
- "Sequence": 12142920,
- "TakerGets": "6537121438",
- "TakerPays": {
- "currency": "USD",
- "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
- "value": "50.9"
- }
- }
- }
- }, {
- "DeletedNode": {
- "FinalFields": {
- "Account": "rfCFLzNJYvvnoGHWQYACmJpTgkLUaugLEw",
- "BookDirectory": "79C54A4EBD69AB2EADCE313042F36092BE432423CC6A4F784C1BA999A513EF78",
- "BookNode": "0000000000000000",
- "Expiration": 508543133,
- "Flags": 0,
- "OwnerNode": "00000000000022F4",
- "PreviousTxnID": "58B3279C2D56AAC3D9B06106E637C01E3D911E9D31E2FE4EA0D886AC9F4DEE1E",
- "PreviousTxnLgrSeq": 18851945,
- "Sequence": 12142889,
- "TakerGets": "6537121438",
- "TakerPays": {
- "currency": "USD",
- "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
- "value": "50.9"
- }
- },
- "LedgerEntryType": "Offer",
- "LedgerIndex": "D3436CE21925E1CB12C5C444963B47D7EA0CD9A0E387926DC76B23FE5CD1C15F"
- }
- }],
- "TransactionIndex": 26,
- "TransactionResult": "tesSUCCESS"
- },
- "status": "closed",
- "transaction": {
- "Account": "rfCFLzNJYvvnoGHWQYACmJpTgkLUaugLEw",
- "Expiration": 508543674,
- "Fee": "11000",
- "Flags": 2147483648,
- "LastLedgerSequence": 18852106,
- "OfferSequence": 12142889,
- "Sequence": 12142920,
- "SigningPubKey": "034841BF24BD72C7CC371EBD87CCBF258D8ADB05C18DE207130364A97D8A3EA524",
- "TakerGets": "6537121438",
- "TakerPays": {
- "currency": "USD",
- "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
- "value": "50.9"
- },
- "TransactionType": "OfferCreate",
- "TxnSignature": "3045022100B9AD678A773FB61F8F9B565713C80CBF187A2F9EB8E9CE0DAC7B839CA6F4B04C02200613D173A0636CD9BE13F2E3EBD13A16932B5B7D8A96BB5F6D561CA5CDBC4AD3",
- "date": 508543090,
- "hash": "D295E2BE50E3B78AED24790D7B9096996DAF43F095BF17DB83EEACC283D14050",
- "owner_funds": "3070197374272"
- },
- "type": "transaction",
- "validated": true
+ "engine_result": "tesSUCCESS",
+ "engine_result_code": 0,
+ "engine_result_message": "The transaction was applied. Only final in a validated ledger.",
+ "ledger_hash": "08547DD866F099CCB3666F113116B7AA2DF520FA2E3011DD1FF9C9C04A6C7C3E",
+ "ledger_index": 18852105,
+ "meta": {
+ "AffectedNodes": [{
+ "ModifiedNode": {
+ "FinalFields": {
+ "Account": "rfCFLzNJYvvnoGHWQYACmJpTgkLUaugLEw",
+ "AccountTxnID": "D295E2BE50E3B78AED24790D7B9096996DAF43F095BF17DB83EEACC283D14050",
+ "Balance": "3070332374272",
+ "Flags": 0,
+ "OwnerCount": 23,
+ "RegularKey": "r9S56zu6QeJD5d8A7QMfLAeYavgB9dhaX4",
+ "Sequence": 12142921
+ },
+ "LedgerEntryType": "AccountRoot",
+ "LedgerIndex": "2880A9B4FB90A306B576C2D532BFE390AB3904642647DCF739492AA244EF46D1",
+ "PreviousFields": {
+ "AccountTxnID": "3CA3422B0E42D76A7A677B0BA0BE72DFCD93676E0C80F8D2EB27C04BD8457A0F",
+ "Balance": "3070332385272",
+ "Sequence": 12142920
+ },
+ "PreviousTxnID": "3CA3422B0E42D76A7A677B0BA0BE72DFCD93676E0C80F8D2EB27C04BD8457A0F",
+ "PreviousTxnLgrSeq": 18852102
+ }
+ }, {
+ "ModifiedNode": {
+ "FinalFields": {
+ "Flags": 0,
+ "IndexPrevious": "00000000000022D2",
+ "Owner": "rfCFLzNJYvvnoGHWQYACmJpTgkLUaugLEw",
+ "RootIndex": "F435FBBEC9654204D7151A01E686BAA8CB325A472D7B61C7916EA58B59355767"
+ },
+ "LedgerEntryType": "DirectoryNode",
+ "LedgerIndex": "29A543B6681AD7FC8AFBD1386DAE7385F02F9B8C4756A467DF6834AB54BBC9DB"
+ }
+ }, {
+ "ModifiedNode": {
+ "FinalFields": {
+ "ExchangeRate": "4C1BA999A513EF78",
+ "Flags": 0,
+ "RootIndex": "79C54A4EBD69AB2EADCE313042F36092BE432423CC6A4F784C1BA999A513EF78",
+ "TakerGetsCurrency": "0000000000000000000000000000000000000000",
+ "TakerGetsIssuer": "0000000000000000000000000000000000000000",
+ "TakerPaysCurrency": "0000000000000000000000005553440000000000",
+ "TakerPaysIssuer": "2ADB0B3959D60A6E6991F729E1918B7163925230"
+ },
+ "LedgerEntryType": "DirectoryNode",
+ "LedgerIndex": "79C54A4EBD69AB2EADCE313042F36092BE432423CC6A4F784C1BA999A513EF78"
+ }
+ }, {
+ "CreatedNode": {
+ "LedgerEntryType": "Offer",
+ "LedgerIndex": "92E235EE80D2B28A89BEE2C905D4545C2A004FD5D4097679C8A3FB25507FD9EB",
+ "NewFields": {
+ "Account": "rfCFLzNJYvvnoGHWQYACmJpTgkLUaugLEw",
+ "BookDirectory": "79C54A4EBD69AB2EADCE313042F36092BE432423CC6A4F784C1BA999A513EF78",
+ "Expiration": 508543674,
+ "OwnerNode": "00000000000022F4",
+ "Sequence": 12142920,
+ "TakerGets": "6537121438",
+ "TakerPays": {
+ "currency": "USD",
+ "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
+ "value": "50.9"
+ }
+ }
+ }
+ }, {
+ "DeletedNode": {
+ "FinalFields": {
+ "Account": "rfCFLzNJYvvnoGHWQYACmJpTgkLUaugLEw",
+ "BookDirectory": "79C54A4EBD69AB2EADCE313042F36092BE432423CC6A4F784C1BA999A513EF78",
+ "BookNode": "0000000000000000",
+ "Expiration": 508543133,
+ "Flags": 0,
+ "OwnerNode": "00000000000022F4",
+ "PreviousTxnID": "58B3279C2D56AAC3D9B06106E637C01E3D911E9D31E2FE4EA0D886AC9F4DEE1E",
+ "PreviousTxnLgrSeq": 18851945,
+ "Sequence": 12142889,
+ "TakerGets": "6537121438",
+ "TakerPays": {
+ "currency": "USD",
+ "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
+ "value": "50.9"
+ }
+ },
+ "LedgerEntryType": "Offer",
+ "LedgerIndex": "D3436CE21925E1CB12C5C444963B47D7EA0CD9A0E387926DC76B23FE5CD1C15F"
+ }
+ }],
+ "TransactionIndex": 26,
+ "TransactionResult": "tesSUCCESS"
+ },
+ "status": "closed",
+ "transaction": {
+ "Account": "rfCFLzNJYvvnoGHWQYACmJpTgkLUaugLEw",
+ "Expiration": 508543674,
+ "Fee": "11000",
+ "Flags": 2147483648,
+ "LastLedgerSequence": 18852106,
+ "OfferSequence": 12142889,
+ "Sequence": 12142920,
+ "SigningPubKey": "034841BF24BD72C7CC371EBD87CCBF258D8ADB05C18DE207130364A97D8A3EA524",
+ "TakerGets": "6537121438",
+ "TakerPays": {
+ "currency": "USD",
+ "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
+ "value": "50.9"
+ },
+ "TransactionType": "OfferCreate",
+ "TxnSignature": "3045022100B9AD678A773FB61F8F9B565713C80CBF187A2F9EB8E9CE0DAC7B839CA6F4B04C02200613D173A0636CD9BE13F2E3EBD13A16932B5B7D8A96BB5F6D561CA5CDBC4AD3",
+ "date": 508543090,
+ "hash": "D295E2BE50E3B78AED24790D7B9096996DAF43F095BF17DB83EEACC283D14050",
+ "owner_funds": "3070197374272"
+ },
+ "type": "transaction",
+ "validated": true
}
```
@@ -7881,7 +8372,7 @@ The `state` object may have some arrangement of the following fields:
## can_delete ##
[[Source] ](https://github.com/ripple/rippled/blob/develop/src/ripple/rpc/handlers/CanDelete.cpp "Source")
-With `online_delete` and `advisory_delete` configuration options enabled, the `can_delete` method informs the rippled server of the latest ledger which may be deleted.
+With `online_delete` and `advisory_delete` configuration options enabled, the `can_delete` method informs the rippled server of the latest ledger which may be deleted.
_The `can_delete` method is an [admin command](#connecting-to-rippled) that cannot be run by unpriviledged users._
@@ -8167,7 +8658,7 @@ The following is an incomplete summary of fields that may be contained in the `i
| synched | Boolean | Whether this server considers itself in sync with the network. |
| state | String | What portion of the consensus process is currently in progress: `open`, `consensus`, `finished`, or `accepted`. |
-It is also normal to get a minimal result where the only field in `info` is `"consensus": "none"`. This indicates that the server is in between consensus rounds.
+It is also normal to get a minimal result where the only field in `info` is `"consensus": "none"`. This indicates that the server is in between consensus rounds.
The results of the `consensus_info` command can vary dramatically if you run it several times, even in short succession.
@@ -8180,7 +8671,7 @@ The results of the `consensus_info` command can vary dramatically if you run it
## fetch_info ##
[[Source] ](https://github.com/ripple/rippled/blob/315a8b6b602798a4cff4d8e1911936011e12abdb/src/ripple/rpc/handlers/FetchInfo.cpp "Source")
-The `fetch_info` command returns information about objects that this server is currently fetching from the network, and how many peers have that information. It can also be used to reset current fetches.
+The `fetch_info` command returns information about objects that this server is currently fetching from the network, and how many peers have that information. It can also be used to reset current fetches.
_The `fetch_info` method is an [admin command](#connecting-to-rippled) that cannot be run by unpriviledged users._
@@ -8336,10 +8827,372 @@ The fields describing a fetch in progress are subject to change without notice.
* Any of the [universal error types](#universal-errors).
+## feature ##
+[[Source] ](https://github.com/ripple/rippled/blob/develop/src/ripple/rpc/handlers/Feature1.cpp "Source")
+
+The `feature` command returns information about [amendments](concept-amendments.html) this server knows about, including whether they are enabled and whether the server is voting in favor of those amendments in the [amendment process](concept-amendments.html#amendment-process). _(New in [version 0.31.0][])_
+
+You can use the `feature` command to temporarily configure the server to vote against or in favor of an amendment. This change does not persist if you restart the server. To make lasting changes in amendment voting, use the `rippled.cfg` file. See [Configuring Amendment Voting](concept-amendments.html#configuring-amendment-voting) for more information.
+
+_The `feature` method is an [admin command](#connecting-to-rippled) that cannot be run by unpriviledged users._
+
+#### Request Format ####
+An example of the request format:
+
+
+
+*WebSocket - list all*
+
+```
+{
+ "id": "list_all_features",
+ "command": "feature"
+}
+```
+
+*WebSocket - reject*
+
+```
+{
+ "id": "reject_multi_sign",
+ "command": "feature",
+ "feature": "4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373",
+ "vetoed": true
+}
+```
+
+*JSON-RPC*
+
+```
+{
+ "method": "feature",
+ "params": [
+ {
+ "feature": "4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373",
+ "vetoed": false
+ }
+ ]
+}
+```
+
+*Commandline*
+
+```
+#Syntax: feature [ [accept|reject]]
+rippled feature 4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373 accept
+```
+
+
+
+The request includes the following parameters:
+
+| Field | Type | Description |
+|---------|------|-------------|
+| feature | String | (Optional) The unique ID of an amendment, as hexadecimal; or the short name of the amendment. If provided, limits the response to one amendment. Otherwise, the response lists all amendments. |
+| vetoed | Boolean | (Optional; ignored unless `feature` also specified) If true, instructs the server to vote against the amendment specified by `feature`. If false, instructs the server to vote in favor of the amendment. |
+
+**Note:** You can configure your server to vote in favor of a new amendment, even if the server does not currently know how to apply that amendment, by specifying the amendment ID in the `feature` field. For example, you might want to do this if you plan to upgrade soon to a new `rippled` version that _does_ support the amendment.
+
+#### Response Format ####
+
+An example of a successful response:
+
+
+
+*WebSocket - list all*
+
+```
+{
+ "id": "list_all_features",
+ "status": "success",
+ "type": "response",
+ "result": {
+ "features": {
+ "42426C4D4F1009EE67080A9B7965B44656D7714D104A72F9B4369F97ABF044EE": {
+ "enabled": false,
+ "name": "FeeEscalation",
+ "supported": true,
+ "vetoed": false
+ },
+ "4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373": {
+ "enabled": false,
+ "name": "MultiSign",
+ "supported": true,
+ "vetoed": false
+ },
+ "6781F8368C4771B83E8B821D88F580202BCB4228075297B19E4FDC5233F1EFDC": {
+ "enabled": false,
+ "name": "TrustSetAuth",
+ "supported": true,
+ "vetoed": false
+ },
+ "C1B8D934087225F509BEB5A8EC24447854713EE447D277F69545ABFA0E0FD490": {
+ "enabled": false,
+ "name": "Tickets",
+ "supported": true,
+ "vetoed": false
+ },
+ "DA1BD556B42D85EA9C84066D028D355B52416734D3283F85E216EA5DA6DB7E13": {
+ "enabled": false,
+ "name": "SusPay",
+ "supported": true,
+ "vetoed": false
+ }
+ }
+ }
+}
+```
+
+*WebSocket - reject*
+
+```
+{
+ "id": "reject_multi_sign",
+ "status": "success",
+ "type": "response",
+ "result": {
+ "features": {
+ "4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373": {
+ "enabled": false,
+ "name": "MultiSign",
+ "supported": true,
+ "vetoed": true
+ }
+ }
+ }
+}
+```
+
+*JSON-RPC*
+
+```
+200 OK
+{
+ "result": {
+ "4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373": {
+ "enabled": false,
+ "name": "MultiSign",
+ "supported": true,
+ "vetoed": false
+ },
+ "status": "success"
+ }
+}
+```
+
+*Commandline*
+
+```
+Loading: "/etc/rippled.cfg"
+Connecting to 127.0.0.1:5005
+{
+ "result": {
+ "4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373": {
+ "enabled": false,
+ "name": "MultiSign",
+ "supported": true,
+ "vetoed": false
+ },
+ "status": "success"
+ }
+}
+```
+
+
+
+The response follows the [standard format](#response-formatting), with a successful result containing **a map of amendments** as a JSON object. The keys of the object are amendment IDs. The values for each key are _amendment objects_ that describe the status of the amendment with that ID. If the request specified a `feature`, the map contains only the requested amendment object, after applying any changes from the request. Each amendment object has the following fields:
+
+| Field | Type | Description |
+|-----------|---------|-------------|
+| enabled | Boolean | Whether this amendment is currently enabled in the latest ledger. |
+| name | String | (May be omitted) The human-readable name for this amendment, if known. |
+| supported | Boolean | Whether this server knows how to apply this amendment. |
+| vetoed | Boolean | Whether the server has been instructed to vote against this amendment. |
+
+**Caution:** The `name` for an amendment does not strictly indicate what that amendment does. The name is not guaranteed to be unique or consistent across servers.
+
+#### Possible Errors ####
+
+* Any of the [universal error types](#universal-errors).
+* `badFeature` - The `feature` specified was invalidly formatted, or the server does not know an amendment with that name.
+
+
+
+## fee ##
+[[Source] ](https://github.com/ripple/rippled/blob/release/src/ripple/rpc/handlers/Fee1.cpp "Source")
+
+The `fee` command reports the current state of the open-ledger requirements for the [transaction cost](concept-transaction-cost.html). This requires the [FeeEscalation amendment](concept-amendments.html#feeescalation) to be enabled. _(New in [version 0.31.0][])_
+
+_The `fee` method is an [admin command](#connecting-to-rippled) that cannot be run by unpriviledged users._
+
+#### Request Format ####
+An example of the request format:
+
+
+
+*WebSocket*
+
+```
+{
+ "id": "fee_websocket_example",
+ "command": "fee"
+}
+```
+
+*JSON-RPC*
+
+```
+{
+ "method": "fee",
+ "params": [{}]
+}
+```
+
+*Commandline*
+
+```
+#Syntax: fee
+rippled fee
+```
+
+
+
+The request does not include any parameters.
+
+#### Response Format ####
+
+An example of a successful response:
+
+
+
+*WebSocket*
+
+```
+{
+ "id": "fee_websocket_example",
+ "status": "success",
+ "type": "response",
+ "result": {
+ "current_ledger_size": "14",
+ "current_queue_size": "0",
+ "drops": {
+ "base_fee": "10",
+ "median_fee": "11000",
+ "minimum_fee": "10",
+ "open_ledger_fee": "10"
+ },
+ "expected_ledger_size": "24",
+ "levels": {
+ "median_level": "281600",
+ "minimum_level": "256",
+ "open_ledger_level": "256",
+ "reference_level": "256"
+ },
+ "max_queue_size": "480"
+ }
+}
+```
+
+*JSON-RPC*
+
+```
+200 OK
+{
+ "result": {
+ "current_ledger_size": "56",
+ "current_queue_size": "11",
+ "drops": {
+ "base_fee": "10",
+ "median_fee": "10000",
+ "minimum_fee": "10",
+ "open_ledger_fee": "2653937"
+ },
+ "expected_ledger_size": "55",
+ "levels": {
+ "median_level": "256000",
+ "minimum_level": "256",
+ "open_ledger_level": "67940792",
+ "reference_level": "256"
+ },
+ "max_queue_size": "1100",
+ "status": "success"
+ }
+}
+```
+
+*Commandline*
+
+```
+Loading: "/etc/rippled.cfg"
+Connecting to 127.0.0.1:5005
+{
+ "result" : {
+ "current_ledger_size" : "16",
+ "current_queue_size" : "2",
+ "drops" : {
+ "base_fee" : "10",
+ "median_fee" : "11000",
+ "minimum_fee" : "10",
+ "open_ledger_fee" : "3203982"
+ },
+ "expected_ledger_size" : "15",
+ "levels" : {
+ "median_level" : "281600",
+ "minimum_level" : "256",
+ "open_ledger_level" : "82021944",
+ "reference_level" : "256"
+ },
+ "max_queue_size" : "300",
+ "status" : "success"
+ }
+}
+```
+
+
+
+The response follows the [standard format](#response-formatting), with a successful result containing the following fields:
+
+| Field | Type | Description |
+|----------------------------|--------|-------------|
+| current\_ledger\_size | String (Integer) | Number of transactions provisionally included in the in-progress ledger. |
+| current\_queue\_size | String (Integer) | Number of transactions currently queued for the next ledger. |
+| drops | Object | Various information about the transaction cost (the `Fee` field of a transaction), in [drops of xrp](#specifying-currency-amounts). |
+| drops.base\_fee | String (Integer) | The transaction cost required for a [reference transaction](#reference-transaction-cost) to be included in a ledger under minimum load, represented in drops of XRP. |
+| drops.median\_fee | String (Integer) | An approximation of the median transaction cost among transactions included in the previous validated ledger, represented in drops of XRP. |
+| drops.minimum\_fee | String (Integer) | The minimum transaction cost for a [reference transaction](#reference-transaction-cost) to be queued for a later ledger, represented in drops of XRP. If greater than `base_fee`, the transaction queue is full. |
+| drops.open\_ledger\_fee | String (Integer) | The minimum transaction cost that a [reference transaction](#reference-transaction-cost) must pay to be included in the current open ledger, represented in drops of XRP. |
+| expected\_ledger\_size | String (Integer) | The approximate number of transactions expected to be included in the current ledger. This is based on the number of transactions in the previous ledger. |
+| levels | Object | Various information about the transaction cost, in _fee levels_. The ratio in fee levels applies to any transaction relative to the minimum cost of that particular transaction. |
+| levels.median\_level | String (Integer) | The median transaction cost among transactions in the previous validated ledger, represented in fee levels. |
+| levels.minimum\_level | String (Integer) | The minimum transaction cost required to be queued for a future ledger, represented in fee levels. |
+| levels.open\_ledger\_level | String (Integer) | The minimum transaction cost required to be included in the current open ledger, represented in fee levels. |
+| levels.reference\_level | String (Integer) | The equivalent of the minimum transaction cost, represented in fee levels. |
+| max\_queue\_size | String (Integer) | The maximum number of transactions that the [transaction queue](concept-transaction-cost.html#queued-transactions) can currently hold. |
+
+### Reference Transaction Cost ###
+
+The "Reference Transaction" is the cheapest possible transaction, in terms of the necessary [transaction cost](concept-transaction-cost.html). Most transactions have the same cost as the reference transaction. Some transactions, such as [multi-signed transactions](reference-transaction-format.html#multi-signing) require a multiple of this cost instead. When the open ledger cost escalates, the requirement is proportional to the basic cost of the transaction.
+
+### Fee Levels ###
+
+_Fee levels_ represent the proportional difference between the minimum cost and the actual cost of a transaction. See the following table for a comparison:
+
+| Transaction | Minimum cost in drops | Minimum cost in Fee levels | Double cost in drops | Double cost in fee levels |
+|-------------|-----------------------|----------------------------|----------------------|---------------------------|
+| Reference transaction (most transactions) | 10 | 256 | 20 | 512 |
+| [Multi-signed transaction](reference-transaction-format.html#multi-signing) with 4 signatures | 50 | 256 | 100 | 512 |
+| [Key reset transaction](concept-transaction-cost.html#key-reset-transaction) | 0 | (Effectively infinite) | N/A | (Effectively infinite) |
+
+#### Possible Errors ####
+
+* Any of the [universal error types](#universal-errors).
+
+
+
## get_counts ##
[[Source] ](https://github.com/ripple/rippled/blob/c7118a183a660648aa88a3546a6b2c5bce858440/src/ripple/rpc/handlers/GetCounts.cpp "Source")
-The `get_counts` command provides various stats about the health of the server, mostly the number of objects of different types that it currently holds in memory.
+The `get_counts` command provides various stats about the health of the server, mostly the number of objects of different types that it currently holds in memory.
_The `get_counts` method is an [admin command](#connecting-to-rippled) that cannot be run by unpriviledged users._
@@ -8490,7 +9343,7 @@ For most other entries, the value indicates the number of objects of that type c
## ledger_cleaner ##
[[Source] ](https://github.com/ripple/rippled/blob/df54b47cd0957a31837493cd69e4d9aade0b5055/src/ripple/rpc/handlers/LedgerCleaner.cpp "Source")
-The `ledger_cleaner` command controls the [Ledger Cleaner](https://github.com/ripple/rippled/blob/f313caaa73b0ac89e793195dcc2a5001786f916f/src/ripple/app/ledger/README.md#the-ledger-cleaner), an asynchronous maintenance process that can find and repair corruption in rippled's database of ledgers.
+The `ledger_cleaner` command controls the [Ledger Cleaner](https://github.com/ripple/rippled/blob/f313caaa73b0ac89e793195dcc2a5001786f916f/src/ripple/app/ledger/README.md#the-ledger-cleaner), an asynchronous maintenance process that can find and repair corruption in rippled's database of ledgers.
_The `ledger_cleaner` method is an [admin command](#connecting-to-rippled) that cannot be run by unpriviledged users._
@@ -8680,7 +9533,7 @@ Connecting to 127.0.0.1:5005
-The response follows the [standard format](#response-formatting). The response format depends on whether the request specified a `severity`. If it did, the log level is changed and a successful result contains no additional fields.
+The response follows the [standard format](#response-formatting). The response format depends on whether the request specified a `severity`. If it did, the log level is changed and a successful result contains no additional fields.
Otherwise, the request contains the following field:
@@ -9769,7 +10622,7 @@ The response follows the [standard format](#response-formatting), with a success
## json ##
-The `json` method is a proxy to running other commands, and accepts the parameters for the command as a JSON value. It is *exclusive to the Commandline client*, and intended for cases where the commandline syntax for specifying parameters is inadequate or undesirable.
+The `json` method is a proxy to running other commands, and accepts the parameters for the command as a JSON value. It is *exclusive to the Commandline client*, and intended for cases where the commandline syntax for specifying parameters is inadequate or undesirable.
#### Request Format ####
An example of the request format:
@@ -9999,3 +10852,4 @@ The response follows the [standard format](#response-formatting), with a success
[version 0.29.0]: https://wiki.ripple.com/Rippled-0.29.0
[version 0.30.0]: https://wiki.ripple.com/Rippled-0.30.0
[version 0.30.1]: https://wiki.ripple.com/Rippled-0.30.1
+[version 0.31.0]: https://wiki.ripple.com/Rippled-0.31.0
diff --git a/content/reference-transaction-format.md b/content/reference-transaction-format.md
index f54231714b..5bc199974a 100644
--- a/content/reference-transaction-format.md
+++ b/content/reference-transaction-format.md
@@ -12,27 +12,50 @@ There are several different types of transactions that perform different actions
* [OfferCreate - Submit an order to exchange currency](#offercreate)
* [OfferCancel - Withdraw a currency-exchange order](#offercancel)
* [TrustSet - Add or modify a trust line](#trustset)
+* [SignerListSet - Set multi-signing settings](#signerlistset)
-Additionally, there are *Psuedo-Transactions* that are not created and submitted in the usual way, but may appear in ledgers:
+Additionally, there are *Pseudo-Transactions* that are not created and submitted in the usual way, but may appear in ledgers:
* [SetFee - Adjust the minimum transaction cost or account reserve](#setfee)
+* [EnableAmendment - Apply a change to transaction processing](#enableamendment)
Transactions are only valid if signed, submitted, and accepted into a validated ledger version. There are many ways a transaction can fail.
-* [Signing and Sending Transactions](#signing-and-sending-transactions)
+* [Authorized Transactions](#authorizing-transactions)
* [Reliable Transaction Submission](#reliable-transaction-submission)
* [Transaction Results - How to find and interpret transaction results](#transaction-results)
* [Full Transaction Response List - Complete table of all error codes](#full-transaction-response-list)
-## Signing and Sending Transactions ##
+## Authorizing Transactions ##
-Signing a transaction cryptographically proves that the person in charge of the account sending the transaction is authorized to do so. Only signed transactions can be submitted to the network and included in a validated ledger. A signed transaction is immutable: its contents cannot change, and the signature is not valid for any other transaction.
+In the decentralized Ripple Consensus Ledger, a digital signature proves that a transaction is authorized to perform a specific set of actions. Only signed transactions can be submitted to the network and included in a validated ledger. A signed transaction is immutable: its contents cannot change, and the signature is not valid for any other transaction.
-You can sign a transaction using a secret key: either the master secret, or a regular secret if the account has a regular key pair associated with it. (See [SetRegularKey](#setregularkey) for details.)
+A transaction can be authorized by any of the following types of signatures:
-Multi-signature transactions are [in development](https://wiki.ripple.com/Multisign).
+* A single signature from the master secret key that is mathematically associated with the sending address. You can disable or enable the master key using an [AccountSet transaction](#accountset).
+* A single signature that matches a regular key associated with the address. You can add, remove, or replace a regular key using a [SetRegularKey transaction](#setregularkey).
+* A [multi-signature](#multi-signing) that matches a list of signers owned by the address. You can add, remove, or replace a list of signers using a [SignerListSet transaction](#signerlistset).
-Typically, you create a transaction in JSON format first. Here is an example of an unsigned Payment-type transaction in JSON:
+Any signature type can authorize any type of transaction, with the following exceptions:
+
+* Only the master key can [disable the master key](#accountset-flags).
+* Only the master key can [permanently give up the ability to freeze](concept-freeze.html#no-freeze).
+* You can never remove the last method of signing transactions from an address.
+
+## Signing and Submitting Transactions ##
+
+Sending a transaction to the Ripple Consensus Ledger involves several steps:
+
+1. Create an [unsigned transaction in JSON format](#unsigned-transaction-format).
+2. Use one or more signatures to [authorize the transaction](#authorizing-transactions).
+3. Submit a transaction to a `rippled` server. If the transaction is properly formed, the server provisionally applies the transaction to its current version of the ledger and relays the transaction to other members of the peer-to-peer network.
+4. The [consensus process](https://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/) determines which provisional transactions get included in the next validated ledger.
+5. The `rippled` servers apply those transactions to the previous ledger in a canonical order and share their results.
+6. If enough [trusted validators](tutorial-rippled-setup.html#reasons-to-run-a-validator) created the exact same ledger, that ledger is declared _validated_ and the [results of the transactions](#transaction-results) in that ledger are immutable.
+
+### Unsigned Transaction Format ###
+
+Here is an example of an unsigned [Payment-type transaction](#payment) in JSON:
```
{
@@ -50,11 +73,11 @@ Typically, you create a transaction in JSON format first. Here is an example of
}
```
-After doing that, you generate the signed binary format for the transaction. There are two ways to do this:
+The Ripple Consensus Ledger only relays and executes a transaction if the transaction object has been authorized by the sending address (in the `Account`) field. For transactions authorized by only a single signature, you have two options:
1. Convert it to a binary blob and sign it offline. This is preferable, since it means that the account secret used for signing the transaction is never transmitted over any network connection.
* You can use [RippleAPI](reference-rippleapi.html#sign) to perform offline signing.
-2. Have a `rippled` server sign the transaction for you. The [sign command](reference-rippled.html#sign) takes a JSON-format transaction and secret and returns the signed binary transaction format ready for submission. (Transmitting your account secret is dangerous, so you should only do this from within a trusted and encrypted sub-net, to a server you control.)
+2. Have a `rippled` server sign the transaction for you. The [sign command](reference-rippled.html#sign) takes a JSON-format transaction and secret and returns the signed binary transaction format ready for submission. (Transmitting your account secret is dangerous, so you should only do this from within a trusted and encrypted connection, or through a local connection, and only to a server you control.)
* As a shortcut, you can use the [submit command](reference-rippled.html#submit) with a `tx_json` object to sign and submit a transaction all at once. This is only recommended for testing and development purposes.
In either case, signing a transaction generates a binary blob that can be submitted to the network. This means using `rippled`'s [submit command](reference-rippled.html#submit). Here is an example of the same transaction, as a signed blob, being submitted with the WebSocket API:
@@ -67,7 +90,11 @@ In either case, signing a transaction generates a binary blob that can be submit
}
```
-After a transaction has been submitted, if it gets accepted into a validated ledger, you can view the final transaction using the API. For example, here is what the WebSocket API [tx command](reference-rippled.html#tx) shows for the same transaction. The field names that begin with capital letters are part of the ledger object; the fields that begin with lower-case letters are additional information generated by the server for the request:
+After a transaction has been submitted, you can check its status using the API, for example using the [tx command](reference-rippled.html#tx).
+
+**Caution:** The success of a transaction is not final unless the transaction appears in a **validated** ledger with the result code `tesSUCCESS`. See also: [Finality of Results](#finality-of-results).
+
+Example response from the `tx` command:
```
{
@@ -157,6 +184,27 @@ After a transaction has been submitted, if it gets accepted into a validated led
}
```
+
+### Multi-Signing ###
+
+Multi-signing in Ripple is the act of [authorizing transactions](#authorizing-transactions) for the Ripple Consensus Ledger by using a combination of multiple secret keys. Multi-signing is due to be enabled by an [Amendment](concept-amendments.html) to the Ripple Consensus Protocol. You can have any combination of authorization methods enabled for your address, including multi-signing, a master key, and a [regular key](#setregularkey). (The only requirement is that _at least one_ method must be enabled.)
+
+The [SignerListSet transaction](#signerlistset) defines which addresses can authorize transactions from your address. You can include up to 8 addresses in a SignerList. You can control how many signatures are needed, in which combinations, by using the quorum and weight values of the SignerList.
+
+To successfully submit a multi-signed transaction, you must do all of the following:
+
+* The address sending the transaction (specified in the `Account` field) must own a [`SignerList` in the ledger](reference-ledger-format.html#signerlist).
+* The transaction must include the `SigningPubKey` field as an empty string.
+* The transaction must include a [`Signers` field](#signers-field) containing an array of signatures.
+* The signatures present in the `Signers` array must match signers defined in the SignerList.
+* For the provided signatures, the total `weight` associated with those signers must be equal or greater than the `quorum` for the SignerList.
+* The [transaction cost](concept-transaction-cost.html) (specified in the `Fee` field) must be at least (N+1) times the normal transaction cost, where N is the number of signatures provided.
+* All fields of the transaction must be defined before collecting signatures. You cannot [auto-fill](#auto-fillable-fields) any fields.
+* If presented in binary form, the `Signers` array must be sorted based on the numeric value of the signer addresses, with the lowest value first. (If submitted as JSON, the [`submit_multisigned` command](reference-rippled.html#submit-multisigned) handles this automatically.)
+
+For more information, see [How to Multi-Sign](tutorial-multisign.html).
+
+
### Reliable Transaction Submission ###
Reliably submitting transactions is the process of achieving both of the following:
@@ -169,7 +217,7 @@ To accomplish both of these, your application should:
1. Construct and sign the transaction first, including a [`LastLedgerSequence`](#lastledgersequence) parameter that gives the transaction a limited viable lifespan.
2. Persist details of the transaction before submitting.
3. Submit the transaction.
-4. Confirm that the transaction was either included in a validated ledger, or that it has expired due to `LastLedgerSequence`.
+4. Confirm that the transaction was either included in a validated ledger, or that it has expired due to `LastLedgerSequence`.
5. If a transaction fails or expires, you can modify and resubmit it.
Main article: [Reliable Transaction Submission](tutorial-reliable-transaction-submission.html)
@@ -193,9 +241,10 @@ Every transaction type has the same set of fundamental fields:
| [LastLedgerSequence](#lastledgersequence) | Number | UInt32 | (Optional, but strongly recommended) Highest ledger sequence number that a transaction can appear in. |
| [Memos](#memos) | Array of Objects | Array | (Optional) Additional arbitrary information used to identify this transaction. |
| [Sequence](#canceling-or-skipping-a-transaction) | Unsigned Integer | UInt32 | (Required, but [auto-fillable](#auto-fillable-fields)) The sequence number, relative to the initiating account, of this transaction. A transaction is only valid if the `Sequence` number is exactly 1 greater than the last-valided transaction from the same account. |
-| SigningPubKey | String | PubKey | (Automatically added when signing) Hex representation of the public key that corresponds to the private key used to sign this transaction. |
+| SigningPubKey | String | PubKey | (Automatically added when signing) Hex representation of the public key that corresponds to the private key used to sign this transaction. If an empty string, indicates a multi-signature is present in the `Signers` field instead. |
+| [Signers](#signers-field) | Array | Array | (Optional) Array of objects that represent a [multi-signature](#multi-signing) which authorizes this transaction. |
| SourceTag | Unsigned Integer | UInt32 | (Optional) Arbitrary integer used to identify the reason for this payment, or the hosted wallet on whose behalf this transaction is made. Conventionally, a refund should specify the initial payment's `SourceTag` as the refund payment's `DestinationTag`. |
-| TransactionType | String | UInt16 | The type of transaction. Valid types include: `Payment`, `OfferCreate`, `OfferCancel`, `TrustSet`, `AccountSet`, and `SetRegularKey`. |
+| TransactionType | String | UInt16 | The type of transaction. Valid types include: `Payment`, `OfferCreate`, `OfferCancel`, `TrustSet`, `AccountSet`, `SetRegularKey`, and `SignerListSet`. |
| TxnSignature | String | VariableLength | (Automatically added when signing) The signature that verifies this transaction as originating from the account it says it is from. |
**Note:** The deprecated `PreviousTxnID` transaction parameter was removed entirely in [rippled 0.28.0][]. Use `AccountTxnID` instead.
@@ -211,13 +260,16 @@ Some fields can be automatically filled in before the transaction is signed, eit
For a production system, we recommend *not* leaving these fields to be filled by the server. For example, if transaction costs become high due to a temporary spike in network load, you may want to wait for the cost to decrease before sending some transactions, instead of paying the temporarily-high cost.
-The [`Paths` field](#paths) of the [Payment](#payment) transaction type can also be automatically filled in.
+The [`Paths` field](#paths) of the [Payment](#payment) transaction type can also be automatically filled in.
+
### Transaction Cost ###
-In order to protect the Ripple Consensus Ledger from being disrupted by spam and denial-of-service attacks, each transaction must destroy a small amount of XRP. This transaction cost is designed to increase along with the load on the network, making it very expensive to deliberately or inadvertently overload the network.
+In order to protect the Ripple Consensus Ledger from being disrupted by spam and denial-of-service attacks, each transaction must destroy a small amount of XRP. This _[transaction cost](concept-transaction-cost.html)_ is designed to increase along with the load on the network, making it very expensive to deliberately or inadvertently overload the network.
-The `Fee` field specifies an amount, in [drops of XRP](reference-rippled.html#specifying-currency-amounts), to destroy as the cost for this transaction. If the transaction is included in a validated leger (whether or not it achieves its intended purpose), then the amount of XRP specified in the `Fee` parameter is destroyed forever. You can [look up the transaction cost](concept-transaction-cost.html#querying-the-transaction-cost) in advance, or [let `rippled` set it automatically](concept-transaction-cost.html#automatically-specifying-the-transaction-cost) when you sign a transaction.
+The `Fee` field specifies an amount, in [drops of XRP](reference-rippled.html#specifying-currency-amounts), to destroy as the cost for relaying this transaction. If the transaction is included in a validated ledger (whether or not it achieves its intended purpose), then the amount of XRP specified in the `Fee` parameter is destroyed forever. You can [look up the transaction cost](concept-transaction-cost.html#querying-the-transaction-cost) in advance, or [let `rippled` set it automatically](concept-transaction-cost.html#automatically-specifying-the-transaction-cost) when you sign a transaction.
+
+**Note:** [Multi-signed transactions](#multi-signing) require additional fees to relay to the network.
### Canceling or Skipping a Transaction ###
@@ -248,7 +300,7 @@ In order to use AccountTxnID, you must first set the [asfAccountTxnID](#accounts
### Memos ###
-The Memos field allows for arbitrary messaging data that can accompany the transaction. It is presented as an array of objects. Each object has only one field, `Memo`, which in turn contains another object with *one or more* of the following fields:
+The `Memos` field allows for arbitrary messaging data that can accompany the transaction. It is presented as an array of objects. Each object has only one field, `Memo`, which in turn contains another object with *one or more* of the following fields:
| Field | Type | [Internal Type](https://wiki.ripple.com/Binary_Format) | Description |
|-------|------|--------------------------------------------------------|-------------|
@@ -279,10 +331,25 @@ Example of a transaction with a Memos field:
}
```
+### Signers Field ###
+
+The `Signers` field contains a [multi-signature](#multi-signing), which has signatures from up to 8 key pairs, that together should authorize the transaction. The `Signers` list is an array of objects, each with one field, `Signer`. The `Signer` field has the following nested fields:
+
+| Field | Type | [Internal Type](https://wiki.ripple.com/Binary_Format) | Description |
+|-------|------|--------------------------------------------------------|-------------|
+| Account | String | AccountID | The address associated with this signature, as it appears in the SignerList. |
+| TxnSignature | String | Blob | A signature for this transaction, verifiable using the `SigningPubKey`. |
+| SigningPubKey | String | PubKey | The public key used to create this signature. |
+
+The `SigningPubKey` must be a key that is associated with the `Account` address. If the referenced `Account` is a funded account in the ledger, then the SigningPubKey can be that account's current Regular Key if one is set. It could also be that account's Master Key, unless the [lsfDisableMaster](reference-ledger-format.html#accountroot-flags) flag is enabled. If the referenced `Account` address is not a funded account in the ledger, then the `SigningPubKey` must be the master key associated with that address.
+
+Because signature verification is a compute-intensive task, multi-signed transactions cost additional XRP to relay to the network. Each signature included in the multi-signature increases the [transaction cost](concept-transaction-cost.html) required for the transaction. For example, if the current minimum transaction cost to relay a transaction to the network is `10000` drops, then a multi-signed transaction with 3 entries in the `Signers` array would need a `Fee` value of at least `40000` drops to relay.
+
+
### Flags ###
-The Flags field allows for additional boolean options regarding the behavior of a transaction. They are represented as binary values that can be combined with bitwise-or operations to set multiple flags at once.
+The `Flags` field allows for additional boolean options regarding the behavior of a transaction. They are represented as binary values that can be combined with bitwise-or operations to set multiple flags at once.
Most flags only have meaning for a specific transaction type. The same bitwise value may be reused for flags on different transaction types, so it is important to pay attention to the `TransactionType` field when setting and reading flags.
@@ -334,7 +401,7 @@ Example payment:
Most of the time, the `issuer` field of a non-XRP [currency amount](reference-rippled.html#specifying-currency-amounts) indicates the account of the gateway that issues that currency. However, when describing payments, there are special rules for the `issuer` field in the `Amount` and `SendMax` fields of a payment.
* There is only ever one balance for the same currency between two accounts. This means that, sometimes, the `issuer` field of an amount actually refers to a counterparty that is redeeming issuances, instead of the account that created the issuances.
-* When the `issuer` field of the destination `Amount` field matches the `Destination` account address, it is treated as a special case meaning "any issuer that the destination accepts." This includes all accounts to which the destination has extended trust lines, as well as issuances created by the destination which may be held on other trust lines.
+* When the `issuer` field of the destination `Amount` field matches the `Destination` account address, it is treated as a special case meaning "any issuer that the destination accepts." This includes all accounts to which the destination has extended trust lines, as well as issuances created by the destination which may be held on other trust lines.
* When the `issuer` field of the `SendMax` field matches the source account's address, it is treated as a special case meaning "any issuer that the source can use." This includes creating new issuances on trust lines that other accounts have extended to the source account, as well as issuances from other accounts that the source account possesses.
### Creating Accounts ###
@@ -391,11 +458,11 @@ When the [*tfPartialPayment* flag](#payment-flags) is enabled, the `Amount` fiel
Ripple defines the "quality" of a currency exchange as the ratio of the numeric amount in to the numeric amount out. For example, if you spend $2 USD to receive £1 GBP, then the "quality" of that exchange is `0.5`.
-The [*tfLimitQuality* flag](#payment-flags) allows you to set a minimum quality of conversions that you are willing to take. This limit quality is defined as the destination `Amount` divided by the `SendMax` amount (just the numeric amounts, regardless of currency). When set, the payment processing engine avoids using any paths whose quality (conversion rate) is worse (numerically lower) than the limit quality.
+The [*tfLimitQuality* flag](#payment-flags) allows you to set a minimum quality of conversions that you are willing to take. This limit quality is defined as the destination `Amount` divided by the `SendMax` amount (just the numeric amounts, regardless of currency). When set, the payment processing engine avoids using any paths whose quality (conversion rate) is worse (numerically lower) than the limit quality.
By itself, the tfLimitQuality flag reduces the number of situations in which a transaction can succeed. Specifically, it rejects payments where some part of the payment uses an unfavorable conversion, even if the overall average *average* quality of conversions in the payment is equal or better than the limit quality. If a payment is rejected in this way, the [transaction result](#transaction-results) is `tecPATH_DRY`.
-Consider the following example. If I am trying to send you 100 Chinese Yuan (`Amount` = 100 CNY) for 20 United States dollars (`SendMax` = 20 USD) or less, then the limit quality is `5`. Imagine one market maker is offering ¥95 for $15 (a ratio of about `6.3` CNY per USD), but the next best offer in the market is ¥5 for $2 (a ratio of `2.5` CNY per USD). If I were to take both offers in order to send you 100 CNY, then it would cost me 17 USD, for an average quality of about `5.9`.
+Consider the following example. If I am trying to send you 100 Chinese Yuan (`Amount` = 100 CNY) for 20 United States dollars (`SendMax` = 20 USD) or less, then the limit quality is `5`. Imagine one market maker is offering ¥95 for $15 (a ratio of about `6.3` CNY per USD), but the next best offer in the market is ¥5 for $2 (a ratio of `2.5` CNY per USD). If I were to take both offers in order to send you 100 CNY, then it would cost me 17 USD, for an average quality of about `5.9`.
Without the tfLimitQuality flag set, this transaction would succeed, because the $17 it costs me is within my specified `SendMax`. However, with the tfLimitQuality flag enabled, the transaction would fail instead, because the path to take the second offer has a quality of `2.5`, which is worse than the limit quality of `5`.
@@ -465,13 +532,13 @@ The available AccountSet flags are:
| asfRequireDest | 1 | Require a destination tag to send transactions to this account. | lsfRequireDestTag |
| asfRequireAuth | 2 | Require authorization for users to hold balances issued by this account. (This prevents users unknown to a gateway from holding funds issued by that gateway.) | lsfRequireAuth |
| asfDisallowXRP | 3 | XRP should not be sent to this account. (Enforced by client applications, not by `rippled`) | lsfDisallowXRP |
-| asfDisableMaster | 4 | Disallow use of the master key. Can only be enabled if the account has a [RegularKey](#setregularkey) configured. | lsfDisableMaster |
+| asfDisableMaster | 4 | Disallow use of the master key. Can only be enabled if the account has configured another way to sign transactions, such as a [Regular Key](#setregularkey) or a [Signer List](#signerlistset). | lsfDisableMaster |
| asfAccountTxnID | 5 | Track the ID of this account's most recent transaction. Required for [AccountTxnID](#accounttxnid) | (None) |
| asfNoFreeze | 6 | Permanently give up the ability to [freeze individual trust lines or disable Global Freeze](concept-freeze.html). This flag can never be disabled after being enabled. | lsfNoFreeze |
| asfGlobalFreeze | 7 | [Freeze](concept-freeze.html) all assets issued by this account. | lsfGlobalFreeze |
| asfDefaultRipple | 8 | Enable [rippling](https://ripple.com/knowledge_center/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))_ | lsfDefaultRipple |
-_New in [rippled 0.28.0][]:_ You cannot send a transaction that enables `asfDisableMaster` or `asfNoFreeze` using a [regular key](#setregularkey). You must use the master key to sign the transaction.
+_New in [rippled 0.28.0][]:_ In order to enable the `asfDisableMaster` or `asfNoFreeze` flags, you must [authorize the transaction](#authorizing-transactions) by signing it with the master key. You cannot use a regular key or a multi-signature.
The following [Transaction flags](#flags), specific to the AccountSet transaction type, serve the same purpose, but are discouraged:
@@ -506,7 +573,7 @@ In rippled's WebSocket and JSON-RPC APIs, the TransferRate is represented as an
[[Source] ](https://github.com/ripple/rippled/blob/4239880acb5e559446d2067f00dabb31cf102a23/src/ripple/app/transactors/SetRegularKey.cpp "Source")
-A SetRegularKey transaction changes the regular key used by the account to sign future transactions.
+A SetRegularKey transaction changes the regular key associated with an address.
```
{
@@ -520,13 +587,15 @@ A SetRegularKey transaction changes the regular key used by the account to sign
| Field | JSON Type | [Internal Type](https://wiki.ripple.com/Binary_Format) | Description |
|-------|-----------|--------------------------------------------------------|-------------|
-| RegularKey | String | Account | (Optional) The public key of a new keypair, to use as the regular key to this account, as a base-58-encoded string in the same format as an account address. If omitted, removes the existing regular key. |
+| RegularKey | String | AccountID | (Optional) A base-58-encoded [Ripple address](reference-rippled.html#addresses) to use as the regular key. If omitted, removes the existing regular key. |
-Instead of using an account's master key to sign transactions, you can set an alternate key pair, called the "Regular Key". As long as the public key for this key pair is set in the `RegularKey` field of an account this way, then the secret of the Regular Key pair can be used to sign transactions. (The master secret can still be used, too, unless you set the [asfDisableMaster account flag](#accountset-flags).)
+In addition to the master key, which is mathematically-related to an address, you can associate **at most 1 additional key pair** with an address using this type of transaction. The additional key pair is called a _regular key_. If your address has a regular key pair defined, you can use the secret key of the regular key pair to [authorize transactions](#authorizing-transactions).
-A Regular Key pair is generated in the same way as any other Ripple keys (for example, with [wallet_propose](reference-rippled.html#wallet-propose)), but it can be changed. A Master Key pair is an intrinsic part of the account's identity (the address is derived from the master public key) so the Master Key cannot be changed. Therefore, using a Regular Key to sign transactions instead of the master key whenever possible is beneficial to security.
+A regular key pair is generated in the same way as any other Ripple keys (for example, with [wallet_propose](reference-rippled.html#wallet-propose)), but it can be changed. A master key pair is an intrinsic part of an address's identity (the address is derived from the master public key). You can [disable](#accountset-flags) a master key but you cannot change it.
-If your regular key is compromised, but the master key is not, you can use this method to regain control of your account. In some cases, you can even send a [key reset transaction](concept-transaction-cost.html#key-reset-transaction) without paying the [transaction cost](#transaction-cost).
+You can protect your master secret by using a regular key instead of the master key to sign transactions whenever possible. If your regular key is compromised, but the master key is not, you can use a SetRegularKey transaction to regain control of your address. In some cases, you can even send a [key reset transaction](concept-transaction-cost.html#key-reset-transaction) without paying the [transaction cost](#transaction-cost).
+
+For even greater security, you can use [multi-signing](#multi-signing), but multi-signing requires additional XRP for the [transaction cost](concept-transaction-cost.html) and [reserve](concept-reserves.html).
@@ -715,7 +784,7 @@ A trust line with settings in the default state is equivalent to no trust line.
The default state of all flags is off, except for the [NoRipple flag](https://ripple.com/knowledge_center/understanding-the-noripple-flag/), whose default state depends on the DefaultRipple flag.
-The Auth flag of a trust line does not determine whether the trust line counts towards its owner's XRP reserve requirement. However, an enabled Auth flag prevents the trust line from being in its default state. An authorized trust line can never be deleted. _(New in [rippled 0.30.0](https://github.com/ripple/rippled/releases/tag/0.30.0))_: You can pre-authorize a trust line with the `tfSetfAuth` flag only, even if the limit and balance of the trust line are 0.
+The Auth flag of a trust line does not determine whether the trust line counts towards its owner's XRP reserve requirement. However, an enabled Auth flag prevents the trust line from being in its default state. An authorized trust line can never be deleted. _(New in [rippled 0.30.0](https://github.com/ripple/rippled/releases/tag/0.30.0))_: The [`TrustSetAuth` Amendment](concept-amendments.html#trustsetauth) would allow you to pre-authorize a trust line with the `tfSetfAuth` flag only, even if the limit and balance of the trust line are 0. This Amendment is not currently enabled.
### TrustSet Flags ###
@@ -730,6 +799,58 @@ Transactions of the TrustSet type support additional values in the [`Flags` fiel
| tfClearFreeze | 0x00200000 | 2097152 | [Unfreeze](concept-freeze.html) the trustline. |
+
+## SignerListSet ##
+[[Source] ](https://github.com/ripple/rippled/blob/ef511282709a6a0721b504c6b7703f9de3eecf38/src/ripple/app/tx/impl/SetSignerList.cpp "Source")
+
+The SignerListSet transaction creates, replaces, or removes a list of signers that can be used to [multi-sign](#multi-signing) a transaction. This transaction type is introduced by the [MultiSign amendment](concept-amendments.html#multisign). _(New in [version 0.31.0][])_
+
+Example SignerListSet:
+
+```
+{
+ "Flags": 0,
+ "TransactionType": "SignerListSet",
+ "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
+ "Fee": "10000",
+ "SignerQuorum": 3,
+ "SignerEntries": [
+ {
+ "SignerEntry": {
+ "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
+ "SignerWeight": 2
+ }
+ },
+ {
+ "SignerEntry": {
+ "Account": "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
+ "SignerWeight": 1
+ }
+ },
+ {
+ "SignerEntry": {
+ "Account": "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
+ "SignerWeight": 1
+ }
+ }
+ ]
+}
+```
+
+| Field | JSON Type | [Internal Type](https://wiki.ripple.com/Binary_Format) | Description |
+|-------|-----------|--------------------------------------------------------|-------------|
+| SignerQuorum | Number | UInt32 | A target number for the signer weights. A multi-signature from this list is valid only if the sum weights of the signatures provided is greater than or equal to this value. To delete a SignerList, use the value `0`. |
+| SignerEntries | Array | Array | (Omitted when deleting) Array of [SignerEntry objects](reference-ledger-format.html#signerentry-object), indicating the addresses and weights of signers in this list. A SignerList must have at least 1 member and no more than 8 members. No address may appear more than once in the list, nor may the `Account` submitting the transaction appear in the list. |
+
+An account may not have more than one SignerList. A successful SignerListSet transaction replaces the existing SignerList, if one exists. To delete a SignerList, you must set `SignerQuorum` to `0` _and_ omit the `SignerEntries` field. Otherwise, the transaction fails with the error [temMALFORMED](#tem-codes). A transaction to delete a SignerList is considered successful even if there was no SignerList to delete.
+
+You cannot create a SignerList such that the SignerQuorum could never be met. The SignerQuorum must be greater than 0 but less than or equal to the sum of the `SignerWeight` values in the list. Otherwise, the transaction fails with the error [temMALFORMED](#tem-codes).
+
+You can create, update, or remove a SignerList using the master key, regular key, or the current SignerList, if those methods of signing transactions are available.
+
+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](reference-ledger-format.html#accountroot-flags) enabled) and the account does not have a [Regular Key](#setregularkey) configured, then you cannot delete the SignerList from the account. Instead, the transaction fails with the error [tecNO\_ALTERNATIVE\_KEY](#tec-codes).
+
+
# Pseudo-Transactions #
Pseudo-Transactions are never submitted by users, nor propagated through the network. Instead, a server may choose to inject them in a proposed ledger directly. If enough servers inject an equivalent pseudo-transaction for it to pass consensus, then it becomes included in the ledger, and appears in ledger data thereafter.
@@ -746,9 +867,9 @@ Some of the fields that are mandatory for normal transactions do not make sense
## SetFee ##
-A change in [transaction cost](concept-transaction-cost.html) or [account reserve](concept-reserves.html) requirements. This is typically in response to changes in the load on the network.
+A change in [transaction cost](concept-transaction-cost.html) or [account reserve](concept-reserves.html) requirements as a result of [Fee Voting](concept-fee-voting.html).
-*Note:* You cannot send a pseudo-transaction, but you may encounter one when processing ledgers.
+**Note:** You cannot send a pseudo-transaction, but you may encounter one when processing ledgers.
```
{
@@ -773,6 +894,29 @@ A change in [transaction cost](concept-transaction-cost.html) or [account reserv
| ReferenceFeeUnits | Unsigned Integer | UInt32 | The cost, in fee units, of the reference transaction |
| ReserveBase | Unsigned Integer | UInt32 | The base reserve, in drops |
| ReserveIncrement | Unsigned Integer | UInt32 | The incremental reserve, in drops |
+| LedgerSequence | Number | UInt32 | The index of the ledger version where this pseudo-transaction appears. This distinguishes the pseudo-transaction from other occurrences of the same change. |
+
+## EnableAmendment ##
+
+Tracks the progress of the [amendment process](concept-amendments.html#amendment-process) for changes in transaction processing. This can indicate that a proposed amendment gained or lost majority approval, or that an amendment has been enabled.
+
+**Note:** You cannot send a pseudo-transaction, but you may encounter one when processing ledgers.
+
+| Field | JSON Type | [Internal Type](https://wiki.ripple.com/Binary_Format) | Description |
+|-------|-----------|--------------------------------------------------------|-------------|
+| Amendment | String | Hash256 | A unique identifier for the amendment. This is not intended to be a human-readable name. See [Amendments](concept-amendments.html) for a list of known amendments. |
+| LedgerSequence | Number | UInt32 | The index of the ledger version where this amendment appears. This distinguishes the pseudo-transaction from other occurrences of the same change. |
+
+### EnableAmendment Flags ###
+
+The `Flags` value of the EnableAmendment pseudo-transaction indicates the status of the amendment at the time of the ledger including the pseudo-transaction.
+
+A `Flags` value of `0` (no flags) indicates that the amendment has been enabled, and applies to all ledgers afterward. Other `Flags` values are as follows:
+
+| Flag Name | Hex Value | Decimal Value | Description |
+|-----------|-----------|---------------|-------------|
+| tfGotMajority | 0x00010000 | 65536 | Support for this amendment increased to at least 80% of trusted validators starting with this ledger version. |
+| tfLostMajority | 0x00020000 | 131072 | Support for this amendment decreased to less than 80% of trusted validators starting with this ledger version. |
@@ -780,7 +924,7 @@ A change in [transaction cost](concept-transaction-cost.html) or [account reserv
## Immediate Response ##
-The response from the [`submit` command](reference-rippled.html#submit) contains a provisional result from the `rippled` server indicating what happened during local processing of the transaction.
+The response from the [`submit` command](reference-rippled.html#submit) contains a provisional result from the `rippled` server indicating what happened during local processing of the transaction.
The response from `submit` contains the following fields:
@@ -802,7 +946,7 @@ __*Note:*__ A successful result at this stage does not indicate that the transac
## Looking up Transaction Results ##
-To see the final result of a transaction, use the [`tx` command](reference-rippled.html#tx), [`account_tx` command](reference-rippled.html#account-tx), or other response from `rippled`. Look for `"validated": true` to indicate that this response uses a ledger version that has been validated by consensus.
+To see the final result of a transaction, use the [`tx` command](reference-rippled.html#tx), [`account_tx` command](reference-rippled.html#account-tx), or other response from `rippled`. Look for `"validated": true` to indicate that this response uses a ledger version that has been validated by consensus.
| Field | Value | Description |
|-------|-------|-------------|
@@ -901,12 +1045,12 @@ These codes indicate an error in the local server processing the transaction; it
| Code | Explanation |
|------|-------------|
-| telLOCAL_ERROR | Unspecified local error. |
| telBAD\_DOMAIN | The transaction specified a domain value (for example, the `Domain` field of an [AccountSet transaction](#accountset)) that cannot be used, probably because it is too long to store in the ledger. |
| telBAD\_PATH_COUNT | The transaction contains too many paths for the local server to process. |
| telBAD\_PUBLIC\_KEY | The transaction specified a public key value (for example, as the `MessageKey` field of an [AccountSet transaction](#accountset)) that cannot be used, probably because it is too long. |
| telFAILED\_PROCESSING | An unspecified error occurred when processing the transaction. |
| telINSUF\_FEE_P | The `Fee` from the transaction is not high enough to meet the server's current [transaction cost](concept-transaction-cost.html) requirement, which is derived from its load level. |
+| telLOCAL_ERROR | Unspecified local error. |
| telNO\_DST\_PARTIAL | The transaction is an XRP payment that would fund a new account, but the [tfPartialPayment flag](#partial-payments) was enabled. This is disallowed. |
### tem Codes ###
@@ -915,7 +1059,6 @@ These codes indicate that the transaction was malformed, and cannot succeed acco
| Code | Explanation |
|------|-------------|
-| temMALFORMED | Unspecified problem with the format of the transaction. |
| temBAD\_AMOUNT | An amount specified by the transaction (for example the destination `Amount` or `SendMax` values of a [Payment](#payment)) was invalid, possibly because it was a negative number. |
| temBAD\_AUTH\_MASTER | The key used to sign this transaction does not match the master key for the account sending it, and the account does not have a [Regular Key](#setregularkey) set. |
| temBAD\_CURRENCY | The transaction improperly specified a currency field. See [Specifying Currency Amounts](reference-rippled.html#specifying-currency-amounts) for the correct format. |
@@ -935,13 +1078,21 @@ These codes indicate that the transaction was malformed, and cannot succeed acco
| temBAD\_SIGNATURE | The signature to authorize this transaction is either missing, or formed in a way that is not a properly-formed signature. (See [tecNO_PERMISSION](#tec-codes) for the case where the signature is properly formed, but not authorized for this account.) |
| temBAD\_SRC\_ACCOUNT | The `Account` on whose behalf this transaction is being sent (the "source account") is not a properly-formed Ripple account. |
| temBAD\_TRANSFER\_RATE | The [`TransferRate` field of an AccountSet transaction](#transferrate) is not properly formatted. |
-| temDST\_IS\_SRC | The [TrustSet](#trustset) transaction improperly specified the destination of the trustline (the `issuer` field of `LimitAmount`) as the `Account` sending the transaction. You cannot extend a trustline to yourself. (In the future, this code could also apply to other cases where the destination of a transaction is not allowed to be the account sending it.) |
+| temDST\_IS\_SRC | The [TrustSet](#trustset) transaction improperly specified the destination of the trust line (the `issuer` field of `LimitAmount`) as the `Account` sending the transaction. You cannot extend a trust line to yourself. (In the future, this code could also apply to other cases where the destination of a transaction is not allowed to be the account sending it.) |
| temDST\_NEEDED | The transaction improperly omitted a destination. This could be the `Destination` field of a [Payment](#payment) transaction, or the `issuer` sub-field of the `LimitAmount` field fo a `TrustSet` transaction. |
| temINVALID | The transaction is otherwise invalid. For example, the transaction ID may not be the right format, the signature may not be formed properly, or something else went wrong in understanding the transaction. |
| temINVALID\_FLAG | The transaction includes a [Flag](#flags) that does not exist, or includes a contradictory combination of flags. |
+| temMALFORMED | Unspecified problem with the format of the transaction. |
| temREDUNDANT | The transaction would accomplish nothing; for example, it is sending a payment directly to the sending account, or creating an offer to buy and sell the same currency from the same issuer. |
| temREDUNDANT\_SEND\_MAX | _(Removed in [rippled 0.28.0][])_ |
| temRIPPLE\_EMPTY | The [Payment](#payment) transaction includes an empty `Paths` field, but paths are necessary to complete this payment. |
+| temBAD_WEIGHT | The [SignerListSet](#signerlistset) transaction includes a `SignerWeight` that is invalid, for example a zero or negative value. |
+| temBAD_SIGNER | The [SignerListSet](#signerlistset) transaction includes a signer who is invalid. For example, there may be duplicate entries, or the owner of the SignerList may also be a member. |
+| temBAD_QUORUM | The [SignerListSet](#signerlistset) transaction has an invalid `SignerQuorum` value. Either the value is not greater than zero, or it is more than the sum of all signers in the list. |
+| temUNCERTAIN | Used internally only. This code should never be returned. |
+| temUNKNOWN | Used internally only. This code should never be returned. |
+| temDISABLED | The transaction requires logic that is currently disabled. Typically this means you are trying to use an [amendment](concept-amendments.html) that is not enabled for the current ledger. |
+
### tef Codes ###
@@ -949,19 +1100,23 @@ These codes indicate that the transaction failed to apply, but the transaction c
| Code | Explanation |
|------|-------------|
-| tefFAILURE | Unspecified failure in applying the transaction. |
| tefALREADY | The same exact transaction has already been applied. |
-| tefBAD\_ADD\_AUTH | Deprecated. This code should never be returned. |
+| tefBAD\_ADD\_AUTH | **DEPRECATED.** |
| tefBAD\_AUTH | The key used to sign this account is not authorized to modify this account. (It could be authorized if the account had the same key set as the [Regular Key](#setregularkey).) |
-| tefBAD\_LEDGER | While processing the transaction, the ledger was discovered in an unexpected state. If you can reproduce this error, please [file a bug](https://ripplelabs.atlassian.net/secure/CreateIssueDetails!init.jspa?pid=10800&issuetype=1) to get it fixed. |
-| tefCREATED | Deprecated. This code should never be returned. |
-| tefEXCEPTION | While processing the transaction, the server entered an unexpected state. This may be caused by unexpected inputs, for example if the binary data for the transaction is grossly malformed. If you can reproduce this error, please [file a bug](https://ripplelabs.atlassian.net/secure/CreateIssueDetails!init.jspa?pid=10800&issuetype=1) to get it fixed. |
-| tefINTERNAL | While attempting to apply the transaction, the server entered an unexpected state. If you can reproduce this error, please [file a bug](https://ripplelabs.atlassian.net/secure/CreateIssueDetails!init.jspa?pid=10800&issuetype=1) to get it fixed. |
-| tefNO\_AUTH\_REQUIRED | The [TrustSet](#trustset) transaction attempted to mark a trustline as authorized, but the `lsfRequireAuth` flag is not enabled for the corresponding account, so authorization is not necessary. |
-| tefPAST\_SEQ | The sequence number of the transaction is lower than the current sequence number of the account sending the transaction. |
-| tefWRONG\_PRIOR | The transaction contained an `AccountTxnID` field (or the deprecated `PreviousTxnID` field), but the transaction specified there does not match the account's previous transaction. |
+| tefBAD\_AUTH\_MASTER | The single signature provided to authorize this transaction does not match the master key, but no regular key is associated with this address. |
+| tefBAD\_LEDGER | While processing the transaction, the ledger was discovered in an unexpected state. If you can reproduce this error, please [report an issue](https://github.com/ripple/rippled/issues) to get it fixed. |
+| tefBAD\_QUORUM | The transaction was [multi-signed](#multi-signing), but the total weights of all included signatures did not meet the quorum. |
+| tefBAD\_SIGNATURE | The transaction was [multi-signed](#multi-signing), but contained a signature for an address not part of a SignerList associated with the sending account. |
+| tefCREATED |**DEPRECATED.** |
+| tefEXCEPTION | While processing the transaction, the server entered an unexpected state. This may be caused by unexpected inputs, for example if the binary data for the transaction is grossly malformed. If you can reproduce this error, please [report an issue](https://github.com/ripple/rippled/issues) to get it fixed. |
+| tefFAILURE | Unspecified failure in applying the transaction. |
+| tefINTERNAL | While attempting to apply the transaction, the server entered an unexpected state. If you can reproduce this error, please [report an issue](https://github.com/ripple/rippled/issues) to get it fixed. |
| tefMASTER\_DISABLED | The transaction was signed with the account's master key, but the account has the `lsfDisableMaster` field set. |
| tefMAX\_LEDGER | The transaction included a [`LastLedgerSequence`](#lastledgersequence) parameter, but the current ledger's sequence number is already higher than the specified value. |
+| tefNO\_AUTH\_REQUIRED | The [TrustSet](#trustset) transaction attempted to mark a trustline as authorized, but the `lsfRequireAuth` flag is not enabled for the corresponding account, so authorization is not necessary. |
+| tefNOT\_MULTI\_SIGNING | The transaction was [multi-signed](#multi-signing), but the sending account has no SignerList defined. |
+| tefPAST\_SEQ | The sequence number of the transaction is lower than the current sequence number of the account sending the transaction. |
+| tefWRONG\_PRIOR | The transaction contained an `AccountTxnID` field (or the deprecated `PreviousTxnID` field), but the transaction specified there does not match the account's previous transaction. |
### ter Codes ###
@@ -969,16 +1124,16 @@ These codes indicate that the transaction failed to apply, but it could apply su
| Code | Explanation |
|------|-------------|
-| terRETRY | Unspecified retriable error. |
-| terFUNDS\_SPENT | Deprecated. This code should never be returned. |
+| terFUNDS\_SPENT | **DEPRECATED.** |
| terINSUF\_FEE\_B | The account sending the transaction does not have enough XRP to pay the `Fee` specified in the transaction. |
-| terNO\_ACCOUNT | The account sending the transaction does not exist in the ledger (yet). |
-| terNO\_AUTH | The transaction would involve adding currency issued by an account with `lsfRequireAuth` enabled to a trustline that is not authorized. For example, you placed an offer to buy a currency you aren't authorized to hold. |
+| terLAST | Used internally only. This code should never be returned. |
+| terNO\_ACCOUNT | The address sending the transaction is not funded in the ledger (yet). |
+| terNO\_AUTH | The transaction would involve adding currency issued by an account with `lsfRequireAuth` enabled to a trust line that is not authorized. For example, you placed an offer to buy a currency you aren't authorized to hold. |
| terNO\_LINE | Used internally only. This code should never be returned. |
+| terNO\_RIPPLE | Used internally only. This code should never be returned. |
| terOWNERS | The transaction requires that account sending it has a nonzero "owners count", so the transaction cannot succeed. For example, an account cannot enable the [`lsfRequireAuth`](#accountset-flags) flag if it has any trust lines or available offers. |
| terPRE\_SEQ | The `Sequence` number of the current transaction is higher than the current sequence number of the account sending the transaction. |
-| terLAST | Used internally only. This code should never be returned. |
-| terNO\_RIPPLE | Used internally only. This code should never be returned. |
+| terRETRY | Unspecified retriable error. |
### tes Success ###
@@ -995,40 +1150,39 @@ These codes indicate that the transaction failed, but it was applied to a ledger
| Code | Value | Explanation |
|------|-------|-------------|
| tecCLAIM | 100 | Unspecified failure, with transaction cost destroyed. |
-| tecPATH\_PARTIAL | 101 | The transaction failed because the provided paths did not have enough liquidity to send the full amount. |
-| tecUNFUNDED\_ADD | 102 | **DEPRECATED.** |
-| tecUNFUNDED\_OFFER | 103 | The [OfferCreate transaction](#offercreate) failed because the account creating the offer does not have any of the `TakerGets` currency. |
-| tecUNFUNDED\_PAYMENT | 104 | The transaction failed because the sending account is trying to send more XRP than it holds, not counting the reserve. (See: [Reserves](concept-reserves.html)) |
+| tecDIR\_FULL | 121 | The address sending the transaction cannot own any more objects in the ledger. |
+| tecDST\_TAG\_NEEDED | 143 | The [Payment](#payment) transaction omitted a destination tag, but the destination account has the `lsfRequireDestTag` flag enabled. _(New in [rippled 0.28.0][])_ |
| tecFAILED\_PROCESSING | 105 | An unspecified error occurred when processing the transaction. |
-| tecDIR\_FULL | 121 | The "owners count" of the account sending the transaction is already maxed out. |
+| tecFROZEN | 137 | The [OfferCreate transaction](#offercreate) failed because one or both of the assets involved are subject to a [global freeze](concept-freeze.html). |
| tecINSUF\_RESERVE\_LINE | 122 | The transaction failed because the sending account does not have enough XRP to create a new trust line. (See: [Reserves](concept-reserves.html)) This error occurs when the counterparty already has a trust line in a non-default state to the sending account for the same currency. (See tecNO\_LINE\_INSUF\_RESERVE for the other case.) |
| tecINSUF\_RESERVE\_OFFER | 123 | The transaction failed because the sending account does not have enough XRP to create a new Offer. (See: [Reserves](concept-reserves.html)) |
+| tecINSUFFICIENT\_RESERVE | 141 | The [SignerListSet](#signerlistset) or other transaction would increase the [reserve requirement](concept-reserves.html) higher than the sending account's balance. See [SignerLists and Reserves](reference-ledger-format.html#signerlists-and-reserves) for more information. |
+| tecINTERNAL | 144 | Unspecified internal error, with transaction cost applied. This error code should not normally be returned. |
+| tecNEED\_MASTER\_KEY | 142 | This transaction attempted to cause changes that require the master key, such as [disabling the master key or giving up the ability to freeze balances](#accountset-flags). _(New in [rippled 0.28.0](https://github.com/ripple/rippled/releases/tag/0.28.0-rc1))_ |
+| tecNO\_ALTERNATIVE\_KEY | 130 | The transaction tried to remove the only available method of [authorizing transactions](#authorizing-transactions). This could be a [SetRegularKey transaction](#setregularkey) to remove the regular key, a [SignerListSet transaction](#signerlistset) to delete a SignerList, or an [AccountSet transaction](#accountset) to disable the master key. (Prior to [rippled 0.30.0](https://github.com/ripple/rippled/releases/tag/0.30.0), this was called `tecMASTER_DISABLED`.) |
+| tecNO\_AUTH | 134 | The transaction failed because it needs to add a balance on a trust line to an account with the `lsfRequireAuth` flag enabled, and that trust line has not been authorized. If the trust line does not exist at all, tecNO\_LINE occurs instead. |
| tecNO\_DST | 124 | The account on the receiving end of the transaction does not exist. This includes Payment and TrustSet transaction types. (It could be created if it received sufficient XRP.) |
| tecNO\_DST\_INSUF_XRP | 125 | The account on the receiving end of the transaction does not exist, and the transaction is not sending enough XRP to create it. |
+| tecNO\_ENTRY | 140 | Reserved for future use. |
+| tecNO\_ISSUER | 133 | The account specified in the `issuer` field of a currency amount does not exist. |
+| tecNO\_LINE | 135 | The `TakerPays` field of the [OfferCreate transaction](#offercreate) specifies an asset whose issuer has `lsfRequireAuth` enabled, and the account making the offer does not have a trust line for that asset. (Normally, making an offer implicitly creates a trust line if necessary, but in this case it does not bother because you cannot hold the asset without authorization.) If the trust line exists, but is not authorized, `tecNO_AUTH` occurs instead. |
| tecNO\_LINE\_INSUF\_RESERVE | 126 | The transaction failed because the sending account does not have enough XRP to create a new trust line. (See: [Reserves](concept-reserves.html)) This error occurs when the counterparty does not have a trust line to this account for the same currency. (See tecINSUF\_RESERVE\_LINE for the other case.) |
| tecNO\_LINE\_REDUNDANT | 127 | The transaction failed because it attempted to set a trust line to its default state, but the trust line did not exist. |
-| tecPATH\_DRY | 128 | The transaction failed because the provided paths did not have enough liquidity to send anything at all. This could mean that the source and destination accounts are not linked by trust lines. |
-| tecUNFUNDED | 129 | **DEPRECATED.** Replaced by tecUNFUNDED\_OFFER and tecUNFUNDED\_PAYMENT. |
-| tecMASTER\_DISABLED | 130 | The [SetRegularKey transaction](#setregularkey) tried to unset the Regular Key, but the account has the `lsfDisableMaster` flag enabled. (Unsetting the Regular Key while also leaving the Master Key disabled would make the account unusable.) |
-| tecNO\_REGULAR\_KEY | 131 | The [AccountSet transaction](#accountset) tried to disable the Master Key, but the account does not have a Regular Key set. (Disabling the Master Key without having a Regular Key configured would make the account unusable.) |
-| tecOWNERS | 132 | The transaction requires that account sending it has a nonzero "owners count", so the transaction cannot succeed. For example, an account cannot enable the [`lsfRequireAuth`](#accountset-flags) flag if it has any trust lines or available offers. |
-| tecNO\_ISSUER | 133 | The account specified in the `issuer` field of a currency amount does not exist. |
-| tecNO\_AUTH | 134 | The transaction failed because it needs to add a balance on a trust line to an account with the `lsfRequireAuth` flag enabled, and that trust line has not been authorized. If the trust line does not exist at all, tecNO\_LINE occurs instead. |
-| tecNO\_LINE | 135 | The `TakerPays` field of the [OfferCreate transaction](#offercreate) specifies an asset whose issuer has `lsfRequireAuth` enabled, and the account making the offer does not have a trust line for that asset. (Normally, making an offer implicitly creates a trust line if necessary, but in this case it does not bother because you cannot hold the asset without authorization.) If the trust line exists, but is not authorized, tecNO\_AUTH occurs instead. |
-| tecINSUFF\_FEE | 136 | The account sending the transaction does not possess enough XRP to pay the specified `Fee`. This error only occurs if the transaction has already been propagated through the network to achieve consensus, |
-| tecFROZEN | 137 | The [OfferCreate transaction](#offercreate) failed because one or both of the assets involved are subject to a [global freeze](concept-freeze.html). |
-| tecNO\_TARGET | 138 | **FORTHCOMING** Part of multi-signature transactions. |
-| tecNO\_PERMISSION | 139 | **FORTHCOMING** Part of multi-signature transactions. |
-| tecNO\_ENTRY | 140 | **FORTHCOMING** Part of multi-signature transactions. |
-| tecINSUFFICIENT\_RESERVE | 141 | **FORTHCOMING** Part of multi-signature transactions. (Code may change; see [RIPD-743](https://ripplelabs.atlassian.net/browse/RIPD-743) for status.) |
-| tecNEED\_MASTER\_KEY | 142 | This transaction attempted to cause changes that require the master key, such as [disabling the master key or giving up the ability to freeze balances](#accountset-flags). _(New in [rippled 0.28.0](https://github.com/ripple/rippled/releases/tag/0.28.0-rc1))_ |
-| tecDST\_TAG\_NEEDED | 143 | The [Payment](#payment) transaction omitted a destination tag, but the destination account has the `lsfRequireDestTag` flag enabled. _(New in [rippled 0.28.0][])_ |
-| tecINTERNAL | 144 | Unspecified internal error, with transaction cost applied. This error code should not normally be returned. |
+| tecNO\_PERMISSION | 139 | Reserved for future use. |
+| tecNO\_REGULAR\_KEY | 131 | The [AccountSet transaction](#accountset) tried to disable the master key, but the account does not have another way to [authorize transactions](#authorizing-transactions). If [multi-signing](#multi-signing) is enabled, this code is deprecated and `tecNO_ALTERNATIVE_KEY` is used instead. |
+| tecNO\_TARGET | 138 | Reserved for future use. |
| tecOVERSIZE | 145 | This transaction could not be processed, because attempted transaction processing created an excessively large amount of metadata. _(New in [rippled 0.29.0-hf1](https://github.com/ripple/rippled/releases/tag/0.29.0-hf1) )_ |
+| tecOWNERS | 132 | The transaction requires that account sending it has a nonzero "owners count", so the transaction cannot succeed. For example, an account cannot enable the [`lsfRequireAuth`](#accountset-flags) flag if it has any trust lines or available offers. |
+| tecPATH\_DRY | 128 | The transaction failed because the provided paths did not have enough liquidity to send anything at all. This could mean that the source and destination accounts are not linked by trust lines. |
+| tecPATH\_PARTIAL | 101 | The transaction failed because the provided paths did not have enough liquidity to send the full amount. |
+| tecUNFUNDED | 129 | **DEPRECATED.** Replaced by tecUNFUNDED\_OFFER and tecUNFUNDED\_PAYMENT. |
+| tecUNFUNDED\_ADD | 102 | **DEPRECATED.** |
+| tecUNFUNDED\_PAYMENT | 104 | The transaction failed because the sending account is trying to send more XRP than it holds, not counting the reserve. (See: [Reserves](concept-reserves.html)) |
+| tecUNFUNDED\_OFFER | 103 | The [OfferCreate transaction](#offercreate) failed because the account creating the offer does not have any of the `TakerGets` currency. |
### tej Codes ###
-These codes are only ever returned by the `ripple-lib` client library, not by `rippled` itself.
+These codes are only ever returned by the `ripple-lib` client library, not by `rippled` itself.
| Code | Explanation |
|------|-------------|
@@ -1042,4 +1196,3 @@ These codes are only ever returned by the `ripple-lib` client library, not by `r
| tejSecretUnknown | The secret for a given account was omitted from the transaction, and ripple-lib was unable to automatically fill it in from saved data. |
| tejServerUntrusted | The application attempted to submit an account secret to an untrusted server for transaction signing. |
| tejUnconnected | The application is not connected to a `rippled` server, but it needs to be in order to process the transaction. |
-
diff --git a/content/tutorial-multisign.md b/content/tutorial-multisign.md
new file mode 100644
index 0000000000..700b2dba84
--- /dev/null
+++ b/content/tutorial-multisign.md
@@ -0,0 +1,605 @@
+How to Multi-Sign
+=============================
+
+Multi-signing is one of three ways to authorize transactions for the Ripple Consensus Ledger, alongside signing with [regular keys](reference-transaction-format.html#setregularkey) and master keys. You can configure your address to allow any combination of the three methods to authorize transactions.
+
+Benefits of multi-signing include:
+
+* You can require keys from different devices, so that a malicious actor must compromise multiple machines to send transactions on your behalf.
+* You can share custody of an address between multiple people, each of whom only has one of several keys necessary to send transactions from that address.
+* You can delegate the power to send transactions from your address to a group of people, who can control your address if you are unavailable or unable to sign normally.
+* ... and more.
+
+To use multi-signing:
+
+1. [The Ripple peer-to-peer network must have multi-signing enabled.](#availability-of-multi-signing)
+2. [Set up a list of signers on your account.](#setting-up-multi-signing)
+3. [Send transactions using multiple signatures.](#sending-a-multi-signed-transaction)
+
+
+Availability of Multi-Signing
+-----------------------------
+
+Multi-signing is built into `rippled` starting with [version 0.31.0](https://wiki.ripple.com/Rippled-0.31.0). Because multi-signing is a change in transaction processing, the change is due to be enabled by an **Amendment** to the Ripple Consensus Protocol. This Amendment must be approved by a consensus of validators showing consistent support for the feature over a period of time. For more information, see [Amendments](concept-amendments.html).
+
+If you want to test multi-signing before it becomes available in the production network, or without risking real money, you can do so by running `rippled` in [stand-alone mode](concept-stand-alone-mode.html) with the MultiSign feature enabled. To enable multi-signing for testing, add the following stanza to your `rippled.cfg`:
+
+ [features]
+ MultiSign
+
+
+Setting up Multi-Signing
+------------------------
+
+Before you can set up multi-signing, first check that [multi-signing is available](#availability-of-multi-signing).
+
+To multi-sign transactions from a particular address, you must create a list of addresses that can contribute to a multi-signature for your address. This list is stored in the Ripple Consensus Ledger as a [SignerList node](reference-ledger-format.html#signerlist). The following procedure demonstrates how to set up a SignerList for your address:
+
+
+### 1. Prepare a funded address ###
+
+You need a Ripple address that can send transactions, and has enough XRP available. Multi-signing requires more than the usual amount of XRP for the [account reserve](concept-reserves.html) and [transaction cost](concept-transaction-cost.html), increasing with the number of signers and signatures you use.
+
+If you started `rippled` in [stand-alone mode](concept-stand-alone-mode.html) with a new genesis ledger, you must:
+
+1. Generate keys for a new address, or reuse keys you already have.
+2. Submit a Payment transaction to fund the new address from the genesis account. (Send at least 100,000,000 [drops of XRP](reference-rippled.html#specifying-currency-amounts).)
+3. Manually close the ledger.
+
+
+### 2. Prepare member keys ###
+
+You need several sets of Ripple keys (address and secret) to include as members of your SignerList. These can be funded addresses that exist in the ledger, or you can generate new addresses using the [`wallet_propose` command](reference-rippled.html#wallet-propose). For example:
+
+ $ rippled wallet_propose
+ Loading: "/home/mduo13/.config/ripple/rippled.cfg"
+ Connecting to 127.0.0.1:5005
+ {
+ "result" : {
+ "account_id" : "rnRJ4dpSBKDR2M1itf4Ah6tZZm5xuNZFPH",
+ "key_type" : "secp256k1",
+ "master_key" : "FLOG SEND GOES CUFF GAGE FAT ANTI DEL GUM TIRE ISLE BEAR",
+ "master_seed" : "snheH5UUjU4CWqiNVLny2k21TyKPC",
+ "master_seed_hex" : "A9F859765EB8614D26809836382AFB82",
+ "public_key" : "aBR4hxFXcDNHnGYvTiqb2KU8TTTV1cYV9wXTAuz2DjBm7S8TYEBU",
+ "public_key_hex" : "03C09A5D112B393D531E4F092E3A5769A5752129F0A9C55C61B3A226BB9B567B9B",
+ "status" : "success"
+ }
+ }
+
+Take note of the `account_id` (Ripple Address) and `master_seed` (Ripple secret key) for each one you generate.
+
+
+### 3. Send SignerListSet transaction ###
+
+[Sign and submit](reference-transaction-format.html#signing-and-submitting-transactions) a [SignerListSet transaction](reference-transaction-format.html#signerlistset) in the normal (single-signature) way. This associates a SignerList with your Ripple address, so that a combination of signatures from the members of that SignerList can multi-sign later transactions on your behalf.
+
+In this example, the SignerList has 3 members, with the weights and quorum set up such that multi-signed transactions need a signature from rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW plus at least one signature from the other two members of the list.
+
+**Caution:** Never submit a secret key to a server you do not control. Do not transmit a secret key unencrypted over the network.
+
+ $ rippled submit shqZZy2Rzs9ZqWTCQAdqc3bKgxnYq '{
+ > "Flags": 0,
+ > "TransactionType": "SignerListSet",
+ > "Account": "rnBFvgZphmN39GWzUJeUitaP22Fr9be75H",
+ > "Fee": "10000",
+ > "SignerQuorum": 3,
+ > "SignerEntries": [
+ > {
+ > "SignerEntry": {
+ > "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
+ > "SignerWeight": 2
+ > }
+ > },
+ > {
+ > "SignerEntry": {
+ > "Account": "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
+ > "SignerWeight": 1
+ > }
+ > },
+ > {
+ > "SignerEntry": {
+ > "Account": "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
+ > "SignerWeight": 1
+ > }
+ > }
+ > ]
+ > }'
+ Loading: "/home/mduo13/.config/ripple/rippled.cfg"
+ Connecting to 127.0.0.1:5005
+ {
+ "result" : {
+ "engine_result" : "tesSUCCESS",
+ "engine_result_code" : 0,
+ "engine_result_message" : "The transaction was applied. Only final in a validated ledger.",
+ "status" : "success",
+ "tx_blob" : "12000C2200000000240000000120230000000368400000000000271073210303E20EC6B4A39A629815AE02C0A1393B9225E3B890CAE45B59F42FA29BE9668D74473045022100BEDFA12502C66DDCB64521972E5356F4DB965F553853D53D4C69B4897F11B4780220595202D1E080345B65BAF8EBD6CA161C227F1B62C7E72EA5CA282B9434A6F04281142DECAB42CA805119A9BA2FF305C9AFA12F0B86A1F4EB1300028114204288D2E47F8EF6C99BCC457966320D12409711E1EB13000181147908A7F0EDD48EA896C3580A399F0EE78611C8E3E1EB13000181143A4C02EA95AD6AC3BED92FA036E0BBFB712C030CE1F1",
+ "tx_json" : {
+ "Account" : "rnBFvgZphmN39GWzUJeUitaP22Fr9be75H",
+ "Fee" : "10000",
+ "Flags" : 0,
+ "Sequence" : 1,
+ "SignerEntries" : [
+ {
+ "SignerEntry" : {
+ "Account" : "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
+ "SignerWeight" : 2
+ }
+ },
+ {
+ "SignerEntry" : {
+ "Account" : "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
+ "SignerWeight" : 1
+ }
+ },
+ {
+ "SignerEntry" : {
+ "Account" : "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
+ "SignerWeight" : 1
+ }
+ }
+ ],
+ "SignerQuorum" : 3,
+ "SigningPubKey" : "0303E20EC6B4A39A629815AE02C0A1393B9225E3B890CAE45B59F42FA29BE9668D",
+ "TransactionType" : "SignerListSet",
+ "TxnSignature" : "3045022100BEDFA12502C66DDCB64521972E5356F4DB965F553853D53D4C69B4897F11B4780220595202D1E080345B65BAF8EBD6CA161C227F1B62C7E72EA5CA282B9434A6F042",
+ "hash" : "3950D98AD20DA52EBB1F3937EF32F382D74092A4C8DF9A0B1A06ED25200B5756"
+ }
+ }
+ }
+
+Make sure that the [Transaction Result](reference-transaction-format.html#transaction-results) is [**tesSUCCESS**](reference-transaction-format.html#tes-success). Otherwise, the transaction failed.
+
+**Note:** The more members in the SignerList, the more XRP your address must have for purposes of the [owner reserve](concept-reserves.html#owner-reserves). If your address does not have enough XRP, the transaction fails with [tecINSUFFICIENT_RESERVE](reference-transaction-format.html#tec-codes). See also: [SignerLists and Reserves](reference-ledger-format.html#signerlists-and-reserves).
+
+
+### 4. Close the ledger ###
+
+On the live network, you can wait 4-7 seconds for the ledger to close automatically.
+
+If you're running `rippled` in stand-alone mode, use the [`ledger_accept` command](reference-rippled.html#ledger-accept) to manually close the ledger:
+
+ $ rippled ledger_accept
+ Loading: "/home/mduo13/.config/ripple/rippled.cfg"
+ Connecting to 127.0.0.1:5005
+ {
+ "result" : {
+ "ledger_current_index" : 6,
+ "status" : "success"
+ }
+ }
+
+
+### 5. Confirm the new signer list ###
+
+Use the [`account_objects` command](reference-rippled.html#account-objects) to confirm that the SignerList is associated with the address in the latest validated ledger.
+
+Normally, an account can own many objects of different types (such as trust lines and offers). If you funded a new address for this tutorial, the SignerList is the only object in the response.
+
+ $ rippled account_objects rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC validated
+ Loading: "/home/mduo13/.config/ripple/rippled.cfg"
+ Connecting to 127.0.0.1:5005
+ {
+ "result" : {
+ "account" : "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
+ "account_objects" : [
+ {
+ "Flags" : 0,
+ "LedgerEntryType" : "SignerList",
+ "OwnerNode" : "0000000000000000",
+ "PreviousTxnID" : "8FDC18960455C196A8C4DE0D24799209A21F4A17E32102B5162BD79466B90222",
+ "PreviousTxnLgrSeq" : 5,
+ "SignerEntries" : [
+ {
+ "SignerEntry" : {
+ "Account" : "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
+ "SignerWeight" : 2
+ }
+ },
+ {
+ "SignerEntry" : {
+ "Account" : "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
+ "SignerWeight" : 1
+ }
+ },
+ {
+ "SignerEntry" : {
+ "Account" : "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
+ "SignerWeight" : 1
+ }
+ }
+ ],
+ "SignerListID" : 0,
+ "SignerQuorum" : 3,
+ "index" : "79FD203E4DDDF2EA78B798C963487120C048C78652A28682425E47C96D016F92"
+ }
+ ],
+ "ledger_hash" : "56E81069F06492FB410A70218C08169BE3AB3CFD5AEA20E999662D81DC361D9F",
+ "ledger_index" : 5,
+ "status" : "success",
+ "validated" : true
+ }
+ }
+
+If the SignerList is present with the expected contents, then your address is ready to multi-sign.
+
+### 6. Further steps ###
+
+At this point, your address is ready to [send a multi-signed transaction](#sending-a-multi-signed-transaction). You may also want to:
+
+* Disable the address's master key by sending an [AccountSet transaction](reference-transaction-format.html#accountset) using the `asfDisableMaster` flag.
+* Remove the address's regular key (if you previously set one) by sending a [SetRegularKey transaction](reference-transaction-format.html#setregularkey).
+
+
+Sending a Multi-Signed Transaction
+----------------------------------
+
+Before you can multi-sign a transaction, first [set up multi-signing](#setting-up-multi-signing) for your address. The following procedure demonstrates how to create, sign, and submit a multi-signed transaction.
+
+### 1. Create the transaction ##
+
+Create a JSON object that represents the transaction you want to submit. You have to specify _everything_ about this transaction, including `Fee` and `Sequence`. Also include the field `SigningPubKey` as an empty string, to indicate that the transaction is multi-signed.
+
+Keep in mind that the `Fee` for multi-signed transactions is significantly higher than for regularly-signed transactions. It should be (N+1) times the normal [transaction cost](concept-transaction-cost.html), where N is the number of signatures you plan to provide. Given that it sometimes takes a while to collect signatures from multiple sources, you may want to include additional buffer in case the [transaction cost](concept-transaction-cost.html) increases in that time.
+
+Here's an example transaction ready to be multi-signed:
+
+ {
+ "TransactionType": "TrustSet",
+ "Account": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
+ "Flags": 262144,
+ "LimitAmount": {
+ "currency": "USD",
+ "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
+ "value": "100"
+ },
+ "Sequence": 2,
+ "SigningPubKey": "",
+ "Fee": "30000"
+ }
+
+(This transaction creates an accounting relationship from rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC to rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh with a maximum balance of 100 USD.)
+
+
+### 2. Get one signature ###
+
+Use the [`sign_for` command](reference-rippled.html#sign-for) with the secret key and address of one of the members of your SignerList to get a signature for that member.
+
+**Caution:** Never submit a secret key to a server you do not control. Do not transmit a secret key unencrypted over the network.
+
+ $ rippled sign_for rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW '{
+ > "TransactionType": "TrustSet",
+ > "Account": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
+ > "Flags": 262144,
+ > "LimitAmount": {
+ > "currency": "USD",
+ > "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
+ > "value": "100"
+ > },
+ > "Sequence": 2,
+ > "SigningPubKey": "",
+ > "Fee": "30000"
+ > }'
+ Loading: "/home/mduo13/.config/ripple/rippled.cfg"
+ Connecting to 127.0.0.1:5005
+ {
+ "result" : {
+ "status" : "success",
+ "tx_blob" : "1200142200040000240000000263D5038D7EA4C680000000000000000000000000005553440000000000B5F762798A53D543A014CAF8B297CFF8F2F937E868400000000000753073008114A3780F5CB5A44D366520FC44055E8ED44D9A2270F3E010732102B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF744730450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E58114204288D2E47F8EF6C99BCC457966320D12409711E1F1",
+ "tx_json" : {
+ "Account" : "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
+ "Fee" : "30000",
+ "Flags" : 262144,
+ "LimitAmount" : {
+ "currency" : "USD",
+ "issuer" : "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
+ "value" : "100"
+ },
+ "Sequence" : 2,
+ "Signers" : [
+ {
+ "Signer" : {
+ "Account" : "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
+ "SigningPubKey" : "02B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF",
+ "TxnSignature" : "30450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E5"
+ }
+ }
+ ],
+ "SigningPubKey" : "",
+ "TransactionType" : "TrustSet",
+ "hash" : "A94A6417D1A7AAB059822B894E13D322ED3712F7212CE9257801F96DE6C3F6AE"
+ }
+ }
+ }
+
+Save the `tx_json` field of the response: it has the new signature in the `Signers` field. You can discard the value of the `tx_blob` field.
+
+
+### 3. Get additional signatures ###
+
+You can collect additional signatures in parallel or in serial:
+
+* In parallel: Use the `sign_for` command with the original JSON for the transaction. Each response has a single signature in the `Signers` array.
+* In serial: Use the `sign_for` command with the `tx_json` value from the previous `sign_for` response. Each response adds a new signature to the existing `Signers` array.
+
+**Caution:** Never submit a secret key to a server you do not control. Do not transmit a secret key unencrypted over the network.
+
+ $ rippled sign_for rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v '{
+ > "Account" : "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
+ > "Fee" : "30000",
+ > "Flags" : 262144,
+ > "LimitAmount" : {
+ > "currency" : "USD",
+ > "issuer" : "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
+ > "value" : "100"
+ > },
+ > "Sequence" : 2,
+ > "Signers" : [
+ > {
+ > "Signer" : {
+ > "Account" : "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
+ > "SigningPubKey" : "02B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF",
+ > "TxnSignature" : "30450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E5"
+ > }
+ > }
+ > ],
+ > "SigningPubKey" : "",
+ > "TransactionType" : "TrustSet",
+ > "hash" : "A94A6417D1A7AAB059822B894E13D322ED3712F7212CE9257801F96DE6C3F6AE"
+ > }'
+ Loading: "/home/mduo13/.config/ripple/rippled.cfg"
+ Connecting to 127.0.0.1:5005
+ {
+ "result" : {
+ "status" : "success",
+ "tx_blob" : "1200142200040000240000000263D5038D7EA4C680000000000000000000000000005553440000000000B5F762798A53D543A014CAF8B297CFF8F2F937E868400000000000753073008114A3780F5CB5A44D366520FC44055E8ED44D9A2270F3E010732102B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF744730450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E58114204288D2E47F8EF6C99BCC457966320D12409711E1E0107321028FFB276505F9AC3F57E8D5242B386A597EF6C40A7999F37F1948636FD484E25B744630440220680BBD745004E9CFB6B13A137F505FB92298AD309071D16C7B982825188FD1AE022004200B1F7E4A6A84BB0E4FC09E1E3BA2B66EBD32F0E6D121A34BA3B04AD99BC181147908A7F0EDD48EA896C3580A399F0EE78611C8E3E1F1",
+ "tx_json" : {
+ "Account" : "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
+ "Fee" : "30000",
+ "Flags" : 262144,
+ "LimitAmount" : {
+ "currency" : "USD",
+ "issuer" : "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
+ "value" : "100"
+ },
+ "Sequence" : 2,
+ "Signers" : [
+ {
+ "Signer" : {
+ "Account" : "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
+ "SigningPubKey" : "02B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF",
+ "TxnSignature" : "30450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E5"
+ }
+ },
+ {
+ "Signer" : {
+ "Account" : "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
+ "SigningPubKey" : "028FFB276505F9AC3F57E8D5242B386A597EF6C40A7999F37F1948636FD484E25B",
+ "TxnSignature" : "30440220680BBD745004E9CFB6B13A137F505FB92298AD309071D16C7B982825188FD1AE022004200B1F7E4A6A84BB0E4FC09E1E3BA2B66EBD32F0E6D121A34BA3B04AD99BC1"
+ }
+ }
+ ],
+ "SigningPubKey" : "",
+ "TransactionType" : "TrustSet",
+ "hash" : "BD636194C48FD7A100DE4C972336534C8E710FD008C0F3CF7BC5BF34DAF3C3E6"
+ }
+ }
+ }
+
+Depending on the SignerList you configured, you may need to repeat this step several times to get signatures from all the necessary parties.
+
+
+### 4. Combine signatures and submit ###
+
+If you collected the signatures in serial, the `tx_json` from the last `sign_for` response has all the signatures assembled, so you can use that as the argument to the [`submit_multisigned` command](reference-rippled.html#submit-multisigned).
+
+If you collected the signatures in parallel, you must manually construct a `tx_json` object with all the signatures included. Take the `Signers` arrays from all the `sign_for` responses, and combine their contents into a single `Signers` array that has each signature. Add the combined `Signers` array to the original transaction JSON value, and use that as the argument to the [`submit_multisigned` command](reference-rippled.html#submit-multisigned).
+
+ $ rippled submit_multisigned '{
+ > "Account" : "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
+ > "Fee" : "30000",
+ > "Flags" : 262144,
+ > "LimitAmount" : {
+ > "currency" : "USD",
+ > "issuer" : "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
+ > "value" : "100"
+ > },
+ > "Sequence" : 2,
+ > "Signers" : [
+ > {
+ > "Signer" : {
+ > "Account" : "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
+ > "SigningPubKey" : "02B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF",
+ > "TxnSignature" : "30450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E5"
+ > }
+ > },
+ > {
+ > "Signer" : {
+ > "Account" : "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
+ > "SigningPubKey" : "028FFB276505F9AC3F57E8D5242B386A597EF6C40A7999F37F1948636FD484E25B",
+ > "TxnSignature" : "30440220680BBD745004E9CFB6B13A137F505FB92298AD309071D16C7B982825188FD1AE022004200B1F7E4A6A84BB0E4FC09E1E3BA2B66EBD32F0E6D121A34BA3B04AD99BC1"
+ > }
+ > }
+ > ],
+ > "SigningPubKey" : "",
+ > "TransactionType" : "TrustSet",
+ > "hash" : "BD636194C48FD7A100DE4C972336534C8E710FD008C0F3CF7BC5BF34DAF3C3E6"
+ > }'
+ Loading: "/home/mduo13/.config/ripple/rippled.cfg"
+ Connecting to 127.0.0.1:5005
+ {
+ "result": {
+ "engine_result": "tesSUCCESS",
+ "engine_result_code": 0,
+ "engine_result_message": "The transaction was applied. Only final in a validated ledger.",
+ "status": "success",
+ "tx_blob": "1200142200040000240000000263D5038D7EA4C680000000000000000000000000005553440000000000B5F762798A53D543A014CAF8B297CFF8F2F937E868400000000000753073008114A3780F5CB5A44D366520FC44055E8ED44D9A2270F3E010732102B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF744730450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E58114204288D2E47F8EF6C99BCC457966320D12409711E1E0107321028FFB276505F9AC3F57E8D5242B386A597EF6C40A7999F37F1948636FD484E25B744630440220680BBD745004E9CFB6B13A137F505FB92298AD309071D16C7B982825188FD1AE022004200B1F7E4A6A84BB0E4FC09E1E3BA2B66EBD32F0E6D121A34BA3B04AD99BC181147908A7F0EDD48EA896C3580A399F0EE78611C8E3E1F1",
+ "tx_json": {
+ "Account": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
+ "Fee": "30000",
+ "Flags": 262144,
+ "LimitAmount": {
+ "currency": "USD",
+ "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
+ "value": "100"
+ },
+ "Sequence": 2,
+ "Signers": [{
+ "Signer": {
+ "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
+ "SigningPubKey": "02B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF",
+ "TxnSignature": "30450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E5"
+ }
+ }, {
+ "Signer": {
+ "Account": "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
+ "SigningPubKey": "028FFB276505F9AC3F57E8D5242B386A597EF6C40A7999F37F1948636FD484E25B",
+ "TxnSignature": "30440220680BBD745004E9CFB6B13A137F505FB92298AD309071D16C7B982825188FD1AE022004200B1F7E4A6A84BB0E4FC09E1E3BA2B66EBD32F0E6D121A34BA3B04AD99BC1"
+ }
+ }],
+ "SigningPubKey": "",
+ "TransactionType": "TrustSet",
+ "hash": "BD636194C48FD7A100DE4C972336534C8E710FD008C0F3CF7BC5BF34DAF3C3E6"
+ }
+ }
+ }
+
+
+Take note of the `hash` value from the response so you can check the results of the transaction later. (In this case, the hash is `BD636194C48FD7A100DE4C972336534C8E710FD008C0F3CF7BC5BF34DAF3C3E6`.)
+
+
+### 5. Close the ledger ##
+
+If you are using the live network, you can wait 4-7 seconds for the ledger to close automatically.
+
+If you're running `rippled` in stand-alone mode, use the [`ledger_accept` command](reference-rippled.html#ledger-accept) to manually close the ledger:
+
+ $ rippled ledger_accept
+ Loading: "/home/mduo13/.config/ripple/rippled.cfg"
+ Connecting to 127.0.0.1:5005
+ {
+ "result" : {
+ "ledger_current_index" : 7,
+ "status" : "success"
+ }
+ }
+
+
+### 6. Confirm transaction results ###
+
+Use the hash value from the response to the `submit_multisigned` command to look up the transaction using the [`tx` command](reference-rippled.html#tx). In particular, check that the `TransactionResult` is the string `tesSUCCESS`.
+
+On the live network, you must also confirm that the `validated` field is set to the boolean `true`. If the field is not `true`, you might need to wait longer for the consensus process to finish; or your transaction may be unable to be included in a ledger for some reason.
+
+In stand-alone mode, the server automatically considers a ledger to be `validated` if it has been manually closed.
+
+ $ rippled tx BD636194C48FD7A100DE4C972336534C8E710FD008C0F3CF7BC5BF34DAF3C3E6
+ Loading: "/home/mduo13/.config/ripple/rippled.cfg"
+ Connecting to 127.0.0.1:5005
+ {
+ "result": {
+ "Account": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
+ "Fee": "30000",
+ "Flags": 262144,
+ "LimitAmount": {
+ "currency": "USD",
+ "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
+ "value": "100"
+ },
+ "Sequence": 2,
+ "Signers": [{
+ "Signer": {
+ "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
+ "SigningPubKey": "02B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF",
+ "TxnSignature": "30450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E5"
+ }
+ }, {
+ "Signer": {
+ "Account": "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
+ "SigningPubKey": "028FFB276505F9AC3F57E8D5242B386A597EF6C40A7999F37F1948636FD484E25B",
+ "TxnSignature": "30440220680BBD745004E9CFB6B13A137F505FB92298AD309071D16C7B982825188FD1AE022004200B1F7E4A6A84BB0E4FC09E1E3BA2B66EBD32F0E6D121A34BA3B04AD99BC1"
+ }
+ }],
+ "SigningPubKey": "",
+ "TransactionType": "TrustSet",
+ "date": 512172510,
+ "hash": "BD636194C48FD7A100DE4C972336534C8E710FD008C0F3CF7BC5BF34DAF3C3E6",
+ "inLedger": 6,
+ "ledger_index": 6,
+ "meta": {
+ "AffectedNodes": [{
+ "ModifiedNode": {
+ "LedgerEntryType": "AccountRoot",
+ "LedgerIndex": "2B6AC232AA4C4BE41BF49D2459FA4A0347E1B543A4C92FCEE0821C0201E2E9A8",
+ "PreviousTxnID": "B7E1D33DB7DEA3BB65BFAB2C80E02125F47FCCF6C957A7FDECD915B3EBE0C1DD",
+ "PreviousTxnLgrSeq": 4
+ }
+ }, {
+ "CreatedNode": {
+ "LedgerEntryType": "RippleState",
+ "LedgerIndex": "93E317B32022977C77810A2C558FBB28E30E744C68E73720622B797F957EC5FA",
+ "NewFields": {
+ "Balance": {
+ "currency": "USD",
+ "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
+ "value": "0"
+ },
+ "Flags": 2162688,
+ "HighLimit": {
+ "currency": "USD",
+ "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
+ "value": "0"
+ },
+ "LowLimit": {
+ "currency": "USD",
+ "issuer": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
+ "value": "100"
+ }
+ }
+ }
+ }, {
+ "ModifiedNode": {
+ "FinalFields": {
+ "Account": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
+ "Balance": "999960000",
+ "Flags": 0,
+ "OwnerCount": 6,
+ "Sequence": 3
+ },
+ "LedgerEntryType": "AccountRoot",
+ "LedgerIndex": "A6B1BA6F2D70813100908EA84ABB7783695050312735E2C3665259F388804EA0",
+ "PreviousFields": {
+ "Balance": "999990000",
+ "OwnerCount": 5,
+ "Sequence": 2
+ },
+ "PreviousTxnID": "8FDC18960455C196A8C4DE0D24799209A21F4A17E32102B5162BD79466B90222",
+ "PreviousTxnLgrSeq": 5
+ }
+ }, {
+ "ModifiedNode": {
+ "FinalFields": {
+ "Flags": 0,
+ "Owner": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
+ "RootIndex": "C2728175908D82FB1DE6676F203D8D3C056995A9FA9B369EF326523F1C65A1DE"
+ },
+ "LedgerEntryType": "DirectoryNode",
+ "LedgerIndex": "C2728175908D82FB1DE6676F203D8D3C056995A9FA9B369EF326523F1C65A1DE"
+ }
+ }, {
+ "CreatedNode": {
+ "LedgerEntryType": "DirectoryNode",
+ "LedgerIndex": "D8120FC732737A2CF2E9968FDF3797A43B457F2A81AA06D2653171A1EA635204",
+ "NewFields": {
+ "Owner": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
+ "RootIndex": "D8120FC732737A2CF2E9968FDF3797A43B457F2A81AA06D2653171A1EA635204"
+ }
+ }
+ }],
+ "TransactionIndex": 0,
+ "TransactionResult": "tesSUCCESS"
+ },
+ "status": "success",
+ "validated": true
+ }
+ }
diff --git a/data-api-v2-tool.html b/data-api-v2-tool.html
index 27e3183080..26bc275e0c 100644
--- a/data-api-v2-tool.html
+++ b/data-api-v2-tool.html
@@ -46,6 +46,7 @@
The point of the Ripple software is to maintain a shared, global ledger that is open to all, so that individual participants can trust the integrity of the ledger without having to trust any single institution to manage it. The rippled server software accomplishes this by maintaining a ledger database that can only be updated according to very specific rules. Each instance of rippled maintains a full copy of the ledger, and the peer-to-peer network of rippled servers distributes candidate transactions among themselves. The consensus process determines which transactions get applied to each new version of the ledger. See also: The Consensus Process.
-
The shared global ledger is actually a series of individual ledgers, or ledger versions, which rippled keeps in its internal database. Every ledger version has a sequence number (also called a ledger index), starting at 1 and incrementing with each new version. Every closed ledger also has an identifying hash value, which uniquely identifies the contents of that ledger. At any given time, a rippled instance has an in-progress "current" open ledger, plus some number of closed ledgers that have not yet been approved by consensus, and any number of historical ledgers that have been validated by consensus. Only the validated ledgers are certain to be accurate and immutable.
+
The shared global ledger is actually a series of individual ledgers, or ledger versions, which rippled keeps in its internal database. Every ledger version has a ledger index which identifies the order in which ledgers occur. Each closed ledger version also has an identifying hash value, which uniquely identifies the contents of that ledger. At any given time, a rippled instance has an in-progress "current" open ledger, plus some number of closed ledgers that have not yet been approved by consensus, and any number of historical ledgers that have been validated by consensus. Only the validated ledgers are certain to be accurate and immutable.
A single ledger version consists of several components:
-
A header - The ledger's unique index (sequence number), hashes of the other contents, and other metadata.
+
A header - The ledger index, hashes of its other contents, and other metadata.
A transaction tree - The transactions that were applied to the previous ledger to make this one. Transactions are the only way to modify the ledger.
A state tree - All the ledger nodes that contain the settings, balances, and objects in the ledger as of this version.
Tree Format
-
As its name might suggest, a ledger's state tree is a tree data structure, with each node identified by a 256-bit value called an index. In JSON, a ledger node's index value is represented as a 64-character hexadecimal string like "193C591BF62482468422313F9D3274B5927CA80B4DD3707E42015DD609E39C94". Every node in the state tree has an index that you can use as a key to look up the node in the state tree; every transaction has an indentifying hash that you can use to look up the transaction in the transaction tree. Do not confuse the index (key) of a ledger node with the ledger_index (sequence number) of a ledger.
+
As its name might suggest, a ledger's state tree is a tree data structure, with each node identified by a 256-bit value called an index. In JSON, a ledger node's index value is represented as a 64-character hexadecimal string like "193C591BF62482468422313F9D3274B5927CA80B4DD3707E42015DD609E39C94". Every node in the state tree has an index that you can use as a key to look up the node in the state tree; every transaction has an indentifying hash that you can use to look up the transaction in the transaction tree. Do not confuse the index (key) of a ledger node with the ledger_index (sequence number) of a ledger.
In the case of transactions, the identifying hash is based on the signed transaction instructions, but the contents of the transaction object when you look it up also contain the results and metadata of the transaction, which are not taken into account when generating the hash.
In the case of state nodes, rippled usually includes the index of the node along with its contents. However, the index itself is not part of the contents. The index is derived by hashing important contents of the node, along with a namespace identifier. The ledger node type determines which namespace identifier to use as well as which contents to include in the hash. This ensures every index is unique. For a hash function, rippled uses SHA-512 and then truncates the result to the first 256 bytes. This algorithm, informally called SHA-512Half, provides an output that has comparable security to SHA-256, but runs faster on 64-bit processors.
The sequence number of the ledger. Some API methods display this as a quoted integer; some display it as a native JSON number.
@@ -187,7 +190,7 @@
parent_hash
String
Hash256
-
The ledger_hash value of the previous ledger that was used to build this one. If there are different versions of the previous ledger by sequence number, this indicates from which one the ledger was derived.
+
The ledger_hash value of the previous ledger that was used to build this one. If there are different versions of the previous ledger index, this indicates from which one the ledger was derived.
total_coins
@@ -208,13 +211,21 @@
An integer in the range [2,120] indicating the maximum number of seconds by which the close_time could be rounded.
A bit-map of flags relating to the closing of this ledger.
+
Ledger Index
+
A ledger index is a 32-bit unsigned integer used to identify a ledger. The ledger index is also known as the ledger's sequence number. The very first ledger was ledger index 1, and each subsequent ledger has a ledger index 1 higher than that of the ledger immediately before it.
+
The ledger index indicates the order of the ledgers; the Hash value identifies the exact contents of the ledger. Two ledgers with the same hash are always identical. For validated ledgers, hash values and sequence numbers are equally valid and correlate 1:1. However, this is not true for in-progress ledgers:
+
+
Two different rippled servers may have different contents for a current ledger with the same ledger index, due to latency in propagating transactions throughout the network.
+
There may be multiple closed ledger versions competing to be validated by consensus. These ledger versions have the same sequence number but different contents (and different hashes). Only one of these closed ledgers can become validated.
+
A current ledger's contents change over time, which would cause its hash to change, even though its ledger index number stays the same. Therefore, the hash of a ledger is not calculated until the ledger is closed.
+
Close Flags
Currently, the ledger has only one flag defined for closeFlags: sLCF_NoConsensusTime (value 1). If this flag is enabled, it means that validators were in conflict regarding the correct close time for the ledger, but built otherwise the same ledger, so they declared consensus while "agreeing to disagree" on the close time. In this case, the consensus ledger contains a close_time value that is 1 second after that of the previous ledger. (In this case, there is no official close time, but the actual real-world close time is probably 3-6 seconds later than the specified close_time.)
The closeFlags field is not included in any JSON representations of a ledger, but it is a part of the binary representation of a ledger, and is one of the fields that determine the ledger's hash.
@@ -304,7 +315,7 @@
PreviousTxnLgrSeq
Number
UInt32
-
The sequence number (ledger_index) of the ledger that contains the transaction that most recently modified this node.
+
The index of the ledger that contains the transaction that most recently modified this node.
AccountTxnID
@@ -428,7 +439,7 @@
-
AccountRoot index format
+
AccountRoot Index Format
The index of an AccountRoot node is the SHA-512Half of the following values put together:
The Account space key (a)
@@ -558,7 +569,7 @@
-
Directory index formats
+
Directory Index Formats
There are three different formulas for creating the index of a DirectoryNode, depending on whether the DirectoryNode represents:
The first page (also called the root) of an Owner Directory,
@@ -684,7 +695,7 @@
PreviousTxnLgrSeq
Number
UInt32
-
The sequence number (ledger_index) of the ledger that contains the transaction that most recently modified this node.
+
The index of the ledger that contains the transaction that most recently modified this node.
Expiration
@@ -724,7 +735,7 @@
-
Offer index format
+
Offer Index Format
The index of an Offer node is the SHA-512Half of the following values put together:
The Offer space key (o)
@@ -812,7 +823,7 @@
PreviousTxnLgrSeq
Number
UInt32
-
The sequence number (ledger_index) of the ledger that contains the transaction that most recently modified this node.
+
The index of the ledger that contains the transaction that most recently modified this node.
LowNode
@@ -964,7 +975,7 @@
The lsfLowAuth and lsfHighAuth flags do not count against the default state, because they cannot be disabled.
The default state of the two NoRipple flags depends on the state of the lsfDefaultRipple flag in their corresponding AccountRoot nodes. If DefaultRipple is disabled (the default), then the default state of the lsfNoRipple flag is enabled for all of an account's trust lines. If an account enables DefaultRipple, then the lsfNoRipple flag is disabled (rippling is enabled) for an account's trust lines by default. Note: Prior to the introduction of the DefaultRipple flags in rippled version 0.27.3 (March 10, 2015), the default state for all trust lines was with lsfNoRipple disabled (rippling enabled).
Fortunately, rippled uses lazy evaluation to calculate the owner reserve. This means that even if an account changes the default state of all its trust lines by changing the DefaultRipple flag, that account's reserve stays the same initially. If an account modifies a trust line, rippled re-evaluates whether that individual trust line is in its default state and should contribute the owner reserve.
-
RippleState index format
+
RippleState Index Format
The index of a RippleState node is the SHA-512Half of the following values put together:
The SignerList node type represents a list of parties that, as a group, are authorized to sign a transaction in place of an individual account. You can create, replace, or remove a SignerList using the SignerListSet transaction type This node type is introduced by the MultiSign amendment. (New in [version 0.31.0][])
A hint indicating which page of the owner directory links to this node, in case the directory consists of multiple nodes.
+
+
+
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.
+
+
+
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 allows multiple signer lists for an account, this may change.
+
+
+
PreviousTxnID
+
String
+
Hash256
+
The identifying hash of the transaction that most recently modified this node.
+
+
+
PreviousTxnLgrSeq
+
Number
+
UInt32
+
The index of the ledger that contains the transaction that most recently modified this node.
+
+
+
+
The SignerEntries may be any combination of funded and unfunded addresses that use either secp256k1 or ed25519 keys.
+
SignerEntry Object
+
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
+
A Ripple 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 node, 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 a component of another multi-signature.
+
SignerLists and Reserves
+
A SignerList contributes to its owner's reserve requirement. 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) or Offer node in the ledger.
All methods can potentially return any of the following values for the error code:
unknownCmd - The request does not contain a command that the rippled server recognizes.
-
`jsonInvalid1 - (WebSocket only) The request is not a proper JSON object.
+
jsonInvalid - (WebSocket only) The request is not a proper JSON object.
JSON-RPC returns a 400 Bad Request HTTP error in this case instead.
@@ -490,7 +493,7 @@ Null method
noNetwork - The server is having trouble connecting to the rest of the Ripple Network (and is not running in stand-alone mode).
noCurrent - The server does not know what the current ledger is, due to high load, network problems, validator failures, incorrect configuration, or some other problem.
noClosed - The server does not have a closed ledger, typically because it has not finished starting up.
-
wsTextRequired - (WebSocket only) The request's opcode is not text.
+
wsTextRequired - (WebSocket only) The request's opcode is not text.
Formatting Conventions
The WebSocket and JSON-RPC APIs generally take the same arguments, although they're provided in a different way (See Request Formatting for details). Many similar parameters appear throughout the APIs, and there are conventions for how to specify these parameters.
@@ -578,7 +581,7 @@ Null method
Many API methods require you to specify an instance of the ledger, with the data retrieved being considered accurate and up-to-date as of that particular version of the shared ledger. The commands that accept a ledger version all work the same way. There are three ways you can specify which ledger you want to use:
Specify a ledger by its Ledger Index in the ledger_index parameter. Each closed ledger has an identifying sequence number that is 1 higher than the previously-validated ledger. (The Genesis Ledger has sequence number 0)
-
Specify a ledger by its Hash value in the ledger_hash parameter.
+
Specify a ledger by its Hash value in the ledger_hash parameter.
Specify a ledger by one of the following shortcuts, in the ledger_index parameter:
validated for the most recent ledger that has been validated by the whole network
closed for the most recent ledger that has been closed for modifications and proposed for validation by the node
Accounts are the core unit of authentication in the Ripple Network. Each account can hold balances in multiple currencies, and all transactions must be signed by an account's secret key. In order for an account to exist in a validated ledger version, it must hold a minimum reserve amount of XRP. (The reserve for an account increases with the amount of data it is responsible for in the shared ledger.) It is expected that accounts will correspond loosely to individual users.
+
Accounts are the core unit of authentication in the Ripple Network. Each account can hold balances in multiple currencies, and all transactions must be signed by an account's secret key. In order for an account to exist in a validated ledger version, it must hold a minimum reserve amount of XRP. (The reserve for an account increases with the amount of data it is responsible for in the shared ledger.) It is expected that accounts will correspond loosely to individual users.
The account_currencies command retrieves a simple list of currencies that an account can send or receive, based on its trust lines. (This is not a thoroughly confirmed list, but it can be used to populate user interfaces.)
The account_info command retrieves information about an account, its activity, and its XRP balance. All information retrieved is relative to a particular version of the ledger.
+
The account_info command retrieves information about an account, its activity, and its XRP balance. All information retrieved is relative to a particular version of the ledger.
Request Format
An example of an account_info request:
@@ -1629,7 +1635,7 @@ rippled account_offers r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 current
The account_objects command returns the raw ledger format for all objects owned by an account, such as outstanding offers, trust lines in non-default state, and tickets (which are part of forthcoming multi-sign code). For getting the balance of an account's trust lines, we recommend account_lines instead.
+
The account_objects command returns the raw ledger format for all objects owned by an account, such as outstanding offers, trust lines in non-default state, and signer lists. For getting the balance of an account's trust lines, we recommend account_lines instead.
Request Format
An example of the request format:
@@ -4731,7 +4737,7 @@ rippled ledger_accept
There are several sources of complication in transactions. Unlike traditional banking, where a trusted third party (the bank, or the ACH) verifies the participants' identities and ensures their balances are adjusted accurately, Ripple uses cryptography and decentralized computing power to accomplish the same thing. Sending XRP, the Ripple Network's native crypto-currency, requires no third party aside from the distributed network itself. However, that is missing out on the key feature of Ripple: unlike individual crypto-currencies, the Ripple Network natively supports balances in any currency. This brings far more power, but it also means that the system must account for counterparty risk, currency conversions, and other issues. The Ripple Network must be robust to keep track of which transactions have been completely validated, even when subject to hardware failures, attacks, or natural disasters.
The transaction_entry method retrieves information on a single transaction from a specific ledger version. (The tx command, by contrast, searches all ledgers for the specified transaction. We recommend using that method instead.)
+
The transaction_entry method retrieves information on a single transaction from a specific ledger version. (The tx command, by contrast, searches all ledgers for the specified transaction. We recommend using that method instead.)
Note: This method does not support retrieving information from the current in-progress ledger. You must specify a ledger version in either ledger_index or ledger_hash.
+
Note: This method does not support retrieving information from the current in-progress ledger. You must specify a ledger version in either ledger_index or ledger_hash.
WebSocket API only! The path_find method searches for a path along which a transaction can possibly be made, and periodically sends updates when the path changes over time. For a simpler version that is supported by JSON-RPC, see ripple_path_find. For payments occurring strictly in XRP, it is not necessary to find a path, because XRP can be sent directly to any account.
+
WebSocket API only! The path_find method searches for a path along which a transaction can possibly be made, and periodically sends updates when the path changes over time. For a simpler version that is supported by JSON-RPC, see ripple_path_find. For payments occurring strictly in XRP, it is not necessary to find a path, because XRP can be sent directly to any account.
There are three different modes, or sub-commands, of the path_find command. Specify which one you want with the subcommand parameter:
-
create - Start sending pathfinding information
+
create - Start sending pathfinding information
close - Stop sending pathfinding information
status - Get the information of the currently-open pathfinding request
If fee_mult_max is included, and the automatically provided Fee value is greater than the long-term base transaction cost times fee_mult_max, then the transaction fails with the error rpcHIGH_FEE. This way, you can let the server fill in the current minimum Fee value as long as the current load-based transaction cost is not too high.
-
Paths - For Payment-type transactions (excluding XRP-to-XRP transfers), the Paths field can be automatically filled, as if you did a ripple_path_find. Only filled if build_path is provided.
+
Paths - For Payment-type transactions (excluding XRP-to-XRP transfers), the Paths field can be automatically filled, as if you did a ripple_path_find. Only filled if build_path is provided.
tooBusy - The transaction did not include paths, but the server is too busy to do pathfinding right now. Does not occur if you are connected as an admin.
noPath - The transaction did not include paths, and the server was unable to find a path by which this payment can occur.
The Transaction to sign. Unlike using the sign command, all fields of the transaction must be provided, including Fee and Sequence. The transaction must include the field SigningPubKey with an empty string as the value. The object may optionally contain a Signers array with previously-collected signatures.
+
+
+
secret
+
String
+
(Optional) The secret key to sign with. (Cannot be used with key_type.)
+
+
+
passphrase
+
String
+
(Optional) A passphrase to use as the secret key to sign with.
+
+
+
seed
+
String
+
(Optional) A base-58-encoded secret key to sign with.
+
+
+
seed_hex
+
String
+
(Optional) A hexadecimal secret key to sign with.
+
+
+
key_type
+
String
+
(Optional) The type of key to use for signing. This can be secp256k1 or ed25519. (Ed25519 support is experimental.)
+
+
+
+
You must provide exactly 1 field with the secret key. You can use any of the following fields: secret, passphrase, seed, or seed_hex.
The response follows the standard format, with a successful result containing the following fields:
+
+
+
+
Field
+
Type
+
Description
+
+
+
+
+
tx_blob
+
String
+
Hexadecimal representation of the signed transaction, including the newly-added signature. If it has enough signatures, you can submit this string using the submit command.
The submit method sends a transaction to the network to be confirmed and included in future ledgers.
+
The submit method applies a transaction and sends it to the network to be confirmed and included in future ledgers.
This command has two modes:
Submit-only mode takes a signed, serialized transaction as a binary blob, and submits it to the network as-is. Since signed transaction objects are immutable, no portion of the transaction can be modified or automatically filled in after submission.
Sign-and-submit mode takes a JSON-formatted Transaction object, completes and signs the transaction in the same manner as the sign command, and then submits the signed transaction. We recommend only using this mode for testing and development.
-
To send a transaction as robustly as possible, you should construct and sign it in advance, persist it somewhere that you can access even after a power outage, then submit it as a tx_blob. After submission, monitor the network with the tx command to see if the transaction was successfully applied; if a restart or other problem occurs, you can safely re-submit the tx_blob transaction: it won't be applied twice since it has the same sequence number as the old transaction.
+
To send a transaction as robustly as possible, you should construct and sign it in advance, persist it somewhere that you can access even after a power outage, then submit it as a tx_blob. After submission, monitor the network with the tx command to see if the transaction was successfully applied; if a restart or other problem occurs, you can safely re-submit the tx_blob transaction: it won't be applied twice since it has the same sequence number as the old transaction.
Submit-Only Mode
A submit-only request includes the following parameters:
Caution: Even if the WebSocket response has "status":"success", indicating that the command was successfully received, that does not necessarily indicate that the transaction has taken place. There are many cases that can prevent a transaction from processing successfully, such as a lack of trust lines connecting the two accounts in a payment, or changes in the state of the network since the time the transaction was constructed. Even if nothing is wrong, it may take several seconds to close and validate the ledger version that includes the transaction. See the full list of transaction responses for details, and do not consider the transaction's results final until they appear in a validated ledger version.
+
Caution: Even if the WebSocket response has "status":"success", indicating that the command was successfully received, that does not indicate that the transaction executed successfully. Many situations can prevent a transaction from processing successfully, such as a lack of trust lines connecting the two accounts in a payment, or changes in the state of the ledger since the time the transaction was constructed. Even if nothing is wrong, it may take several seconds to close and validate the ledger version that includes the transaction. See the full list of transaction responses for details, and do not consider the transaction's results final until they appear in a validated ledger version.
Caution: If this command results in an error messages, the message can contain an account secret, if one was provided in the request. (This is not a problem if the request contained a signed tx_blob instead.) Make sure that these errors are not visible to others, including:
Do not write an error including your secret to a log file that can be seen by multiple people
Do not paste an error including your secret to a public place for debugging
Do not display an error message including your secret on a website, even by accident
internalSubmit - An internal error occurred when submitting the transaction. This could be caused by many aspects of the transaction, including a bad signature or some fields being malformed.
internalJson - An internal error occurred when serializing the transaction to JSON. This could be caused by many aspects of the transaction, including a bad signature or some fields being malformed.
The submit_multisigned command applies a multi-signed transaction and sends it to the network to be included in future ledgers. (You can also submit multi-signed transactions in binary form using the submit command in submit-only mode.)
Transaction in JSON format with an array of Signers. To be successful, the weights of the signatures must be equal or higher than the quorum of the SignerList.
+
+
+
fail_hard
+
Boolean
+
(Optional, defaults to false) If true, and the transaction fails locally, do not retry or relay the transaction to other servers.
The book_offers method retrieves a list of offers, also known as the order book, between two currencies. If the results are very large, a partial result is returned with a marker so that subsequent requests can resume from where the previous one left off.
Normally, offers that are not funded are omitted; however, offers made by the specified taker account are always displayed. This allows you to look up your own unfunded offers in order to cancel them with an OfferCancel transaction.
The response follows the standard format. The fields contained in the response vary depending on what subscriptions were included in the request.
accounts and accounts_proposed - No fields returned
-
Stream: server - Information about the server status, such as load_base (the current load level of the server), random (a randomly-generated value), and others, subject to change.
+
Stream: server - Information about the server status, such as load_base (the current load level of the server), random (a randomly-generated value), and others, subject to change.
Stream: transactions, Stream: transactions_proposed, and Stream: validations - No fields returned
Stream: ledger - Information about the ledgers on hand and current fee schedule, such as fee_base (current base fee for transactions in XRP), fee_ref (current base fee for transactions in fee units), ledger_hash (hash of the latest validated ledger), reserve_base (minimum reserve for accounts), and more.
books - No fields returned by default. If "snapshot": true is set in the request, returns offers (an array of offer definition objects defining the order book)
The server_state command asks the server for various machine-readable information about the rippled server's current state. The results are very similar to server_info, but generally the units are chosen to be easier to process instead of easier to read. (For example, XRP values are given in integer drops instead of scientific notation or decimal values, and time is given in milliseconds instead of seconds.)
With online_delete and advisory_delete configuration options enabled, the can_delete method informs the rippled server of the latest ledger which may be deleted.
+
With online_delete and advisory_delete configuration options enabled, the can_delete method informs the rippled server of the latest ledger which may be deleted.
The can_delete method is an admin command that cannot be run by unpriviledged users.
-
Request Format
+
Request Format
An example of the request format:
WebSocket
@@ -9413,7 +9938,7 @@ a successful result containing the following fields:
Use this command with no parameter to query the existing can_delete setting.
The consensus_info command provides information about the consensus process for debugging purposes.
The consensus_info method is an admin command that cannot be run by unpriviledged users.
-
Request Format
+
Request Format
An example of the request format:
WebSocket
@@ -9448,7 +9973,7 @@ rippled consensus_info
The request has no parameters.
-
Response Format
+
Response Format
An example of a successful response:
JSON-RPC
@@ -9658,17 +10183,17 @@ Connecting to 127.0.0.1:5005
-
It is also normal to get a minimal result where the only field in info is "consensus": "none". This indicates that the server is in between consensus rounds.
+
It is also normal to get a minimal result where the only field in info is "consensus": "none". This indicates that the server is in between consensus rounds.
The results of the consensus_info command can vary dramatically if you run it several times, even in short succession.
The fetch_info command returns information about objects that this server is currently fetching from the network, and how many peers have that information. It can also be used to reset current fetches.
+
The fetch_info command returns information about objects that this server is currently fetching from the network, and how many peers have that information. It can also be used to reset current fetches.
The fetch_info method is an admin command that cannot be run by unpriviledged users.
-
Request Format
+
Request Format
An example of the request format:
WebSocket
@@ -9710,7 +10235,7 @@ rippled fetch_info
-
Response Format
+
Response Format
An example of a successful response:
JSON-RPC
@@ -9846,15 +10371,432 @@ Connecting to 127.0.0.1:5005
-
The feature command returns information about amendments this server knows about, including whether they are enabled and whether the server is voting in favor of those amendments in the amendment process. (New in version 0.31.0)
+
You can use the feature command to temporarily configure the server to vote against or in favor of an amendment. This change does not persist if you restart the server. To make lasting changes in amendment voting, use the rippled.cfg file. See Configuring Amendment Voting for more information.
+
The feature method is an admin command that cannot be run by unpriviledged users.
(Optional) The unique ID of an amendment, as hexadecimal; or the short name of the amendment. If provided, limits the response to one amendment. Otherwise, the response lists all amendments.
+
+
+
vetoed
+
Boolean
+
(Optional; ignored unless feature also specified) If true, instructs the server to vote against the amendment specified by feature. If false, instructs the server to vote in favor of the amendment.
+
+
+
+
Note: You can configure your server to vote in favor of a new amendment, even if the server does not currently know how to apply that amendment, by specifying the amendment ID in the feature field. For example, you might want to do this if you plan to upgrade soon to a new rippled version that does support the amendment.
The response follows the standard format, with a successful result containing a map of amendments as a JSON object. The keys of the object are amendment IDs. The values for each key are amendment objects that describe the status of the amendment with that ID. If the request specified a feature, the map contains only the requested amendment object, after applying any changes from the request. Each amendment object has the following fields:
+
+
+
+
Field
+
Type
+
Description
+
+
+
+
+
enabled
+
Boolean
+
Whether this amendment is currently enabled in the latest ledger.
+
+
+
name
+
String
+
(May be omitted) The human-readable name for this amendment, if known.
+
+
+
supported
+
Boolean
+
Whether this server knows how to apply this amendment.
+
+
+
vetoed
+
Boolean
+
Whether the server has been instructed to vote against this amendment.
+
+
+
+
Caution: The name for an amendment does not strictly indicate what that amendment does. The name is not guaranteed to be unique or consistent across servers.
The response follows the standard format, with a successful result containing the following fields:
+
+
+
+
Field
+
Type
+
Description
+
+
+
+
+
current_ledger_size
+
String (Integer)
+
Number of transactions provisionally included in the in-progress ledger.
+
+
+
current_queue_size
+
String (Integer)
+
Number of transactions currently queued for the next ledger.
+
+
+
drops
+
Object
+
Various information about the transaction cost (the Fee field of a transaction), in drops of xrp.
+
+
+
drops.base_fee
+
String (Integer)
+
The transaction cost required for a reference transaction to be included in a ledger under minimum load, represented in drops of XRP.
+
+
+
drops.median_fee
+
String (Integer)
+
An approximation of the median transaction cost among transactions included in the previous validated ledger, represented in drops of XRP.
+
+
+
drops.minimum_fee
+
String (Integer)
+
The minimum transaction cost for a reference transaction to be queued for a later ledger, represented in drops of XRP. If greater than base_fee, the transaction queue is full.
+
+
+
drops.open_ledger_fee
+
String (Integer)
+
The minimum transaction cost that a reference transaction must pay to be included in the current open ledger, represented in drops of XRP.
+
+
+
expected_ledger_size
+
String (Integer)
+
The approximate number of transactions expected to be included in the current ledger. This is based on the number of transactions in the previous ledger.
+
+
+
levels
+
Object
+
Various information about the transaction cost, in fee levels. The ratio in fee levels applies to any transaction relative to the minimum cost of that particular transaction.
+
+
+
levels.median_level
+
String (Integer)
+
The median transaction cost among transactions in the previous validated ledger, represented in fee levels.
+
+
+
levels.minimum_level
+
String (Integer)
+
The minimum transaction cost required to be queued for a future ledger, represented in fee levels.
+
+
+
levels.open_ledger_level
+
String (Integer)
+
The minimum transaction cost required to be included in the current open ledger, represented in fee levels.
+
+
+
levels.reference_level
+
String (Integer)
+
The equivalent of the minimum transaction cost, represented in fee levels.
+
+
+
max_queue_size
+
String (Integer)
+
The maximum number of transactions that the transaction queue can currently hold.
+
+
+
+
Reference Transaction Cost
+
The "Reference Transaction" is the cheapest possible transaction, in terms of the necessary transaction cost. Most transactions have the same cost as the reference transaction. Some transactions, such as multi-signed transactions require a multiple of this cost instead. When the open ledger cost escalates, the requirement is proportional to the basic cost of the transaction.
+
Fee Levels
+
Fee levels represent the proportional difference between the minimum cost and the actual cost of a transaction. See the following table for a comparison:
The get_counts command provides various stats about the health of the server, mostly the number of objects of different types that it currently holds in memory.
+
The get_counts command provides various stats about the health of the server, mostly the number of objects of different types that it currently holds in memory.
The get_counts method is an admin command that cannot be run by unpriviledged users.
-
Request Format
+
Request Format
An example of the request format:
WebSocket
@@ -9896,7 +10838,7 @@ rippled get_counts 100
-
Response Format
+
Response Format
An example of a successful response:
JSON-RPC
@@ -9999,16 +10941,16 @@ Connecting to 127.0.0.1:5005
For most other entries, the value indicates the number of objects of that type currently in memory.
The ledger_cleaner command controls the Ledger Cleaner, an asynchronous maintenance process that can find and repair corruption in rippled's database of ledgers.
+
The ledger_cleaner command controls the Ledger Cleaner, an asynchronous maintenance process that can find and repair corruption in rippled's database of ledgers.
The ledger_cleaner method is an admin command that cannot be run by unpriviledged users.
-
Request Format
+
Request Format
An example of the request format:
WebSocket
@@ -10067,7 +11009,7 @@ Connecting to 127.0.0.1:5005
-
Response Format
+
Response Format
An example of a successful response:
JSON-RPC
@@ -10098,7 +11040,7 @@ Connecting to 127.0.0.1:5005
-
The log_level command changes the rippled server's logging verbosity, or returns the current logging level for each category (called a partition) of log messages.
The log_level method is an admin command that cannot be run by unpriviledged users.
@@ -10219,7 +11161,7 @@ Connecting to 127.0.0.1:5005
}
-
The response follows the standard format. The response format depends on whether the request specified a severity. If it did, the log level is changed and a successful result contains no additional fields.
+
The response follows the standard format. The response format depends on whether the request specified a severity. If it did, the log level is changed and a successful result contains no additional fields.
Otherwise, the request contains the following field:
@@ -10237,7 +11179,7 @@ Connecting to 127.0.0.1:5005
Use the validation_create command to generate the keys for a rippled validating node. Similar to the wallet_propose command, this command makes no real changes, but only generates a set of keys in the proper format.
The validation_create method is an admin command that cannot be run by unpriviledged users.
-
Request Format
+
Request Format
An example of the request format:
WebSocket
@@ -10353,7 +11295,7 @@ rippled validation_create "BAWL MAN JADE MOON DOVE GEM SON NOW HAD ADEN GLOW TIR
Note: The security of your validator depends on the entropy of your seed. Do not use a secret value that is not sufficiently randomized for real business purposes. We recommend omitting the secret when generating new credentials for the first time.
-
Response Format
+
Response Format
An example of a successful response:
JSON-RPC
@@ -10406,7 +11348,7 @@ Connecting to 127.0.0.1:5005
-
badSeed - The request provided an invalid seed value. This usually means that the seed value appears to be a valid string of a different format, such as an account address or validation public key.
@@ -10415,7 +11357,7 @@ Connecting to 127.0.0.1:5005
The validation_seed command temporarily sets the secret value that rippled uses to sign validations. This value resets based on the config file when you restart the server.
The validation_seed request is an admin command that cannot be run by unpriviledged users!
-
Request Format
+
Request Format
An example of the request format:
WebSocket
@@ -10447,7 +11389,7 @@ rippled validation_seed 'BAWL MAN JADE MOON DOVE GEM SON NOW HAD ADEN GLOW TIRE'
-
Response Format
+
Response Format
An example of a successful response:
JSON-RPC
@@ -10501,7 +11443,7 @@ Connecting to 127.0.0.1:5005
-
badSeed - The request provided an invalid secret value. This usually means that the secret value appears to be a valid string of a different format, such as an account address or validation public key.
@@ -10510,7 +11452,7 @@ Connecting to 127.0.0.1:5005
The peers command returns a list of all other rippled servers currently connected to this one, including information on their connection and sync status.
The peers request is an admin command that cannot be run by unpriviledged users!
-
Request Format
+
Request Format
An example of the request format:
WebSocket
@@ -10524,7 +11466,7 @@ Connecting to 127.0.0.1:5005
The request includes no additional parameters.
-
Response Format
+
Response Format
An example of a successful response:
WebSocket
@@ -10984,7 +11926,7 @@ Connecting to 127.0.0.1:5005
-
The print command returns the current status of various internal subsystems, including peers, the ledger cleaner, and the resource manager.
The print request is an admin command that cannot be run by unpriviledged users!
-
Request Format
+
Request Format
An example of the request format:
WebSocket
@@ -11006,7 +11948,7 @@ Connecting to 127.0.0.1:5005
The request includes no parameters.
-
Response Format
+
Response Format
An example of a successful response:
Commandline
@@ -11195,7 +12137,7 @@ Connecting to 127.0.0.1:5005
The response follows the standard format. Additional fields in the result depend on the internal state of the rippled server. The results of this command are subject to change without notice.
The response follows the standard format, with a successful result containing no fields. The client can measure the round-trip time from request to response as latency.
internal - Some internal error occurred, possibly relating to the random number generator.
json
-
The json method is a proxy to running other commands, and accepts the parameters for the command as a JSON value. It is exclusive to the Commandline client, and intended for cases where the commandline syntax for specifying parameters is inadequate or undesirable.
-
Request Format
+
The json method is a proxy to running other commands, and accepts the parameters for the command as a JSON value. It is exclusive to the Commandline client, and intended for cases where the commandline syntax for specifying parameters is inadequate or undesirable.
Signing a transaction cryptographically proves that the person in charge of the account sending the transaction is authorized to do so. Only signed transactions can be submitted to the network and included in a validated ledger. A signed transaction is immutable: its contents cannot change, and the signature is not valid for any other transaction.
-
You can sign a transaction using a secret key: either the master secret, or a regular secret if the account has a regular key pair associated with it. (See SetRegularKey for details.)
Typically, you create a transaction in JSON format first. Here is an example of an unsigned Payment-type transaction in JSON:
+
Authorizing Transactions
+
In the decentralized Ripple Consensus Ledger, a digital signature proves that a transaction is authorized to perform a specific set of actions. Only signed transactions can be submitted to the network and included in a validated ledger. A signed transaction is immutable: its contents cannot change, and the signature is not valid for any other transaction.
+
A transaction can be authorized by any of the following types of signatures:
+
+
A single signature from the master secret key that is mathematically associated with the sending address. You can disable or enable the master key using an AccountSet transaction.
+
A single signature that matches a regular key associated with the address. You can add, remove, or replace a regular key using a SetRegularKey transaction.
Submit a transaction to a rippled server. If the transaction is properly formed, the server provisionally applies the transaction to its current version of the ledger and relays the transaction to other members of the peer-to-peer network.
+
The consensus process determines which provisional transactions get included in the next validated ledger.
+
The rippled servers apply those transactions to the previous ledger in a canonical order and share their results.
After doing that, you generate the signed binary format for the transaction. There are two ways to do this:
+
The Ripple Consensus Ledger only relays and executes a transaction if the transaction object has been authorized by the sending address (in the Account) field. For transactions authorized by only a single signature, you have two options:
Convert it to a binary blob and sign it offline. This is preferable, since it means that the account secret used for signing the transaction is never transmitted over any network connection.
Have a rippled server sign the transaction for you. The sign command takes a JSON-format transaction and secret and returns the signed binary transaction format ready for submission. (Transmitting your account secret is dangerous, so you should only do this from within a trusted and encrypted sub-net, to a server you control.)
+
Have a rippled server sign the transaction for you. The sign command takes a JSON-format transaction and secret and returns the signed binary transaction format ready for submission. (Transmitting your account secret is dangerous, so you should only do this from within a trusted and encrypted connection, or through a local connection, and only to a server you control.)
As a shortcut, you can use the submit command with a tx_json object to sign and submit a transaction all at once. This is only recommended for testing and development purposes.
After a transaction has been submitted, if it gets accepted into a validated ledger, you can view the final transaction using the API. For example, here is what the WebSocket API tx command shows for the same transaction. The field names that begin with capital letters are part of the ledger object; the fields that begin with lower-case letters are additional information generated by the server for the request:
+
After a transaction has been submitted, you can check its status using the API, for example using the tx command.
+
Caution: The success of a transaction is not final unless the transaction appears in a validated ledger with the result code tesSUCCESS. See also: Finality of Results.
Multi-signing in Ripple is the act of authorizing transactions for the Ripple Consensus Ledger by using a combination of multiple secret keys. Multi-signing is due to be enabled by an Amendment to the Ripple Consensus Protocol. You can have any combination of authorization methods enabled for your address, including multi-signing, a master key, and a regular key. (The only requirement is that at least one method must be enabled.)
+
The SignerListSet transaction defines which addresses can authorize transactions from your address. You can include up to 8 addresses in a SignerList. You can control how many signatures are needed, in which combinations, by using the quorum and weight values of the SignerList.
+
To successfully submit a multi-signed transaction, you must do all of the following:
+
+
The address sending the transaction (specified in the Account field) must own a SignerList in the ledger.
+
The transaction must include the SigningPubKey field as an empty string.
+
The transaction must include a Signers field containing an array of signatures.
+
The signatures present in the Signers array must match signers defined in the SignerList.
+
For the provided signatures, the total weight associated with those signers must be equal or greater than the quorum for the SignerList.
+
The transaction cost (specified in the Fee field) must be at least (N+1) times the normal transaction cost, where N is the number of signatures provided.
+
All fields of the transaction must be defined before collecting signatures. You cannot auto-fill any fields.
+
If presented in binary form, the Signers array must be sorted based on the numeric value of the signer addresses, with the lowest value first. (If submitted as JSON, the submit_multisigned command handles this automatically.)
(Automatically added when signing) Hex representation of the public key that corresponds to the private key used to sign this transaction.
+
(Automatically added when signing) Hex representation of the public key that corresponds to the private key used to sign this transaction. If an empty string, indicates a multi-signature is present in the Signers field instead.
(Optional) Array of objects that represent a multi-signature which authorizes this transaction.
SourceTag
@@ -361,7 +410,7 @@
TransactionType
String
UInt16
-
The type of transaction. Valid types include: Payment, OfferCreate, OfferCancel, TrustSet, AccountSet, and SetRegularKey.
+
The type of transaction. Valid types include: Payment, OfferCreate, OfferCancel, TrustSet, AccountSet, SetRegularKey, and SignerListSet.
TxnSignature
@@ -379,10 +428,11 @@
Sequence - Automatically use the next sequence number for the account sending the transaction.
For a production system, we recommend not leaving these fields to be filled by the server. For example, if transaction costs become high due to a temporary spike in network load, you may want to wait for the cost to decrease before sending some transactions, instead of paying the temporarily-high cost.
-
The Paths field of the Payment transaction type can also be automatically filled in.
+
The Paths field of the Payment transaction type can also be automatically filled in.
Transaction Cost
-
In order to protect the Ripple Consensus Ledger from being disrupted by spam and denial-of-service attacks, each transaction must destroy a small amount of XRP. This transaction cost is designed to increase along with the load on the network, making it very expensive to deliberately or inadvertently overload the network.
-
The Fee field specifies an amount, in drops of XRP, to destroy as the cost for this transaction. If the transaction is included in a validated leger (whether or not it achieves its intended purpose), then the amount of XRP specified in the Fee parameter is destroyed forever. You can look up the transaction cost in advance, or let rippled set it automatically when you sign a transaction.
+
In order to protect the Ripple Consensus Ledger from being disrupted by spam and denial-of-service attacks, each transaction must destroy a small amount of XRP. This transaction cost is designed to increase along with the load on the network, making it very expensive to deliberately or inadvertently overload the network.
+
The Fee field specifies an amount, in drops of XRP, to destroy as the cost for relaying this transaction. If the transaction is included in a validated ledger (whether or not it achieves its intended purpose), then the amount of XRP specified in the Fee parameter is destroyed forever. You can look up the transaction cost in advance, or let rippled set it automatically when you sign a transaction.
An important and intentional feature of the Ripple Network is that a transaction is final as soon as it has been incorporated in a validated ledger.
However, if a transaction has not yet been included in a validated ledger, you can effectively cancel it by rendering it invalid. Typically, this means sending another transaction with the same Sequence value from the same account. If you do not want to perform the same transaction again, you can perform an AccountSet transaction with no options.
@@ -397,7 +447,7 @@
One situation in which this is useful is if you have a primary system for submitting transactions and a passive backup system. If the passive backup system becomes disconnected from the primary, but the primary is not fully dead, and they both begin operating at the same time, you could potentially encounter serious problems like some transactions sending twice and others not at all. Chaining your transactions together with AccountTxnID ensures that, even if both systems are active, only one of them can submit valid transactions at a time.
In order to use AccountTxnID, you must first set the asfAccountTxnID flag, so that the ledger keeps track of the ID for the account's previous transaction.
Memos
-
The Memos field allows for arbitrary messaging data that can accompany the transaction. It is presented as an array of objects. Each object has only one field, Memo, which in turn contains another object with one or more of the following fields:
+
The Memos field allows for arbitrary messaging data that can accompany the transaction. It is presented as an array of objects. Each object has only one field, Memo, which in turn contains another object with one or more of the following fields:
@@ -446,8 +496,42 @@
"Amount": "1"
}
+
Signers Field
+
The Signers field contains a multi-signature, which has signatures from up to 8 key pairs, that together should authorize the transaction. The Signers list is an array of objects, each with one field, Signer. The Signer field has the following nested fields:
The address associated with this signature, as it appears in the SignerList.
+
+
+
TxnSignature
+
String
+
Blob
+
A signature for this transaction, verifiable using the SigningPubKey.
+
+
+
SigningPubKey
+
String
+
PubKey
+
The public key used to create this signature.
+
+
+
+
The SigningPubKey must be a key that is associated with the Account address. If the referenced Account is a funded account in the ledger, then the SigningPubKey can be that account's current Regular Key if one is set. It could also be that account's Master Key, unless the lsfDisableMaster flag is enabled. If the referenced Account address is not a funded account in the ledger, then the SigningPubKey must be the master key associated with that address.
+
Because signature verification is a compute-intensive task, multi-signed transactions cost additional XRP to relay to the network. Each signature included in the multi-signature increases the transaction cost required for the transaction. For example, if the current minimum transaction cost to relay a transaction to the network is 10000 drops, then a multi-signed transaction with 3 entries in the Signers array would need a Fee value of at least 40000 drops to relay.
Flags
-
The Flags field allows for additional boolean options regarding the behavior of a transaction. They are represented as binary values that can be combined with bitwise-or operations to set multiple flags at once.
+
The Flags field allows for additional boolean options regarding the behavior of a transaction. They are represented as binary values that can be combined with bitwise-or operations to set multiple flags at once.
Most flags only have meaning for a specific transaction type. The same bitwise value may be reused for flags on different transaction types, so it is important to pay attention to the TransactionType field when setting and reading flags.
The only flag that applies globally to all transactions is as follows:
@@ -545,7 +629,7 @@
Most of the time, the issuer field of a non-XRP currency amount indicates the account of the gateway that issues that currency. However, when describing payments, there are special rules for the issuer field in the Amount and SendMax fields of a payment.
There is only ever one balance for the same currency between two accounts. This means that, sometimes, the issuer field of an amount actually refers to a counterparty that is redeeming issuances, instead of the account that created the issuances.
-
When the issuer field of the destination Amount field matches the Destination account address, it is treated as a special case meaning "any issuer that the destination accepts." This includes all accounts to which the destination has extended trust lines, as well as issuances created by the destination which may be held on other trust lines.
+
When the issuer field of the destination Amount field matches the Destination account address, it is treated as a special case meaning "any issuer that the destination accepts." This includes all accounts to which the destination has extended trust lines, as well as issuances created by the destination which may be held on other trust lines.
When the issuer field of the SendMax field matches the source account's address, it is treated as a special case meaning "any issuer that the source can use." This includes creating new issuances on trust lines that other accounts have extended to the source account, as well as issuances from other accounts that the source account possesses.
Creating Accounts
@@ -603,9 +687,9 @@
When the tfPartialPayment flag is enabled, the Amount field is not guaranteed to be the amount received. The delivered_amount field of a payment's metadata indicates the amount of currency actually received by the destination account. When receiving a payment, use delivered_amount instead of the Amount field to determine how much your account received instead.
Limit Quality
Ripple defines the "quality" of a currency exchange as the ratio of the numeric amount in to the numeric amount out. For example, if you spend $2 USD to receive £1 GBP, then the "quality" of that exchange is 0.5.
-
The tfLimitQuality flag allows you to set a minimum quality of conversions that you are willing to take. This limit quality is defined as the destination Amount divided by the SendMax amount (just the numeric amounts, regardless of currency). When set, the payment processing engine avoids using any paths whose quality (conversion rate) is worse (numerically lower) than the limit quality.
+
The tfLimitQuality flag allows you to set a minimum quality of conversions that you are willing to take. This limit quality is defined as the destination Amount divided by the SendMax amount (just the numeric amounts, regardless of currency). When set, the payment processing engine avoids using any paths whose quality (conversion rate) is worse (numerically lower) than the limit quality.
By itself, the tfLimitQuality flag reduces the number of situations in which a transaction can succeed. Specifically, it rejects payments where some part of the payment uses an unfavorable conversion, even if the overall average average quality of conversions in the payment is equal or better than the limit quality. If a payment is rejected in this way, the transaction result is tecPATH_DRY.
-
Consider the following example. If I am trying to send you 100 Chinese Yuan (Amount = 100 CNY) for 20 United States dollars (SendMax = 20 USD) or less, then the limit quality is 5. Imagine one market maker is offering ¥95 for $15 (a ratio of about 6.3 CNY per USD), but the next best offer in the market is ¥5 for $2 (a ratio of 2.5 CNY per USD). If I were to take both offers in order to send you 100 CNY, then it would cost me 17 USD, for an average quality of about 5.9.
+
Consider the following example. If I am trying to send you 100 Chinese Yuan (Amount = 100 CNY) for 20 United States dollars (SendMax = 20 USD) or less, then the limit quality is 5. Imagine one market maker is offering ¥95 for $15 (a ratio of about 6.3 CNY per USD), but the next best offer in the market is ¥5 for $2 (a ratio of 2.5 CNY per USD). If I were to take both offers in order to send you 100 CNY, then it would cost me 17 USD, for an average quality of about 5.9.
Without the tfLimitQuality flag set, this transaction would succeed, because the $17 it costs me is within my specified SendMax. However, with the tfLimitQuality flag enabled, the transaction would fail instead, because the path to take the second offer has a quality of 2.5, which is worse than the limit quality of 5.
The tfLimitQuality flag is most useful when combined with partial payments. When both tfPartialPayment and tfLimitQuality are set on a transaction, then the transaction delivers as much of the destination Amount as it can, without using any conversions that are worse than the limit quality.
In the above example with a ¥95/$15 offer and a ¥5/$2 offer, the situation is different if my transaction has both tfPartialPayment and tfLimitQuality enabled. If we keep my SendMax of 20 USD and a destination Amount of 100 CNY, then the limit quality is still 5. However, because I am doing a partial payment, the transaction sends as much as it can instead of failing if the full destination amount cannot be sent. This means that my transaction consumes the ¥95/$15 offer, whose quality is about 6.3, but it rejects the ¥5/$2 offer because that offer's quality of 2.5 is worse than the quality limit of 5. In the end, my transaction only delivers ¥95 instead of the full ¥100, but it avoids wasting money on poor exchange rates.
@@ -729,7 +813,7 @@
asfDisableMaster
4
-
Disallow use of the master key. Can only be enabled if the account has a RegularKey configured.
+
Disallow use of the master key. Can only be enabled if the account has configured another way to sign transactions, such as a Regular Key or a Signer List.
lsfDisableMaster
@@ -758,7 +842,7 @@
-
New in rippled 0.28.0: You cannot send a transaction that enables asfDisableMaster or asfNoFreeze using a regular key. You must use the master key to sign the transaction.
+
New in rippled 0.28.0: In order to enable the asfDisableMaster or asfNoFreeze flags, you must authorize the transaction by signing it with the master key. You cannot use a regular key or a multi-signature.
The following Transaction flags, specific to the AccountSet transaction type, serve the same purpose, but are discouraged:
@@ -817,7 +901,7 @@
In rippled's WebSocket and JSON-RPC APIs, the TransferRate is represented as an integer, the amount that must be sent in order for 1 billion units to arrive. For example, a 20% transfer fee is represented as the value 1200000000. The value cannot be less than 1000000000. (Less than that would indicate giving away money for sending transactions, which is exploitable.) You can specify 0 as a shortcut for 1000000000, meaning no fee.
(Optional) The public key of a new keypair, to use as the regular key to this account, as a base-58-encoded string in the same format as an account address. If omitted, removes the existing regular key.
+
AccountID
+
(Optional) A base-58-encoded Ripple address to use as the regular key. If omitted, removes the existing regular key.
-
Instead of using an account's master key to sign transactions, you can set an alternate key pair, called the "Regular Key". As long as the public key for this key pair is set in the RegularKey field of an account this way, then the secret of the Regular Key pair can be used to sign transactions. (The master secret can still be used, too, unless you set the asfDisableMaster account flag.)
-
A Regular Key pair is generated in the same way as any other Ripple keys (for example, with wallet_propose), but it can be changed. A Master Key pair is an intrinsic part of the account's identity (the address is derived from the master public key) so the Master Key cannot be changed. Therefore, using a Regular Key to sign transactions instead of the master key whenever possible is beneficial to security.
-
If your regular key is compromised, but the master key is not, you can use this method to regain control of your account. In some cases, you can even send a key reset transaction without paying the transaction cost.
+
In addition to the master key, which is mathematically-related to an address, you can associate at most 1 additional key pair with an address using this type of transaction. The additional key pair is called a regular key. If your address has a regular key pair defined, you can use the secret key of the regular key pair to authorize transactions.
+
A regular key pair is generated in the same way as any other Ripple keys (for example, with wallet_propose), but it can be changed. A master key pair is an intrinsic part of an address's identity (the address is derived from the master public key). You can disable a master key but you cannot change it.
+
You can protect your master secret by using a regular key instead of the master key to sign transactions whenever possible. If your regular key is compromised, but the master key is not, you can use a SetRegularKey transaction to regain control of your address. In some cases, you can even send a key reset transaction without paying the transaction cost.
An OfferCreate transaction is effectively a limit order. It defines an intent to exchange currencies, and creates an Offer node in the Ripple Consensus Ledger if not completely fulfilled when placed. Offers can be partially fulfilled.
A trust line with settings in the default state is equivalent to no trust line.
The default state of all flags is off, except for the NoRipple flag, whose default state depends on the DefaultRipple flag.
-
The Auth flag of a trust line does not determine whether the trust line counts towards its owner's XRP reserve requirement. However, an enabled Auth flag prevents the trust line from being in its default state. An authorized trust line can never be deleted. (New in rippled 0.30.0): You can pre-authorize a trust line with the tfSetfAuth flag only, even if the limit and balance of the trust line are 0.
+
The Auth flag of a trust line does not determine whether the trust line counts towards its owner's XRP reserve requirement. However, an enabled Auth flag prevents the trust line from being in its default state. An authorized trust line can never be deleted. (New in rippled 0.30.0): The TrustSetAuth Amendment would allow you to pre-authorize a trust line with the tfSetfAuth flag only, even if the limit and balance of the trust line are 0. This Amendment is not currently enabled.
TrustSet Flags
Transactions of the TrustSet type support additional values in the Flags field, as follows:
The SignerListSet transaction creates, replaces, or removes a list of signers that can be used to multi-sign a transaction. This transaction type is introduced by the MultiSign amendment. (New in [version 0.31.0][])
A target number for the signer weights. A multi-signature from this list is valid only if the sum weights of the signatures provided is greater than or equal to this value. To delete a SignerList, use the value 0.
+
+
+
SignerEntries
+
Array
+
Array
+
(Omitted when deleting) Array of SignerEntry objects, indicating the addresses and weights of signers in this list. A SignerList must have at least 1 member and no more than 8 members. No address may appear more than once in the list, nor may the Account submitting the transaction appear in the list.
+
+
+
+
An account may not have more than one SignerList. A successful SignerListSet transaction replaces the existing SignerList, if one exists. To delete a SignerList, you must set SignerQuorum to 0and omit the SignerEntries field. Otherwise, the transaction fails with the error temMALFORMED. A transaction to delete a SignerList is considered successful even if there was no SignerList to delete.
+
You cannot create a SignerList such that the SignerQuorum could never be met. The SignerQuorum must be greater than 0 but less than or equal to the sum of the SignerWeight values in the list. Otherwise, the transaction fails with the error temMALFORMED.
+
You can create, update, or remove a SignerList using the master key, regular key, or the current SignerList, if those methods of signing transactions are available.
+
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 enabled) and the account does not have a Regular Key configured, then you cannot delete the SignerList from the account. Instead, the transaction fails with the error tecNO_ALTERNATIVE_KEY.
Pseudo-Transactions
Pseudo-Transactions are never submitted by users, nor propagated through the network. Instead, a server may choose to inject them in a proposed ledger directly. If enough servers inject an equivalent pseudo-transaction for it to pass consensus, then it becomes included in the ledger, and appears in ledger data thereafter.
Some of the fields that are mandatory for normal transactions do not make sense for pseudo-transactions. In those cases, the pseudo-transaction has the following default values:
@@ -1168,8 +1313,8 @@
SetFee
-
A change in transaction cost or account reserve requirements. This is typically in response to changes in the load on the network.
-
Note: You cannot send a pseudo-transaction, but you may encounter one when processing ledgers.
The index of the ledger version where this pseudo-transaction appears. This distinguishes the pseudo-transaction from other occurrences of the same change.
+
+
+
+
EnableAmendment
+
Tracks the progress of the amendment process for changes in transaction processing. This can indicate that a proposed amendment gained or lost majority approval, or that an amendment has been enabled.
+
Note: You cannot send a pseudo-transaction, but you may encounter one when processing ledgers.
A unique identifier for the amendment. This is not intended to be a human-readable name. See Amendments for a list of known amendments.
+
+
+
LedgerSequence
+
Number
+
UInt32
+
The index of the ledger version where this amendment appears. This distinguishes the pseudo-transaction from other occurrences of the same change.
+
+
+
+
EnableAmendment Flags
+
The Flags value of the EnableAmendment pseudo-transaction indicates the status of the amendment at the time of the ledger including the pseudo-transaction.
+
A Flags value of 0 (no flags) indicates that the amendment has been enabled, and applies to all ledgers afterward. Other Flags values are as follows:
+
+
+
+
Flag Name
+
Hex Value
+
Decimal Value
+
Description
+
+
+
+
+
tfGotMajority
+
0x00010000
+
65536
+
Support for this amendment increased to at least 80% of trusted validators starting with this ledger version.
+
+
+
tfLostMajority
+
0x00020000
+
131072
+
Support for this amendment decreased to less than 80% of trusted validators starting with this ledger version.
+
Transaction Results
Immediate Response
-
The response from the submit command contains a provisional result from the rippled server indicating what happened during local processing of the transaction.
+
The response from the submit command contains a provisional result from the rippled server indicating what happened during local processing of the transaction.
The response from submit contains the following fields:
@@ -1258,7 +1463,7 @@
Note: A successful result at this stage does not indicate that the transaction has completely succeeded; only that it was successfully applied to the provisional version of the ledger kept by the local server. See Finality of Results for details.
Looking up Transaction Results
-
To see the final result of a transaction, use the tx command, account_tx command, or other response from rippled. Look for "validated": true to indicate that this response uses a ledger version that has been validated by consensus.
+
To see the final result of a transaction, use the tx command, account_tx command, or other response from rippled. Look for "validated": true to indicate that this response uses a ledger version that has been validated by consensus.
@@ -1439,10 +1644,6 @@
-
telLOCAL_ERROR
-
Unspecified local error.
-
-
telBAD_DOMAIN
The transaction specified a domain value (for example, the Domain field of an AccountSet transaction) that cannot be used, probably because it is too long to store in the ledger.
@@ -1463,6 +1664,10 @@
The Fee from the transaction is not high enough to meet the server's current transaction cost requirement, which is derived from its load level.
+
telLOCAL_ERROR
+
Unspecified local error.
+
+
telNO_DST_PARTIAL
The transaction is an XRP payment that would fund a new account, but the tfPartialPayment flag was enabled. This is disallowed.
@@ -1479,10 +1684,6 @@
-
temMALFORMED
-
Unspecified problem with the format of the transaction.
-
-
temBAD_AMOUNT
An amount specified by the transaction (for example the destination Amount or SendMax values of a Payment) was invalid, possibly because it was a negative number.
@@ -1560,7 +1761,7 @@
temDST_IS_SRC
-
The TrustSet transaction improperly specified the destination of the trustline (the issuer field of LimitAmount) as the Account sending the transaction. You cannot extend a trustline to yourself. (In the future, this code could also apply to other cases where the destination of a transaction is not allowed to be the account sending it.)
+
The TrustSet transaction improperly specified the destination of the trust line (the issuer field of LimitAmount) as the Account sending the transaction. You cannot extend a trust line to yourself. (In the future, this code could also apply to other cases where the destination of a transaction is not allowed to be the account sending it.)
temDST_NEEDED
@@ -1575,6 +1776,10 @@
The transaction includes a Flag that does not exist, or includes a contradictory combination of flags.
+
temMALFORMED
+
Unspecified problem with the format of the transaction.
+
+
temREDUNDANT
The transaction would accomplish nothing; for example, it is sending a payment directly to the sending account, or creating an offer to buy and sell the same currency from the same issuer.
@@ -1586,6 +1791,30 @@
temRIPPLE_EMPTY
The Payment transaction includes an empty Paths field, but paths are necessary to complete this payment.
+
+
temBAD_WEIGHT
+
The SignerListSet transaction includes a SignerWeight that is invalid, for example a zero or negative value.
+
+
+
temBAD_SIGNER
+
The SignerListSet transaction includes a signer who is invalid. For example, there may be duplicate entries, or the owner of the SignerList may also be a member.
+
+
+
temBAD_QUORUM
+
The SignerListSet transaction has an invalid SignerQuorum value. Either the value is not greater than zero, or it is more than the sum of all signers in the list.
+
+
+
temUNCERTAIN
+
Used internally only. This code should never be returned.
+
+
+
temUNKNOWN
+
Used internally only. This code should never be returned.
+
+
+
temDISABLED
+
The transaction requires logic that is currently disabled. Typically this means you are trying to use an amendment that is not enabled for the current ledger.
+
tef Codes
@@ -1599,48 +1828,48 @@
-
tefFAILURE
-
Unspecified failure in applying the transaction.
-
-
tefALREADY
The same exact transaction has already been applied.
tefBAD_ADD_AUTH
-
Deprecated. This code should never be returned.
+
DEPRECATED.
tefBAD_AUTH
The key used to sign this account is not authorized to modify this account. (It could be authorized if the account had the same key set as the Regular Key.)
+
tefBAD_AUTH_MASTER
+
The single signature provided to authorize this transaction does not match the master key, but no regular key is associated with this address.
+
+
tefBAD_LEDGER
-
While processing the transaction, the ledger was discovered in an unexpected state. If you can reproduce this error, please file a bug to get it fixed.
+
While processing the transaction, the ledger was discovered in an unexpected state. If you can reproduce this error, please report an issue to get it fixed.
+
+
+
tefBAD_QUORUM
+
The transaction was multi-signed, but the total weights of all included signatures did not meet the quorum.
+
+
+
tefBAD_SIGNATURE
+
The transaction was multi-signed, but contained a signature for an address not part of a SignerList associated with the sending account.
tefCREATED
-
Deprecated. This code should never be returned.
+
DEPRECATED.
tefEXCEPTION
-
While processing the transaction, the server entered an unexpected state. This may be caused by unexpected inputs, for example if the binary data for the transaction is grossly malformed. If you can reproduce this error, please file a bug to get it fixed.
+
While processing the transaction, the server entered an unexpected state. This may be caused by unexpected inputs, for example if the binary data for the transaction is grossly malformed. If you can reproduce this error, please report an issue to get it fixed.
+
+
+
tefFAILURE
+
Unspecified failure in applying the transaction.
tefINTERNAL
-
While attempting to apply the transaction, the server entered an unexpected state. If you can reproduce this error, please file a bug to get it fixed.
-
-
-
tefNO_AUTH_REQUIRED
-
The TrustSet transaction attempted to mark a trustline as authorized, but the lsfRequireAuth flag is not enabled for the corresponding account, so authorization is not necessary.
-
-
-
tefPAST_SEQ
-
The sequence number of the transaction is lower than the current sequence number of the account sending the transaction.
-
-
-
tefWRONG_PRIOR
-
The transaction contained an AccountTxnID field (or the deprecated PreviousTxnID field), but the transaction specified there does not match the account's previous transaction.
+
While attempting to apply the transaction, the server entered an unexpected state. If you can reproduce this error, please report an issue to get it fixed.
tefMASTER_DISABLED
@@ -1650,6 +1879,22 @@
tefMAX_LEDGER
The transaction included a LastLedgerSequence parameter, but the current ledger's sequence number is already higher than the specified value.
+
+
tefNO_AUTH_REQUIRED
+
The TrustSet transaction attempted to mark a trustline as authorized, but the lsfRequireAuth flag is not enabled for the corresponding account, so authorization is not necessary.
+
+
+
tefNOT_MULTI_SIGNING
+
The transaction was multi-signed, but the sending account has no SignerList defined.
+
+
+
tefPAST_SEQ
+
The sequence number of the transaction is lower than the current sequence number of the account sending the transaction.
+
+
+
tefWRONG_PRIOR
+
The transaction contained an AccountTxnID field (or the deprecated PreviousTxnID field), but the transaction specified there does not match the account's previous transaction.
+
ter Codes
@@ -1663,30 +1908,34 @@
-
terRETRY
-
Unspecified retriable error.
-
-
terFUNDS_SPENT
-
Deprecated. This code should never be returned.
+
DEPRECATED.
terINSUF_FEE_B
The account sending the transaction does not have enough XRP to pay the Fee specified in the transaction.
+
terLAST
+
Used internally only. This code should never be returned.
+
+
terNO_ACCOUNT
-
The account sending the transaction does not exist in the ledger (yet).
+
The address sending the transaction is not funded in the ledger (yet).
terNO_AUTH
-
The transaction would involve adding currency issued by an account with lsfRequireAuth enabled to a trustline that is not authorized. For example, you placed an offer to buy a currency you aren't authorized to hold.
+
The transaction would involve adding currency issued by an account with lsfRequireAuth enabled to a trust line that is not authorized. For example, you placed an offer to buy a currency you aren't authorized to hold.
terNO_LINE
Used internally only. This code should never be returned.
+
terNO_RIPPLE
+
Used internally only. This code should never be returned.
+
+
terOWNERS
The transaction requires that account sending it has a nonzero "owners count", so the transaction cannot succeed. For example, an account cannot enable the lsfRequireAuth flag if it has any trust lines or available offers.
@@ -1695,12 +1944,8 @@
The Sequence number of the current transaction is higher than the current sequence number of the account sending the transaction.
-
terLAST
-
Used internally only. This code should never be returned.
-
-
-
terNO_RIPPLE
-
Used internally only. This code should never be returned.
+
terRETRY
+
Unspecified retriable error.
@@ -1737,24 +1982,14 @@
Unspecified failure, with transaction cost destroyed.
-
tecPATH_PARTIAL
-
101
-
The transaction failed because the provided paths did not have enough liquidity to send the full amount.
+
tecDIR_FULL
+
121
+
The address sending the transaction cannot own any more objects in the ledger.
-
tecUNFUNDED_ADD
-
102
-
DEPRECATED.
-
-
-
tecUNFUNDED_OFFER
-
103
-
The OfferCreate transaction failed because the account creating the offer does not have any of the TakerGets currency.
-
-
-
tecUNFUNDED_PAYMENT
-
104
-
The transaction failed because the sending account is trying to send more XRP than it holds, not counting the reserve. (See: Reserves)
+
tecDST_TAG_NEEDED
+
143
+
The Payment transaction omitted a destination tag, but the destination account has the lsfRequireDestTag flag enabled. (New in rippled 0.28.0)
tecFAILED_PROCESSING
@@ -1762,9 +1997,9 @@
An unspecified error occurred when processing the transaction.
-
tecDIR_FULL
-
121
-
The "owners count" of the account sending the transaction is already maxed out.
The transaction failed because it needs to add a balance on a trust line to an account with the lsfRequireAuth flag enabled, and that trust line has not been authorized. If the trust line does not exist at all, tecNO_LINE occurs instead.
+
+
tecNO_DST
124
The account on the receiving end of the transaction does not exist. This includes Payment and TrustSet transaction types. (It could be created if it received sufficient XRP.)
@@ -1787,6 +2047,21 @@
The account on the receiving end of the transaction does not exist, and the transaction is not sending enough XRP to create it.
+
tecNO_ENTRY
+
140
+
Reserved for future use.
+
+
+
tecNO_ISSUER
+
133
+
The account specified in the issuer field of a currency amount does not exist.
+
+
+
tecNO_LINE
+
135
+
The TakerPays field of the OfferCreate transaction specifies an asset whose issuer has lsfRequireAuth enabled, and the account making the offer does not have a trust line for that asset. (Normally, making an offer implicitly creates a trust line if necessary, but in this case it does not bother because you cannot hold the asset without authorization.) If the trust line exists, but is not authorized, tecNO_AUTH occurs instead.
+
+
tecNO_LINE_INSUF_RESERVE
126
The transaction failed because the sending account does not have enough XRP to create a new trust line. (See: Reserves) This error occurs when the counterparty does not have a trust line to this account for the same currency. (See tecINSUF_RESERVE_LINE for the other case.)
@@ -1797,24 +2072,24 @@
The transaction failed because it attempted to set a trust line to its default state, but the trust line did not exist.
-
tecPATH_DRY
-
128
-
The transaction failed because the provided paths did not have enough liquidity to send anything at all. This could mean that the source and destination accounts are not linked by trust lines.
-
-
-
tecUNFUNDED
-
129
-
DEPRECATED. Replaced by tecUNFUNDED_OFFER and tecUNFUNDED_PAYMENT.
-
-
-
tecMASTER_DISABLED
-
130
-
The SetRegularKey transaction tried to unset the Regular Key, but the account has the lsfDisableMaster flag enabled. (Unsetting the Regular Key while also leaving the Master Key disabled would make the account unusable.)
+
tecNO_PERMISSION
+
139
+
Reserved for future use.
tecNO_REGULAR_KEY
131
-
The AccountSet transaction tried to disable the Master Key, but the account does not have a Regular Key set. (Disabling the Master Key without having a Regular Key configured would make the account unusable.)
This transaction could not be processed, because attempted transaction processing created an excessively large amount of metadata. (New in rippled 0.29.0-hf1 )
tecOWNERS
@@ -1822,74 +2097,39 @@
The transaction requires that account sending it has a nonzero "owners count", so the transaction cannot succeed. For example, an account cannot enable the lsfRequireAuth flag if it has any trust lines or available offers.
-
tecNO_ISSUER
-
133
-
The account specified in the issuer field of a currency amount does not exist.
+
tecPATH_DRY
+
128
+
The transaction failed because the provided paths did not have enough liquidity to send anything at all. This could mean that the source and destination accounts are not linked by trust lines.
-
tecNO_AUTH
-
134
-
The transaction failed because it needs to add a balance on a trust line to an account with the lsfRequireAuth flag enabled, and that trust line has not been authorized. If the trust line does not exist at all, tecNO_LINE occurs instead.
+
tecPATH_PARTIAL
+
101
+
The transaction failed because the provided paths did not have enough liquidity to send the full amount.
-
tecNO_LINE
-
135
-
The TakerPays field of the OfferCreate transaction specifies an asset whose issuer has lsfRequireAuth enabled, and the account making the offer does not have a trust line for that asset. (Normally, making an offer implicitly creates a trust line if necessary, but in this case it does not bother because you cannot hold the asset without authorization.) If the trust line exists, but is not authorized, tecNO_AUTH occurs instead.
+
tecUNFUNDED
+
129
+
DEPRECATED. Replaced by tecUNFUNDED_OFFER and tecUNFUNDED_PAYMENT.
-
tecINSUFF_FEE
-
136
-
The account sending the transaction does not possess enough XRP to pay the specified Fee. This error only occurs if the transaction has already been propagated through the network to achieve consensus,
The Payment transaction omitted a destination tag, but the destination account has the lsfRequireDestTag flag enabled. (New in rippled 0.28.0)
-
-
-
tecINTERNAL
-
144
-
Unspecified internal error, with transaction cost applied. This error code should not normally be returned.
-
-
-
tecOVERSIZE
-
145
-
This transaction could not be processed, because attempted transaction processing created an excessively large amount of metadata. (New in rippled 0.29.0-hf1 )
+
tecUNFUNDED_OFFER
+
103
+
The OfferCreate transaction failed because the account creating the offer does not have any of the TakerGets currency.
tej Codes
-
These codes are only ever returned by the ripple-lib client library, not by rippled itself.
+
These codes are only ever returned by the ripple-lib client library, not by rippled itself.
Multi-signing is one of three ways to authorize transactions for the Ripple Consensus Ledger, alongside signing with regular keys and master keys. You can configure your address to allow any combination of the three methods to authorize transactions.
+
Benefits of multi-signing include:
+
+
You can require keys from different devices, so that a malicious actor must compromise multiple machines to send transactions on your behalf.
+
You can share custody of an address between multiple people, each of whom only has one of several keys necessary to send transactions from that address.
+
You can delegate the power to send transactions from your address to a group of people, who can control your address if you are unavailable or unable to sign normally.
Multi-signing is built into rippled starting with version 0.31.0. Because multi-signing is a change in transaction processing, the change is due to be enabled by an Amendment to the Ripple Consensus Protocol. This Amendment must be approved by a consensus of validators showing consistent support for the feature over a period of time. For more information, see Amendments.
+
If you want to test multi-signing before it becomes available in the production network, or without risking real money, you can do so by running rippled in stand-alone mode with the MultiSign feature enabled. To enable multi-signing for testing, add the following stanza to your rippled.cfg:
To multi-sign transactions from a particular address, you must create a list of addresses that can contribute to a multi-signature for your address. This list is stored in the Ripple Consensus Ledger as a SignerList node. The following procedure demonstrates how to set up a SignerList for your address:
+
1. Prepare a funded address
+
You need a Ripple address that can send transactions, and has enough XRP available. Multi-signing requires more than the usual amount of XRP for the account reserve and transaction cost, increasing with the number of signers and signatures you use.
+
If you started rippled in stand-alone mode with a new genesis ledger, you must:
+
+
Generate keys for a new address, or reuse keys you already have.
+
Submit a Payment transaction to fund the new address from the genesis account. (Send at least 100,000,000 drops of XRP.)
+
Manually close the ledger.
+
+
2. Prepare member keys
+
You need several sets of Ripple keys (address and secret) to include as members of your SignerList. These can be funded addresses that exist in the ledger, or you can generate new addresses using the wallet_propose command. For example:
Take note of the account_id (Ripple Address) and master_seed (Ripple secret key) for each one you generate.
+
3. Send SignerListSet transaction
+
Sign and submit a SignerListSet transaction in the normal (single-signature) way. This associates a SignerList with your Ripple address, so that a combination of signatures from the members of that SignerList can multi-sign later transactions on your behalf.
+
In this example, the SignerList has 3 members, with the weights and quorum set up such that multi-signed transactions need a signature from rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW plus at least one signature from the other two members of the list.
+
Caution: Never submit a secret key to a server you do not control. Do not transmit a secret key unencrypted over the network.
Note: The more members in the SignerList, the more XRP your address must have for purposes of the owner reserve. If your address does not have enough XRP, the transaction fails with tecINSUFFICIENT_RESERVE. See also: SignerLists and Reserves.
+
4. Close the ledger
+
On the live network, you can wait 4-7 seconds for the ledger to close automatically.
+
If you're running rippled in stand-alone mode, use the ledger_accept command to manually close the ledger:
Use the account_objects command to confirm that the SignerList is associated with the address in the latest validated ledger.
+
Normally, an account can own many objects of different types (such as trust lines and offers). If you funded a new address for this tutorial, the SignerList is the only object in the response.
Disable the address's master key by sending an AccountSet transaction using the asfDisableMaster flag.
+
Remove the address's regular key (if you previously set one) by sending a SetRegularKey transaction.
+
+
Sending a Multi-Signed Transaction
+
Before you can multi-sign a transaction, first set up multi-signing for your address. The following procedure demonstrates how to create, sign, and submit a multi-signed transaction.
+
1. Create the transaction
+
Create a JSON object that represents the transaction you want to submit. You have to specify everything about this transaction, including Fee and Sequence. Also include the field SigningPubKey as an empty string, to indicate that the transaction is multi-signed.
+
Keep in mind that the Fee for multi-signed transactions is significantly higher than for regularly-signed transactions. It should be (N+1) times the normal transaction cost, where N is the number of signatures you plan to provide. Given that it sometimes takes a while to collect signatures from multiple sources, you may want to include additional buffer in case the transaction cost increases in that time.
+
Here's an example transaction ready to be multi-signed:
(This transaction creates an accounting relationship from rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC to rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh with a maximum balance of 100 USD.)
+
2. Get one signature
+
Use the sign_for command with the secret key and address of one of the members of your SignerList to get a signature for that member.
+
Caution: Never submit a secret key to a server you do not control. Do not transmit a secret key unencrypted over the network.
Save the tx_json field of the response: it has the new signature in the Signers field. You can discard the value of the tx_blob field.
+
3. Get additional signatures
+
You can collect additional signatures in parallel or in serial:
+
+
In parallel: Use the sign_for command with the original JSON for the transaction. Each response has a single signature in the Signers array.
+
In serial: Use the sign_for command with the tx_json value from the previous sign_for response. Each response adds a new signature to the existing Signers array.
+
+
Caution: Never submit a secret key to a server you do not control. Do not transmit a secret key unencrypted over the network.
Depending on the SignerList you configured, you may need to repeat this step several times to get signatures from all the necessary parties.
+
4. Combine signatures and submit
+
If you collected the signatures in serial, the tx_json from the last sign_for response has all the signatures assembled, so you can use that as the argument to the submit_multisigned command.
+
If you collected the signatures in parallel, you must manually construct a tx_json object with all the signatures included. Take the Signers arrays from all the sign_for responses, and combine their contents into a single Signers array that has each signature. Add the combined Signers array to the original transaction JSON value, and use that as the argument to the submit_multisigned command.
Take note of the hash value from the response so you can check the results of the transaction later. (In this case, the hash is BD636194C48FD7A100DE4C972336534C8E710FD008C0F3CF7BC5BF34DAF3C3E6.)
+
5. Close the ledger
+
If you are using the live network, you can wait 4-7 seconds for the ledger to close automatically.
+
If you're running rippled in stand-alone mode, use the ledger_accept command to manually close the ledger:
Use the hash value from the response to the submit_multisigned command to look up the transaction using the tx command. In particular, check that the TransactionResult is the string tesSUCCESS.
+
On the live network, you must also confirm that the validated field is set to the boolean true. If the field is not true, you might need to wait longer for the consensus process to finish; or your transaction may be unable to be included in a ledger for some reason.
+
In stand-alone mode, the server automatically considers a ledger to be validated if it has been manually closed.
