ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-20 03:35:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

amendments updates

Browse Source
This commit is contained in:
mDuo13
2016-03-30 13:45:05 -07:00
parent 976a383ed0
commit d1a537f434
4 changed files with 367 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

165
concept-amendments.html
View File

@@ -132,21 +132,162 @@
<main class="main" role="main">
<div class="content">
<h1 id="amendments">Amendments</h1>
<p>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 for two weeks before they go into effect.</p>
<p>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 <strong>80% support for two weeks</strong> before it can apply.</p>
<p>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.</p>
<h2 id="background">Background</h2>
<p>Any changes to transaction processing could cause servers to build a different ledger with the same set of transactions. This could cause anything from minor inconveniences (a minority of servers spend more time and bandwidth fetching the actual consensus ledger because they cannot rely on their own) to serious problems: consensus might halt from validating ledgers because servers are unable to reach a majority who agree on the same result.</p>
<p>In theory, this could prompt a situation where the Ripple Consensus Ledger ceases to function because only a portion of validators have upgraded to a new version of the software.</p>
<p>Amendments fix that problem while also providing advance notice of when any transaction processing changes will go into effect, so that any users and businesses who rely on the behavior of the Ripple Consensus Ledger have fair warning in advance. API changes that do not impact the Consensus process do not require Amendments.</p>
<h2 id="amendment-lifecycle">Amendment Lifecycle</h2>
<p>An amendment is a fully-functional feature or change, ready to apply as soon as a consensus of servers can handle it. A server that wants to use an amendment must have functional code for two modes: without the amendment (previous behavior) and with the amendment (new behavior). Every amendment has a unique identifying string, which should indicate who developed it, in order to avoid potential overlap.</p>
<p>Every 256th ledger is called a "flag" ledger. The process of approving an amendment starts in the ledger version immediately before the flag ledger: at this time, <code>rippled</code> validator servers submit votes in favor of specific amendments alongside their validations for that ledger.</p>
<p>In the flag ledger itself, there is nothing unusual. However, during that time, the servers look at the votes of the validators they trust, and decide whether to insert an <code>Amendment</code> pseudo-transaction into the following ledger, with flags to indicate what it thinks happened:</p>
<p>Any changes to transaction processing could cause servers to build a different ledger with the same set of transactions. This could cause anything from minor inconveniences (a minority of servers spend more time and bandwidth fetching the actual consensus ledger because they cannot rely on their own) to serious problems: consensus might be unable to validate new ledger versions because servers are unable to reach a consensus who agree to the exact same result.</p>
<p>In theory, this could prompt a situation where the Ripple Consensus Ledger cannot make progress because only a portion of validators have upgraded to a new version of the software. Amendments provide solution to this problem, so that new features can be enabled only when enough validators support those features.</p>
<p>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 <a href="https://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/">the consensus process</a> do not require Amendments.</p>
<h2 id="amendment-process">Amendment Process</h2>
<p>An amendment is a fully-functional feature or change, ready to apply when a consensus of servers can handle it. A <code>rippled</code> server that wants to use an amendment has business logic 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 does not affect the status of the amendment.</p>
<p>Every 256th ledger is called a "flag" ledger. The process of approving an amendment starts in the ledger version immediately before the flag ledger: at this time, <code>rippled</code> validator servers submit votes in favor of specific amendments alongside their validations for that ledger. (<a href="concept-fee-voting.html">Fee Voting</a> also occurs around flag ledgers.)</p>
<p>In the flag ledger itself, there is nothing unusual. However, during that time, the servers look at the votes of the validators they trust, and decide whether to insert an <a href="reference-transaction-format.html#enableamendment"><code>EnableAmendment</code> pseudo-transaction</a> into the following ledger. The flags of an EnableAmendment pseudo-transaction indicate what the server thinks happened:</p>
<ul>
<li>The <code>tfGotMajority</code> flag means that support for a feature has increased across the threshold of 80% of trusted validators.</li>
<li>The <code>tfLostMajority</code> flag means that support for a feature has decreased across the threshold of 80% of trusted validators.</li>
<li>An Amendment pseudo-transaction with no flags means that support for a feature has been enabled. This is called the <em>"Enabled"</em> Amendment.</li>
<li>The <code>tfGotMajority</code> flag means that support for the amendment has increased to at least 80% of trusted validators.</li>
<li>The <code>tfLostMajority</code> flag means that support for the amendment has decreased to less than 80% of trusted validators.</li>
<li>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.)</li>
</ul>
<p>A server only inserts the "Enabled" Amendment if there is a validated ledger which closed at least two weeks prior to the current flag ledger, with a Got-Majority Amendment psuedo-transaction, and no Lost-Majority Amendment psuedo-transactions for the same feature in the validated ledgers in between.</p>
<p>A server only inserts the pseudo-transaction to enable an amendment if all of the following conditions are met:</p>
<ul>
<li>There is a validated ledger which closed at least two weeks prior to the current flag ledger, which includes an EnableAmendment pseudo-transaction for this amendment with the <code>tfGotMajority</code> flag enabled.</li>
<li>There are no EnableAmendment pseudo-transactions for this amendment with the <code>tfLostMajority</code> flag enabled in the validated ledgers between the <code>tfGotMajority</code> pseudo-transaction and the current ledger.</li>
</ul>
<p>It is theoretically possible (but extremely unlikely) that a <code>tfLostMajority</code> 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 <code>tfLostMajority</code> pseudo-transaction has no effect.</p>
<h2 id="amendment-voting">Amendment Voting</h2>
<p>Operators of <code>rippled</code> validators can choose which amendments to support or reject using the <a href="reference-rippled.html#feature"><code>feature</code> command</a>. This decides which amendments the validator votes for in the <a href="#amendment-process">amendment process</a>. By default, <code>rippled</code> votes in favor of every amendment it knows about.</p>
<p>The operator of a <code>rippled</code> validator can "veto" an amendment using the <a href="reference-rippled.html#feature"><code>feature</code> command</a>. In this case, that validator never sends a vote in favor of the amendment. If enough trusted validators veto an amendment, then the amendment does not apply.</p>
<p>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 recommends only trusting the 5 default validators that Ripple (the company) operates. For now, trusting only those validators is sufficient to coordinate with Ripple on releasing new features.</p>
<h1 id="known-amendments">Known Amendments</h1>
<p>The following is a comprehensive list of all known amendments and their status on the production Ripple Consensus Ledger:</p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Introduced</th>
<th>Enabled</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#tickets">Tickets</a></td>
<td>v0.31.0</td>
<td>TBD</td>
</tr>
<tr>
<td><a href="#suspay">SusPay</a></td>
<td>v0.31.0</td>
<td>TBD</td>
</tr>
<tr>
<td><a href="#trustsetauth">TrustSetAuth</a></td>
<td>v0.30.0</td>
<td>TBD</td>
</tr>
<tr>
<td><a href="#multisign">MultiSign</a></td>
<td>v0.31.0</td>
<td>Expected 2016-04-18</td>
</tr>
<tr>
<td><a href="#feeescalation">FeeEscalation</a></td>
<td>v0.31.0</td>
<td>Expected 2016-04-11</td>
</tr>
</tbody>
</table>
<h2 id="feeescalation">FeeEscalation</h2>
<table>
<thead>
<tr>
<th>Amendment ID</th>
</tr>
</thead>
<tbody>
<tr>
<td>42426C4D4F1009EE67080A9B7965B44656D7714D104A72F9B4369F97ABF044EE</td>
</tr>
</tbody>
</table>
<p>Changes the way the <a href="concept-transaction-cost.html">transaction cost</a> applies to proposed transactions. Modifies the consensus process to prioritize transactions that pay a higher transaction cost.</p>
<p>This amendment introduces a fixed-size transaction queue for transactions that were not able to be included in the previous consensus round. If the <code>rippled</code> 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 (<code>Fee</code> 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.</p>
<p>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.</p>
<p>A transaction remains in the queue until one of the following happens:</p>
<ul>
<li>It gets applied to a validated ledger (regardless of success or failure)</li>
<li>It becomes invalid (for example, the <a href="reference-transaction-format.html#lastledgersequence"><code>LastLedgerSequence</code></a> causes it to expire)</li>
<li>It gets dropped because there are too many transactions in the queue with a higher transaction cost.</li>
</ul>
<h2 id="multisign">MultiSign</h2>
<table>
<thead>
<tr>
<th>Amendment ID</th>
</tr>
</thead>
<tbody>
<tr>
<td>4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373</td>
</tr>
</tbody>
</table>
<p>Introduces simple <a href="reference-transaction-format.html#multi-signing">multi-signing</a> as a way to authorize transactions. Creates the <a href="reference-ledger-format.html#signerlist"><code>SignerList</code> ledger node type</a> and the <a href="reference-transaction-format.html#signerlistset"><code>SignerListSet</code> transaction type</a>. Adds the optional <code>Signers</code> field to all transaction types. Modifies some transaction result codes.</p>
<p>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."</p>
<p>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. This amendment does not allow second-level multi-signing (signers using multi-signatures to contribute to multi-signatures). Multi-signed transactions have the same permissions as transactions signed with a regular key.</p>
<p>An address with a SignerList can disable the master key even without a regular key, or remove a regular key even if the master key is disabled. Therefore, the <code>tecMASTER_DISABLED</code> transaction result code is renamed <code>tecNO_ALTERNATIVE_KEY</code>. The <code>tecNO_REGULAR_KEY</code> transaction result is retired and replaced with <code>tecNO_ALTERNATIVE_KEY</code>. Additionally, this amendment adds the following new <a href="reference-transaction-format.html#result-categories">transaction result codes</a>:</p>
<ul>
<li><code>temBAD_SIGNER</code></li>
<li><code>temBAD_QUORUM</code></li>
<li><code>temBAD_WEIGHT</code></li>
<li><code>tefBAD_SIGNATURE</code></li>
<li><code>tefBAD_QUORUM</code></li>
<li><code>tefNOT_MULTI_SIGNING</code></li>
<li><code>tefBAD_AUTH_MASTER</code></li>
</ul>
<h2 id="suspay">SusPay</h2>
<table>
<thead>
<tr>
<th>Amendment ID</th>
</tr>
</thead>
<tbody>
<tr>
<td>DA1BD556B42D85EA9C84066D028D355B52416734D3283F85E216EA5DA6DB7E13</td>
</tr>
</tbody>
</table>
<p>Provides "Suspended Payments" for XRP as a means of escrow within the Ripple Consensus Ledger. Creates the <code>SuspendedPayment</code> ledger node type and the new transaction types <code>SuspendedPaymentCreate</code>, <code>SuspendedPaymentFinish</code>, and <code>SuspendedPaymentCancel</code>.</p>
<p>This amendment is still in development. The current version is enabled on the <a href="https://ripple.com/build/ripple-test-net/">Ripple Test Net</a>.</p>
<h2 id="trustsetauth">TrustSetAuth</h2>
<table>
<thead>
<tr>
<th>Amendment ID</th>
</tr>
</thead>
<tbody>
<tr>
<td>6781F8368C4771B83E8B821D88F580202BCB4228075297B19E4FDC5233F1EFDC</td>
</tr>
</tbody>
</table>
<p>Allows pre-authorization of accounting relationships (zero-balance trust lines) when using <a href="tutorial-gateway-guide.html#authorized-accounts">Authorized Accounts</a>.</p>
<p>With this amendment enabled, a <code>TrustSet</code> transaction with <a href="reference-transaction-format.html#trustset-flags"><code>tfSetfAuth</code> enabled</a> can create a new <a href="reference-ledger-format.html#ripplestate"><code>RippleState</code> ledger node</a> even if it keeps all the other values of the <code>RippleState</code> node in their default state. The new <code>RippleState</code> node has the <a href="reference-ledger-format.html#ripplestate-flags"><code>lsfLowAuth</code> or <code>lsfHighAuth</code> flag</a> enabled accordingly. The sender of the transaction must have <a href="reference-ledger-format.html#accountroot-flags"><code>lsfRequireAuth</code> enabled</a>.</p>
<h2 id="tickets">Tickets</h2>
<table>
<thead>
<tr>
<th>Amendment ID</th>
</tr>
</thead>
<tbody>
<tr>
<td>C1B8D934087225F509BEB5A8EC24447854713EE447D277F69545ABFA0E0FD490</td>
</tr>
</tbody>
</table>
<p>Introduces Tickets as a way to reserve a transaction sequence number for later execution. Creates the <code>Ticket</code> ledger node type and the transaction types <code>TicketCreate</code> and <code>TicketCancel</code>.</p>
<p>This amendment is still in development.</p>
</div>
</main>
</div>

125
content/concept-amendments.md
View File

@@ -1,25 +1,126 @@
# Amendments #
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 for two weeks before they go into effect.
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. This could cause anything from minor inconveniences (a minority of servers spend more time and bandwidth fetching the actual consensus ledger because they cannot rely on their own) to serious problems: consensus might halt from validating ledgers because servers are unable to reach a majority who agree on the same result.
Any changes to transaction processing could cause servers to build a different ledger with the same set of transactions. This could cause anything from minor inconveniences (a minority of servers spend more time and bandwidth fetching the actual consensus ledger because they cannot rely on their own) to serious problems: consensus might be unable to validate new ledger versions because servers are unable to reach a consensus who agree to the exact same result.
In theory, this could prompt a situation where the Ripple Consensus Ledger ceases to function because only a portion of validators have upgraded to a new version of the software.
In theory, this could prompt a situation where the Ripple Consensus Ledger cannot make progress because only a portion of validators have upgraded to a new version of the software. Amendments provide solution to this problem, so that new features can be enabled only when enough validators support those features.
Amendments fix that problem while also providing advance notice of when any transaction processing changes will go into effect, so that any users and businesses who rely on the behavior of the Ripple Consensus Ledger have fair warning in advance. API changes that do not impact the Consensus process do not require Amendments.
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.
## Amendment Lifecycle ##
An amendment is a fully-functional feature or change, ready to apply as soon as a consensus of servers can handle it. A server that wants to use an amendment must have functional code for two modes: without the amendment (previous behavior) and with the amendment (new behavior). Every amendment has a unique identifying string, which should indicate who developed it, in order to avoid potential overlap.
## 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: at this time, `rippled` validator servers submit votes in favor of specific amendments alongside their validations for that ledger.
An amendment is a fully-functional feature or change, ready to apply when a consensus of servers can handle it. A `rippled` server that wants to use an amendment has business logic 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 does not affect the status of the amendment.
In the flag ledger itself, there is nothing unusual. However, during that time, the servers look at the votes of the validators they trust, and decide whether to insert an `Amendment` pseudo-transaction into the following ledger, with flags to indicate what it thinks happened:
Every 256th ledger is called a "flag" ledger. The process of approving an amendment starts in the ledger version immediately before the flag ledger: at this time, `rippled` validator servers submit votes in favor of specific amendments alongside their validations for that ledger. ([Fee Voting](concept-fee-voting.html) also occurs around flag ledgers.)
* The `tfGotMajority` flag means that support for a feature has increased across the threshold of 80% of trusted validators.
* The `tfLostMajority` flag means that support for a feature has decreased across the threshold of 80% of trusted validators.
* An Amendment pseudo-transaction with no flags means that support for a feature has been enabled. This is called the _"Enabled"_ Amendment.
In the flag ledger itself, there is nothing unusual. 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:
A server only inserts the "Enabled" Amendment if there is a validated ledger which closed at least two weeks prior to the current flag ledger, with a Got-Majority Amendment psuedo-transaction, and no Lost-Majority Amendment psuedo-transactions for the same feature in the validated ledgers in between.
* 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:
* There is a validated ledger which closed at least two weeks prior to the current flag ledger, which includes an EnableAmendment pseudo-transaction for this amendment with the `tfGotMajority` flag enabled.
* There are no EnableAmendment pseudo-transactions for this amendment with the `tfLostMajority` flag enabled in the validated 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 using the [`feature` command](reference-rippled.html#feature). In this case, that validator never sends a vote in favor of the amendment. If enough trusted validators veto an amendment, then 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 recommends only trusting the 5 default validators that Ripple (the company) operates. For now, trusting only those validators is sufficient to coordinate with Ripple on releasing new features.
# 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 | Expected 2016-04-18 |
| [FeeEscalation](#feeescalation) | v0.31.0 | Expected 2016-04-11 |
## 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. This amendment does not allow second-level multi-signing (signers using multi-signatures to contribute to multi-signatures). 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 without a regular key, or 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.

45
content/reference-transaction-format.md
View File

@@ -12,10 +12,12 @@ 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.
@@ -30,9 +32,9 @@ In the decentralized Ripple Consensus Ledger, a digital signature proves that a
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 address. You can disable or enable the master key using an [AccountSet transaction](#accountset).
* A single signature that matches a regular key enabled for the address. You can enable, remove, or replace a regular key using a [SetRegularKey transaction](#setregularkey).
* A [multi-signature](#multi-signing) that matches a list of signers enabled for the address. You can enable, remove, or replace a list of signers using a [SignerListSet transaction](#SignerListSet).
* 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).
Any signature type can authorize any type of transaction, with the following exceptions:
@@ -223,7 +225,7 @@ Every transaction type has the same set of fundamental fields:
| [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. 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 which authorizes this transaction. |
| [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`, `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. |
@@ -519,7 +521,7 @@ The available AccountSet flags are:
| 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:
@@ -765,7 +767,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 ###
@@ -848,9 +850,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.
```
{
@@ -876,8 +878,27 @@ A change in [transaction cost](concept-transaction-cost.html) or [account reserv
| ReserveBase | Unsigned Integer | UInt32 | The base reserve, in drops |
| ReserveIncrement | Unsigned Integer | UInt32 | The incremental reserve, in drops |
## 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. |
@@ -1074,7 +1095,7 @@ These codes indicate that the transaction failed to apply, but the transaction c
| 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. |
| tefBAD\_QUORUM | The transaction was [multi-signed](#multi-signing), but the total weights of all included signatures did not meet the quorum. |
| tefNOT\_MULTI\_SIGNING | The transaction was [multi-signed](#multi-signing), but the sending account has no SignerList defined. |
| tefBAD\_AUTH\_MASTER | <span class='draft-comment'>(something to do with the key not being the right one for this account)</span> |
| 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. |
### ter Codes ###
@@ -1122,8 +1143,8 @@ These codes indicate that the transaction failed, but it was applied to a ledger
| 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. |
| tecNO\_ALTERNATIVE\_KEY | 130 | The transaction tried to remove the only available method of signing 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` instead.) |
| 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.) |
| 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` instead.) |
| 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. |
| 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. |

80
reference-transaction-format.html
View File

@@ -140,10 +140,12 @@
<li><a href="#offercreate">OfferCreate - Submit an order to exchange currency</a></li>
<li><a href="#offercancel">OfferCancel - Withdraw a currency-exchange order</a></li>
<li><a href="#trustset">TrustSet - Add or modify a trust line</a></li>
<li><a href="#signerlistset">SignerListSet - Set multi-signing settings</a></li>
</ul>
<p>Additionally, there are <em>Psuedo-Transactions</em> that are not created and submitted in the usual way, but may appear in ledgers:</p>
<p>Additionally, there are <em>Pseudo-Transactions</em> that are not created and submitted in the usual way, but may appear in ledgers:</p>
<ul>
<li><a href="#setfee">SetFee - Adjust the minimum transaction cost or account reserve</a></li>
<li><a href="#enableamendment">EnableAmendment - Apply a change to transaction processing</a></li>
</ul>
<p>Transactions are only valid if signed, submitted, and accepted into a validated ledger version. There are many ways a transaction can fail.</p>
<ul>
@@ -156,9 +158,9 @@
<p>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.</p>
<p>A transaction can be authorized by any of the following types of signatures:</p>
<ul>
<li>A single signature from the master secret key that is mathematically associated with the address. You can disable or enable the master key using an <a href="#accountset">AccountSet transaction</a>.</li>
<li>A single signature that matches a regular key enabled for the address. You can enable, remove, or replace a regular key using a <a href="#setregularkey">SetRegularKey transaction</a>.</li>
<li>A <a href="#multi-signing">multi-signature</a> that matches a list of signers enabled for the address. You can enable, remove, or replace a list of signers using a <a href="#SignerListSet">SignerListSet transaction</a>.</li>
<li>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 <a href="#accountset">AccountSet transaction</a>.</li>
<li>A single signature that matches a regular key associated with the address. You can add, remove, or replace a regular key using a <a href="#setregularkey">SetRegularKey transaction</a>.</li>
<li>A <a href="#multi-signing">multi-signature</a> that matches a list of signers owned by the address. You can add, remove, or replace a list of signers using a <a href="#SignerListSet">SignerListSet transaction</a>.</li>
</ul>
<p>Any signature type can authorize any type of transaction, with the following exceptions:</p>
<ul>
@@ -382,7 +384,7 @@
<td><a href="#signers-field">Signers</a></td>
<td>Array</td>
<td>Array</td>
<td>(Optional) Array of objects that represent a multi-signature which authorizes this transaction.</td>
<td>(Optional) Array of objects that represent a <a href="#multi-signing">multi-signature</a> which authorizes this transaction.</td>
</tr>
<tr>
<td>SourceTag</td>
@@ -826,7 +828,7 @@
</tr>
</tbody>
</table>
<p><em>New in <a href="https://github.com/ripple/rippled/releases/tag/0.28.0-rc1">rippled 0.28.0</a>:</em> You cannot send a transaction that enables <code>asfDisableMaster</code> or <code>asfNoFreeze</code> using a <a href="#setregularkey">regular key</a>. You must use the master key to sign the transaction.</p>
<p><em>New in <a href="https://github.com/ripple/rippled/releases/tag/0.28.0-rc1">rippled 0.28.0</a>:</em> In order to enable the <code>asfDisableMaster</code> or <code>asfNoFreeze</code> flags, you must <a href="#authorizing-transactions">authorize the transaction</a> by signing it with the master key. You cannot use a regular key or a multi-signature.</p>
<p>The following <a href="#flags">Transaction flags</a>, specific to the AccountSet transaction type, serve the same purpose, but are discouraged:</p>
<table>
<thead>
@@ -1158,7 +1160,7 @@
<p>Since a trust line occupies space in the ledger, <a href="concept-reserves.html">a trust line increases the XRP your account must hold in reserve</a>. This applies to the account extending trust, not to the account receiving it.</p>
<p>A trust line with settings in the default state is equivalent to no trust line.</p>
<p>The default state of all flags is off, except for the <a href="https://ripple.com/knowledge_center/understanding-the-noripple-flag/">NoRipple flag</a>, whose default state depends on the DefaultRipple flag.</p>
<p>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. <em>(New in <a href="https://github.com/ripple/rippled/releases/tag/0.30.0">rippled 0.30.0</a>)</em>: You can pre-authorize a trust line with the <code>tfSetfAuth</code> flag only, even if the limit and balance of the trust line are 0.</p>
<p>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. <em>(New in <a href="https://github.com/ripple/rippled/releases/tag/0.30.0">rippled 0.30.0</a>)</em>: The <a href="concept-amendments.html#trustsetauth"><code>TrustSetAuth</code> Amendment</a> would allow you to pre-authorize a trust line with the <code>tfSetfAuth</code> flag only, even if the limit and balance of the trust line are 0. This Amendment is not currently enabled.</p>
<h3 id="trustset-flags">TrustSet Flags</h3>
<p>Transactions of the TrustSet type support additional values in the <a href="#flags"><code>Flags</code> field</a>, as follows:</p>
<table>
@@ -1297,8 +1299,8 @@
</tbody>
</table>
<h2 id="setfee">SetFee</h2>
<p>A change in <a href="concept-transaction-cost.html">transaction cost</a> or <a href="concept-reserves.html">account reserve</a> requirements. This is typically in response to changes in the load on the network.</p>
<p><em>Note:</em> You cannot send a pseudo-transaction, but you may encounter one when processing ledgers.</p>
<p>A change in <a href="concept-transaction-cost.html">transaction cost</a> or <a href="concept-reserves.html">account reserve</a> requirements as a result of <a href="concept-fee-voting.html">Fee Voting</a>.</p>
<p><strong>Note:</strong> You cannot send a pseudo-transaction, but you may encounter one when processing ledgers.</p>
<pre><code>{
"Account": "rrrrrrrrrrrrrrrrrrrrrhoLvTp",
"BaseFee": "000000000000000A",
@@ -1350,6 +1352,60 @@
</tr>
</tbody>
</table>
<h2 id="enableamendment">EnableAmendment</h2>
<p>Tracks the progress of the <a href="concept-amendments.html#amendment-process">Amendment process</a> for changes in transaction processing. This can indicate that a proposed Amendment gained or lost majority approval, or that an Amendment has been enabled.</p>
<p><strong>Note:</strong> You cannot send a pseudo-transaction, but you may encounter one when processing ledgers.</p>
<table>
<thead>
<tr>
<th>Field</th>
<th>JSON Type</th>
<th><a href="https://wiki.ripple.com/Binary_Format">Internal Type</a></th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>Amendment</td>
<td>String</td>
<td>Hash256</td>
<td>A unique identifier for the Amendment. This is not intended to be a human-readable name. See <a href="concept-amendments.html">Amendments</a> for a list of known Amendments.</td>
</tr>
<tr>
<td>LedgerSequence</td>
<td>Number</td>
<td>UInt32</td>
<td>The index of the ledger version where this Amendment appears. This distinguishes the pseudo-transaction from other occurrences of the same change.</td>
</tr>
</tbody>
</table>
<h3 id="enableamendment-flags">EnableAmendment Flags</h3>
<p>The <code>Flags</code> value of the EnableAmendment pseudo-transaction indicates the status of the Amendment at the time of the ledger including the pseudo-transaction.</p>
<p>A <code>Flags</code> value of <code>0</code> (no flags) indicates that the Amendment has been enabled, and applies to all ledgers afterward. Other <code>Flags</code> values are as follows:</p>
<table>
<thead>
<tr>
<th>Flag Name</th>
<th>Hex Value</th>
<th>Decimal Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>tfGotMajority</td>
<td>0x00010000</td>
<td>65536</td>
<td>Support for this Amendment increased to at least 80% of trusted validators starting with this ledger version.</td>
</tr>
<tr>
<td>tfLostMajority</td>
<td>0x00020000</td>
<td>131072</td>
<td>Support for this Amendment decreased to less than 80% of trusted validators starting with this ledger version.</td>
</tr>
</tbody>
</table>
<h1 id="transaction-results">Transaction Results</h1>
<h2 id="immediate-response">Immediate Response</h2>
<p>The response from the <a href="reference-rippled.html#submit"><code>submit</code> command</a> contains a provisional result from the <code>rippled</code> server indicating what happened during local processing of the transaction.</p>
@@ -1805,7 +1861,7 @@
</tr>
<tr>
<td>tefBAD_AUTH_MASTER</td>
<td><span class="draft-comment">(something to do with the key not being the right one for this account)</span></td>
<td>The single signature provided to authorize this transaction does not match the master key, but no regular key is associated with this address.</td>
</tr>
</tbody>
</table>
@@ -1966,12 +2022,12 @@
<tr>
<td>tecNO_ALTERNATIVE_KEY</td>
<td>130</td>
<td>The transaction tried to remove the only available method of signing transactions. This could be a <a href="#setregularkey">SetRegularKey transaction</a> to remove the Regular Key, a <a href="#signerlistset">SignerListSet transaction</a> to delete a SignerList, or an <a href="#accountset">AccountSet transaction</a> to disable the Master Key. (Prior to <a href="https://github.com/ripple/rippled/releases/tag/0.30.0">rippled 0.30.0</a>, this was called <code>tecMASTER_DISABLED</code> instead.)</td>
<td>The transaction tried to remove the only available method of <a href="#authorizing-transactions">authorizing transactions</a>. This could be a <a href="#setregularkey">SetRegularKey transaction</a> to remove the regular key, a <a href="#signerlistset">SignerListSet transaction</a> to delete a SignerList, or an <a href="#accountset">AccountSet transaction</a> to disable the master key. (Prior to <a href="https://github.com/ripple/rippled/releases/tag/0.30.0">rippled 0.30.0</a>, this was called <code>tecMASTER_DISABLED</code> instead.)</td>
</tr>
<tr>
<td>tecNO_REGULAR_KEY</td>
<td>131</td>
<td>The <a href="#accountset">AccountSet transaction</a> 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.)</td>
<td>The <a href="#accountset">AccountSet transaction</a> tried to disable the master key, but the account does not have another way to <a href="#authorizing-transactions">authorize transactions</a>. If <a href="#multi-signing">multi-signing</a> is enabled, this code is deprecated and <code>tecNO_ALTERNATIVE_KEY</code> is used instead.</td>
</tr>
<tr>
<td>tecOWNERS</td>