mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-04 03:45:49 +00:00
WIP reorg
This commit is contained in:
ddawson
@@ -1,6 +1,5 @@
|
||||
---
|
||||
html: amendments.html
|
||||
parent: consensus-network.html
|
||||
blurb: Amendments represent new features or other changes to transaction processing. Validators coordinate through consensus to apply these upgrades to the XRP Ledger in an orderly fashion.
|
||||
labels:
|
||||
- Blockchain
|
||||
@@ -234,6 +233,7 @@ Rather than maintain the source code for all old behavior indefinitely, [XRP Led
|
||||
When pre-amendment code has been retired, the server follows the amended logic for all transactions at all times. As a result, the server is no longer guaranteed to produce historically-accurate results if you try to replay ledgers older than the cutoff date. The server prints a warning if you try to [load and replay a ledger](load-a-saved-ledger-in-stand-alone-mode.html) that is older than the cutoff date. To produce historically-accurate results, you must compile or download an old server binary that has the legacy code.
|
||||
|
||||
|
||||
<!--
|
||||
## See Also
|
||||
|
||||
- **Concepts:**
|
||||
@@ -247,6 +247,7 @@ When pre-amendment code has been retired, the server follows the amended logic f
|
||||
- [EnableAmendment pseudo-transaction][]
|
||||
- [feature method][]
|
||||
- [server_info method][]
|
||||
-->
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
@@ -1,23 +0,0 @@
|
||||
---
|
||||
html: about-canceling-a-transaction.html
|
||||
parent: consensus-network.html
|
||||
blurb: 送信済みのトランザクションのキャンセルがいつどのように可能か説明します。
|
||||
labels:
|
||||
- トランザクション送信
|
||||
---
|
||||
# トランザクションの取消しについて
|
||||
|
||||
XRP Ledgerの重要かつ意図的な機能の1つに、トランザクションが検証済みレジャーに組み込まれると、即時に最終的なトランザクションになるという機能があります。
|
||||
|
||||
ただし、検証済みレジャーにまだ記録されていないトランザクションは、無効に設定することで実質的に取り消すことができます。通常は、同じアカウントから同じ`Sequence`値を指定した別のトランザクションを送信することになります。置換トランザクションが何もしないようにしたい場合は、オプションを指定せずに[AccountSetトランザクション][]を送信します。
|
||||
|
||||
たとえば、シーケンス番号が11、12、13の3つのトランザクションを送信しようとしたときに、トランザクション11が何らかの理由で失われるか、またはトランザクション11にネットワークに伝達するのに十分な[トランザクションコスト](transaction-cost.html)がない場合には、オプションを指定せずシーケンス番号11を指定したAccuontSetトランザクションを送信すれば、トランザクション11を取り消せます。このトランザクションは（新しいトランザクション11のトランザクションコストを消却する以外は）何も行いませんが、トランザクション12と13を有効にできます。
|
||||
|
||||
この方法により、異なるシーケンス番号のトランザクションの内容が実質的に重複することを防げるため、トランザクション12と13の番号を変更して再送信するよりも望ましい方法です。
|
||||
|
||||
つまり、オプションが指定されていないAccountSetトランザクションは標準的な「[no-op](http://en.wikipedia.org/wiki/NOP)」トランザクションです。
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
@@ -1,27 +0,0 @@
|
||||
---
|
||||
html: about-canceling-a-transaction.html
|
||||
parent: consensus-network.html
|
||||
blurb: Understand when and how it's possible to cancel a transaction that has already been sent.
|
||||
labels:
|
||||
- Transaction Sending
|
||||
---
|
||||
# About Canceling a Transaction
|
||||
|
||||
An important and intentional feature of the XRP Ledger is that a [transaction](transaction-basics.html)'s outcome is [final](finality-of-results.html) as soon as it has been incorporated in a [ledger version](ledgers.html) that is validated by the [consensus process](consensus.html).
|
||||
|
||||
If a transaction has _not_ yet been included in a validated ledger, it may be possible to effectively cancel it by sending another transaction from the same sending address with the same `Sequence` value. If you do not want the replacement transaction to do anything, send an [AccountSet transaction][] with no options.
|
||||
|
||||
**Caution:** There is no guaranteed way to cancel a valid transaction after it has been distributed to the network. The process described here may or may not work depending on factors including how busy the network is, the network topology, and the [transaction cost](transaction-cost.html) of the proposed transaction.
|
||||
|
||||
If the transaction has already been distributed to the network and proposed as a [candidate transaction](consensus.html#consensus-1) in servers' consensus proposals, it may be too late to cancel. It is more likely that you can successfully cancel a transaction that is [queued](transaction-queue.html) or is stuck "in limbo" because its [transaction cost](transaction-cost.html) is not high enough to meet the network's current requirements. In this case, the replacement transaction can either do nothing, or do the same thing as the transaction to be canceled. The replacement transaction is more likely to succeed if its transaction cost is higher.
|
||||
|
||||
For example, if you try to submit 3 transactions with sequence numbers 11, 12, and 13, but transaction 11 gets lost somehow or does not have a high enough [transaction cost](transaction-cost.html) to be propagated to the network, then you can cancel transaction 11 by submitting an AccountSet transaction with no options and sequence number 11. This does nothing (except destroying the transaction cost for the new transaction 11), but it allows transactions 12 and 13 to become valid.
|
||||
|
||||
This approach is preferable to renumbering and resubmitting transactions 12 and 13, because it prevents transactions from being effectively duplicated under different sequence numbers.
|
||||
|
||||
In this way, an AccountSet transaction with no options is the canonical "[no-op](http://en.wikipedia.org/wiki/NOP)" transaction.
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
@@ -1,111 +0,0 @@
|
||||
---
|
||||
html: consensus-principles-and-rules.html
|
||||
parent: consensus-network.html
|
||||
blurb: XRP Ledgerは世界規模の決済システムで、ユーザーはメールを送るときのようにスムーズに国境を越えて送金することができます。
|
||||
labels:
|
||||
- ブロックチェーン
|
||||
---
|
||||
# コンセンサスの原理とルール
|
||||
|
||||
XRP Ledgerは世界規模の決済システムで、ユーザーはメールを送るときのようにスムーズに国境を越えて送金することができます。Bitcoinなどの他のピアツーピア決済ネットワークと同様に、XRP Ledgerでは分散型コンピューターネットワークを介したピアツーピア取引の決済が可能です。他のデジタル通貨プロトコルとは異なり、XRP LedgerではXRP（XRP Ledgerのネイティブ資産）の他にユーザーが選択した通貨（法定通貨、デジタル通貨、その他の価値形態など）建てでトランザクションを実行できます。
|
||||
|
||||
XRP Ledgerのテクノロジーにより、ほぼリアルタイムでの決済（3～6秒）が可能です。また、その分散型取引所により自動的に最も安価な通貨取引注文を決済に適用して通貨をブリッジングすることができます。
|
||||
|
||||
# 背景
|
||||
|
||||
## 仕組み
|
||||
|
||||
根本的には、XRP Ledgerはアカウント、残高、および資産取引オファーなどの情報を記録する共有データベースです。「トランザクション」と呼ばれる署名付きの指示により、アカウントの作成、支払いの実行、資産の取引などの変更が行われます。
|
||||
|
||||
暗号化システムであるため、XRP Ledgerアカウントの所有者は _暗号ID_ により識別されます。暗号IDは、公開鍵/秘密鍵のペアに相当します。トランザクションは、暗号IDに一致する暗号署名によって承認されます。すべてのサーバーでは、同一の確定的な既知のルールに基づいてすべてのトランザクションが処理されます。最終的な目標は、ネットワーク内のすべてのサーバーがまったく同じレジャー状態の完全なコピーを保有できるようにし、1つの中央機関がトランザクションを調停する必要がないようにすることです。
|
||||
|
||||
|
||||
## 二重支払いの問題
|
||||
|
||||
「二重支払い」の問題は、どのような決済システムの運用においても根本的な課題となります。この問題は、ある場所でお金を支払うときに、別の場所ではそのお金を支払うことができないという要件に起因しています。一般的には、2つのトランザクションがあり、いずれかのトランザクションが有効で、両方が同時に有効になることがない場合にこの問題が発生します。
|
||||
|
||||
たとえば、Alice、Bob、Charlieが決済システムを使用しており、Aliceの残高が$10であるとします。この決済システムが機能するためには、Aliceはこの$10をBobまたはCharlieに送金できる必要があります。ただしAliceがBobに$10を送金し、同時にCharlieにも$10を送金しようとすると、二重支払いの問題が発生します。
|
||||
|
||||
Aliceが「同じ」$10をCharlieとBobの両方に送金できてしまう場合、この決済システムは正しく機能したとはいえなくなります。決済システムでは、発生したトランザクションについてすべての参加者が合意できるように、成功すべきトランザクションと失敗すべきトランザクションを選択する手段が必要です。これら2つのトランザクションはいずれも、トランザクションとしては同じく有効です。ただし、どのトランザクションが最初に発生したかについては、決済システムの参加者によって見方が異なります。
|
||||
|
||||
従来、決済システムでは中央機関がトランザクションを追跡、承認することで、この二重支払いの問題が解決されてきました。たとえば銀行は唯一の管理人として、保有する小切手振出人の預金残高に基づいて小切手を決済します。このようなシステムでは、すべての参加者が中央機関の決定に従う必要があります。
|
||||
|
||||
XRP Ledgerなどの分散型台帳技術では中央機関が存在せず、二重支払いの問題を他の方法で解決する必要があります。
|
||||
|
||||
|
||||
# コンセンサスの仕組み
|
||||
|
||||
## 問題の単純化
|
||||
|
||||
二重支払いの問題のほとんどは、既知のルール（アカウントが保有していない資金を利用することを禁止するなど）により解決できます。実際に、二重支払いの問題はトランザクションを順に整理することで削減できます。
|
||||
|
||||
BobとCharlieの両方に同じ$10を送金しようとしたAliceの例で説明します。Bobへの支払いが最初であることが判明している場合は、AliceにはBobに支払う資金があることで全員が合意できます。Charlieへの支払いが2番目であることが判明している場合は、資金はすでにBobに送金されたため、Charlieには資金を送金できないことで全員が合意できます。
|
||||
|
||||
また、確定的なルールに基づいてトランザクションを順に並べることもできます。トランザクションはデジタル情報の集合であるため、コンピューターで簡単にソートできます。
|
||||
|
||||
中央機関なしに二重支払いの問題を解決するにはこれで十分ですが、トランザクションの結果を確認する前に、発生するすべてのトランザクションを把握し、ソートする必要があります。これは明らかに非現実的です。 <!-- STYLE_OVERRIDE: obviously -->
|
||||
|
||||
トランザクションをグループにまとめ、グループ単位で合意できる場合には、グループ内でトランザクションをソートできます。ひとまとめで処理するトランザクションについて参加者全員が合意している限り、中央機関を必要とすることなく、確定的なルールに基づいて二重支払いの問題を解決できます。各参加者がトランザクションをソートし、既知のルールに従い確定的な方法でそれらのトランザクションを適用します。XRP Ledgerでは、二重支払いの問題をこの方法で解決します。
|
||||
|
||||
XRP Ledgerでは、合意されたグループに複数の競合するトランザクションを含めることができます。トランザクションのグループは確定的なルールに従って実行されるので、ソートルールに基づいて最初に発生したトランザクションが成功し、2番目に発生した競合するトランザクションは失敗します。
|
||||
|
||||
## コンセンサスルール
|
||||
|
||||
コンセンサスの主な役割は、プロセスの参加者が、二重支払いの問題を解決するためグループ単位で処理するトランザクションについて合意を形成できるようにすることです。次の4つの理由により、この合意の形成は予想以上に容易です。
|
||||
|
||||
1. トランザクションをトランザクショングループに含めてはならない理由が特にない場合、すべての公正な参加者はそのトランザクションをグループに含めることで合意します。すべての参加者がすでに合意している場合、コンセンサスが果たす役割はありません。
|
||||
2. トランザクションをトランザクショングループに含めてはならない何らかの理由がある場合、すべての公正な参加者はそのトランザクションの除外を希望します。トランザクションがまだ有効であり、次のラウンドに含めてはならない理由が特にない場合は、そのトランザクションを次のラウンドに含めることで全員が合意します。
|
||||
3. トランザクションをグループ化する方法に参加者が特に関心を示すことは極めてまれです。合意の形成は、参加者全員がこれを最優先と認識している場合は最も容易になされ、参加者の関心が異なる場合に限り難しくなります。
|
||||
4. 確定的なルールはグループ編成時にも使用でき、エッジケースについてのみ不合意を形成します。たとえば、ラウンドに2つの競合するトランザクションがある場合、確定的なルールを使用して次のラウンドに含めるトランザクションを決定できます。
|
||||
|
||||
すべての参加者は正確さを最も重視します。共有レジャーの整合性を損なわないようにするため、最初にこれらのルールを適用する必要があります。たとえば、適切な署名がないトランザクションは（他の参加者が処理を希望する場合でも）処理されることはありません。ただし、公正な参加者全員が2番目に重視するのは合意です。二重支払いが発生する可能性のあるネットワークはまったく役に立ちません。公正な参加者全員が正確さの次に重視するのが合意であるという事実により、合意が促進されます。
|
||||
|
||||
## コンセンサスラウンド
|
||||
|
||||
コンセンサスラウンドとは、トランザクションのグループについての合意形成に向けた取り組みで、これによりトランザクションの処理を可能とします。コンセンサスラウンドでは、合意形成を希望する各参加者が最初の見解を表明します。これは、参加者が確認した有効なトランザクションセットです。
|
||||
|
||||
次に、合意に向けて、参加者の見解が「次々に寄せられます」。特定のトランザクションが過半数の支持を得られない場合、参加者はそのトランザクションの保留に合意します。特定のトランザクションが過半数の支持を得ている場合、参加者はそのトランザクションを追加することに合意します。このように、支持が過半数をわずかに上回れば即座に全面的に支持され、過半数をわずかに下回れば即座に現行ラウンドでは全面的に却下されることになります。
|
||||
|
||||
コンセンサスが50%前後で行き詰まることを防ぎ、確実な合意を形成する上で必要となる重複を低減するため、トランザクションの追加に関する所定のしきい値は時間の経過とともに増加します。最初は、50%以上の他の参加者が合意していれば、参加者はトランザクションの追加についての合意の継続を支持します。参加者が合意しない場合、このしきい値が増加します。最初は60%に増加し、その後は問題のトランザクションが現行セットから削除されるまで増加し続けます。このようにして除外されたトランザクションはすべて次のレジャーバージョンに繰り越されます。
|
||||
|
||||
次に処理するトランザクションセットについて圧倒的多数が合意し、参加者がこれを確認した場合は、コンセンサスに達したと宣言します。
|
||||
|
||||
## コンセンサス失敗の可能性
|
||||
|
||||
完全なコンセンサスの達成に失敗することがないコンセンサスアルゴリズムの開発は非現実的です。その理由を理解するため、コンセンサスプロセスがどのように終了するかについて説明します。各参加者はある時点で、コンセンサスに達し、特定のトランザクションセットがそのコンセンサスプロセスの結果であると宣言する必要があります。この宣言により参加者は、特定のトランザクションセットがコンセンサスプロセスの結果であると取り消し不能の表明をすることになります。
|
||||
|
||||
いずれかの参加者がこの宣言を最初に行う必要があります。この宣言を行なう参加者がいなければ、合意に達することができません。次に、この宣言を最初に行う参加者について説明します。最初に宣言を行う参加者が、コンセンサスは完了したと判断した時点では、他の参加者はまだそのような判断に至っていません。もし他の参加者が各自の視点をもとに合意済のセットを変更できないのであれば、最初の宣言が行われた時点で、他の参加者はコンセンサスは完了したと判断していたでしょう。したがって、参加者は合意済のセットを変更できるはずです。 <!-- STYLE_OVERRIDE: will -->
|
||||
|
||||
つまり、コンセンサスプロセスを完了するには、その他のすべての参加者が合意済のトランザクションセットを理論的に変更できる場合でも、特定の参加者がトランザクションセットについてコンセンサスに達したことを宣言する必要があります。
|
||||
|
||||
たとえば、あるグループが部屋の中でどのドアから外に出るかについて合意しようとしている場合を考えてください。参加者がどれほど話し合っても、ある時点で _誰か_ が最初にドアから外に出なければなりません。これは、その後に続く人々が考えを変えて別のドアから外に出ることができるとしてもです。
|
||||
|
||||
このような失敗が生じる確率を低く抑えることはできますが、ゼロにすることはできません。技術上のトレードオフとして、この確率を1000分の1未満に抑えると、コンセンサスにかかる時間が非常に長くなり、ネットワークとエンドポイントの障害に対する耐性が低くなります。
|
||||
|
||||
## XRP Ledgerでのコンセンサス失敗の処理
|
||||
|
||||
コンセンサスラウンドが完了したら、各参加者は、合意に達したと各自が理解しているトランザクションのセットを適用します。その結果、レジャーの次の段階と各自が想定しているものが生成されます。
|
||||
|
||||
バリデータでもある参加者が、次のレジャーの暗号フィンガープリントを公開します。このフィンガープリントを「検証投票」と呼びます。コンセンサスラウンドが成功した場合、公正なバリデータの過半数が同じフィンガープリントを公開します。
|
||||
|
||||
次に参加者がこれらの検証投票を収集します。検証投票から、参加者は前のコンセンサスラウンドの結果、参加者の圧倒的多数がトランザクションセットについて合意しているか否かを確認できます。
|
||||
|
||||
参加者は次の3つのいずれかの状況になります（確率の高い順）。
|
||||
|
||||
1. 圧倒的多数が合意したレジャーと同じレジャーを構築します。この場合、参加者はそのレジャーが完全に検証済みであると見なし、その内容を信頼できます。
|
||||
2. 圧倒的多数が合意したレジャーとは異なるレジャーを構築します。この場合、参加者は圧倒的多数が合意したレジャーを構築して受け入れる必要があります。これは通常、参加者が早期にコンセンサスを宣言した後、他の多くの参加者が考えを変えたことを意味します。圧倒的多数が合意したレジャーに「ジャンプ」して操作を再開する必要があります。
|
||||
3. 受信した検証からは圧倒的多数が明確ではありません。この場合、前のコンセンサスラウンドが無駄となったため、いずれかのレジャーが検証される前に新しいラウンドが発生する必要があります。
|
||||
|
||||
ケース1が最も一般的に発生する状況です。ケース2はネットワークに一切悪影響を及ぼしません。ごく少数の参加者は、あらゆるラウンドでケース2の状況になることがありますが、ネットワークは特に問題なく動作します。このような参加者も、構築したレジャーが圧倒的多数が支持するレジャーと同じでなかったことを認識できるので、圧倒的多数との合意に達するまでは、その結果を最終結果として報告してはならないことを理解しています。
|
||||
|
||||
ケース3では、ネットワークは数秒間遅滞する結果となります。この間に処理を進められる可能性はありますが、非常にまれです。このケースでは、意見の相違はコンセンサスプロセスで解決され、未解決のまま残っている意見の相違のみが失敗の原因となるため、次のコンセンサスラウンドが失敗する可能性は大幅に低下します。
|
||||
|
||||
まれに、ネットワーク全体が数秒間にわって処理を進めることができないことがあります。その代わり、トランザクションの平均確認時間は短くなります。
|
||||
|
||||
# 理念
|
||||
|
||||
信頼性の1つの要素として、一部のコンポーネントで障害が発生している、悪意のある参加者がいるなどの状況でも結果を提供できるというシステムの能力があげられます。この点は重要ですが、暗号決済システムに関してはこれよりもさらに重要なもう1つの信頼性の要素があります。それは、信頼できる結果を提供するシステムの能力です。つまり、システムが結果を信頼できるものとして報告する場合、その結果を信頼できなければなりません。
|
||||
|
||||
ただし実際のシステムは、この両方の信頼性が損なわれる可能性のある運用状況に直面します。このような状況には、ハードウェア障害、通信障害、不正な参加者などがあります。XRP Ledgerの設計理念の1つとして、信頼してはならない結果を提供するのではなく、結果の信頼性が損なわれている状況を検知し、報告することを掲げています。
|
||||
|
||||
XRP Ledgerのコンセンサスアルゴリズムは、プルーフオブワークシステムに代わる堅牢な仕組みで、コンピューティングリソースを不必要に消費することはありません。ビザンチン障害が発生する可能性があり、また実際に発生することがありますが、その影響はわずかな遅延にとどまります。どのケースでも、XRP Ledgerのコンセンサスアルゴリズムは、結果が実際に信頼できるものである場合にのみ、信頼できる結果として報告します。
|
||||
@@ -1,16 +0,0 @@
|
||||
---
|
||||
html: consensus-research.html
|
||||
parent: consensus-network.html
|
||||
blurb: コンセンサスアルゴリズムに関する学術論文と関連研究。
|
||||
labels:
|
||||
- ブロックチェーン
|
||||
---
|
||||
# コンセンサスの研究
|
||||
|
||||
Rippleでは、XRP Ledgerのコンセンサスプロトコルの理論上の制限と実際の制限の両方についての研究を進め、この分野にてさまざまなアイデアを探究しています。以下の表に、Rippleが発表した学術論文の一覧を示します。
|
||||
|
||||
| 日付 | タイトル | 著者 | 概要 |
|
||||
|---|---|---|---|
|
||||
| 2018-02-20 | [Cobalt: BFT Governance in Open Networks](https://arxiv.org/abs/1802.07240) | MacBrough | コンセンサスUNLの柔軟性を高める新しいアトミックブロードキャストアルゴリズム、Cobaltの紹介。 |
|
||||
| 2018-02-20 | [Analysis of the XRP Ledger Consensus Protocol](https://arxiv.org/abs/1802.07242) | Chase, MacBrough | XRP Ledgerのコンセンサスアルゴリズムとその安全性および活性の特性に関する最新の詳細な分析。 |
|
||||
| 2014 | [The Ripple Protocol Consensus Algorithm](https://ripple.com/files/ripple_consensus_whitepaper.pdf) | Schwartz, Youngs, Britto | XRP Ledgerで採用されているコンセンサスアルゴリズムの紹介。 |
|
||||
@@ -1,88 +0,0 @@
|
||||
---
|
||||
html: federated-sidechains.html
|
||||
parent: consensus-network.html
|
||||
blurb: サイドチェーンとXRP Ledgerの間で、XRPやその他のトークン（IOU）の形で価値を効率的に移動させることができる、フェデレーションサイドチェーンについてご紹介します。
|
||||
labels:
|
||||
- ブロックチェーン
|
||||
---
|
||||
# フェデレーションサイドチェーン
|
||||
|
||||
_フェデレーションサイドチェーンは開発者プレビューとして提供されており、`rippled` 1.8.0を使った開発やテストに使用することができます。_
|
||||
|
||||
サイドチェーンとは、独自のコンセンサスアルゴリズムと取引の種類やルールを持つ独立した台帳のことです。独自のブロックチェーンとして機能します。フェデレーションは、XRPや他のトークンの形で、サイドチェーンとXRP Ledger _メインチェーン_（通常はMainnetですが、テスト用に[Testnet or Devnet](parallel-networks.html)にすることもできます）の間で、価値を効率的に移動させることができます。フェデレーションサイドチェーンは、公開メインネットのスピード、効率、スループットを損なうことなく動作します。
|
||||
|
||||
フェデレーションサイドチェーンにより、開発者はXRP Ledger技術の基盤を使って新機能や革新的なアプリケーションを立ち上げることができます。サイドチェーンは、特定のユースケースやプロジェクトのニーズに合わせてXRP Ledgerのプロトコルをカスタマイズし、独自のブロックチェーンとして運用することができます。いくつかの例をご紹介します。
|
||||
|
||||
* Ethereum Virtual Machine (EVM)、Web Assembly、またはMove VMと互換性のあるエンジンを搭載した、スマートコントラクトレイヤーの構築。例えば、[smart sidechain with Hooks](https://hooks-testnet.xrpl-labs.com/)を有効にする等。
|
||||
* 台帳の種類や取引ルールをカスタマイズした独自のアルゴリズムでのステーブルコインの構築。
|
||||
* Mainnetの[分散型取引所](decentralized-exchange.html)で取引することが可能な資産を持つ、許可制またはほぼ無許可、中央集権型または大部分が分散型の台帳の構築。
|
||||
|
||||
## フェデレーションサイドチェーンのしくみ
|
||||
|
||||
サイドチェーンは、独自のコンセンサス・アルゴリズムや取引の種類・ルールを持つ独立した台帳です。各サイドチェーンは独自のサーバーセット(バリデータを含む)によって運営されており、サイドチェーン上の取引についてはMainnet上のバリデータに依存しません。
|
||||
|
||||
各サイドチェーンには、サイドチェーン上とメインチェーン上の2つのドアアカウントがあり、サイドチェーン上のフェデレータが管理しています。フェデレータは、この両方のドアアカウントとの間のトランザクションを監視します。
|
||||
|
||||
サイドチェーンには、両ネットワークのドア・アカウントを共同で管理する _フェデレータ_ がおり、[マルチサイン](multi-signing.html)を用いて、フェデレータの80%が取引を承認しなければなりません。多くの場合、フェデレータはサイドチェーンの信頼できる検証者でもあるべきです。。
|
||||
|
||||
ドアアカウントがサイドチェーンまたはメインチェーンのいずれかでトランザクションを受け取ると、フェデレータは他のチェーンでミラートランザクションを作成します。(例えば、メインチェーンの _ドアアカウントにXRPを送信_ した場合、フェデレータはサイドチェーンのドアアカウントからXRPを _目的の受信者に送信_ するために、サイドチェーンでトランザクションを作成します) フェデレータはそのトランザクションに署名し、お互いにブロードキャストします。同時に、フェデレータは他のフェデレータからの署名付きトランザクションをリッスンし、それを収集します。
|
||||
|
||||
フェデレータの80％がトランザクションに署名したら、それを適宜サイドチェーンまたはメインチェーンに提出します。こうすることで、メインチェーンのドアアカウントが持つ資産をサイドチェーンの他の人に割り当てたり、サイドチェーンのドアアカウントが受け取る資産をメインチェーンの他の人に送ったりすることができます。
|
||||
|
||||
サイドチェーン内の取引は、サイドチェーン上のサーバーからは見えません。
|
||||
|
||||
|
||||
## 用語解説
|
||||
|
||||
_サイドチェーン_: XRP Ledgerのサイドチェーンとは、XRP Ledgerの技術をベースにした別のブロックチェーンのことです。_フェデレーター_ サイドチェーンは、メインチェーンからサイドチェーンへの資産移転の手段を提供します。サイドチェーンは、XRP Ledgerのプロトコルの完全なコピーを使用することもできますし、[コンセンサス・アルゴリズム](consensus.html)、[トランザクション・タイプ](transaction-types.html)、その他のルールを含む変更を加えることもできます。
|
||||
|
||||
_フェデレーター_: サイドチェーン上のサーバーで、メインチェーンとサイドチェーンの両方のトランザクションのトリガーをリッスンします。各フェデレーターは、トランザクションの署名に使用される署名鍵を持っています。トランザクションを送信するには、フェデレータの定足数による署名が必要です。フェデレータは、有効なレスポンス・トランザクションの作成と署名、他のフェデレータからの署名の収集、メイン・チェーンとサイド・チェーンへのトランザクションの送信に責任を負います。
|
||||
|
||||
_メインチェーン_: 資産が生まれるブロックチェーンで、サイドチェーンで使用されている間、資産が保持される場所。ほとんどのサイドチェーンでは、メインチェーンはXRP Ledger Mainnet、Testnet、またはDevnetとなっています。
|
||||
|
||||
_サイドチェーン_: 一部の資産がメインチェーンに裏付けられているカスタムブロックチェーンです。代理資産はサイドチェーンで発行され、同等の資産はメインチェーンのドアアカウントで保有されます。サイドチェーンはメインチェーンとは別の履歴、ルール、バリデーターを持ちます。サイドチェーン上の代理資産は、メインチェーンに送り返され、フェデレータの管理下からロックを解除することができます。
|
||||
|
||||
_ドアアカウント_: フェデレータが管理するアカウントです。ドアアカウントは、メインチェーン上とサイドチェーン上の2つがあります。クロスチェーンの取引は、ユーザーがドアアカウントにアセットを送ることで始まります。メインチェーンからサイドチェーンへの取引では、メインチェーンのドアアカウントの残高が増加し、サイドチェーンのドアアカウントの残高が減少します。ドアと呼ばれるのは、あるチェーンから別のチェーンへと資産を移動させるための仕組みだからです。
|
||||
|
||||
_トリガー トランザクション_: フェデレータが新たな応答トランザクションに署名して提出するプロセスを開始するきっかけとなるトランザクションのこと。例えば、メインチェーンのドアアカウントにXRPを送ることは、サイドチェーン上でフェデレータに新しいトランザクションを提出させるトリガーとなるトランザクションです。
|
||||
|
||||
_レスポンス トランザクション_: トリガーとなるトランザクションに反応してフェデレータが提出するトランザクション。ほとんどの場合、レスポンス・トランザクションはトリガー・トランザクションと反対側のチェーンで発生する。ただし、失敗したトランザクションを処理するためのいくつかの例外があります。
|
||||
|
||||
|
||||
## フェデレーションサイドチェーンのセットアップ方法
|
||||
|
||||
フェデレーションサイドチェーンは現在開発者プレビューとして提供されているため、サイドチェーンの可能性を実験的に探ることができます。メインチェーンネットワーク内の[サーバー](xrpl-servers.html)のバージョンが1.8.0以上であれば、サイドチェーンをXRP Ledger Testnet、Devnet、Mainnetに接続することができます。
|
||||
|
||||
**注意:** サイドチェーンをXRP Ledger Mainnetに接続することで、少量の開発やテストを行うことができますが、フェデレーションサイドチェーンがリリースされるまでは、本番環境での使用はお勧めできません。
|
||||
|
||||
サイドチェーンの設定には、次のような大まかなステップがあります。
|
||||
|
||||
1. rippled`のソースコードをクローンして、`sidechain`ブランチをチェックアウトします。https://github.com/ripple/rippled/tree/sidechain。
|
||||
2. サイドチェーンのソースコードをカスタマイズします。例えば、カスタムの[トランザクションタイプ](transaction-types.html)を書きたいと思うかもしれません。 これは重要で簡単ではない作業であることに注意してください。
|
||||
3. 各サイドチェーン・フェデレーターにはそれぞれ設定ファイルがあり、以下の情報を含むように更新する必要があります。
|
||||
- `[sidechain]` 節 - 署名鍵、メインチェーンアカウント、リッスンするメインチェーンアドレス（IPとポート）などの詳細を追加します。
|
||||
`[sidechain_assets]` 節 - クロスチェーン取引に使用できる資産（XRPまたは[発行されたトークン](issued-currencies.html)）、資産の交換レート、デフォルトになる可能性のある取引を阻止するためのオプションの返金ペナルティを定義します。
|
||||
- [sidechain_federators] 節 - 署名に使用されるフェデレータ公開鍵のリスト。このリストは、サイドチェーン上のすべてのフェデレータに共通です。
|
||||
4. クロスチェーン取引を可能にするため、ドアアカウントを設定する。これには（両方のチェーンで）以下の手順が必要です。
|
||||
- ドアアカウントの作成と資金調達
|
||||
- ドアアカウントの[署名者リストの設定](set-up-multi-signing.html)
|
||||
- エラー処理のためにの3つの[チケット](tickets.html)の作成
|
||||
- そして最後に、フェデレータがドアアカウントを共同で管理するようにするためのドアアカウントの[マスターキーペアの無効化](disable-master-key-pair.html)
|
||||
|
||||
なお、この最後のステップは、これまでのステップが正常に完了した後に実行することが重要です。
|
||||
|
||||
|
||||
_サイドチェーン ローンチキット_ は、フェデレーションサイドチェーンの設定を簡素化するコマンドラインツールで、ローカルマシン上でサイドチェーンを素早く立ち上げるのに使用できます。また、ローンチキットは、サイドチェーンとの対話を可能にするインタラクティブなサイドチェーンシェルをインストールします。
|
||||
|
||||
[サイドチェーン ローンチキット >](https://github.com/xpring-eng/sidechain-launch-kit/blob/main/README.md)
|
||||
|
||||
|
||||
## 関連項目
|
||||
|
||||
- **概念:**
|
||||
- [フェデーレーションサイドチェーン ビデオ](https://www.youtube.com/embed/NhH4LM8NxgY)
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -1,48 +0,0 @@
|
||||
---
|
||||
html: fee-voting.html
|
||||
parent: consensus-network.html
|
||||
blurb: トランザクションコストと必要準備金の変更投票について。
|
||||
labels:
|
||||
- 手数料
|
||||
- XRP
|
||||
---
|
||||
# 手数料投票
|
||||
|
||||
バリデータは、基本の[トランザクションコスト](transaction-cost.html)と[必要準備金](reserves.html)の変更について投票できます。バリデータの構成の設定がネットワークの現在の設定と異なる場合、バリデータはその設定をネットワークに定期的に公開します。定数のバリデータが変更に合意すると、変更を適用できるようになり、以後この変更が有効になります。バリデータはさまざまな理由から（特にXRPの価値の長期的な変化に適応するために）、この処理を行います。
|
||||
|
||||
[`rippled`バリデータ](run-rippled-as-a-validator.html)のオペレーターは、`rippled.cfg`ファイルの`[voting]`スタンザでトランザクションコストと必要準備金の設定を指定できます。
|
||||
|
||||
**注意:** 信頼できるバリデータの合意により不十分な必要準備金が採用された場合、XRP Ledgerピアツーピアネットワークがサービス拒否（DoS）攻撃を受ける可能性があります。
|
||||
|
||||
設定できるパラメーターは次の通りです。
|
||||
|
||||
| パラメーター | 説明 | 推奨される値 |
|
||||
|-----------|-------------|-------------------|
|
||||
| `reference_fee` | リファレンストランザクション（最も安価なトランザクション）を送信するときに消却する必要があるXRPの額（ _drop_ 単位）。（1 XRP = 100万drop）実際のトランザクションコストはこの値の数倍であり、個々のサーバーの負荷に基づいて動的に調整されます。 | `10` （0.00001 XRP） |
|
||||
| `account_reserve` | アカウントの準備金に必要なXRPの最小額（ _drop_ 単位）。これは、レジャーの新しいアカウントへの資金供給のために送金できる最小額です。 | `10000000` （10 XRP） |
|
||||
| `owner_reserve` | アドレスがレジャーで所有するオブジェクト _ごと_ に必要なXRPの額（ _drop_ 単位）。 | `2000000` （2 XRP） |
|
||||
|
||||
## 投票プロセス
|
||||
|
||||
256番目の各レジャーは「フラグ」レジャーと呼ばれます。（フラグレジャーは`ledger_index` [modulo](https://en.wikipedia.org/wiki/Modulo_operation) `256`が`0`になるように定義されています。）フラグレジャーの直前のレジャーでは、アカウント準備金またはトランザクションコストの設定が現行のネットワーク設定と異なる各バリデータは、そのレジャー検証とともに「投票」メッセージを配信し、バリデータが希望する値を示します。
|
||||
|
||||
フラグレジャー自体では何も起こりませんが、バリデータは信頼する他のバリデータからの投票を受信して記録します。
|
||||
|
||||
他のバリデータの投票を集計した後、各バリデータは自身の設定と信頼する過半数のバリデータの設定の間で妥協点を探ります。（たとえば、あるバリデータが最小トランザクションコストを10から100に引き上げることを望む一方で、ほとんどのバリデータは10から20に引き上げることを望んでいる場合、そのバリデータは当該のコストを20に引き上げることにします。ただし、そのバリデータは10未満の値または100を超える値にすることはありません。）妥協できる場合、バリデータはフラグレジャーの直後のレジャーに対する提案に[SetFee疑似トランザクション](setfee.html)を挿入します。同じ変更を求める他のバリデータは、同じレジャーに対する各自の提案に同じSetFee疑似トランザクションを挿入します。（設定が既存のネットワーク設定と一致している場合、バリデータは何も行いません。）SetFee疑似トランザクションがコンセンサスプロセスを通過し、検証済みレジャーに追加される場合、SetFee疑似トランザクションで設定された新しいトランザクションコストと準備金の設定がその次のレジャーから有効になります。
|
||||
|
||||
まとめ:
|
||||
|
||||
* **フラグレジャー-1**: バリデータが投票を送信します。
|
||||
* **フラグレジャー**: バリデータが投票を集計し、どのSetFeeの内容を含めるか決定します（存在する場合）。
|
||||
* **フラグレジャー+1**: バリデータは、SetFee疑似トランザクションを各自の提案レジャーに挿入します。
|
||||
* **フラグレジャー+2**: SetFee疑似トランザクションがコンセンサスに達すると、新しい設定が有効になります。
|
||||
|
||||
## 手数料の最大値
|
||||
|
||||
手数料の最大可能値は、[FeeSettingsレジャーオブジェクト](feesettings.html)に保管されている内部データ型により制限されます。これらの値は次のとおりです。
|
||||
|
||||
| パラメーター | 最大値（drop） | 最大値（XRP）
|
||||
|-----------|-----------------------|----|
|
||||
| `reference_fee` | 2**64 | （これまでに存在したXRP総額よりも大きい） |
|
||||
| `account_reserve` | 2^32 drop | 約4294 XRP |
|
||||
| `owner_reserve` | 2^32 drop | 約4294 XRP |
|
||||
@@ -1,157 +0,0 @@
|
||||
---
|
||||
html: invariant-checking.html
|
||||
parent: consensus-network.html
|
||||
blurb: 不変性チェックとは何か、なぜ存在するのか、どのように機能するのか、どのような不変性チェックが有効なのかを理解することができます。
|
||||
labels:
|
||||
- ブロックチェーン
|
||||
- セキュリティ
|
||||
---
|
||||
# 不変性チェック
|
||||
|
||||
不変性チェックは、XRP Ledgerの安全機能です。これは、通常のトランザクション処理とは別に、すべての取引において特定の「不変量」が真であることを保証する一連のチェックで構成されています。
|
||||
|
||||
多くの安全機能がそうであるように、私たちは不変性チェックが実際に何もする必要がないことを望んでいます。しかし、XRP Ledger の不変量は XRP Ledger のトランザクション処理に対するハードリミットを定義しているため、それを理解することは有用であり、万が一不変量チェックに違反したためにトランザクションが失敗した場合に問題を認識するために有用です。
|
||||
|
||||
不変性はトリガーされるべきではありませんが、まだ発見されていない、あるいは作成されてもいないバグからXRP Ledgerの整合性を確保するものです。
|
||||
|
||||
|
||||
## なぜ存在するのか
|
||||
|
||||
- XRP Ledgerのソースコードは複雑かつ膨大であり、コードが誤って実行される可能性が高いです。
|
||||
- トランザクションを誤って実行した場合のコストは高く、どのような基準でも許容されるものではありません。
|
||||
|
||||
具体的には、不正なトランザクションの実行により、無効または破損したデータが作成され、後にネットワーク上のサーバーを「動作不可能」な状態にすることで一貫してクラッシュさせ、ネットワーク全体を停止させる可能性があります。
|
||||
|
||||
不正なトランザクションの処理は、XRP Ledgerの信頼という価値を損なうことになリマス。不変性チェックは、信頼性という機能を付加するため、XRP Ledger 全体に価値を提供します。
|
||||
|
||||
|
||||
|
||||
## 仕組み
|
||||
|
||||
不変性チェッカーは、各トランザクションの後にリアルタイムで自動的に実行される第2層のコードです。トランザクションの結果がレジャーにコミットされる前に、不変性チェッカーはそれらの変更が正しいかどうかを検証します。もしトランザクションの結果がXRP Ledgerの厳格なルールに沿わない場合、不変性チェッカーはそのトランザクションを拒否します。このように拒否されたトランザクションは結果コード `tecINVARIANT_FAILED` を持ち、何の効果もなくレジャーに含まれます。
|
||||
|
||||
トランザクションを `tec` クラスのコードでレジャーに含めるには、何らかの最小限の処理が必要です。この最小限の処理でも不変条件に沿わない場合、トランザクションは `tefINVARIANT_FAILED` というコードで失敗し、レジャーには一切含まれません。
|
||||
|
||||
|
||||
## 有効な不変条件
|
||||
|
||||
XRP Ledgerは、各トランザクションについて、以下のすべての不変条件をチェックします。
|
||||
|
||||
[[ソース]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L92 "ソース")
|
||||
|
||||
- [トランザクション手数料チェック](#トランザクション手数料チェック)
|
||||
|
||||
[[ソース]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L118 "ソース")
|
||||
|
||||
- [XRPは作成されません](#xrpは作成されません)
|
||||
|
||||
[[ソース]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L146 "ソース")
|
||||
|
||||
- [アカウントルートが削除されていない](#アカウントルートが削除されていない)
|
||||
|
||||
[[ソース]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L173 "ソース")
|
||||
|
||||
- [XRPの残高確認](#xrpの残高確認)
|
||||
|
||||
[[ソース]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L197 "ソース")
|
||||
|
||||
- [レジャーエントリ形式の一致](#レジャーエントリ形式の一致)
|
||||
|
||||
[[ソース]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L224 "ソース")
|
||||
|
||||
- [XRPのトラストラインはありません](#xrpのトラストラインはありません)
|
||||
|
||||
[[ソース]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L251 "ソース")
|
||||
|
||||
- [不正なオファーでない](#不正なオファーでない)
|
||||
|
||||
[[ソース]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L275 "ソース")
|
||||
|
||||
- [0のエスクローでない](#0のエスクローでない)
|
||||
|
||||
[[ソース]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L300 "ソース")
|
||||
|
||||
- [有効な新規アカウントルート](#有効な新規アカウントルート)
|
||||
|
||||
|
||||
### トランザクション手数料チェック
|
||||
|
||||
- **不変条件:**
|
||||
- [トランザクションコスト](transaction-cost.html)の金額は決してマイナスになってはならず、またトランザクションで指定されたコストより大きくなってはいけません。
|
||||
|
||||
|
||||
### XRPは作成されません
|
||||
|
||||
- **不変条件:**
|
||||
- トランザクションはXRPを生成してはならず、XRPを破棄するのみです[トランザクションコスト](transaction-cost.html)。
|
||||
|
||||
|
||||
### アカウントルートが削除されていない
|
||||
|
||||
- **不変条件:**
|
||||
- [アカウント](accounts.html)は、[AccountDeleteトランザクション][]によってのみレジャーから削除することができます。
|
||||
- AccountDelete が成功すると、常にちょうど1つのアカウントが削除されます。
|
||||
|
||||
|
||||
### XRPの残高確認
|
||||
|
||||
- **不変条件:**
|
||||
- アカウントのXRP残高はXRPの形式である必要があり、0未満または1000億XRPを超えることはできません。
|
||||
|
||||
|
||||
### レジャーエントリ形式の一致
|
||||
|
||||
- **不変条件:**
|
||||
- 変更されたレジャーの項目は形式が一致し、追加された項目は[有効なタイプ](ledger-object-types.html)である必要があります。
|
||||
|
||||
|
||||
### XRPのトラストラインはありません
|
||||
|
||||
- **不変条件:**
|
||||
- XRPを使用した[トラストライン](trust-lines-and-issuing.html)は作成できません。
|
||||
|
||||
|
||||
### 不正なオファーでない
|
||||
|
||||
- **不変条件:**
|
||||
- [オファー](offer.html)は負でない金額でなければならず、XRP同士であってはいけません。
|
||||
|
||||
|
||||
### 0のエスクローでない
|
||||
|
||||
- **不変条件:**
|
||||
- [エスクロー](escrow-object.html)エントリーは、0XRP以上1000億XRP未満を保有している必要があります。
|
||||
|
||||
|
||||
### 有効な新規アカウントルート
|
||||
|
||||
- **不変条件:**
|
||||
- 新しい[アカウントルート](accountroot.html)は、支払いの結果でなければなりません。
|
||||
- 新しいアカウントルートは、正しい開始[シーケンス](basic-data-types.html#アカウントシーケンス)を持たなければなりません。
|
||||
- 1つのトランザクションで複数の新しい[アカウント](accounts.html)を作成してはいけません。
|
||||
|
||||
|
||||
## 関連項目
|
||||
|
||||
- **ブログ:**
|
||||
- [レジャーの保護: 不変性チェック](https://xrpl.org/blog/2017/invariant-checking.html)
|
||||
|
||||
- **リポジトリ:**
|
||||
- [Invariant Check.h](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h)
|
||||
- [Invariant Check.cpp](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.cpp)
|
||||
- [System Parameters](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/SystemParameters.h#L43)
|
||||
- [XRP Amount](https://github.com/ripple/rippled/blob/develop/src/ripple/basics/XRPAmount.h#L244)
|
||||
- [Ledger Formats](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/protocol/LedgerFormats.h#L36-L94)
|
||||
|
||||
|
||||
- **その他:**
|
||||
- [Authorized Trust Lines](authorized-trust-lines.html)
|
||||
- [XRPの特性](xrp.html#xrpの特性)
|
||||
- [トランザクションの残高変化の計算](https://xrpl.org/blog/2015/calculating-balance-changes-for-a-transaction.html#calculating-balance-changes-for-a-transaction)
|
||||
|
||||
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
@@ -1,185 +0,0 @@
|
||||
---
|
||||
html: negative-unl.html
|
||||
parent: consensus-network.html
|
||||
blurb: ネガティブUNLが部分的な停止時に台帳の耐障害性を向上させることを理解する。
|
||||
labels:
|
||||
- ブロックチェーン
|
||||
---
|
||||
# ネガティブUNL
|
||||
|
||||
_([NegativeUNL Amendment](known-amendments.html#negativeunl)が必要です。)_
|
||||
|
||||
ネガティブUNLは、XRPレジャーの[コンセンサスプロトコル](consensus.html)の機能で、バリデータの部分的な停止中にネットワークの前進を可能にする _liveness_ を向上させるものです。ネガティブUNLを使用すると、サーバーは現在オンラインかつ稼働中のバリデータに基づいて有効なUNLを調整するため、信頼できるバリデータが複数オフラインの場合でも、新しい [レジャーバージョン](ledgers.html) を _validated_ と宣言することができるようになるのです。
|
||||
|
||||
ネガティブUNLは、部分的な停止中に結果を確定するネットワークの能力を向上させる以外、ネットワークのトランザクション処理方法やトランザクションの結果に影響を与えることはありません。
|
||||
|
||||
## 背景
|
||||
|
||||
XRPレジャープロトコルの各サーバーは、UNL（Unique Node List）と呼ばれる、共謀しないよう信頼できるバリデータのリストを持ち、各サーバーは、信頼できるバリデータが十分に新しいレジャーバージョンに合意したときのコンセンサスに基づいて、レジャーバージョンの検証を独自に決定しています。(デフォルトの構成では、リップル社が十分にユニークで信頼性が高く、独立性が高いと考えるバリデータからなる、リップル社が署名した推奨UNLを使用しています)。標準的な定足数要件は、信頼できるバリデータの少なくとも80%が合意することである。
|
||||
|
||||
信頼できるバリデータの20%以上がオフラインになるか、ネットワークの残りの部分と通信できなくなると、ネットワークは定足数に達しないため、新しいレジャーの検証を停止する。これは、取引の結果が確定した後に変更されないようにするための設計上の選択である。このような状況では、残りのサーバーはまだオンラインであり、過去および暫定的なトランザクションデータを提供できるが、新しいトランザクションの最終的で不変の結果を確認することはできない。
|
||||
|
||||
しかしこれは、広く信頼されているバリデータがいくつかオフラインになった場合、ネットワークが前進しなくなる可能性があることを意味する。2020-10-06現在、リップル社が推奨するUNLには34人のバリデータがいるので、そのうち7人以上がオフラインになると、ネットワークの前進が止まってしまうことになります。さらに、1人または2人のバリデータが長期間オフラインになると、ネットワークは残りのバリデータ間の不一致の余地が少なくなり、コンセンサスの達成に時間がかかる可能性があります。
|
||||
|
||||
## 要約
|
||||
|
||||
ハードウェアのメンテナンス、ソフトウェアのアップグレード、インターネット接続の問題、標的型攻撃、人為的ミス、ハードウェアの故障、自然災害などの外部環境など、多くの原因でバリデータは一時的に利用できなくなる可能性があるため、多様なバリデータのセットで100%の稼働時間を維持を期待することは合理的ではありません。
|
||||
|
||||
「ネガティブUNL」とは、**オフラインまたは故障していると思われる信頼できる バリデータのリスト**であり、残存バリデータの総意として宣言されるものである。ネガティブUNLに含まれるバリデータは、新しいレジャーのバージョンがコンセンサスを得たかどうか を判断する際には無視される。
|
||||
|
||||
ネガティブUNL上のバリデータがオンラインに復帰し、一貫性のある検証投票を送信すると、 残りのバリデータはしばらくしてそのバリデータをネガティブUNLから削除します。
|
||||
|
||||
バリデータが一度に1つか2つオフラインになった場合、残りのバリデータはネガティブUNLを使用して、徐々に有効UNLを調整し、ネットワークが定足数を達成するのに _オンライン_ バリデータの80%しか必要としないようにすることができる。ネットワークが分断されるのを防ぐため、定足数はバリデータ _全体_ の60%以上というハードな最低値を持つ。
|
||||
|
||||
20%以上のバリデータが突然一度にオフラインになった場合、残りのサーバーは新しいレジャーを検証するのに必要な定足数を達成できないため、新しいレジャーを検証することができない。しかし、そのようなサーバーでも、コンセンサスラウンドを重ねることで暫定的な前進は可能である。時間が経つにつれて、残りのバリデータは暫定的なレジャーにネガティブUNLの変更を適用し、有効なUNLを調整し続ける。最終的に、この状況が続けば、ネットワークは暫定的なレジャーのバージョンから調整後のネガティブUNLを使用して、レジャーの検証を完全に再開することが可能である。
|
||||
スタンドアロンモードでは、サーバーはコンセンサスを使用しないので、ネガティブUNLは[スタンドアロンモード](rippled-server-modes.html)に影響を及ぼさない。
|
||||
|
||||
|
||||
## ネガティブUNLをテストに使用できるようにする
|
||||
|
||||
ネガティブUNL機能は現在[Devnet](parallel-networks.html)でテストすることが可能である。ネガティブUNL機能をテストするには、[XRPL Altnetへのrippledの接続](connect-your-rippled-to-the-xrp-test-net.html) にあるように `rippled.cfg` ファイルに `[features]` 節 を追加したり変更したりすることで可能です。
|
||||
|
||||
|
||||
|
||||
## 仕組み
|
||||
|
||||
ネガティブUNLは[コンセンサスプロセス](consensus.html) と密接に関連し、不利な状況下でもネットワークの継続性と信頼性を維持できるように安全策をとって設計されたものである。すべての信頼できるバリデータが正常に動作している場合、ネガティブUNLは使用されず、何の効果もない。一部のバリデータがオフラインまたは同期していないように見えるとき、ネガティブUNLルールは有効になる。
|
||||
|
||||
ネガティブUNLは意図的にゆっくりとした速度で変化するように設計されており、あるバージョンのレジャーの合意形成プロセスにおいて、どのネガティブUNLを適用すべきかという時間ベースの不一致を回避するためである。
|
||||
|
||||
|
||||
### 信頼性評価
|
||||
|
||||
ネットワーク上の各サーバーは、共謀しないように信頼するバリデータのリストであるUNLを持っています。(デフォルトでは、サーバーの正確なUNLはリップル社が公表している推奨バリデータリストに基づいて暗黙的に設定されます)。各サーバーは、信頼できるバリデータの「信頼性」を1つの指標で追跡します。それは、直近256件のレジャーのうち、バリデータの検証投票がサーバーの考えるコンセンサスと一致した割合です。言い換えれば
|
||||
|
||||
> 信頼性 = V<sub>a</sub> ÷ 256
|
||||
|
||||
V<sub>a</sub>は、サーバー側のコンセンサス見解と一致した過去256のレジャーに対して、1人のバリデータから受け取った検証票の総数である。
|
||||
|
||||
この信頼性指標は、バリデータの可用性 _及び_ バリデータの挙動を測定するものである。バリデータがネットワークの他の部分と同期しており、採点サーバと同じプロトコル規則に 従っている場合、そのバリデータの信頼性スコアは高くなるはずである。バリデータの信頼性スコアは、以下のような理由で低下することがある。
|
||||
|
||||
- バリデータ間のネットワーク接続が悪いため、バリデータの検証票がサーバーに届かない。
|
||||
- バリデータが動作を停止したり、過負荷になっている。
|
||||
- 様々な理由により、バリデータはサーバと同じプロトコルルールに従わない。可能性としては、設定ミス、ソフトウェアのバグ、意図的に[異なるネットワーク](parallel-networks.html)に従っている、または悪意ある行動などが考えられます。
|
||||
|
||||
バリデータの信頼性が **50%** 未満である場合、そのバリデータはネガティブUNLに追加される候補である。ネガティブUNLから削除するには、バリデータの信頼性が **80%** 以上でなければならない。
|
||||
|
||||
バリデータを含む各サーバーは、信頼できるバリデータ全員について独自に信頼性スコアを算出している。あるバリデータの信頼性について、サーバーが異なると結論が異なることがある。それは、そのバリデータの投票が一方のサーバーに届いて他方のサーバーに届かなかったり、特定のレジャーについて意見が異なることが多かったり少なかったりするためである。あるバリデータをネガティブUNLに追加または削除するには、信頼できるバリデータの総意として、あるバリデータが信頼性の閾値を超えるか下回るかに合意する必要がある。
|
||||
|
||||
**ヒント:** バリデータは自分自身の信頼性を追跡するが、自分自身をネガティブUNLに加えることは提案しない。バリデータの信頼性測定は、バリデータの投票がネットワークを通じて どの程度うまく伝わるかを考慮できないので、外部のサーバーからの測定値よりも 信頼性が低い。
|
||||
|
||||
|
||||
|
||||
### ネガティブUNLの変更
|
||||
|
||||
レジャーバージョンが256で均等に割り切れる場合、_フラグレジャー_ とみなされます。ネガティブUNLはフラグレジャーでのみ変更可能です。(フラグレジャーは、XRPレジャーメインネットで約15分に1回発生します。トランザクション量の少ないテストネットワークでは、もっと低頻度な場合があります)
|
||||
|
||||
各フラグレジャーは、以下の全ての変更が適用されます。
|
||||
|
||||
1. 前のフラグレジャーで予定されていたネガティブUNLの変更は、次のレジャーバージョンから有効となる。このフラグレジャーの検証のための合意プロセスそのものは、予定されていた変更を利用しない。
|
||||
|
||||
**注記:** これは、[トランザクション](transaction-basics.html)や[疑似トランザクション](pseudo-transaction-types.html)を行わずにレジャーの状態データを変更する唯一の機会です。
|
||||
|
||||
2. ネガティブUNLが満杯でない場合、各サーバーは信頼度50%未満のバリデータの中から、**最大1つ**のバリデータをネガティブUNLに追加することを提案する。
|
||||
3. ネガティブUNLが空でない場合、各サーバーはネガティブUNLから **最大1つ**のバリデータを削除することを提案する。サーバーがバリデータをネガティブUNLから削除することを提案できる理由は2つある。
|
||||
- バリデータの信頼度が80%を超えている。
|
||||
- 自身のUNLにそのバリデーターを持たない。(バリデータが永久に停止した場合、このルールは、サーバーの設定済み UNLからバリデータが削除された後に、オンレジャーのネガティブUNLからバリデータが 削除されることを確実にする)。
|
||||
4. ネガティブUNLの変更案がコンセンサスに達した場合、その変更は次のフラグレジャーから適用される予定である。この方法で最大1つの追加と1つの削除をスケジュールすることができる。
|
||||
|
||||
ネガティブUNLにバリデータを追加したり削除したりする提案は[UNLModify pseudo-transactions][]の形式を取る。それぞれの擬似トランザクションは他の[擬似トランザクション](pseudo-transaction-types.html)と同じように合意形成プロセスによって合意を得るか捨てられるかが決定される。言い換えると、あるバリデータがネガティブUNLに追加されたり削除されたりするためには、サーバーの総意として同じ変更を提案する必要がある。
|
||||
|
||||
ネガティブUNLの予定された有効な変更は、レジャーの状態データの中の[ネガティブUNLオブジェクト](negativeunl.html)に追跡される。
|
||||
|
||||
|
||||
### ネガティブUNLの制限
|
||||
|
||||
ネットワークが2つ以上のサブネットワークに分断されるのを防ぐために、ネガティブUNLは定足数要件をUNLエントリ全体の60%未満に減らすことができない。これを強制するために、サーバーはネガティブUNL上のバリデータ数がサーバーの設定済みUNL内のバリデータ数の25%(切り捨て)である場合、ネガティブUNLが "満杯 "になったと見なす。(この25%は、25%のバリデータが削除された場合、残りの75%のバリデータの 80%の合意は元の数の60%に等しいという計算に基づいている)。もしサーバーがネガティブUNLが一杯になったと判断した場合、ネガティブUNLへの新たな追加は提案されない。
|
||||
|
||||
|
||||
### 複数のバリデーター候補から選択する
|
||||
|
||||
信頼性の閾値に基づき、複数のバリデータがネガティブUNLに追加される候補となる可能性がある。一度に最大1つのバリデータをネガティブUNLに追加できるので、サーバーはどのバリデータを 追加するかを選択しなければならない。複数の候補がある場合、サーバーは以下のメカニズムでどの候補を提案するかを 選択する。
|
||||
|
||||
1. 親レジャーバージョンのレジャーハッシュを取得する。
|
||||
0. 各バリデータ候補の公開鍵を取得する。
|
||||
0. 候補のバリデータと親レジャーのハッシュの排他的論理和(XOR)を計算する。
|
||||
0. XOR演算の結果のうち、数値が最も小さいバリデータを提案する。
|
||||
|
||||
あるフラグレジャーのネガティブUNLから削除される候補が複数ある場合、サーバーは同じメカニズムでそれらの中から選択します。
|
||||
|
||||
このメカニズムには、いくつかの有用な特性があります。
|
||||
|
||||
- すべてのサーバーが容易に入手でき、かつ迅速に計算できる情報を使用する。
|
||||
- 信頼できるバリデータのスコアが多少異なっていても、ほとんどのサーバーは同じ候補を選択する。これは、どのバリデータの信頼度が「最低」なのか「最高」なのかについて、 サーバ間で見解の相違があったとしても同様である。これは、あるバリデータが信頼性の閾値より上か下かについて、各サーバが 意見を異にしている場合でさえも同様である。したがって、ネットワークは、どのバリデータを追加または削除するかについて、 合意が得られる可能性が高い。
|
||||
- レジャーバージョンごとに同じ結果が出るとは限りません。もしネガティブUNLへのある変更案が合意に至らなかったとしても、ネットワークは毎回その1つのバリデータの追加や削除を試みて失敗し続けることはない。ネットワークは、後のフラグ付きレジャーで別の候補をネガティブUNLに追加・削除することを試みることができる。
|
||||
|
||||
|
||||
### 検証のフィルタリング
|
||||
|
||||
[コンセンサスプロセスの検証ステップ](consensus.html#検証)では、親レジャーのネガティブUNLのバリデータを無効化します。各サーバーは無効化されたバリデータを取り除いた設定済みUNLからなる "有効UNL "を計算し、定足数を再計算します。(定足数は常に有効 UNL の 80% 以上、かつ設定 UNL の 60% 以上です)。無効化されたバリデータが検証票を送信した場合、サーバーは無効化されたバリデータの信頼性を計算するためにその票を追跡するが、あるバージョンのレジャーが合意に達したかどうかを判断するためにその票を使うことはありません。
|
||||
|
||||
**注記:** ネガティブUNLは、定足数を直接計算するのではなく、定足数の計算元となる信頼できるバリデータの合計を調整するものです。定足数はパーセンテージですが、投票数は整数であるため、信頼できるバリデータの合計を減らしても、定足数に達するために必要な投票数が変わるとは限りません。たとえば、総バリデータが15人である場合、80%はちょうど12人のバリデータである。これを14人に減らすと、80%は11.2人となり、定足数に達するには依然として12人の有効投票者が必要である。
|
||||
|
||||
ネガティブUNLは、提案されたトランザクションセットにどのトランザクションを含めるかを選択するなど、コンセンサスプロセスの他の部分には影響を与えない。これらのステップは常に設定されたUNLに依存し、その閾値は何人の信頼できるバリデータがコンセンサスラウンドに積極的に参加しているかに基づいている。ネガティブUNLにあるバリデータもコンセンサスプロセスに参加することができる。
|
||||
|
||||
### 例
|
||||
|
||||
次の例は、ネガティブUNLが合意形成プロセスにどのような影響を与えるかを示している。
|
||||
|
||||
1. サーバーのUNLが38人の信頼できるバリデータで構成されているとすると、80%の定足数は38人のうち少なくとも31人の信頼できるバリデータである。
|
||||
|
||||
{{ include_svg("img/negative-unl-01.svg", "Diagram: 通常の場合。ネガティブUNLは未使用、定足数は設定されたバリデータの80%である。") }}
|
||||
|
||||
2. MissingAとUnsteadyBという2人のバリデータがオフラインになったとする。(両者とも信頼度スコアは50%未満である。) レジャー _N_ の合意プロセスにおいて、残りのバリデータの多くがUnsteadyBをネガティブUNLに追加することを提案する。この動議は残りのバリデーターのうち少なくとも31人の定足数で可決され、 レジャー _N_はUnsteadyBを無効化する予定で有効になった。
|
||||
|
||||
{{ include_svg("img/negative-unl-02.svg", "Diagram: UnsteadyBは無効になる予定。") }}
|
||||
|
||||
|
||||
3. レジャー _N+1_ から _N+256_ については、コンセンサスプロセスをそのまま継続する。
|
||||
|
||||
4. 次のフラグレジャー _N+256_ では、UnsteadyBはレジャーの「予定」から「無効」リストへ自動的に移動する。また、MissingAがまだオフラインであるため、検証者の総意として、次のフラグレジャーでMissingAを無効化する予定とする。
|
||||
|
||||
{{ include_svg("img/negative-unl-04.svg", "UnsteadyBが無効化され、MissingAも無効化される予定。") }}
|
||||
|
||||
5. レジャー _N+257_ から _N+512_ について、定足数は37名中30名となった。
|
||||
|
||||
6. UnsteadyBがレジャー _N+270_ でオンラインに復帰。レジャー _N+270_ から _N+511_ に対してネットワークの他の部分と一致する検証票を送信し、信頼性スコアが80%以上となる。
|
||||
|
||||
{{ include_svg("img/negative-unl-06.svg", "Diagram: UnsteadyBがオンラインに戻るが、まだ無効化されている。") }}
|
||||
|
||||
7. 次のフラグレジャー _N+256_ では、予定通りMissingAが自動的に無効リストに移される。一方、UnsteadyBは信頼性スコアが向上したため、検証者の総意としてネガティブUNLから削除される予定である。
|
||||
|
||||
{{ include_svg("img/negative-unl-07.svg", "Diagram: MissingAを無効化し、UnsteadyBを再有効化する予定。") }}
|
||||
|
||||
8. レジャー _N+513_ から _N+768_ の場合、定足数は36人中29人である。MissingAがオフラインの間、UnsteadyBは安定的に検証結果を送り続ける。
|
||||
|
||||
9. フラグレジャー _N+768_ では、予定通りUnsteadyBが無効リストから自動的に削除されています。
|
||||
|
||||
{{ include_svg("img/negative-unl-09.svg", "Diagram: UnsteadyBを無効リストから削除。") }}
|
||||
|
||||
10. 最終的に、あなたはMissingAがおそらく戻ってこないと判断し、あなたのサーバーの設定されたUNLからそれを削除します。あなたのサーバーはそれ以降、各フラグレジャーからMissingAをネガティブUNLから削除することを提案し始める。
|
||||
|
||||
{{ include_svg("img/negative-unl-10.svg", "Diagram: MissingAを設定済みUNLから削除した後、ネガティブUNLからも削除することを提案する。 ") }}
|
||||
|
||||
11. バリデータ操作者が自分の設定したUNLからMissingAを削除すると、そのバリデータ操作者は ネガティブUNLからMissingAを削除するように投票する。十分な数のバリデータが投票した時点で、MissingAを削除する提案は合意に達し、MissingAはスケジュールされ、最終的にネガティブUNLから削除される。
|
||||
|
||||
{{ include_svg("img/negative-unl-11.svg", "Diagram: MissingAをネガティブUNLから削除。") }}
|
||||
|
||||
|
||||
### 関連項目
|
||||
|
||||
- **コンセンサス:**
|
||||
- [コンセンサスプロトコル](consensus.html)
|
||||
- **チュートリアル:**
|
||||
- [Testnetや別の並列ネットワークへ接続する](connect-your-rippled-to-the-xrp-test-net.html)
|
||||
- [バリデータとしての`rippled`の実行](run-rippled-as-a-validator.html)
|
||||
- **リファレンス:**
|
||||
- [negativeUNL オブジェクト](negativeunl.html)
|
||||
- [UNLModify pseudo-transaction][]
|
||||
- [ledger_entry メソッド][]
|
||||
- [consensus_info メソッド][]
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
@@ -1,53 +0,0 @@
|
||||
---
|
||||
html: parallel-networks.html
|
||||
parent: consensus-network.html
|
||||
blurb: テストネットワークおよび代替レジャーチェーンと本番環境のXRP Ledgerとの関係について説明します。
|
||||
labels:
|
||||
- ブロックチェーン
|
||||
---
|
||||
# 並列ネットワーク
|
||||
|
||||
XRP Ledgerにはピアツーピアの本番環境のネットワークが1つ存在し、XRP Ledger上で行われるすべての取引はその本番環境のネットワーク、すなわちMainnet内で発生します。
|
||||
|
||||
また、Rippleでは、XRPLコミュニティーのメンバーがMainnet上にあるものに影響を及ぼすことなくXRPLテクノロジーとやり取りできるように、TestnetとDevnetの2つの代替ネットワーク（AltNet）を提供しています。3つすべてのネットワークの詳細を以下に示します。
|
||||
|
||||
| ネットワーク | アップグレード頻度 | 説明 |
|
||||
|:--------|:----------------|:-------------------------------------------------|
|
||||
| Mainnet | 安定版リリース | [XRP Ledger](xrp-ledger-overview.html)。ピアツーピアサーバーのネットワーク機能を備えた分散型の暗号台帳であり、[XRP](xrp.html)の土台となるものです。 |
|
||||
| Testnet | 安定版リリース | XRP Ledger上に構築したソフトウェアのテスト環境として動作する「代替環境」のネットワーク。本番環境のXRP Ledgerユーザーに影響を及ぼすことも、本物の通貨をリスクにさらすこともありません。Testnetの[Amendmentのステータス](known-amendments.html)は、Mainnetを厳密に反映するようになっていますが、分散型システムが持つ予測不可能な性質により、タイミングにわずかな違いが生じることがあります。 |
|
||||
| Devnet | ベータ版リリース | 次期リリースのプレビュー。XRP Ledgerのコアソフトウェアへの不安定な変更がテストされます。このAltNetを使用すると、開発者はまだMainnetで有効になっていないXRPLの計画段階の新機能やAmendmentを操作したり学習したりすることができます。 |
|
||||
|
||||
TestnetとDevnetはそれぞれ独自にテスト用XRPを提供しています。このテスト用XRPは、XRP Ledgerの試用およびアプリケーション開発やインテグレーションに関心のある対象者に、Rippleが[無料で提供](xrp-testnet-faucet.html)するものです。テスト用XRPは、現実世界での価値はなく、ネットワークがリセットされると失われます。
|
||||
|
||||
**注意:** RippleはAltNetの安定性について一切保証しません。これらのネットワークは、サーバー構成、ネットワークトポロジー、ネットワークパフォーマンスのさまざまな特性をテストする目的でこれまで使用され、またこれからも同様に使用されます。
|
||||
|
||||
|
||||
## 並列ネットワークとコンセンサス
|
||||
|
||||
使用するネットワークを定義する`rippled`の設定はありません。その代わり、信頼するバリデータのコンセンサスに基づいてどのレジャーを正しいレジャーとして受け入れるかを把握します。`rippled`インスタンスからなる異なるコンセンサスグループが、同じグループの他のメンバーだけを信頼する場合、各グループは引き続き並列ネットワークとして機能します。悪意のあるコンピューターや不適切に動作するコンピューターが両方のネットワークに接続している場合でも、各ネットワークのメンバーが、定数設定を超えて別のネットワークのメンバーを信頼するように設定されていない限り、コンセンサスプロセスに混乱は生じません。
|
||||
|
||||
Rippleでは、TestnetとDevnetでメインサーバーを運用しています。[独自の`rippled`サーバーをTestnetに接続](connect-your-rippled-to-the-xrp-test-net.html)していただくことも可能です。TestnetとDevnetでは、多様で検閲耐性のあるバリデータのセットが使用されていません。そのため、RippleはTestnetやDevnetを定期的にリセットできます。
|
||||
|
||||
|
||||
## 関連項目
|
||||
|
||||
- **ツール:**
|
||||
- [XRP Testnet Faucet](xrp-test-net-faucet.html)
|
||||
- **コンセプト:**
|
||||
- [コンセンサスについて](intro-to-consensus.html)
|
||||
- [Amendment](amendments.html)
|
||||
- **チュートリアル:**
|
||||
- [XRP Testnetへの`rippled`の接続](connect-your-rippled-to-the-xrp-test-net.html)
|
||||
- [スタンドアロンモードでのrippledの使用](use-stand-alone-mode.html)
|
||||
- **リファレンス:**
|
||||
- [Server_infoメソッド][]
|
||||
- [Consensus_infoメソッド][]
|
||||
- [Validator_list_sitesメソッド][]
|
||||
- [Validatorsメソッド][]
|
||||
- [デーモンモードのオプション](commandline-usage.html#デーモンモードのオプション)
|
||||
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
@@ -1,155 +0,0 @@
|
||||
---
|
||||
html: transaction-malleability.html
|
||||
parent: consensus-network.html
|
||||
blurb: トランザクションが想定とは異なるハッシュを持つようにどのように変更される可能性があるか注意してください。
|
||||
labels:
|
||||
- セキュリティ
|
||||
- トランザクション送信
|
||||
---
|
||||
# トランザクション展性
|
||||
|
||||
署名後のトランザクションを、署名に使用されたキーを使用せずに変更できる場合、そのトランザクションには「展性がある」ことになります。XRP Ledgerでは、署名付きトランザクションの**機能性**は変更できませんが、場合によっては第三者がトランザクションの署名と識別用ハッシュを変更できる _可能性があります_ 。
|
||||
|
||||
展性のあるトランザクションは元のハッシュでのみ実行できると想定して、脆弱なソフトウェアが展性のあるトランザクションを送信した場合、トランザクションの状況を把握できなくなる可能性があります。最悪の場合、不正使用者がこの点を悪用して脆弱なシステムから資金を盗むことが可能です。
|
||||
|
||||
次の2つの状況は、トランザクション展性の問題につながる可能性があります。
|
||||
|
||||
1. デフォルトの署名アルゴリズム（ECDSAとsecp256k1曲線）を使用して署名されたトランザクションにtfFullyCanonicalSigフラグが指定されていない。
|
||||
|
||||
**[tfFullyCanonicalSigフラグ](transaction-common-fields.html#グローバルフラグ)を使用** して、トランザクションに展性がないことを保証します。[Ed25519キーで署名されている](cryptographic-keys.html#署名アルゴリズム)トランザクションはこの問題に対して脆弱ではありませんが、 _すべての_ トランザクションにこのフラグを使用しても **特に不都合はありません** 。
|
||||
|
||||
2. トランザクションが[マルチ署名済み](multi-signing.html)であり、署名の数が必要以上に多い場合。元々トランザクションに必要な数を上回る署名がされていなかった場合でも、権限のある署名者が追加の署名を提供すると、このトランザクションが展性を得ることがあります。
|
||||
|
||||
適切な運用セキュリティ対策を導入することで、このような問題を防ぐことができます。ガイドラインについては、[マルチ署名の展性の緩和対策](#マルチ署名の展性の緩和対策)を参照してください。
|
||||
|
||||
|
||||
## 背景
|
||||
|
||||
XRP Ledgerでは、以下の条件に該当しない場合にはトランザクションを実行できません。
|
||||
|
||||
- 署名自体を除く[トランザクションのすべてのフィールド](transaction-common-fields.html)に署名がなされている。
|
||||
- トランザクションの署名に使用されるキーペアが、[そのアカウントの代理としてトランザクションを送信することが承認されている](transaction-basics.html#トランザクションの承認)。
|
||||
- 署名は _正規_ であり、トランザクションの指示に一致している。
|
||||
|
||||
署名付きフィールドに変更を加えると、どれほど小さな変更であっても署名が無効となるため、署名自体を除き、トランザクションのいかなる部分にも展性が生じることはありません。ほとんどの場合、署名自体を変更すると常に署名が無効になりますが、以下で説明するような特定の例外があります。
|
||||
|
||||
署名はトランザクションの識別用ハッシュの計算に使用されるデータの1つであるため、展性のあるトランザクションを変更すると、ハッシュ値が変わります。
|
||||
|
||||
### 代替secp256k1署名
|
||||
|
||||
「正規」であるためには、ECDSAアルゴリズムとsecp256k1曲線（デフォルト）を使用して作成された署名が以下の要件を満たしている必要があります。
|
||||
|
||||
- 署名が適切な[DERエンコードデータ](https://en.wikipedia.org/wiki/X.690#DER_encoding)である必要があります。
|
||||
- 署名ではDERエンコードデータ外部に埋め込みバイトがあってはなりません。
|
||||
- 署名を構成する整数はマイナスであってはならず、またsecp256k1係数以下でなければなりません。
|
||||
|
||||
一般に、あらゆる標準ECDSA実装ではこれらの要件が自動的に処理されます。ただしsecp256k1では、展性を防ぐにはこれらの要件では不十分です。したがってXRP Ledgerでは、同様の問題がない「完全に正規である」署名という概念を採用しています。
|
||||
|
||||
ECDSA署名はRおよびSと呼ばれる2つの整数で構成されています。secp256k1係数はNと呼ばれ、すべてのsecp256k1署名の定数です。具体的にはNは値`0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141`です。署名`(R,S)`では、署名`(R, N-S)`（Sの位置にN-Sを使用）も有効です。
|
||||
|
||||
このように、 _完全に_ 正規である署名を使用する場合には、2つの有効な値のうちどちらを使用するかを選択し、もう一方が無効であることを宣言する必要があります。XRP Ledgerの作成者は、2つの有効な値（`S`と`N-S`）のいずれか _小さい方_ を任意に選択すると決めました。トランザクションが選択された（小さな）値`S`を使用し、正規トランザクションとなるためのすべての標準ルールに準拠している場合、このトランザクションは _完全に正規_ であるとみなされます。
|
||||
|
||||
完全に正規である署名の生成が確実に行われていなかった古いソフトウェアとの互換性を維持するため、XRP Ledgerは完全に正規ではないトランザクションも受け入れます。新しいユーザーを悪用から保護するため、XRP Ledgerではトランザクション向けに[**tfFullyCanonicalSig**](transaction-common-fields.html#グローバルフラグ)というフラグがあります。このフラグが設定されている場合、トランザクションが有効となるには _完全に正規_ の署名を使用する必要があります。
|
||||
|
||||
完全に正規であるECDSA署名を計算するには、SとN-Sを比較していずれが小さいかを見極めて、トランザクションの`Signature`フィールドにその値を使用する必要があります。
|
||||
|
||||
Rippleが公開しているすべてのXRP Ledgerソフトウェア（`rippled`およびripple-lib/xrpl.jsを含む）では、完全に正規である署名のみが生成されます。ユーザーの保護を強化するため、Rippleは、可能な限りデフォルトで**tfFullyCanonicalSig**フラグを有効にするようにコードを構成しています。XRP Ledgerソフトウェアのサードパーティ実装においても、完全に正規である署名だけを生成し、デフォルトでトランザクションのtfFullyCanonicalSigが有効にすることを強く推奨します。
|
||||
|
||||
次の2つの状況においては、RippleのXRP Ledgerの署名実装によってtfFullyCanonicalSigフラグが自動的に有効になりません。次の状況では、フラグを慎重に設定する必要があります。
|
||||
|
||||
- ユーザーがトランザクションの`Flags`フィールドを明示的に指定している場合。ビット単位のORを使用してtfFullyCanonicalSig _と_ その他の必要なすべてのフラグを適用します。
|
||||
- ユーザーがトランザクションにマルチ署名を提供する場合。マルチ署名の複数の参加者は _厳密に_ 同一のデータに署名する必要があるので、署名コードはtfFullyCanonicalSigフラグを追加するというトランザクションの指示を事前に処理しません。マルチ署名済みトランザクションでは、常にtfFullyCanonicalSigフラグを明示的に有効にしてください。
|
||||
|
||||
|
||||
### マルチ署名の展性
|
||||
|
||||
マルチ署名の明示的で重要な機能として、さまざまな設定によってトランザクションを有効にできるという機能があげられます。たとえば、5人の署名者のうち3人の署名者の署名によってトランザクションを承認できるようにアカウントを設定できます。ただしこの場合、有効なトランザクションにはいくつかのバリエーションが存在する可能性があり、識別用ハッシュは各バリエーションごとに異なります。
|
||||
|
||||
以下のケースはすべて、トランザクション展性の問題につながる可能性があります。
|
||||
|
||||
- トランザクションへの署名を1つ以上を削除しても、まだその定数を満たすのに十分な数の署名がある場合。第三者が署名を削除し、署名なしでトランザクションを再送信できる可能性があります。
|
||||
- すでに定数に達しているトランザクションに有効な署名を追加できる場合。このような署名を作成できるのは、送信側アカウントの権限のある署名者だけです。
|
||||
- 定数を維持しながら、あるトランザクションの署名を、別の有効な署名に置き換えることができる場合。このような署名を作成できるのは、送信側アカウントの権限のある署名者だけです。
|
||||
|
||||
権限のある署名者に意図的な悪意がない場合でも、混乱や不適切な調整が原因で、複数の署名者が同じトランザクションの異なる有効バージョンを送信することがあります。
|
||||
|
||||
#### マルチ署名の展性の緩和対策
|
||||
|
||||
**適切な運用セキュリティ対策を導入することで、このような問題を防ぐことができます。** 通常、以下のような適切な運用セキュリティ対策に従っていれば、マルチ署名でのトランザクション展性の問題を防ぐことができます。
|
||||
|
||||
- 必要な数以上の署名を収集しない。
|
||||
- 必要な数の署名を収集した後でトランザクションを作成する当事者を任命するか、または署名者が事前に定義された順序でトランザクション指示に署名して次に渡せるように「チェーン」を指定する。
|
||||
- マルチ署名リストに不要な署名者または信頼できない署名者を追加しない。これは、これらの署名者のキーに関連付けられている`weight`の値が、トランザクションの承認には不十分である場合にも該当する。
|
||||
- トランザクションが異なるハッシュまたは想定外の署名セットを使用して実行される可能性に対処できるよう備える。アカウントから送信されたトランザクションを注意深く監視する（[account_txメソッド][]などを使用）。
|
||||
- アカウントの`Sequence`番号を監視する（[account_infoメソッド][]などを使用）。この番号は、アカウントがトランザクションを正常に送信するたびに1ずつ増えますが、それ以外の状況で増えることはありません。番号が想定した番号と一致しない場合は、最近のトランザクションを調べてその原因を確認します。（展性のあるトランザクションの他にも、このような状況が発生することがあります。たとえばトランザクションを送信するように別のアプリケーションを設定する場合などです。不正使用者が秘密鍵にアクセスした可能性もあります。あるいは、アプリケーションでデータが失われ、送信済みのトランザクションが忘れられた可能性もあります。）
|
||||
- トランザクションを再度作成してマルチ署名済みにする場合は、目的の処理がまだ実行されていないことを手動で確認している場合を除き、`Sequence`番号を変更 _しないでください_ 。
|
||||
- 署名前にtfFullyCanonicalSigフラグが有効であることを確認する。
|
||||
|
||||
セキュリティ強化のため、上記のガイドラインにより何重もの保護対策が講じられます。
|
||||
|
||||
|
||||
## 展性のあるトランザクションを使用した悪用
|
||||
|
||||
XRP Ledgerとのインフターフェイスに使用するソフトウェアから展性のあるトランザクションが送信されると、不正使用者がソフトウェアをだましてトランザクションの最終結果を確認できなくし、（最悪の場合）同額の支払いを複数回送金させることが可能になります。
|
||||
|
||||
シングルシグネチャーを使用していて、tfFullyCanonicalSigフラグを常に有効にしている場合には、このような悪用に対し脆弱ではありません。マルチ署名を使用していて、署名者が必要な数を超える署名を提供する場合には脆弱になります。
|
||||
|
||||
### 悪用シナリオの流れ
|
||||
|
||||
脆弱なシステムを悪用するプロセスは、以下のような順で進みます。
|
||||
|
||||
1. 脆弱なシステムが、tfFullyCanonicalSigを有効にせずにトランザクションを生成し署名する。
|
||||
|
||||
トランザクションでtfFullyCanonicalSigフラグが有効に設定されない状況として以下の3つがあります。
|
||||
|
||||
- システムが`Flags`フィールドを明示的に指定し、このフィールドでtfFullyCanonicalSigビットが有効になっていない。
|
||||
- トランザクションがマルチ署名済みであり、tfFullyCanonicalSigフラグが明示的に有効にされていない。
|
||||
- システムでトランザクションのフィールドから`Flags`フィールドが省略されているが、署名時にtfFullyCanonicalSigを自動的に有効にしない非標準の実装が使用されている。
|
||||
|
||||
トランザクションがECDSAキーペアで署名されている場合、そのトランザクションは脆弱になります。マルチ署名済みの場合、トランザクションの署名に少なくとも1つのECDSAキーペアが使用される必要があります。
|
||||
|
||||
ほとんどの場合、脆弱なトランザクションには完全に正規である署名が使用されていますが、トランザクションが完全に正規ではない署名を使用していても、フラグはそのトランザクションが有効であると示します。また、限られた時間内に最終結果が判かるように、トランザクションで`LastLedgerSequence`が使用されていることもあります。
|
||||
|
||||
2. システムは脆弱なトランザクションの識別用ハッシュを確認し、そのハッシュをXRP Ledgerネットワークに送信し、検証済みレジャーバージョンにそのハッシュが記録されるのを監視し始めます。
|
||||
|
||||
3. 不正使用者は、トランザクションが確定する前にそのトランザクションがネットワークを通じて伝搬することを確認します。
|
||||
|
||||
4. 不正使用者が脆弱なトランザクションの代替署名を計算します。
|
||||
|
||||
異なるトランザクション指示の署名を作成する場合とは異なり、この場合は大量の計算処理は不要です。最初に署名を生成する場合よりもかなり短い時間で完了する可能性があります。
|
||||
|
||||
改ざんされた署名により、異なる識別用ハッシュが生成されます。（ネットワークに送信する前にハッシュを計算する必要はありませんが、ハッシュがあれば後でトランザクションのステータスを容易に確認できることを理解しています。）
|
||||
|
||||
5. 不正使用者が改ざんした（完全に正規ではない可能性のある）トランザクションをネットワークに送信します。
|
||||
|
||||
これにより、当初送信されたトランザクションと、不正使用者によって送信された改ざんバージョンが「競争」します。この2つのトランザクションが同時に記録されることはありません。いずれのトランザクションも有効ですが、`Sequence`番号をはじめ厳密に同一のトランザクションデータを含んでいるので、検証済みレジャーに記録できるのは常にいずれか1つになります。
|
||||
|
||||
ピアツーピアネットワークのサーバーは、どちらが「最初に到着した」トランザクションであるか、またはどちらが元の送信者が意図したトランザクションであるかを認識できません。ネットワーク接続での遅延やその他の偶発的な事象により、バリデータはコンセンサス提案をファイナライズする時点で、いずれかのトランザクションだけを認識する結果になる可能性があります。この場合、いずれかのトランザクションが「競争に勝った」ことになります。
|
||||
|
||||
もし不正使用者がピアツーピアネットワークで適切に接続しているいくつかのサーバーを乗っ取れば、これらのサーバーがバリデータとして信頼されていなくても、非正規トランザクションを確定できる確率を高めることができます。
|
||||
|
||||
脆弱なシステムからのトランザクションを唯一受信したサーバーを不正使用者が乗っ取った場合、不正使用者はネットワークの他の部分に配信されるバージョンを容易に制御できるようになります。
|
||||
|
||||
6. 不正ユーザーのトランザクションがコンセンサスに達し、検証済みレジャーに記録されます。
|
||||
|
||||
この時点でトランザクションは実行されており、このトランザクションを無効にすることはできません。その影響（XRPの送金など）は最終的です。本来のトランザクションは、その`Sequence`番号がすでに使用されているために有効ではなくなります。
|
||||
|
||||
XRP Ledgerでのトランザクションの影響は、本来のバージョンが実行された場合とまったく同じです。
|
||||
|
||||
7. 脆弱なシステムは、予期しているトランザクションハッシュを認識せず、トランザクションが実行されなかったという誤った結論に達します。
|
||||
|
||||
トランザクションに`LastLedgerSequence`フィールドが含まれている場合は、指定されたレジャーインデックスを経過した後でこの状況が発生します。
|
||||
|
||||
トランザクションで`LastLedgerSequence`フィールドが省略されている場合は、別の意味で誤っている可能性があります。つまり、同じ送信者からの他のトランザクションでは同じ`Sequence`番号が使用されていない場合、トランザクションはその後、時間の経過に関係なく、理論上成功します。（詳細は、[確実なトランザクションの送信](reliable-transaction-submission.html)を参照してください。）
|
||||
|
||||
8. 脆弱なシステムは、トランザクションが失敗したと想定してアクションを実行します。
|
||||
|
||||
たとえば、XRP Ledgerで送金されていないと判断した資金についての責任を果たすため、システムで顧客の残高に返金します（または単に引き落としを行いません）。
|
||||
|
||||
さらに、脆弱なシステムがトランザクションを置き換えるために新しいトランザクションを生成し、ネットワークの現在の状態に基づいて新しい`Sequence`、`LastLedgerSequence`、および`Fee`パラメーターを選択し、その一方でトランザクションの残りの部分は本来のトランザクションと同じ状態で維持することがあります。この新しいトランザクションにも展性がある場合、システムは何度も同じように悪用される可能性があります。
|
||||
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
@@ -1,80 +0,0 @@
|
||||
---
|
||||
html: transaction-queue.html
|
||||
parent: consensus-network.html
|
||||
blurb: コンセンサスに至る前にトランザクションをどのようにキューに入れることができるか説明します。
|
||||
labels:
|
||||
- トランザクション送信
|
||||
---
|
||||
# トランザクションキュー
|
||||
|
||||
`rippled`サーバーは、トランザクションキューを使用して[オープンレジャーコスト](transaction-cost.html#オープンレジャーコスト)を適用します。オープンレジャーコストにより、特定のレジャーの目標トランザクション数が設定され、オープンレジャーがこのサイズを超えると、必要なトランザクションコストが迅速に引き上げられます。`rippled`は引き上げられたトランザクションコストを支払うことができないトランザクションを無効にする代わりに、次のレジャーの構築に使用するトランザクションキューにそれらのトランザクションを入れようとします。
|
||||
|
||||
## トランザクションキューとコンセンサス
|
||||
|
||||
トランザクションキューは、コンセンサスプロセスで特定のレジャーバージョンに記録されるトランザクションと除外されるトランザクションを選択する際に、重要な役割を果たします。以下のステップでは、トランザクションキューと[コンセンサスプロセス](consensus.html)の関係を説明します。
|
||||
|
||||
[](img/consensus-with-queue.ja.png)
|
||||
|
||||
1. **コンセンサスラウンド1** - 各バリデータが、次のレジャーバージョンに記録するトランザクションセットを提案します。各バリデータは、現在提案されていないトランザクション候補のキューも保持します。
|
||||
|
||||
2. **コンセンサスラウンド2** - バリデータは後のラウンドで自身の提案からトランザクションを削除する場合、そのトランザクションをキューに追加します。
|
||||
|
||||
3. **コンセンサスラウンドN** - 十分な数のサーバーがトランザクションセットについて合意するまで、コンセンサスプロセスが継続されます。
|
||||
|
||||
4. **検証** - 複数のサーバーが、各々同一のレジャーを構築したことを確認し、そのレジャーが検証済みであると宣言します。
|
||||
|
||||
5. **次の提案の作成** - 各バリデータは、キューに入れられているトランザクションを最初に使用して、次のレジャーバージョンの提案を準備します。
|
||||
|
||||
6. **キューへの追加** - 次の提案レジャーがすでにいっぱいである場合は、着信トランザクションはその後のレジャーバージョンのキューに入れられます。（[オープンレジャーコスト](transaction-cost.html#オープンレジャーコスト)を支払うトランザクションは、次の提案レジャーが「いっぱい」であってもそのレジャーに追加されますが、このようにトランザクションが追加されるたびにオープンレジャーコストは急激に増加します。）
|
||||
|
||||
このステップの後、プロセスが最初から繰り返されます。
|
||||
|
||||
**注記:** 技術的には、上記のプロセスで説明したステップのいくつかは並行して発生します。これは、各サーバーは常に新しいトランザクションに備えて待機しており、前のレジャーバージョンのコンセンサスプロセスの実行中に次のレジャー提案の準備を開始するためです。
|
||||
|
||||
## キューの制約事項
|
||||
|
||||
`rippled`サーバーはさまざまな経験則によるテストを行って「レジャーに追加される可能性がある」トランザクションを推定します。現行の実装では、以下のルールに基づいてキューに入れるトランザクションが決定されます。
|
||||
|
||||
- トランザクションは適切な形式で作成され、有効な署名によって[承認](transaction-basics.html#トランザクションの承認)されている必要があります。
|
||||
- `AccountTxnID`フィールドが指定されているトランザクションはキューに入れることができません。
|
||||
- 1つの送信側アドレスには、同時に最大10個のトランザクションを入れることができます。
|
||||
- トランザクションをキューに入れるには、送信者が以下のすべてを行うのに十分なXRPを保有している必要があります。[更新: rippled 1.2.0][]
|
||||
- キュー内のすべての送信者のトランザクションの`Fee`フィールドに指定されているXRP[トランザクションコスト](transaction-cost.html)の消却。キュー内のトランザクションの合計額は、アカウントの基本準備金（現時点では10 XRP）を超えることはできません。（トランザクションコストの支払いが最小額の0.00001 XRPを大幅に上回るトランザクションは、キューをスキップし、オープンレジャーに直接追加されます。）
|
||||
- キュー内のすべての送信者のトランザクションの送金を可能とするXRPの最大合計額の送信。
|
||||
- アカウントの[必要準備金](reserves.html)を確保するのに十分なXRPの保有。
|
||||
- あるトランザクションが、送信側アドレスがトランザクションを承認する方法に影響する場合、同じアドレスからの他のトランザクションをそのトランザクションの後にキューに入れることはできません。[新規: rippled 0.32.0][]
|
||||
- トランザクションに`LastLedgerSequence`フィールドが指定されている場合、そのフィールドの値は少なくとも **現在のレジャーインデックス+ 2**になります。
|
||||
|
||||
### 手数料の平均化
|
||||
|
||||
[新規: rippled 0.33.0][]
|
||||
|
||||
送信側アドレスのキューに1つ以上のトランザクションが入っている場合、その送信者はキューに入れられている既存のトランザクションをオープンレジャーに「プッシュ」するため、それらすべてのトランザクションのトランザクションコストの支払いをするのに十分なトランザクションコストが指定された新しいトランザクションを送信します。具体的には、新しいトランザクションは、そのトランザクション自体と、そのトランザクションより先にキュー内に入れられている同じ送信者からの各トランザクションの[オープンレジャーコスト](transaction-cost.html#オープンレジャーコスト)をカバーするのに十分なトランザクションコストを支払う必要があります。（オープンレジャーコストは、トランザクションがトランザクションコストを支払うたびに急激に増加することに留意してください。）トランザクションは他の[キューの制約事項](#キューの制約事項)にも従い、送信側アドレスはキュー内のすべてのトランザクションのトランザクションコストを支払うのに十分な額のXRPを保有している必要があります。
|
||||
|
||||
この機能により、特定の状況を回避できます。キュー内にある低コストのトランザクションを1つ以上送信した場合、同じアドレスから新しいトランザクションを送信するには、以下のいずれかを実行する必要があります。
|
||||
|
||||
* キュー内のトランザクションが検証済みレジャーに追加されるまで待機する。
|
||||
* キュー内のトランザクションに[`LastLedgerSequence`フィールド](reliable-transaction-submission.html#lastledgersequence)が設定されている場合、それらのトランザクションが完全に無効化されるまで待機する。
|
||||
* [キュー内のトランザクションを取り消す](cancel-or-skip-a-transaction.html)。このためには、同じシーケンス番号で、これらのトランザクションよりも高いトランザクションコストを指定した新しいトランザクションを送信します。
|
||||
|
||||
上記のどの操作も行われないと、トランザクションは理論上無期限にキューに入れられたままとなり、他の送信者はそれらよりもトランザクションコストが高いトランザクションを送信してキューに「割り込む」ことができます。署名済みのトランザクションは変更できないため、キュー内のトランザクションのトランザクションコストを増加して、トランザクションの優先度を上げることはできません。以前に送信されたトランザクションを無効にしたくない場合には、手数料の平均化が回避策となります。新しいトランザクションのトランザクションコストを増額して不足分を補えば、キュー内のトランザクションは即時にオープンレジャーに追加されます。
|
||||
|
||||
## キュー内の順序
|
||||
|
||||
トランザクションキュー内では、最も高いトランザクションコストを支払うトランザクションが一番になるようにトランザクションがランク付けされています。このランク付けはトランザクションの _絶対_ XRPコストではなく、 _[該当するトランザクションタイプの最小コスト](transaction-cost.html#特別なトランザクションコスト)に相対的な_ コストに基づいています。トランザクションコストが同額のトランザクションが複数ある場合は、サーバーが受信した順にランク付けされます。キュー内のトランザクションの順序にはその他の要因も影響します。たとえば、同一送信者からのトランザクションはその`Sequence`番号によりソートされ、順に送信されます。
|
||||
|
||||
キュー内のトランザクションの数が次のレジャーバージョンの予期サイズを超える場合には、キュー内のトランザクションの正確な順序に基づいて、次の処理レジャーバージョンに追加されるトランザクションが決定します。トランザクションの順序は**検証済みレジャー内でのトランザクションの実行順序には影響しません**。各検証済みレジャーバージョンでは、そのバージョンのトランザクションセットが[正規の順序](consensus.html#検証の計算と共有)で実行されます。
|
||||
|
||||
**注記:**`rippled`がトランザクションをキューに入れるときに付与される暫定的な[トランザクション応答コード](transaction-results.html)は`terQUEUED`です。つまり、トランザクションは今後のレジャーバージョンで成功する見込みです。すべての暫定的な応答コードと同様に、トランザクションが検証済みレジャーに追加されるか、または[完全に無効であると示される](finality-of-results.html)までは、トランザクションの結果は最終的ではありません。
|
||||
|
||||
|
||||
## 関連項目
|
||||
|
||||
- トランザクションコストが設けられている理由と、XRP Ledgerでのトランザクションコストの適用方法については、[トランザクションコスト](transaction-cost.html)を参照してください。
|
||||
- コンセンサスプロセスによるトランザクション承認方法についての詳しい説明は、[コンセンサス](consensus.html)を参照してください。
|
||||
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
101
content/concepts/introduction/txn-and-requests.md
Normal file
101
content/concepts/introduction/txn-and-requests.md
Normal file
@@ -0,0 +1,101 @@
|
||||
---
|
||||
html: txn-and-requests.html
|
||||
parent: intro-to-xrpl.html
|
||||
blurb: All interactions with the ledger are either transactions or requests.
|
||||
labels:
|
||||
- Blockchain
|
||||
---
|
||||
|
||||
# Transactions and Requests
|
||||
|
||||
All interactions with the XRP Ledger involve either sending a transaction that makes changes to the ledger or sending a request for information from the ledger.
|
||||
|
||||
## How Do Transactions Work?
|
||||
|
||||
You execute a transaction by sending a REST command to the XRP Ledger and waiting for the response. The command syntax is always the same for every transaction.
|
||||
|
||||
You must always provide the _TransactionType_ and the public address of the _Account_ making the transaction.
|
||||
|
||||
Two required fields are the _Fee_ for the transaction and the next _Sequence_ number for transactions from the account. These fields can be filled in automatically by the ledger server when you submit the transaction.
|
||||
|
||||
Specific transactions also have required fields specific to the transaction type. For example, a _Payment_ transaction requires an _Amount_ value (in _drops_, or millionths of an XRP) and a _Destination_ public address to which the funds are credited.
|
||||
|
||||
Here is a sample transaction in JSON format. This transaction transfers 1 XRP from account _rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn_ to destination account _ra5nK24KXen9AHvsdFTKHSANinZseWnPcX_.
|
||||
|
||||
```json
|
||||
{
|
||||
"TransactionType": "Payment",
|
||||
"Account": rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn,
|
||||
"Amount": 1000000,
|
||||
"Destination": ra5nK24KXen9AHvsdFTKHSANinZseWnPcX
|
||||
}
|
||||
```
|
||||
|
||||
Optional fields are available for all transactions, with additional fields available for specific transactions. You can include as many optional fields as you need, but do not have to include every field in every transaction.
|
||||
|
||||
You send the transaction to the ledger as a RESTful command from JavaScript, Python, the command line, or any compatible service. The rippled server proposes the transaction to the ledger. When 80% of the validators approve the transaction, it is recorded as part of the permanent ledger. The ledger returns the results of the transaction.
|
||||
|
||||
For more information on Transactions, see [Transactions](../understanding-xrpl/transactions/transactions.md).
|
||||
|
||||
## How Do Requests Work?
|
||||
|
||||
Requests are similar to transactions, but they do not make changes to the ledger.
|
||||
|
||||
The fields you send vary with the type of information you request. They typically have several optional fields, but only a few required fields.
|
||||
|
||||
This is a sample request in JSON format. This request gets the current account information for the account number you provide.
|
||||
|
||||
```json
|
||||
{
|
||||
"command": "account_info",
|
||||
"account": "rG1QQv2nh2gr7RCZ1P8YYcBUKCCN633jCn"
|
||||
}
|
||||
```
|
||||
|
||||
The request returns the information in a format appropriate for the language you used to make the request. Here is an example of the response for an account information request in JSON format.
|
||||
|
||||
```json
|
||||
{
|
||||
"result": {
|
||||
"account_data": {
|
||||
"Account": "rG1QQv2nh2gr7RCZ1P8YYcBUKCCN633jCn",
|
||||
"Balance": "999999999960",
|
||||
"Flags": 8388608,
|
||||
"LedgerEntryType": "AccountRoot",
|
||||
"OwnerCount": 0,
|
||||
"PreviousTxnID": "4294BEBE5B569A18C0A2702387C9B1E7146DC3A5850C1E87204951C6FDAA4C42",
|
||||
"PreviousTxnLgrSeq": 3,
|
||||
"Sequence": 6,
|
||||
"index": "92FA6A9FC8EA6018D5D16532D7795C91BFB0831355BDFDA177E86C8BF997985F"
|
||||
},
|
||||
"ledger_current_index": 4,
|
||||
"queue_data": {
|
||||
"auth_change_queued": true,
|
||||
"highest_sequence": 10,
|
||||
"lowest_sequence": 6,
|
||||
"max_spend_drops_total": "500",
|
||||
"transactions": [
|
||||
{
|
||||
"auth_change": false,
|
||||
"fee": "100",
|
||||
"fee_level": "2560",
|
||||
"max_spend_drops": "100",
|
||||
"seq": 6
|
||||
},
|
||||
... (trimmed for length) ...
|
||||
{
|
||||
"LastLedgerSequence": 10,
|
||||
"auth_change": true,
|
||||
"fee": "100",
|
||||
"fee_level": "2560",
|
||||
"max_spend_drops": "100",
|
||||
"seq": 10
|
||||
}
|
||||
],
|
||||
"txn_count": 5
|
||||
},
|
||||
"status": "success",
|
||||
"validated": false
|
||||
}
|
||||
}
|
||||
```
|
||||
45
content/concepts/introduction/what-is-xrp.md
Normal file
45
content/concepts/introduction/what-is-xrp.md
Normal file
@@ -0,0 +1,45 @@
|
||||
---
|
||||
html: what-is-xrp.html
|
||||
parent: intro-to-xrpl.html
|
||||
blurb: Learn about XRP, the cryptocurrency traded on the XRP Ledger.
|
||||
labels:
|
||||
- Blockchain
|
||||
---
|
||||
|
||||
# What is XRP?
|
||||
|
||||
XRP is the cryptocurrency supported by the XRP Ledger.
|
||||
|
||||
## What Is Cryptocurrency?
|
||||
|
||||
A cryptocurrency is a digital or virtual currency that is secured by cryptography and tracked using a blockchain. The security and integrity of cryptocurrency makes it nearly impossible to counterfeit or double-spend.
|
||||
|
||||
Cryptocurrencies, digital currencies, and digital assets all fall into the same general category. Cryptocurrencies are:
|
||||
- digitally native (meaning they are built for the internet)
|
||||
- programmable
|
||||
- fast to transfer at a low cost
|
||||
- open and transparent
|
||||
- not restricted by borders or governments (so no need for nostro accounts that hold funds in another country)
|
||||
- not subject to counterfeit
|
||||
- do not require a bank account or infrastructure to settle payments.
|
||||
|
||||
Cryptocurrencies are _fungible tokens_. _Fungible_ means that you can replace one token with other tokens of equal value. Postage is an example of a fungible token: if it costs 50 cents to mail a letter, you can use 2 25-cent stamps or 5 10-cent stamps for the postage, because postage stamps are fungible (consistent in relative value and interchangeable).
|
||||
|
||||
Cryptocurrencies are also decentralized. There’s no central authority governing the currency. Once the ledger is on the blockchain you cannot change it. It is difficult to censor cryptocurrency: so long as the system is sufficiently decentralized, no one can roll back transactions, freeze balances, or block someone from using a decentralized digital asset. Rules do not change without significant coordination among all participants.
|
||||
|
||||
Cryptocurrencies are compelling for investors and developers because no single entity can “pull the plug” on them and have them disappear.
|
||||
|
||||
## But Why Is It Valuable?
|
||||
|
||||
It might seem strange that cryptocurrency is based solely on computer data, and not on any sort of tangible commodity such as precious metal. Traditionally, currencies have been based on cattle, sea shells, rare metals, stones, or other physical objects. But these items have value only because there was agreement between people in a culture.
|
||||
|
||||
While it might seem safer to have something “real” in your hand, I personally wouldn’t know fool’s gold from the actual thing, or cubic zirconia from a genuine diamond. Paper money can be counterfeit. You can forget you have a $10 bill in your pocket and ruin it in the wash. It is costly to safely store and transport valuable items for payment.
|
||||
|
||||
The value of cryptocurrency comes from the faith that holders place in the currency. Given the distributed nature of the records and the complex cryptographic safeguards to secure the funds, cryptocurrency could be considered a much more robust, secure, and convenient form of currency than traditional fiat currencies.
|
||||
|
||||
|
||||
## XRP is Cryptocurrency
|
||||
|
||||
XRP is a cryptocurrency created in 2011 by a company named OpenCoin, which later changed its name to Ripple. The Ripple name is based on the way technology allows payments to "ripple" through multiple hops and currencies. The _X_ prefix is the ISO 4217 standard for non-national currencies. In choosing the ticker symbol, the creators chose _XRP_ to refer to the asset in all contexts.
|
||||
|
||||
At the time of its creation, there were 100 billion XRP. XRP are held in escrow and sold at intervals that help to maintain the stability of the currency and ensure that the general supply grows predictably.
|
||||
59
content/concepts/introduction/what-is-xrpl.md
Normal file
59
content/concepts/introduction/what-is-xrpl.md
Normal file
@@ -0,0 +1,59 @@
|
||||
---
|
||||
html: what-is-xrpl.html
|
||||
parent: intro-to-xrpl.html
|
||||
blurb: Learn about the XRP Ledger blockchain.
|
||||
labels:
|
||||
- Blockchain
|
||||
---
|
||||
|
||||
# What is the XRP Ledger?
|
||||
|
||||
The XRP Ledger is a _blockchain_ that records transactions of XRP and other tokens.
|
||||
|
||||
## What Is a Blockchain?
|
||||
|
||||
A blockchain is a continuously growing list of records. The blockchain starts with a block of data.
|
||||
|
||||
A group of trusted validator nodes reach consensus that the data is valid.
|
||||
|
||||
The block is uniquely identified with a very elaborate, complicated, computer-generated, cryptographic Hash number that is 64 hexadecimal characters long,
|
||||
|
||||
The block is also identified by a timestamp with its creation time.
|
||||
|
||||
Each validator node gets its own copy of the data block. There is no single central authority. All copies are equally valid.
|
||||
|
||||
Each block contains a hash pointer as a link to the previous block. It also has a timestamp, new data, and its own unique hash number.
|
||||
|
||||
Using this structure, each block has a clear position in the chain, linking back to the previous data block. This creates an immutable chain of blocks. You can always verify all current information on the chain by tracing back through the previous blocks.
|
||||
|
||||
By design, blockchains are resistant to modification of the data. Every ledger node gets an exact copy of the blockchain.
|
||||
|
||||
This creates an open, distributed ledger that records transactions between parties efficiently and in a verifiable and permanent way.
|
||||
|
||||
Once recorded, the data in any given block cannot be altered retroactively, unless a majority of the validators agree to the change. If so, all subsequent blocks are changed in the same way (a very rare and extreme occurrence).
|
||||
|
||||
|
||||
## What Is the XRPL?
|
||||
|
||||
The XRP Ledger (XRPL) is the blockchain on which XRP currency is based and exchanged. All accounts on the XRPL can transfer XRP between one another and must hold a minimum amount of XRP as a reserve.
|
||||
|
||||
|
||||
### What Is In the XRPL Ecosystem?
|
||||
|
||||
The basis of the XRP Ledger is a peer-to-peer network of always-on rippled (pronounced _ripple-d_) servers sharing transactions, engaging in the consensus process, and processing transactions. Everything else in the XRP Ledger ecosystem is directly or indirectly built on top of this peer-to-peer network.
|
||||
|
||||
Programming Libraries exist in higher level software, where they are imported directly into program code, and contain methods to access the XRP Ledger.
|
||||
|
||||
Middleware provides indirect access to XRP Ledger data. Applications in this layer often have their own data storage and processing.
|
||||
|
||||
Apps and Services provide user-level interaction with the XRP Ledger, or provide a basis for even higher-level apps and services.
|
||||
|
||||
### How Does the Federated Consensus Process Work?
|
||||
|
||||
Most of the rippled servers in the XRPL monitor or propose transactions. An important subset of servers are run as validators. These trusted servers accumulate lists of new transactions into a new possible ledger instance (a new block in the block chain). They share their lists with all of the other validators. The validators incorporate proposed changes from one another and distribute a new version of the ledger proposal. When 80% of the validators agree on a set of transactions, they create a new ledger instance at the end of the chain and start the process again. This consensus process takes 4-6 seconds. You can monitor as ledger instances are created in real time by visiting [https://livenet.xrpl.org/](https://livenet.xrpl.org/).
|
||||
|
||||
### What Networks Are Available?
|
||||
|
||||
The XRPL is open to anyone who wants to set up their own instance of the rippled server and connect. The node can monitor the network, perform transactions, or become a validator.
|
||||
|
||||
For developers or new users who want to try out the features of XRPL without investing their own funds, there are two developer environments, _Testnet_ and _Devnet_. Users can create an account funded with 10,000 (fake) XRP and connect to either environment to interact with the XRPL.
|
||||
@@ -1,181 +0,0 @@
|
||||
---
|
||||
html: transaction-cost.html
|
||||
parent: transaction-basics.html
|
||||
blurb: トランザクションコストとはトランザクション送信のために償却される少額のXRPで、これによってレジャーがスパムから保護されます。トランザクションコストの適用方法について説明します。
|
||||
labels:
|
||||
- 手数料
|
||||
- トランザクション送信
|
||||
---
|
||||
# トランザクションコスト
|
||||
|
||||
XRP LedgerをスパムやDoS攻撃から守るため、各トランザクションでは少額の[XRP](xrp.html)が消却されます。この _トランザクションコスト_ はネットワークの負荷とともに増加するように設計されており、故意または不注意にネットワークに過剰な負荷をかけると非常に高くつきます。
|
||||
|
||||
各トランザクションのトランザクションコストを支払う際には、[消却するXRPの額を指定](#トランザクションコストの指定)する必要があります。
|
||||
|
||||
|
||||
## 現在のトランザクションコスト
|
||||
|
||||
ネットワークが標準のトランザクションに必要とする現在の最低トランザクションコストは**0.00001 XRP**（10 drop）です。これは負荷が通常より高くなると増加することがあります。
|
||||
|
||||
また、[現在のトランザクションコストについて`rippled`に問い合わせる](#トランザクションコストの問い合わせ)こともできます。
|
||||
|
||||
### 特別なトランザクションコスト
|
||||
|
||||
一部のトランザクションには異なるトランザクションコストがあります。
|
||||
|
||||
| トランザクション | 負荷スケーリング前のコスト |
|
||||
|-----------------------|--------------------------|
|
||||
| [Referenceトランザクション](#referenceトランザクションコスト)（ほとんどのトランザクション） | 10 drop |
|
||||
| [Key Resetトランザクション](#key-resetトランザクション)| 0 |
|
||||
| [マルチ署名済みトランザクション](multi-signing.html)| 10 drop × （1 + 署名の数） |
|
||||
| [フルフィルメントを伴うEscrowFinishトランザクション](escrowfinish.html)| 10 drop × （33 + （バイト単位のフルフィルメントサイズ ÷ 16）） |
|
||||
| [AccountDeleteトランザクション](accounts.html#アカウントの削除)| 5,000,000 drop |
|
||||
|
||||
|
||||
## トランザクションコストの受取人
|
||||
|
||||
トランザクションコストは誰かに支払われるものではありません。XRPは取り消し不能で消却されます。XRPを新たに作ることはできないため、XRPの希少性が高まり、XRPの価値を高めることによって、すべてのXRP保有者に利益がもたらされます。
|
||||
|
||||
|
||||
## 負荷コストとオープンレジャーコスト
|
||||
|
||||
[FeeEscalation Amendment][]が有効な場合、トランザクションコストには以下の2つのしきい値があります。
|
||||
|
||||
* トランザクションコストが`rippled`サーバーの[負荷ベーストランザクションコストのしきい値](#ローカル負荷コスト)を満たしていない場合、サーバーはそのトランザクションを完全に無視します。（このロジックはAmendmentの有無にかかわらず基本的に変わりません。）
|
||||
* トランザクションコストが`rippled`サーバーの[オープンレジャーコストのしきい値](#オープンレジャーコスト)を満たしていない場合、サーバーはそのトランザクションを後のレジャーのキューに入れます。
|
||||
|
||||
これによってトランザクションは大まかに以下の3つのカテゴリーに分けられます。
|
||||
|
||||
* トランザクションコストが低く設定され、負荷ベーストランザクションコストによって拒否されるトランザクション。
|
||||
* トランザクションコストが高く設定され、現在のオープンレジャーに組み入れられるトランザクション。
|
||||
* その中間のトランザクション。[後のレジャーバージョンのキューに入れられます](#キューに入れられたトランザクション)。
|
||||
|
||||
|
||||
## ローカル負荷コスト
|
||||
|
||||
各`rippled`サーバーには、現在の負荷に基づいてコストしきい値が保持されています。送信するトランザクションの`Fee`値が`rippled`サーバーの現在の負荷ベーストランザクションコストより低い場合、そのサーバーはトランザクションの適用も中継もしません。（**注記:** [管理者接続](get-started-using-http-websocket-apis.html)を介してトランザクションを送信する場合、トランザクションがスケーリングされていない最低トランザクションコストを満たすかぎり、サーバーはそのトランザクションを適用し、中継します。）トランザクションの`Fee`値が大半のサーバーの要件を満たさないかぎり、そのトランザクションが[コンセンサスプロセス](consensus.html)を完了する可能性は極めて低くなります。
|
||||
|
||||
## オープンレジャーコスト
|
||||
|
||||
`rippled`サーバーにはトランザクションコストを強制する2つ目のメカニズムがあり、 _オープンレジャーコスト_ と呼ばれます。トランザクションがXRPによるオープンレジャーコスト要件を満たす場合のみ、そのトランザクションをオープンレジャーに含めることができます。オープンレジャーコスト要件を満たさないトランザクションは、[次のレジャーのキューに入れられます](#キューに入れられたトランザクション)。
|
||||
|
||||
新しいレジャーバージョンごとに、サーバーは前のレジャーのトランザクション数に基づいてオープンレジャーに含めるトランザクション数のソフトリミットを選択します。オープンレジャーコストは、オープンレジャー内のトランザクション数がソフトリミットと等しくなるまでは、スケーリングされていない最低トランザクションコストと同じです。それを超えると、オープンレジャーコストはオープンレジャーに含まれるトランザクションごとに急激に増加します。次のレジャーでは、現行のレジャーにソフトリミットを超えるトランザクションが含まれていれば、サーバーはソフトリミットを高くし、コンセンサスプロセスに5秒より時間が掛かる場合はソフトリミットを低くします。
|
||||
|
||||
オープンレジャーコストの水準は、絶対的なトランザクションコストではなく[標準的なトランザクションコストに比例](#手数料レベル)しています。標準よりも高い要件を持つトランザクションタイプ（[マルチ署名済みトランザクション](multi-signing.html)など）は、オープンレジャーコストを満たすために最低限のトランザクションコスト要件を持つトランザクションよりも多く支払う必要があります。
|
||||
|
||||
関連項目: [`rippled`リポジトリー内のFee Escalationの説明](https://github.com/ripple/rippled/blob/release/src/ripple/app/misc/FeeEscalation.md)。
|
||||
|
||||
### キューに入れられたトランザクション
|
||||
|
||||
`rippled`が、サーバーのローカル負荷コストは満たすが[オープンレジャーコスト](#オープンレジャーコスト)は満たさないトランザクションを受け取った場合、サーバーはそのトランザクションが後のレジャーに「含まれる可能性」を判断します。その可能性が高いと判断すれば、サーバーはそのトランザクションをトランザクションキューに追加し、他のネットワークメンバーにトランザクションを中継します。そうでない場合、サーバーはトランザクションを破棄します。[トランザクションコストは検証済みレジャーに含まれるトランザクションにのみ適用される](#トランザクションコストと失敗したトランザクション)ため、サーバーは、トランザクションコストを支払わないトランザクションにより生じるネットワーク負荷量を最低限に抑えようとします。
|
||||
|
||||
キューに入れられたトランザクションの詳細は、[トランザクションキュー](transaction-queue.html)を参照してください。
|
||||
|
||||
## Referenceトランザクションコスト
|
||||
|
||||
「Referenceトランザクション」とは、負荷スケーリング前の[トランザクションコスト](transaction-cost.html)という観点からは、最も安価な（無料ではない）トランザクションと言えます。ほとんどのトランザクションのコストはReferenceトランザクションと同じです。[マルチ署名済みトランザクション](multi-signing.html)など一部のトランザクションでは、このコストの数倍のコストが必要です。オープンレジャーコストが上昇する場合は、コスト水準はトランザクションの基本コストに比例します。
|
||||
|
||||
### 手数料レベル
|
||||
|
||||
_手数料レベル_ は、トランザクションの最少コストと実際のコストとの相対的な差を表します。[オープンレジャーコスト](#オープンレジャーコスト)は絶対的なコストではなく手数料レベルで評価されます。比較する場合は以下の表を参照してください。
|
||||
|
||||
| トランザクション | drop単位の最少コスト | 手数料レベルでの最少コスト | drop単位で倍のコスト | 手数料レベルで倍のコスト |
|
||||
|-------------|-----------------------|----------------------------|----------------------|---------------------------|
|
||||
| Referenceトランザクション（ほとんどのトランザクション） | 10 | 256 | 20 | 512 |
|
||||
| 4つの署名を持つ[マルチ署名済みトランザクション](multi-signing.html) | 50 | 256 | 100 | 512 |
|
||||
| [Key Resetトランザクション](transaction-cost.html#key-resetトランザクション) | 0 | （事実上無限） | なし | （事実上無限） |
|
||||
| 32バイトのプリイメージ付きの[EscrowFinishトランザクション](escrowfinish.html)。 | 350 | 256 | 700 | 512 |
|
||||
|
||||
|
||||
## トランザクションコストの問い合わせ
|
||||
|
||||
`rippled` APIには、ローカル負荷ベースのトランザクションコストを問い合わせる方法が2つあります。`server_info`コマンド（人を対象とする）と`server_state`コマンド（マシンを対象とする）です。
|
||||
|
||||
[FeeEscalation Amendment][]が有効である場合、[feeメソッド][]を使用してオープンレジャーコストを確認することができます。
|
||||
|
||||
### server_info
|
||||
|
||||
[server_infoメソッド][]は、`validated_ledger.base_fee_xrp`と同様に、前のレジャー時点のスケーリングされていない最低XRPコストを10進XRPの形式でレポートします。トランザクションを中継するために必要な実際のコストをスケーリングするには、その`base_fee_xrp`値に同じ応答内の`load_factor`パラメーターを掛けます。このパラメーターは、サーバーの現在の負荷レベルを表します。つまり、次の式になります。
|
||||
|
||||
**XRP単位の現在のトランザクションコスト = `base_fee_xrp` × `load_factor`**
|
||||
|
||||
|
||||
### server_state
|
||||
|
||||
[server_stateメソッド][]は、`rippled`の内部負荷計算の内容をそのままの表示形式で返します。この場合、有効負荷率は`load_base`に対する`load_factor`の割合です。`validated_ledger.base_fee`パラメーターは、[XRPのdrop](basic-data-types.html#通貨額の指定)単位の最低トランザクションコストをレポートします。この設計により、`rippled`では整数のみでトランザクションコストの計算ができ、サーバー負荷の微調整も十分に行えます。実際のトランザクションコストの計算は以下のようになります。
|
||||
|
||||
**drop単位の現在のトランザクションコスト = (`base_fee` × `load_factor`) ÷ `load_base`**
|
||||
|
||||
|
||||
|
||||
## トランザクションコストの指定
|
||||
|
||||
署名されたすべてのトランザクションの[`Fee`フィールド](transaction-common-fields.html)には、トランザクションコストを含める必要があります。署名されたトランザクションのすべてのフィールドと同様に、このフィールドは署名の無効化を行わなければ変更できません。
|
||||
|
||||
通常、XRP Ledgerはトランザクションを署名された _とおりに_ 実行します。（少なくとも、分散型コンセンサスネットワーク全体をコーディネートしてそれ以外のことを実行するのは難しいと思われます。）したがって、`Fee`フィールドに指定されたXRPの額が、ネットワーク内で指定されているどの現在の最低トランザクションコストをもはるかに上回っていたとしても、指定したとおりのXRPがすべてのトランザクションで消却されます。トランザクションコストでは、アカウントの[準備金](reserves.html)用に確保していたXRPも消却される場合があります。
|
||||
|
||||
トランザクションに署名する前に、[現在の負荷ベースのトランザクションコストを調べる](#トランザクションコストの問い合わせ)ことをお勧めします。負荷スケーリングが原因でトランザクションコストが高い場合は、低下するまで待つことができます。トランザクションをすぐに送信するつもりがない場合は、トランザクションコストにおける将来の負荷ベースの変動を考慮して、少し高めのトランザクションコストを指定することをお勧めします。
|
||||
|
||||
|
||||
### トランザクションコストの自動指定
|
||||
|
||||
オンラインでトランザクションに署名する場合は、`Fee`フィールドを省略できます。この場合、`rippled`または[クライアントライブラリ](client-libraries.html)が現在の要件に照らしてピアツーピアネットワークの状態を確認し、トランザクションに署名する前に`Fee`値を追加します。ただし、このようなトランザクションコストへの自動入力にはいくつかの欠点と制限事項があります。
|
||||
|
||||
* トランザクションに署名し、分散するまでの間にネットワークのトランザクションコストが上昇した場合、そのトランザクションは承認されない場合があります。
|
||||
* 最悪の場合、トランザクションに`LastLedgerSequence`パラメーターが含まれているか、同じ`Sequence`番号を使用する新しいトランザクションによってそのトランザクションがキャンセルされない限り、トランザクションは明確に承認も拒否もされない状態のままとなってしまいます。ベストプラクティスについては、[信頼できるトランザクションの送信](reliable-transaction-submission.html)を参照してください。
|
||||
* 署名するトランザクションの`Fee`フィールドの正確な値は事前にわかりません。
|
||||
* `rippled`を使用している場合は、[signメソッド][]の`fee_mult_max`パラメーターと`fee_div_max`パラメーターを使用して、署名しようとしている負荷スケーリングに制限を設定することもできます。
|
||||
* オフラインのマシンから現在のトランザクションコストを調べることはできません。
|
||||
* [マルチ署名](multi-signing.html)の場合、トランザクションコストの自動指定は行えません。
|
||||
|
||||
|
||||
|
||||
## トランザクションコストと失敗したトランザクション
|
||||
|
||||
トランザクションコストの目的はXRP Ledgerピアツーピアネットワークを過度な負荷から保護することであるため、トランザクションが成功するかどうかにかかわらず、ネットワークに分散されるすべてのトランザクションにコストが適用されます。ただし、共有のグローバルレジャーに作用するため、トランザクションを検証済みレジャーに含める必要があります。したがって、`rippled`サーバーは[`tec`ステータスコード](transaction-results.html)（「tec」は「トランザクションエンジン - 請求手数料のみ」（Transaction Engine - Claimed fee only）を表します）で、失敗したトランザクションをレジャーに含めようとします。
|
||||
|
||||
トランザクションコストは、トランザクションが実際に検証済みレジャーに含められた場合に、送信者のXRP残高から差し引かれるだけです。このことは、トランザクションが成功するか`tec`コードとともに失敗するかにかかわらず適用されます。
|
||||
|
||||
トランザクションの失敗が[確定](finality-of-results.html)である場合、`rippled`サーバーによるネットワークへの中継は行われません。トランザクションは検証済みレジャーに含まれないため、誰のXRP残高にも影響することはありません。
|
||||
|
||||
### 不十分なXRP
|
||||
|
||||
`rippled`サーバーが最初にトランザクションを評価するとき、送信側アカウントにXRPトランザクションコストを支払うのに十分なXRP残高がない場合は、エラーコード`terINSUF_FEE_B`にてトランザクションを拒否します。これは`ter`（再試行）コードであるため、トランザクションの結果が[確定](finality-of-results.html)になるまで、`rippled`サーバーはネットワークへの中継を行わずにトランザクションを再試行します。
|
||||
|
||||
トランザクションはすでにネットワークに配信されているけれども、アカウントにトランザクションコストを支払うのに十分なXRPがない場合は、結果コード`tecINSUFF_FEE`が発生します。この場合、アカウントからは可能なかぎりすべてのXRPが支払われるため、最終的に0 XRPになります。これは、`rippled`がトランザクションをネットワークに中継するかどうかを進行中のレジャーに基づいて判断するために起こります。しかしコンセンサスレジャーを作成するときにトランザクションは破棄されるか並べ替えられることになります。
|
||||
|
||||
|
||||
## Key Resetトランザクション
|
||||
|
||||
特殊なケースですが、アカウントの[lsfPasswordSpentフラグ](accountroot.html)が無効であるかぎり、そのアカウントはトランザクションコスト`0`で[SetRegularKey](setregularkey.html)トランザクションを送信できます。このトランザクションにはアカウントの _マスターキーペア_ による署名が必要です。このトランザクションを送信すると、lsfPasswordSpentフラグが有効になります。
|
||||
|
||||
この機能は、レギュラーキーが危害を受けた場合に、危害を受けたアカウントに使用可能なXRPがあるかどうかを気にすることなく、そのアカウントを復元できるように設計されています。このようにして、追加のXRPを送信する前にそのアカウントを再び管理できるようになります。
|
||||
|
||||
[lsfPasswordSpentフラグ](accountroot.html)は無効になります。このフラグを有効にするには、マスターキーペアによって署名されたSetRegularKeyトランザクションを送信します。アカウントでXRPの[支払い](payment.html)が受け入れた場合、再び無効になります。
|
||||
|
||||
[FeeEscalation Amendment][]が有効な場合、Key Resetトランザクションの名目トランザクションコストがゼロであっても、`rippled`は他のトランザクションよりもKey Resetトランザクションを優先します。
|
||||
|
||||
|
||||
## トランザクションコストの変更
|
||||
|
||||
XRP Ledgerは、XRPの価値が長期的に変化することを見越して、最低トランザクションコストを変更するしくみを備えています。変更はすべて、コンセンサスプロセスによる承認が必要です。詳細は、[手数料の投票](fee-voting.html)を参照してください。
|
||||
|
||||
|
||||
## 関連項目
|
||||
|
||||
- **コンセプト:**
|
||||
- [準備金](reserves.html)
|
||||
- [手数料投票](fee-voting.html)
|
||||
- [トランザクションキュー](transaction-queue.html)
|
||||
- **チュートリアル:**
|
||||
- [信頼できるトランザクションの送信](reliable-transaction-submission.html)
|
||||
- **リファレンス:**
|
||||
- [feeメソッド][]
|
||||
- [server_infoメソッド][]
|
||||
- [FeeSettingsオブジェクト](feesettings.html)
|
||||
- [SetFee疑似トランザクション][]
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
@@ -0,0 +1,43 @@
|
||||
# Creating Accounts
|
||||
|
||||
There is not a dedicated "create account" transaction. The `Payment` transaction automatically creates a new account if a payment sends XRP equal to or greater than the account reserve to a mathematically valid address that does not already have an account. This is called _funding_ an account, and creates an AccountRoot object in the ledger. No other transaction can create an account.
|
||||
|
||||
**Caution:** Funding an account _does not_ give you any special privileges over that account. Whoever has the secret key corresponding to the account's address has full control over the account and all XRP it contains. For some addresses, it is possible that no one has the secret key, in which case the account is a black hole and the XRP is lost forever.
|
||||
|
||||
The typical way to get an account in the XRP Ledger is as follows:
|
||||
|
||||
1. Generate a key pair from a strong source of randomness and calculate the address of that key pair. (For example, you can use the `wallet_propose` method to do this.)
|
||||
|
||||
2. Have someone who already has an account in the XRP Ledger send XRP to the address you generated.
|
||||
|
||||
- For example, you can buy XRP in a private exchange, then withdraw XRP from the exchange to the address you specified.
|
||||
|
||||
**Caution:** The first time you receive XRP at your own XRP Ledger address, you must pay the account reserve (currently 10 XRP), which locks up that amount of XRP indefinitely. In contrast, private exchanges usually hold all their customers' XRP in a few shared XRP Ledger accounts, so customers don't have to pay the reserve for individual accounts at the exchange. Before withdrawing, consider whether having your own account directly on the XRP Ledger is worth the price.
|
||||
|
||||
|
||||
|
||||
## Transaction History
|
||||
|
||||
In the XRP Ledger, transaction history is tracked by a "thread" of transactions linked by a transaction's identifying hash and the ledger index. The `AccountRoot` ledger object has the identifying hash and ledger of the transaction that most recently modified it; the metadata of that transaction includes the previous state of the `AccountRoot` node, so it is possible to iterate through the history of a single account this way. This transaction history includes any transactions that modify the `AccountRoot` node directly, including:
|
||||
|
||||
- Transactions sent by the account, because they modify the account's `Sequence` number. These transactions also modify the account's XRP balance because of the [transaction cost](../transactions/transaction-cost.md).
|
||||
- Transactions that modified the account's XRP balance, including incoming `Payment` transactions and other types of transactions such as `PaymentChannelClaim` and `EscrowFinish`.
|
||||
|
||||
The _conceptual_ transaction history of an account also includes transactions that modified the account's owned objects and non-XRP balances. These objects are separate ledger objects, each with their own thread of transactions that affected them. If you have an account's full ledger history, you can follow it forward to find the ledger objects created or modified by it. A "complete" transaction history includes the history of objects owned by a transaction, such as:
|
||||
|
||||
- `RippleState` objects (Trust Lines) connected to the account.
|
||||
- `DirectoryNode` objects, especially the owner directory tracking the account's owned objects.
|
||||
- `Offer` objects, representing the account's outstanding currency-exchange orders in the decentralized exchange
|
||||
- `PayChannel` objects, representing asynchronous payment channels to and from the account
|
||||
- `Escrow` objects, representing held payments to or from the account that are locked by time or a crypto-condition.
|
||||
- `SignerList` objects, representing lists of addresses that can authorize transactions for the account by multi-signing.
|
||||
|
||||
|
||||
## Address Encoding
|
||||
|
||||
**Tip:** These technical details are only relevant for people building low-level library software for XRP Ledger compatibility!
|
||||
|
||||
[[Source]](https://github.com/ripple/rippled/blob/35fa20a110e3d43ffc1e9e664fc9017b6f2747ae/src/ripple/protocol/impl/AccountID.cpp#L109-L140 "Source")
|
||||
|
||||
XRP Ledger addresses are encoded using base58 with the _dictionary_ `rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz`. Since the XRP Ledger encodes several types of keys with base58, it prefixes the encoded data with a one-byte "type prefix" (also called a "version prefix") to distinguish them. The type prefix causes addresses to usually start with different letters in base58 format.
|
||||
|
||||
@@ -0,0 +1,23 @@
|
||||
# Deleting Accounts
|
||||
|
||||
The DeletableAccounts amendment (enabled 2020-05-08) made it possible to delete accounts.
|
||||
|
||||
To be deleted, an account must meet the following requirements:
|
||||
|
||||
- The account's `Sequence` number plus 256 must be less than the current `Ledger Index`.
|
||||
- The account must not be linked to any of the following types of ledger objects (as a sender or receiver):
|
||||
- `Escrow`
|
||||
- `PayChannel`
|
||||
- `RippleState`
|
||||
- `Check`
|
||||
- The account must own fewer than 1000 objects in the ledger.
|
||||
- The `AccountDelete` transaction must pay a special transaction cost equal to at least the owner reserve for one item (currently 2 XRP).
|
||||
|
||||
After an account is deleted, you can recreate the account in the ledger through the normal method of creating accounts. An account that has been deleted and recreated is no different than an account created for the first time.
|
||||
|
||||
**Warning:** The `AccountDelete` transaction's transaction cost always applies when the transaction is included in a validated ledger, even if the transaction failed because the account does not meet the requirements to be deleted. To greatly reduce the chances of paying the high transaction cost if the account cannot be deleted, submit the transaction with `fail_hard` enabled.
|
||||
|
||||
Unlike Bitcoin and many other cryptocurrencies, each new version of the XRP Ledger's public ledger chain contains the full state of the ledger, which increases in size with each new account. For that reason, you should not create new XRP Ledger accounts unless necessary. You can recover some of an account's 10 XRP reserve by deleting the account, but you must still destroy at least 2 XRP to do so.
|
||||
|
||||
Institutions who send and receive value on behalf of many users can use **Source Tags** and **Destination Tags** to distinguish payments from and to their customers while only using one (or a handful) of accounts in the XRP Ledger.
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
# Account Structure
|
||||
|
||||
The core elements of an account are:
|
||||
|
||||
- An identifying **address**, such as `rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn`.
|
||||
- An **XRP balance**. Some of this XRP is set aside for the account reserve.
|
||||
- A **sequence number**, which helps make sure any transactions this account sends are applied in the correct order and only once. To execute a transaction, the transaction's sequence number and its sender's sequence number must match. Then, as part of applying the transaction, the account's sequence number increases by 1.
|
||||
- A **history of transactions** that affected this account and its balances.
|
||||
- One or more ways to authorize transactions, possibly including:
|
||||
- A master key pair intrinsic to the account. (This can be disabled, but not changed.)
|
||||
- A "regular" key pair that can be rotated.
|
||||
- A signer list for multi-signing. (Stored separately from the account's core data.)
|
||||
|
||||
In the ledger's data tree, an account's core data is stored in the AccountRoot ledger object type. An account can also be the owner (or partial owner) of several other types of data.
|
||||
|
||||
**Tip:** An "Account" in the XRP Ledger is somewhere between the financial usage (like "bank account") and the computing usage (like "UNIX account"). Non-XRP currencies and assets are not stored in an XRP Ledger Account itself; each such asset is stored in an accounting relationship called a "Trust Line" that connects two parties.
|
||||
|
||||
## Address Encoding
|
||||
|
||||
**Tip:** These technical details are only relevant for people building low-level library software for XRP Ledger compatibility!
|
||||
|
||||
[[Source]](https://github.com/ripple/rippled/blob/35fa20a110e3d43ffc1e9e664fc9017b6f2747ae/src/ripple/protocol/impl/AccountID.cpp#L109-L140 "Source")
|
||||
|
||||
XRP Ledger addresses are encoded using `base58` with the _dictionary_ `rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz`. Since the XRP Ledger encodes several types of keys with base58, it prefixes the encoded data with a one-byte "type prefix" (also called a "version prefix") to distinguish them. The type prefix causes addresses to usually start with different letters in base58 format.
|
||||
@@ -0,0 +1,80 @@
|
||||
# Account Types
|
||||
|
||||
In the XRP Ledger, financial institutions typically use multiple XRP Ledger accounts to minimize the risk associated with a compromised secret key. The industry standard is to separate roles as follows:
|
||||
|
||||
* One *issuing account*, also known as a "cold wallet." This account is the hub of the financial institution's accounting relationships in the ledger, but sends as few transactions as possible.
|
||||
* One or more *operational accounts*, also known as "hot wallets." Automated, internet-connected systems use the secret keys to these accounts to conduct day-to-day business like transfers to customers and partners.
|
||||
* Optional *standby accounts*, also known as "warm wallets." Trusted human operators use these accounts to transfer money to the operational accounts.
|
||||
|
||||
## Issuing Account
|
||||
|
||||
The issuing account is like a vault. Partners, customers, and operational accounts create trust lines to the issuing account, but this account sends as few transactions as possible. Periodically, a human operator creates and signs a transaction from the issuing account to refill the balances of a standby or operational account. Ideally, the secret key used to sign these transactions should never be accessible from any internet-connected computer.
|
||||
|
||||
Unlike a vault, the issuing account can receive payments directly from customers and partners. Since all transactions in the XRP Ledger are public, automated systems can watch for payments to the issuing account without needing a secret key.
|
||||
|
||||
### Issuing Account Compromise
|
||||
|
||||
If a malicious actor learns the secret key behind a institution's issuing account, that actor can create new tokens and send them to users or trade them in the decentralized exchange. This can make a stablecoin issuer insolvent. It can become difficult for the financial institution to distinguish legitimately-obtained tokens and redeem them fairly. If a financial institution loses control of its issuing account, the institution must create a new issuing account, and all users who have trust lines to the old issuing account must create new trust lines with the new account.
|
||||
|
||||
### Multiple Issuing Accounts
|
||||
|
||||
A financial institution can issue more than one type of token in the XRP Ledger from a single issuing account. However, there are some settings that apply equally to all (fungible) tokens issued from an account, including the percentage for [transfer fees](../tokens/transfer-fees.md) and the [global freeze](../tokens/freezing-tokens.md) status. If the financial institution wants the flexibility to manage settings differently for each type of token, the institution must multiple issuing accounts.
|
||||
|
||||
|
||||
## Operational Accounts
|
||||
|
||||
An operational account is like a cash register. It makes payments on behalf of the institution by transferring tokens to customers and partners. To sign transactions automatically, the secret key for an operational account must be stored on a server that is connected to the internet. (The secret key can be stored encrypted, but the server must decrypt it to sign transactions.) Customers and partners do not, and should not, create trust lines to an operational account.
|
||||
|
||||
Each operational account has a limited balance of tokens and XRP. When the balance of an operational account gets low, the financial institution refills it by sending a payment from the issuing account or a standby account.
|
||||
|
||||
### Operational Account Compromise
|
||||
|
||||
If a malicious actor learns the secret key behind an operational account, the financial institution can only lose as much as that operational account holds. The institution can switch to a new operational account with no action from customers and partners.
|
||||
|
||||
|
||||
## Standby Accounts
|
||||
|
||||
Another optional step that an institution can take to balance risk and convenience is to use "standby accounts" as an intermediate step between the issuing account and operational accounts. The institution can fund additional XRP Ledger accounts as standby accounts, whose keys are not available to always-online servers, but are entrusted to different trusted users.
|
||||
|
||||
When an operational account is running low on funds (either tokens or XRP), a trusted user can use a standby account to refill the operational account's balance. When a standby accounts run low on funds, the institution can use the issuing account to send more funds to a standby account in a single transaction, and the standby accounts can distribute those funds among themselves if necessary. This improves security of the issuing account, allowing it to make fewer total transactions, without leaving too much money in the control of a single automated system.
|
||||
|
||||
As with operational accounts, a standby account must have an accounting relationship with the issuing account, and not with customers or partners. All precautions that apply to operational accounts also apply to standby accounts.
|
||||
|
||||
### Standby Account Compromise
|
||||
|
||||
If a standby account is compromised, the consequences are like an operational account being compromised. A malicious actor can steal any balances possessed by the standby account, and the financial institution can change to a new standby account with no action from customers and partners.
|
||||
|
||||
## Funds Lifecycle
|
||||
|
||||
When a token issuer follows this separation of roles, funds tend to flow in specific directions, as in the following diagram:
|
||||
|
||||
<!--
|
||||
{{ include_svg("../../../img/issued-currency-funds-flow.svg", "Diagram: Funds flow from the issuing account to standby accounts, to operational accounts, to customer and partner accounts, and finally back to the issuing account.")}}
|
||||
-->
|
||||
|
||||
The issuing account creates tokens by sending payments to standby accounts. These tokens have negative value from the perspective of the issuing account, since they (often) represent obligations. The same tokens have positive value from other perspectives, including from the perspective of a standby account.
|
||||
|
||||
The standby accounts, which are operated by actual humans, send those tokens to operational accounts. This step allows the issuing account to be used as little as possible after this point, while having at least some tokens available on standby.
|
||||
|
||||
Operational accounts, which are operated by automated systems, send payments to other counterparties, such as liquidity providers, partners, and other customers. Those counterparties may send funds freely among themselves multiple times.
|
||||
|
||||
As always, token payments must "ripple through" the issuer across trust lines with sufficient limits.
|
||||
|
||||
Eventually, someone sends tokens back to the issuer. This destroys those tokens, reducing the issuer's obligations in the XRP Ledger. If the token is a stablecoin, this is the first step of redeeming the tokens for the corresponding off-ledger assets.
|
||||
|
||||
<!--
|
||||
|
||||
## See Also
|
||||
|
||||
- **Concepts:**
|
||||
- [Accounts](accounts.html)
|
||||
- [Cryptographic Keys](cryptographic-keys.html)
|
||||
- **Tutorials:**
|
||||
- [Become an XRP Ledger Gateway](become-an-xrp-ledger-gateway.html)
|
||||
- [Assign a Regular Key Pair](assign-a-regular-key-pair.html)
|
||||
- [Change or Remove a Regular Key Pair](change-or-remove-a-regular-key-pair.html)
|
||||
- **References:**
|
||||
- [account_info method][]
|
||||
- [SetRegularKey transaction][]
|
||||
- [AccountRoot object](accountroot.html)
|
||||
-->
|
||||
21
content/concepts/understanding-xrpl/accounts/accounts.md
Normal file
21
content/concepts/understanding-xrpl/accounts/accounts.md
Normal file
@@ -0,0 +1,21 @@
|
||||
# Accounts
|
||||
|
||||
An "Account" in the XRP Ledger represents a holder of XRP and a sender of transactions.
|
||||
|
||||
## Account Structure
|
||||
|
||||
The core elements of an account are:
|
||||
|
||||
- An identifying **address**, such as `rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn`.
|
||||
- An **XRP balance**. Some of this XRP is set aside for the account reserve.
|
||||
- A **sequence number**, which helps make sure any transactions this account sends are applied in the correct order and only once. To execute a transaction, the transaction's sequence number and its sender's sequence number must match. Then, as part of applying the transaction, the account's sequence number increases by 1.
|
||||
- A **history of transactions** that affected this account and its balances.
|
||||
- One or more ways to authorize transactions, possibly including:
|
||||
- A master key pair intrinsic to the account. (This can be disabled, but not changed.)
|
||||
- A "regular" key pair that can be rotated.
|
||||
- A signer list for multi-signing. (Stored separately from the account's core data.)
|
||||
|
||||
In the ledger's data tree, an account's core data is stored in the AccountRoot ledger object type. An account can also be the owner (or partial owner) of several other types of data.
|
||||
|
||||
**Tip:** An "Account" in the XRP Ledger is somewhere between the financial usage (like "bank account") and the computing usage (like "UNIX account"). Non-XRP currencies and assets are not stored in an XRP Ledger Account itself; each such asset is stored in an accounting relationship called a "Trust Line" that connects two parties.
|
||||
|
||||
46
content/concepts/understanding-xrpl/accounts/addresses.md
Normal file
46
content/concepts/understanding-xrpl/accounts/addresses.md
Normal file
@@ -0,0 +1,46 @@
|
||||
## Addresses
|
||||
|
||||
Accounts in the XRP Ledger are identified by an address in the XRP Ledger's base58 format. The address is derived from the account's master [public key](https://en.wikipedia.org/wiki/Public-key_cryptography), which is in turn derived from a secret key. An address is represented as a string in JSON and has the following characteristics:
|
||||
|
||||
* Between 25 and 35 characters in length
|
||||
* Starts with the character `r`
|
||||
* Uses alphanumeric characters, excluding the number "`0`" capital letter "`O`", capital letter "`I`", and lowercase letter "`l`"
|
||||
* Case-sensitive
|
||||
* Includes a 4-byte checksum so that the probability of generating a valid address from random characters is approximately 1 in 2<sup>32</sup>
|
||||
|
||||
> **Note:** The XRP community has proposed an **X**-address format that "packs" a destination tag into the address. These addresses start with an `X` (for the mainnet) or a `T` (for the [testnet](../networks/parallel-networks.md)). Exchanges and wallets can use X-addresses to represent all the data a customer needs to know in one value. For more information, see the [X-address format site](https://xrpaddress.info/) and [codec](https://github.com/xrp-community/xrpl-tagged-address-codec).
|
||||
>
|
||||
> The XRP Ledger protocol only supports "classic" addresses natively, but many client libraries support X-addresses too.
|
||||
|
||||
|
||||
For more information, see [Accounts](accounts.md).
|
||||
|
||||
|
||||
Any valid address can become an account in the XRP Ledger by being funded. You can also use an address that has not been funded to represent a regular key or a member of a signer list. Only a funded account can be the sender of a transaction.
|
||||
|
||||
Creating a valid address is a strictly mathematical task starting with a key pair. You can generate a key pair and calculate its address entirely offline without communicating to the XRP Ledger or any other party. The conversion from a public key to an address involves a one-way hash function, so it is possible to confirm that a public key matches an address but it is impossible to derive the public key from the address alone. (This is part of the reason why signed transactions include the public key _and_ the address of the sender.)
|
||||
|
||||
For more technical details of how to calculate an XRP Ledger address, see [Address Encoding](#address-encoding).
|
||||
|
||||
|
||||
## Address Encoding
|
||||
|
||||
**Tip:** These technical details are only relevant for people building low-level library software for XRP Ledger compatibility!
|
||||
|
||||
[[Source]](https://github.com/ripple/rippled/blob/35fa20a110e3d43ffc1e9e664fc9017b6f2747ae/src/ripple/protocol/impl/AccountID.cpp#L109-L140 "Source")
|
||||
|
||||
XRP Ledger addresses are encoded using `base58` with the _dictionary_ `rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz`. Since the XRP Ledger encodes several types of keys with base58, it prefixes the encoded data with a one-byte "type prefix" (also called a "version prefix") to distinguish them. The type prefix causes addresses to usually start with different letters in base58 format.
|
||||
|
||||
|
||||
### Special Addresses
|
||||
|
||||
Some addresses have special meaning, or historical uses, in the XRP Ledger. In many cases, these are "black hole" addresses, meaning the address is not derived from a known secret key. Since it is effectively impossible to guess a secret key from only an address, any XRP possessed by black hole addresses is lost forever.
|
||||
|
||||
|
||||
| Address | Name | Meaning | Black Hole? |
|
||||
|-------------------------------|------|---------|-------------|
|
||||
| `rrrrrrrrrrrrrrrrrrrrrhoLvTp` | ACCOUNT\_ZERO | An address that is the XRP Ledger's base58 encoding of the value `0`. In peer-to-peer communications, `rippled` uses this address as the issuer for XRP. | Yes |
|
||||
| `rrrrrrrrrrrrrrrrrrrrBZbvji` | ACCOUNT\_ONE | An address that is the XRP Ledger's base58 encoding of the value `1`. In the ledger, [RippleState entries](ripplestate.html) use this address as a placeholder for the issuer of a trust line balance. | Yes |
|
||||
| `rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh` | The genesis account | When `rippled` starts a new genesis ledger from scratch (for example, in stand-alone mode), this account holds all the XRP. This address is generated from the seed value `masterpassphrase` which is [hard-coded](https://github.com/ripple/rippled/blob/94ed5b3a53077d815ad0dd65d490c8d37a147361/src/ripple/app/ledger/Ledger.cpp#L184). | No |
|
||||
| `rrrrrrrrrrrrrrrrrNAMEtxvNvQ` | Ripple Name reservation black-hole | In the past, Ripple asked users to send XRP to this account to reserve Ripple Names.| Yes |
|
||||
| `rrrrrrrrrrrrrrrrrrrn5RM1rHd` | NaN Address | Previous versions of [ripple-lib](https://github.com/XRPLF/xrpl.js) generated this address when encoding the value [NaN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN) using the XRP Ledger's base58 string encoding format. | Yes |
|
||||
3
content/concepts/understanding-xrpl/accounts/balances.md
Normal file
3
content/concepts/understanding-xrpl/accounts/balances.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# Balances
|
||||
|
||||
Placeholder for details of the account balances.
|
||||
@@ -0,0 +1,257 @@
|
||||
# Cryptographic Keys
|
||||
|
||||
In the XRP Ledger, a digital signature _authorizes_ a [transaction](../transactions/transactions.md) to do a specific set of actions. Only signed transactions can be submitted to the network and included in a validated ledger.
|
||||
|
||||
To make a digital signature, you use a cryptographic key pair associated with the transaction's sending account. A key pair may be generated using any of the XRP Ledger's supported cryptographic signing algorithms signing-algorithms. A key pair can be used as a master key pair, regular key pair, or a member of a signer list, regardless of what algorithm was used to generate it.
|
||||
|
||||
**Warning:** It is important to maintain proper security over your cryptographic keys. Digital signatures are the only way of authorizing transactions in the XRP Ledger, and there is no privileged administrator who can undo or reverse any transactions after they have applied. If someone else knows the seed or private key of your XRP Ledger account, that person can create digital signatures to authorize any transaction the same as you could.
|
||||
|
||||
## Generating Keys
|
||||
|
||||
Many [client libraries](../../../references/client-libraries.md) and applications can generate a key pair suitable for use with the XRP Ledger. However, you should only use keypairs that were generated with devices and software you trust. Compromised applications can expose your secret to malicious users who can then send transactions from your account later.
|
||||
|
||||
|
||||
## Key Components
|
||||
|
||||
A cryptographic key pair is a **private key** and a **public key** that are connected mathematically through a key derivation process. Each key is a number; the private key should be chosen using a strong source of randomness. The cryptographic signing algorithm defines the key derivation process and sets constraints on the numbers that can be cryptographic keys.
|
||||
|
||||
When dealing with the XRP Ledger, you may also use some related values such as a passphrase, seed, account ID, or address.
|
||||
|
||||
{{ include_svg("../../../img/cryptographic-keys.svg", "Diagram: Passphrase → Seed → Private Key → Public Key → Account ID ←→ Address") }}
|
||||
_Figure: A simplified view of the relationship between cryptographic key values._
|
||||
|
||||
|
||||
The passphrase, seed, and private key are **secrets**: if you know any of these values for an account, you can make valid signatures and you have full control over that account. If you own an account, be **very careful** with your account's secret information. If you don't have it, you can't use your account. If someone else can access it, they can take control of your account.
|
||||
|
||||
The public key, account ID, and address are public information. There are some situations where you might temporarily keep a public key to yourself, but eventually you need to publish it as part of a transaction so that the XRP Ledger can verify the signature and process the transaction.
|
||||
|
||||
<!--
|
||||
For more technical details of how key derivation works, see [Key Derivation](#key-derivation).
|
||||
-->
|
||||
|
||||
### Passphrase
|
||||
|
||||
You can, optionally, use a passphrase or some other input as a way of choosing a seed or private key. This is less secure than choosing the seed or private key completely at random, but there are some rare cases where you want to do this. (For example, in 2018 "XRPuzzler" gave away XRP to the first person [to solve a puzzle](https://bitcoinexchangeguide.com/cryptographic-puzzle-creator-xrpuzzler-offers-137-xrp-reward-to-anyone-who-can-solve-it/); he used the puzzle's solution as the passphrase to an account holding the prize XRP.) <!-- SPELLING_IGNORE: xrpuzzler -->
|
||||
|
||||
The passphrase is secret information, so you must protect it very carefully. Anyone who knows an address's passphrase has effectively full control over the address.
|
||||
|
||||
### Seed
|
||||
|
||||
A _seed_ value is a compact value that is used to derive the actual private and public keys for an account. In a `wallet_propose` method response, the `master_key`, `master_seed`, and `master_seed_hex` all represent the same seed value, in various formats. Any of these formats can be used to sign transactions in the rippled APIs and some [other XRP Ledger software](../xrpl/xrpl-ecosystem.md). Despite being prefixed with `master_`, the keys this seed represents are not necessarily the master keys for an account; you can use a key pair as a regular key or a member of a multi-signing list as well.
|
||||
|
||||
The seed value is secret information, so you must protect it very carefully. Anyone who has knows an address's seed value has effectively full control over that address.
|
||||
|
||||
### Private Key
|
||||
|
||||
The _private key_ is the value that is used to create a digital signature. Most XRP Ledger software does not explicitly show the private key, and derives the private key from the seed value when necessary. It is technically possible to save the private key instead of the seed and use that to sign transactions directly, but this usage is rare.
|
||||
|
||||
Like the seed, the private key is secret information, so you must protect it very carefully. Anyone who has knows an address's private key has effectively full control over that address.
|
||||
|
||||
### Public Key
|
||||
|
||||
The _public key_ is the value used to verify the authenticity of a digital signature. The public key is derived from the private key as part of key derivation. In a `wallet_propose` method response, the `public_key` and `public_key_hex` both represent the same public key value.
|
||||
|
||||
Transactions in the XRP Ledger must include the public keys so that the network can verify the transactions' signatures. The public key cannot be used to create valid signatures, so it is safe to share publicly.
|
||||
|
||||
|
||||
### Account ID and Address
|
||||
|
||||
The **Account ID** is the core identifier for an account or a key pair. It is derived from the public key. In the XRP Ledger protocol, the Account ID is 20 bytes of binary data. Most XRP Ledger APIs represent the Account ID as an address, in one of two formats:
|
||||
|
||||
- A "classic address" writes an Account ID in base58 with a checksum. In a `wallet_propose method` response, this is the `account_id` value.
|
||||
- An "X-Address" combines an Account ID _and_ a Destination Tag and writes the combined value in base58 with a checksum.
|
||||
|
||||
The checksum in both formats is there so that small changes result in an invalid address, instead of changing it to refer to a different, but still potentially valid, account. This way, if you make a typo or a transmission error occurs, you don't send money to the wrong place.
|
||||
|
||||
It is important to know that not all Account IDs (or addresses) refer to accounts in the ledger. Deriving keys and addresses is purely a mathematical operation. For an account to have a record in the XRP Ledger, it must receive a payment of XRP that funds its reserve requirement. An account cannot send any transactions until after it has been funded.
|
||||
|
||||
Even if an Account ID or address does not refer to a funded account, you _can_ use that Account ID or address to represent a regular key pair or a member of a signer list.
|
||||
|
||||
### Key Type
|
||||
|
||||
The XRP Ledger supports more than one cryptographic signing algorithm. Any given key pair is only valid for a specific cryptographic signing algorithm. Some private keys may technically qualify as valid keys for more than one algorithm, but those private keys would have different public keys for each algorithm, and you should not reuse private keys anyway.
|
||||
|
||||
The `key_type` field in the `wallet_propose method` refers to the cryptographic signing algorithm to use.
|
||||
|
||||
|
||||
## Master Key Pair
|
||||
|
||||
The master key pair consists of a private key and a public key. The address of an account is derived from the account's master key pair, so they are intrinsically related. You cannot change or remove the master key pair, but you can disable it.
|
||||
|
||||
The `wallet_propose method` is one way of generating a master key pair. The response from this method shows the account's seed, address, and master public key together.
|
||||
|
||||
<!-- For some other ways of setting up master key pairs, see [Set Up Secure Signing](set-up-secure-signing.html). -->
|
||||
|
||||
**Warning:** If a malicious actor learns your master private key (or seed), they have full control over your account, unless your master key pair is disabled. They can take all the money your account holds and do other irreparable harm. Treat your secret values with care!
|
||||
|
||||
Because changing a master key pair is impossible, you should treat it with care proportionate to the value it holds. A good practice is to keep your master key pair offline and set up a regular key pair to sign transactions from your account instead. By keeping the master key pair enabled but offline, you can be reasonably certain that no one can get access to it using the internet, but you can still go find it to use in an emergency.
|
||||
|
||||
Keeping your master key pair offline means not putting the secret information (passphrase, seed, or private key) anywhere that malicious actors can get access to it. In general, this means it is not within reach of a computer program that interacts with the internet at large. For example, you could keep it on an air-gapped machine that never connects to the internet, on a piece of paper stored in a safe, or have it completely memorized. (Memorization has some drawbacks, though, including making it impossible to pass the key on after you are dead.)
|
||||
|
||||
|
||||
|
||||
### Special Permissions
|
||||
|
||||
**Only** the master key pair can authorize transactions to do certain things:
|
||||
|
||||
- Send an account's very first transaction, because accounts cannot be initialized with another way of authorizing transactions.
|
||||
|
||||
- Disable the master key pair.
|
||||
|
||||
- Permanently give up the ability to [freeze](../tokens/freezing-tokens.md#no-freeze).
|
||||
|
||||
- Send a special key reset transaction with a transaction cost of 0 XRP.
|
||||
|
||||
A regular key or multi-signature can do anything else the same as the master key pair. Notably, after you have disabled the master key pair, you can re-enable it using a regular key pair or multi-signature. You can also [delete an account](account-deleting.md) if it meets the requirements for deletion.
|
||||
|
||||
|
||||
## Regular Key Pair
|
||||
|
||||
An XRP Ledger account can authorize a secondary key pair, called a _regular key pair_. After doing so, you can use either the master key pair or the regular key to authorize transactions. You can remove or replace your regular key pair at any time without changing the rest of your account.
|
||||
|
||||
A regular key pair can authorize most of the same types of transactions as the master key pair, with certain exceptions. For example, a regular key pair _can_ authorize a transaction to change the regular key pair.
|
||||
|
||||
A good security practice is to save your master private key somewhere offline, and use a regular key pair most of the time. As a precaution, you can change the regular key pair regularly. If a malicious user learns your regular private key, you can get the master key pair out of offline storage and use it to change or remove the regular key pair. This way, you can regain control of your account. Even if you are not fast enough to stop the malicious user from stealing your money, at least you don't need to move to a new account and re-create all your settings and relationships from scratch.
|
||||
|
||||
Regular key pairs have the same format as master key pairs. You generate them the same way (for example, using the `wallet_propose` method). The only difference is that a regular key pair is not intrinsically tied to the account it signs transactions for. It is possible (but not a good idea) to use the master key pair from one account as the regular key pair for another account.
|
||||
|
||||
The `SetRegularKey` transaction assigns or changes the regular key pair for an account.
|
||||
|
||||
<!--
|
||||
For a tutorial on assigning or changing a regular key pair, see [Assign a Regular Key Pair](assign-a-regular-key-pair.html).
|
||||
-->
|
||||
|
||||
## Signing Algorithms
|
||||
|
||||
Cryptographic key pairs are always tied to a specific signing algorithm, which defines the mathematical relationships between the secret key and the public key. Cryptographic signing algorithms have the property that, given the current state of cryptographic techniques, it is "easy" to use a secret key to calculate a matching public key, but it is effectively impossible to compute a matching secret key by starting from a public key. <!-- STYLE_OVERRIDE: easy -->
|
||||
|
||||
The XRP Ledger supports the following cryptographic signing algorithms:
|
||||
|
||||
| Key Type | Algorithm | Description |
|
||||
|-------------|-----------|---|
|
||||
| `secp256k1` | [ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) using the elliptic curve [secp256k1](https://en.bitcoin.it/wiki/Secp256k1) | This is the same scheme Bitcoin uses. The XRP Ledger uses these key types by default. |
|
||||
| `ed25519` | [EdDSA](https://tools.ietf.org/html/rfc8032) using the elliptic curve [Ed25519](https://ed25519.cr.yp.to/) | This is a newer algorithm which has better performance and other convenient properties. Since Ed25519 public keys are one byte shorter than secp256k1 keys, `rippled` prefixes Ed25519 public keys with the byte `0xED` so both types of public key are 33 bytes. |
|
||||
|
||||
When you generate a key pair with the `wallet_propose` method, you can specify the `key_type` to choose which cryptographic signing algorithm to use to derive the keys. If you generated a key type other than the default, you must also specify the `key_type` when signing transactions.
|
||||
|
||||
The supported types of key pairs can be used interchangeably throughout the XRP Ledger as master key pairs, regular key pairs, and members of signer lists. The process of deriving an address is the same for secp256k1 and Ed25519 key pairs.
|
||||
|
||||
|
||||
### Future Algorithms
|
||||
|
||||
In the future, it is likely that the XRP Ledger will need new cryptographic signing algorithms to keep up with developments in cryptography. For example, if quantum computers using [Shor's algorithm](https://en.wikipedia.org/wiki/Shor's_algorithm) (or something similar) will soon be practical enough to break elliptic curve cryptography, XRP Ledger developers can add a cryptographic signing algorithm that isn't easily broken. As of mid 2020, there's no clear first choice "quantum-resistant" signing algorithm and quantum computers are not yet practical enough to be a threat, so there are no immediate plans to add any specific algorithms. <!-- STYLE_OVERRIDE: will, easily -->
|
||||
|
||||
|
||||
## Key Derivation
|
||||
|
||||
The process of deriving a key pair depends on the signing algorithm. In all cases, keys are generated from a _seed_ value that is 16 bytes (128 bits) in length. The seed value can be completely random (recommended) or it can be derived from a specific passphrase by taking the [SHA-512 hash][Hash] and keeping the first 16 bytes (like [SHA-512Half][], but keeping only 128 bits instead of 256 bits of the output).
|
||||
|
||||
### Sample Code
|
||||
|
||||
The key derivation processes described here are implemented in multiple places and programming languages:
|
||||
|
||||
- In C++ in the `rippled` code base:
|
||||
- [Seed definition](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/Seed.h)
|
||||
- [General & Ed25519 key derivation](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/impl/SecretKey.cpp)
|
||||
- [secp256k1 key derivation](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/impl/SecretKey.cpp)
|
||||
- In Python 3 in [this repository's code samples section]({{target.github_forkurl}}/blob/{{target.github_branch}}/content/_code-samples/key-derivation/py/key_derivation.py).
|
||||
- In JavaScript in the [`ripple-keypairs`](https://github.com/ripple/ripple-keypairs/) package.
|
||||
|
||||
### Ed25519 Key Derivation
|
||||
[[Source]](https://github.com/ripple/rippled/blob/fc7ecd672a3b9748bfea52ce65996e324553c05f/src/ripple/protocol/impl/SecretKey.cpp#L203 "Source")
|
||||
|
||||
{{ include_svg("img/key-derivation-ed25519.svg", "Passphrase → Seed → Secret Key → Prefix + Public Key") }}
|
||||
|
||||
1. Calculate the `SHA-512Half` of the seed value. The result is the 32-byte secret key.
|
||||
|
||||
**Tip:** All 32-byte numbers are valid Ed25519 secret keys. However, only numbers that are chosen randomly enough are secure enough to be used as secret keys.
|
||||
|
||||
2. To calculate an Ed25519 public key, use the standard public key derivation for [Ed25519](https://ed25519.cr.yp.to/software.html) to derive the 32-byte public key.
|
||||
|
||||
**Caution:** As always with cryptographic algorithms, use a standard, well-known, publicly-audited implementation whenever possible. For example, [OpenSSL](https://www.openssl.org/) has implementations of core Ed25519 and secp256k1 functions.
|
||||
|
||||
3. Prefix the 32-byte public key with the single byte `0xED` to indicate an Ed25519 public key, resulting in 33 bytes.
|
||||
|
||||
If you are implementing code to sign transactions, remove the `0xED` prefix and use the 32-byte key for the actual signing process.
|
||||
|
||||
4. When serializing an account public key to base58, use the account public key prefix `0x23`.
|
||||
|
||||
Validator ephemeral keys cannot be Ed25519.
|
||||
|
||||
### secp256k1 Key Derivation
|
||||
[[Source]](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/impl/SecretKey.cpp "Source")
|
||||
|
||||
{{ include_svg("../../../img/key-derivation-secp256k1.svg", "Passphrase → Seed → Root Key Pair → Intermediate Key Pair → Master Key Pair") }}
|
||||
|
||||
Key derivation for secp256k1 XRP Ledger account keys involves more steps than Ed25519 key derivation for a couple reasons:
|
||||
|
||||
- Not all 32-byte numbers are valid secp256k1 secret keys.
|
||||
- The XRP Ledger's reference implementation has an unused, incomplete framework for deriving a family of key pairs from a single seed value.
|
||||
|
||||
The steps to derive the XRP Ledger's secp256k1 account key pair from a seed value are as follows:
|
||||
|
||||
1. Calculate a "root key pair" from the seed value, as follows:
|
||||
|
||||
1. Concatenate the following in order, for a total of 20 bytes:
|
||||
- The seed value (16 bytes)
|
||||
- A "root sequence" value (4 bytes), as a big-endian unsigned integer. Use 0 as a starting value for the root sequence.
|
||||
|
||||
2. Calculate the SHA-512Half of the concatenated (seed+root sequence) value.
|
||||
|
||||
3. If the result is not a valid secp256k1 secret key, increment the root sequence by 1 and start over. [[Source]](https://github.com/ripple/rippled/blob/fc7ecd672a3b9748bfea52ce65996e324553c05f/src/ripple/crypto/impl/GenerateDeterministicKey.cpp#L103 "Source")
|
||||
|
||||
A valid secp256k1 key must not be zero, and it must be numerically less than the _secp256k1 group order_. The secp256k1 group order is the constant value `0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141`.
|
||||
|
||||
4. With a valid secp256k1 secret key, use the standard ECDSA public key derivation with the secp256k1 curve to derive the root public key. (As always with cryptographic algorithms, use a standard, well-known, publicly-audited implementation whenever possible. For example, [OpenSSL](https://www.openssl.org/) has implementations of core Ed25519 and secp256k1 functions.)
|
||||
|
||||
**Tip:** Validators use this root key pair. If you are calculating a validator's key pair, you can stop here. To distinguish between these two different types of public keys, the base58 serialization for validator public keys uses the prefix `0x1c`.
|
||||
|
||||
2. Convert the root public key to its 33-byte compressed form.
|
||||
|
||||
The uncompressed form of any ECDSA public key consists of a pair of 32-byte integers: an X coordinate, and a Y coordinate. The compressed form is the X coordinate and a one-byte prefix: `0x02` if the Y coordinate is even, or `0x03` if the Y coordinate is odd.
|
||||
|
||||
You can convert an uncompressed public key to the compressed form with the `openssl` commandline tool. For example, if the uncompressed public key is in the file `ec-pub.pem`, you can output the compressed form like this:
|
||||
|
||||
$ openssl ec -in ec-pub.pem -pubin -text -noout -conv_form compressed
|
||||
|
||||
3. Derive an "intermediate key pair" from the compressed root public key you, as follows:
|
||||
|
||||
1. Concatenate the following in order, for a total of 41 bytes:
|
||||
- The compressed root public key (33 bytes)
|
||||
- `0x00000000000000000000000000000000` (4 bytes of zeroes). (This value was intended to be used to derive different members of the same family, but in practice only the value 0 is used.)
|
||||
- A "key sequence" value (4 bytes), as a big-endian unsigned integer. Use 0 as a starting value for the key sequence.
|
||||
|
||||
2. Calculate the SHA-512Half of the concatenated value.
|
||||
|
||||
3. If the result is not a valid secp256k1 secret key, increment the key sequence by 1 and restart deriving the account's intermediate key pair.
|
||||
|
||||
4. With a valid secp256k1 secret key, use the standard ECDSA public key derivation with the secp256k1 curve to derive the intermediate public key. (As always with cryptographic algorithms, use a standard, well-known, publicly-audited implementation whenever possible. For example, [OpenSSL](https://www.openssl.org/) has implementations of core Ed25519 and secp256k1 functions.)
|
||||
|
||||
4. Derive the master public key pair by adding the intermediate public key to the root public key. Similarly, derive the secret key by adding the intermediate secret key to the root secret key.
|
||||
|
||||
- An ECDSA secret key is a very large integer, so you can calculate the sum of two secret keys by summing them modulo the secp256k1 group order.
|
||||
|
||||
- An ECDSA public key is a point on the elliptic curve, so you should use elliptic curve math to sum the points.
|
||||
|
||||
5. Convert the master public key to its 33-byte compressed form, as before.
|
||||
|
||||
6. When serializing an account's public key to its base58 format, use the account public key prefix, `0x23`.
|
||||
|
||||
See [Address Encoding](addresses.md#address-encoding) for information and sample code to convert from an account's public key to its address.
|
||||
|
||||
<!--
|
||||
|
||||
## See Also
|
||||
|
||||
- **Concepts:**
|
||||
- [Issuing and Operational Addresses](issuing-and-operational-addresses.html)
|
||||
- **Tutorials:**
|
||||
- [Assign a Regular Key Pair](assign-a-regular-key-pair.html)
|
||||
- [Change or Remove a Regular Key Pair](change-or-remove-a-regular-key-pair.html)
|
||||
- **References:**
|
||||
- [SetRegularKey transaction][]
|
||||
- [AccountRoot ledger object](accountroot.html)
|
||||
- [wallet_propose method][]
|
||||
- [account_info method][]
|
||||
|
||||
-->
|
||||
@@ -0,0 +1,111 @@
|
||||
# Deposit Authorization
|
||||
|
||||
_(Added by the DepositAuth amendment.)_
|
||||
|
||||
Deposit Authorization is an optional [account](accounts.md) setting in the XRP Ledger. If enabled, Deposit Authorization blocks all transfers from strangers, including transfers of XRP and [tokens](../tokens/tokens.md). An account with Deposit Authorization can only receive value in two ways:
|
||||
|
||||
- From accounts it has [preauthorized](#preauthorization).
|
||||
- By sending a transaction to receive the funds. For example, an account with Deposit Authorization could finish an escrow that was initiated by a stranger.
|
||||
|
||||
By default, new accounts have DepositAuth disabled and can receive XRP from anyone.
|
||||
|
||||
## Background
|
||||
|
||||
Financial services regulations and licenses may require that a business or entity must know the sender of all transactions it receives. This presents a challenge on a decentralized system like the XRP Ledger where participants are identified by pseudonyms which can be freely generated and the default behavior is for any address to be able to pay any other.
|
||||
|
||||
The Deposit Authorization flag introduces an option for those using the XRP Ledger to comply with such regulations without changing the fundamental nature of the decentralized ledger. With Deposit Authorization enabled, an account can only receive funds it explicitly approves by sending a transaction. The owner of an account using Deposit Authorization can perform the due diligence necessary to identify the sender of any funds _before_ sending the transaction that causes the account to receive the money.
|
||||
|
||||
When you have Deposit Authorization enabled, you can receive money from checks, escrow, and payment channels. In these transactions' "two-step" model, first the source sends a transaction to authorize sending funds, then the destination sends a transaction to authorize receiving those funds.
|
||||
|
||||
To receive money from `Payment` transactions when you have Deposit Authorization enabled, you must [preauthorize](#preauthorization) the senders of those Payments. _(Added by the `DepositPreauth` amendment.)_
|
||||
|
||||
## Recommended Usage
|
||||
|
||||
To get the full effect of Deposit Authorization, Ripple recommends also doing the following:
|
||||
|
||||
- Always maintain an XRP balance higher than the minimum reserve requirement.
|
||||
- Keep the Default Ripple flag in its default (disabled) state. Do not enable rippling on any trust lines. When sending TrustSet transactions, always use the `tfSetNoRipple` flag.
|
||||
- Do not place Offers. It is impossible to know in advance which matching offers will be consumed to execute such a trade. <!-- STYLE_OVERRIDE: will -->
|
||||
|
||||
## Precise Semantics
|
||||
|
||||
An account with Deposit Authorization enabled:
|
||||
|
||||
- **Cannot** be the destination of `Payment` transactions, with **the following exceptions**:
|
||||
- If the destination has [preauthorized](#preauthorization) the sender of the Payment. _(Added by the DepositPreauth amendment)_
|
||||
- If the account's XRP balance is equal to or below the minimum account reserve requirement, it can be the destination of an XRP Payment whose `Amount` is equal or less than the minimum account reserve (currently 10 XRP). This is to prevent an account from becoming "stuck" by being unable to send transactions but also unable to receive XRP. The account's owner reserve does not matter for this case.
|
||||
- Can receive XRP from `PaymentChannelClaim` transactions **only in the following cases**:
|
||||
- The sender of the `PaymentChannelClaim` transaction is the destination of the payment channel.
|
||||
- The destination of the `PaymentChannelClaim` transaction has [preauthorized](#preauthorization) the sender of the PaymentChannelClaim. _(Added by the DepositPreauth amendment)_
|
||||
- Can receive XRP from `EscrowFinish` transactions **only in the following cases**:
|
||||
- The sender of the `EscrowFinish` transaction is the destination of the escrow.
|
||||
- The destination of the `EscrowFinish` transaction has [preauthorized](#preauthorization) the sender of the `EscrowFinish`. _(Added by the DepositPreauth amendment)_
|
||||
- **Can** receive XRP or tokens by sending a `CheckCash` transaction. _(Added by the Checks amendment.)_
|
||||
- **Can** receive XRP or tokens by sending `OfferCreate` transactions.
|
||||
- If the account sends an OfferCreate transaction that is not fully executed immediately, it **can** receive the rest of the ordered XRP or token later when the offer is consumed by other accounts' `Payment` and `OfferCreate` transactions.
|
||||
- If the account has created any trust lines without the No Ripple flag enabled, or has enabled the Default Ripple flag and issued any currency, the account **can** receive the tokens of those trust lines in `Payment` transactions as a result of rippling. It cannot be the destination of those transactions.
|
||||
- In general, an account in the XRP Ledger **cannot** receive any non-XRP currencies in the XRP Ledger as long as all of the following are true. (This rule is not specific to the DepositAuth flag.)
|
||||
- The account has not created any trust lines with a nonzero limit.
|
||||
- The account has not issued tokens on trust lines created by others.
|
||||
- The account has not placed any offers.
|
||||
|
||||
The following table summarizes whether a transaction type can deposit money with DepositAuth enabled or disabled:
|
||||
|
||||
{% include '_snippets/depositauth-semantics-table.html' %}
|
||||
<!--{#_ #}-->
|
||||
|
||||
|
||||
## Enabling or Disabling Deposit Authorization
|
||||
|
||||
An account can enable deposit authorization by sending an `AccountSet` transaction with the `SetFlag` field set to the `asfDepositAuth` value (9). The account can disable deposit authorization by sending an `AccountSet` transaction with the `ClearFlag` field set to the `asfDepositAuth` value (9).
|
||||
|
||||
<!-- For more information on AccountSet flags, see [AccountSet flags](accountset.html). -->
|
||||
|
||||
## Checking Whether an Account Has DepositAuth Enabled
|
||||
|
||||
To see whether an account has Deposit Authorization enabled, use the `account_info` method to look up the account. Compare the value of the `Flags` field (in the `result.account_data` object) with the bitwise flags defined for an AccountRoot ledger object.
|
||||
|
||||
If the result of the `Flags` value bitwise-AND the `lsfDepositAuth` flag value (`0x01000000`) is nonzero, then the account has DepositAuth enabled. If the result is zero, then the account has DepositAuth disabled.
|
||||
|
||||
## Preauthorization
|
||||
|
||||
_(Added by the `DepositPreauth` amendment.)_
|
||||
|
||||
Accounts with DepositAuth enabled can _preauthorize_ certain senders, to allow payments from those senders to succeed even with DepositAuth enabled. This allows specific senders to send funds directly without the receiver taking action on each transaction individually. Preauthorization is not required to use DepositAuth, but can make certain operations more convenient.
|
||||
|
||||
Preauthorization is currency-agnostic. You cannot preauthorize accounts for specific currencies only.
|
||||
|
||||
To preauthorize a particular sender, send a `DepositPreauth` transaction with the address of another account to preauthorize in the `Authorize` field. To revoke preauthorization, provide the other account's address in the `Unauthorize` field instead. Specify your own address in the `Account` field as usual. You can preauthorize or unauthorize accounts even if you do not currently have DepositAuth enabled; the preauthorization status you set for other accounts is saved, but has no effect unless you enable DepositAuth. An account cannot preauthorize itself. Preauthorizations are one-directional, and have no effect on payments going the opposite direction.
|
||||
|
||||
Preauthorizing another account adds a `DepositPreauth` object to the ledger, which increases the owner reserve of the account providing the authorization. If the account revokes this preauthorization, doing so removes the object and decreases the owner reserve.
|
||||
|
||||
After the DepositPreauth transaction has been processed, the authorized account can send funds to your account, even if you have DepositAuth enabled, using any of the following transaction types:
|
||||
|
||||
- `Payment`
|
||||
- `EscrowFinish`
|
||||
- `PaymentChannelClaim`
|
||||
|
||||
Preauthorization has no effect on the other ways to send money to an account with DepositAuth enabled.
|
||||
|
||||
<!--
|
||||
See [Precise Semantics](#precise-semantics) for the exact rules.
|
||||
-->
|
||||
|
||||
### Checking for Authorization
|
||||
|
||||
You can use the `deposit_authorized` method to see if an account is authorized to deposit to another account. This method checks two things: <!-- STYLE_OVERRIDE: is authorized to -->
|
||||
|
||||
- Whether the destination account requires Deposit Authorization. (If it does not require authorization, then all source accounts are considered authorized.)
|
||||
- Whether the source account is preauthorized to send money to the destination.
|
||||
|
||||
<!--
|
||||
## See Also
|
||||
|
||||
- The [DepositPreauth transaction][] reference.
|
||||
- The [DepositPreauth ledger object type](depositpreauth-object.html).
|
||||
- The [deposit_authorized method][] of the [`rippled` API](http-websocket-apis.html).
|
||||
- The [Authorized Trust Lines](authorized-trust-lines.html) feature (`RequireAuth` flag) limits which counterparties can hold non-XRP currencies issued by an account.
|
||||
- The `DisallowXRP` flag indicates that an account should not receive XRP. This is a softer protection than Deposit Authorization, and is not enforced by the XRP Ledger. (Client applications should honor this flag or at least warn about it.)
|
||||
- The `RequireDest` flag indicates that an account can only receive currency amounts if the sending transaction specifies a [Destination Tag](become-an-xrp-ledger-gateway.html#source-and-destination-tags). This protects users from forgetting to indicate the purpose of a payment, but does not protect recipients from unknown senders, who can make up arbitrary destination tags.
|
||||
- [Partial Payments](partial-payments.html) provide a way for accounts to return unwanted payments while subtracting [transfer fees](transfer-fees.html) and exchange rates from the amount delivered instead of adding them to the amount sent.
|
||||
-->
|
||||
3
content/concepts/understanding-xrpl/accounts/history.md
Normal file
3
content/concepts/understanding-xrpl/accounts/history.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# History
|
||||
|
||||
Placeholder for details of account history.
|
||||
67
content/concepts/understanding-xrpl/accounts/reserves.md
Normal file
67
content/concepts/understanding-xrpl/accounts/reserves.md
Normal file
@@ -0,0 +1,67 @@
|
||||
# Reserves
|
||||
|
||||
The XRP Ledger applies _reserve requirements_, in XRP, to protect the shared global ledger from growing excessively large as the result of spam or malicious usage. The goal is to constrain the growth of the ledger to match improvements in technology so that a current commodity-level machine can always fit the current ledger in RAM.
|
||||
|
||||
To have an account, an address must hold a minimum amount of XRP in the shared global ledger. You cannot send this XRP to other addresses. To fund a new address, you must send that address enough XRP to meet the reserve requirement.
|
||||
|
||||
The current minimum reserve requirement is **10 XRP**. (This is the cost of an address that owns no other objects in the ledger.) Each new account must set aside this much XRP. Some of this XRP can be recovered by deleting the account.
|
||||
|
||||
The [Fee Voting](../xrpl/fee-voting.md) process can change the reserve requirement if enough validators agree to new reserve settings.
|
||||
|
||||
|
||||
## Base Reserve and Owner Reserve
|
||||
|
||||
The reserve requirement is divided into two parts:
|
||||
|
||||
* The **Base Reserve** is a minimum amount of XRP that is required for each address in the ledger. Currently, this is 10 XRP (`10000000` drops).
|
||||
* The **Owner Reserve** is an increase to the reserve requirement for each object that the address owns in the ledger. Currently, this is 2 XRP (`2000000` drops) per item.
|
||||
|
||||
|
||||
### Owner Reserves
|
||||
|
||||
Many objects in the ledger are owned by a particular address, and count toward the reserve requirement of that address. When objects are removed from the ledger, they no longer count against their owner's reserve requirement.
|
||||
|
||||
- Offers are owned by the address that placed them. Transaction processing automatically removes Offers that are fully consumed or found to be unfunded. Alternatively, the owner can cancel an Offer by sending an `OfferCancel` transaction, or by sending an `OfferCreate` transaction that contains an `OfferSequence` parameter.
|
||||
- Trust lines are shared between two addresses. The owner reserve can apply to one or both of the addresses, depending on whether the fields that address controls are in their default state.
|
||||
|
||||
<!-- See [Contributing to the Owner Reserve](ripplestate.html#contributing-to-the-owner-reserve) for details.
|
||||
-->
|
||||
|
||||
- A SignerList counts as 1 object for purposes of the owner reserve (since the `MultiSignReserve amendment` activated in April 2019).
|
||||
|
||||
<!-- See also: [Signer Lists and Reserves](signerlist.html#signer-lists-and-reserves). -->
|
||||
- Held Payments (Escrow) are owned by the address that placed them.
|
||||
- Payment Channels are owned by the address that created them.
|
||||
- Owner directories list all the ledger objects that contribute to an address's owner reserve. However, the owner directory itself does not count towards the reserve.
|
||||
- Checks are owned by the address that created them (the sender, not the destination).
|
||||
|
||||
|
||||
#### Owner Reserve Edge Cases
|
||||
|
||||
The XRP Ledger considers an `OfferCreate` transaction to be an explicit statement of willingness to hold an asset. Consuming the offer automatically creates a trust line (with limit 0, and a balance above that limit) for the `taker_pays` currency if such a trust line does not exist. However, if the offer's owner does not hold enough XRP to also meet the owner reserve requirement of the new trust line, the offer is considered unfunded. See also: `Lifecycle of an Offer`.
|
||||
|
||||
|
||||
## Going Below the Reserve Requirement
|
||||
|
||||
During transaction processing, the [transaction cost](../transactions/transaction-cost.md) destroys some of the sending address's XRP balance. This can cause an address's XRP to go below the reserve requirement.
|
||||
|
||||
When an address holds less XRP than its current reserve requirement, it cannot send new transactions that would transfer XRP to others, or increase its own reserve. Even so, the address continues to exist in the ledger and can send other transactions as long as it has enough XRP to pay the transaction cost. The address can become able to send all types of transactions again if it receives enough XRP to meet its reserve requirement again, or if the [reserve requirement decreases](#changing-the-reserve-requirements) to less than the address's XRP holdings.
|
||||
|
||||
**Tip:** When an address is below the reserve requirement, it can send new `OfferCreate transactions` to acquire more XRP, or other currencies on its existing trust lines. These transactions cannot create new trust lines or Offer nodes in the ledger, so they can only execute trades that consume offers that are already in the order books.
|
||||
|
||||
|
||||
## Changing the Reserve Requirements
|
||||
|
||||
The XRP Ledger has a mechanism to adjust the reserve requirements. Such adjustments may consider, for example, long-term changes in the value of XRP, improvements in the capacity of commodity-level machine hardware, or increased efficiency in the server software implementation. Any changes have to be approved by the consensus process. See [Fee Voting](../xrpl/fee-voting.md) for more information.
|
||||
|
||||
<!--
|
||||
## See Also
|
||||
|
||||
- [account_objects method][]
|
||||
- [AccountRoot Object][]
|
||||
- [Fee Voting](fee-voting.html)
|
||||
|
||||
|
||||
|
||||
- [SetFee pseudo-transaction][]
|
||||
-->
|
||||
3
content/concepts/understanding-xrpl/accounts/sequence.md
Normal file
3
content/concepts/understanding-xrpl/accounts/sequence.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# Sequence
|
||||
|
||||
Placeholder for details of sequence with regard to account transactions.
|
||||
27
content/concepts/understanding-xrpl/fees.md
Normal file
27
content/concepts/understanding-xrpl/fees.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# Fees (Disambiguation)
|
||||
|
||||
The XRP Ledger is a decentralized ledger, secured by cryptography and powered by a distributed peer-to-peer network of servers. This means that no one party, not even Ripple, can require a fee for access to the network.
|
||||
|
||||
However, the rules of the XRP Ledger include several types of fees, including neutral fees which protect the ledger against abuse. These neutral fees are not paid to anyone. There are also several optional ways that users can collect fees from each other, both inside and outside the XRP Ledger.
|
||||
|
||||
|
||||
## In the Ledger
|
||||
|
||||
### Neutral Fees
|
||||
|
||||
The _**transaction cost**_ (sometimes called the transaction fee) is a miniscule amount of XRP destroyed to send a transaction. This cost scales with the load of the network, which protects the peer-to-peer network from spam. See [Transaction Cost](./transactions/transaction-cost.md) for more information.
|
||||
|
||||
The _**reserve requirement**_ is a minimum amount of XRP that an account must hold. It increases with the number of objects the account owns in the ledger. This disincentivizes users from increasing the size of the ledger carelessly or maliciously. See [Reserves](./accounts/reserves.md) for more information.
|
||||
|
||||
### Optional Fees
|
||||
|
||||
_**Transfer fees**_ are optional percentage fees that issuers can charge to transfer the currencies they issue to other addresses within the XRP Ledger. See [Transfer Fees](./tokens/transfer-fees.md) for more information.
|
||||
|
||||
_**Trust line quality**_ is a setting that allows an account to value balances on a trust line at higher or lower than face value. This can lead to situations that are like charging a fee. Trust line quality does not apply to XRP, which is not tied to a trust line.
|
||||
|
||||
|
||||
## Outside the Ledger
|
||||
|
||||
Although the fees described above are the only fees built into the XRP Ledger, people can still invent ways to charge fees associated with the ledger. For example, financial institutions commonly charge their customers to send money into and out of the XRP Ledger.
|
||||
|
||||
Many other fees are also possible. Businesses might charge for access to a client application, maintenance of non-XRP Ledger accounts, exchange services (especially when buying XRP on a private market instead of within the XRP Ledger's decentralized exchange) and any number of other services. Always be aware of the fee schedule before doing business with any financial institution.
|
||||
@@ -1,10 +1,3 @@
|
||||
---
|
||||
html: federated-sidechains.html
|
||||
parent: consensus-network.html
|
||||
blurb: Learn about federated sidechains, which enable value in the form of XRP and other tokens (IOUs) to move efficiently between a sidechain and the XRP Ledger.
|
||||
labels:
|
||||
- Blockchain
|
||||
---
|
||||
# Federated Sidechains
|
||||
|
||||
_Federated Sidechains are available as an Engineering Preview and can be used to develop and test using `rippled` 1.8.0._
|
||||
@@ -81,8 +74,3 @@ The _Sidechain Launch Kit_ is a commandline tool that simplifies setting up fede
|
||||
|
||||
- **Concepts:**
|
||||
- [Federated Sidechains Video](https://www.youtube.com/embed/NhH4LM8NxgY)
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -1,15 +1,8 @@
|
||||
---
|
||||
html: parallel-networks.html
|
||||
parent: consensus-network.html
|
||||
blurb: Understand how test networks and alternate ledger chains relate to the production XRP Ledger.
|
||||
labels:
|
||||
- Blockchain
|
||||
---
|
||||
# Parallel Networks
|
||||
|
||||
There is one production XRP Ledger peer-to-peer network, and all business that takes place on the XRP Ledger occurs within the production network—the Mainnet.
|
||||
|
||||
To help members of the XRP Ledger community interact with XRP Ledger technology without affecting anything on the Mainnet, there are alternative networks, or altnets. Here's a breakdown of some public altnets:
|
||||
To help members of the XRP Ledger community interact with XRP Ledger technology without affecting anything on the Mainnet, Ripple hosts two alternative networks, or altnets: the Testnet and the Devnet. Here's a breakdown of all three networks:
|
||||
|
||||
| Network | Upgrade Cadence | Description |
|
||||
|:--------|:----------------|:-------------------------------------------------|
|
||||
@@ -19,16 +12,16 @@ To help members of the XRP Ledger community interact with XRP Ledger technology
|
||||
| NFT-Devnet | [XLS-20 pre-release](https://github.com/ripple/rippled/tree/xls20) | A preview of the [XLS-20d](https://github.com/XRPLF/XRPL-Standards/discussions/46) standard for non-fungible tokens on the XRP Ledger. |
|
||||
| [Hooks Testnet V2](https://hooks-testnet-v2.xrpl-labs.com/) | [Hooks server](https://github.com/XRPL-Labs/xrpld-hooks) | A preview of on-chain smart contract functionality using [hooks](https://write.as/xumm/xrpl-labs-is-working-on-the-transaction-hooks-amendment-for-the-xrp-ledger). |
|
||||
|
||||
Each altnet has its own separate supply of test XRP, which is [given away for free](xrp-testnet-faucet.html) to parties interested in experimenting with the XRP Ledger and developing applications and integrations. Test XRP does not have real-world value and is lost when the network is reset.
|
||||
Each test network has its own separate supply of test XRP, which is [given away for free](xrp-testnet-faucet.html) to parties interested in experimenting with the XRP Ledger and developing applications and integrations. Test XRP does not have real-world value and is lost when the network is reset.
|
||||
|
||||
**Caution:** Unlike the XRP Ledger Mainnet, test networks are usually _centralized_ and there are no guarantees about the stability and availability of these networks. They have been and continue to be used to test various properties of server configuration, network topology, and network performance.
|
||||
|
||||
|
||||
## Parallel Networks and Consensus
|
||||
|
||||
The main factor in determining which network a server follows is its configured UNL—the list of validators it trusts not to collude. Each server uses its configured UNL to know which ledger to accept as the truth. When different consensus groups of `rippled` instances only trust other members of the same group, each group continues as a parallel network. Even if malicious or misbehaving computers connect to both networks, the consensus process avoids confusion as long as the members of each network are not configured to trust members of another network in excess of their quorum settings.
|
||||
The main factor in determining which network a server follows is its configured UNL—the list of validators it trusts not to collude. Each server uses its configured UNL to know which ledger to accept as the truth. When different consensus groups of `rippled` instances only trust other members of the same group, each group continues as a parallel network. Even if malicious or misbehaving computers connect to both networks, the consensus process overrides the confusion as long as the members of each network are not configured to trust members of another network in excess of their quorum settings.
|
||||
|
||||
Ripple runs the main servers in the Testnet, Devnet, and NFT-Devnet; you can also [connect your own `rippled` server to these networks](connect-your-rippled-to-the-xrp-test-net.html). The Testnet and Devnet do not use diverse, censorship-resistant sets of validators. This makes it possible for Ripple to reset the Testnet or Devnet at any time.
|
||||
Ripple runs the main servers in the Testnet, Devnet, and NFT-Devnet; you can also [connect your own `rippled` server to these networks](connect-your-rippled-to-the-xrp-test-net.html). The Testnet and Devnet do not use diverse, censorship-resistant sets of validators. This makes it possible for Ripple to reset the Testnet or Devnet on a regular basis.
|
||||
|
||||
|
||||
## See Also
|
||||
@@ -46,10 +39,4 @@ Ripple runs the main servers in the Testnet, Devnet, and NFT-Devnet; you can als
|
||||
- [consensus_info method][]
|
||||
- [validator_list_sites method][]
|
||||
- [validators method][]
|
||||
- [Daemon Mode Options](commandline-usage.html#daemon-mode-options)
|
||||
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
- [Daemon Mode Options](commandline-usage.html#daemon-mode-options)
|
||||
@@ -0,0 +1,3 @@
|
||||
# The XRP Ledger Networks
|
||||
|
||||
Placeholder for XRPL networks documentation.
|
||||
@@ -0,0 +1,3 @@
|
||||
# Clio Server
|
||||
|
||||
Placeholder for Clio server documentation.
|
||||
145
content/concepts/understanding-xrpl/server/invariant-checking.md
Normal file
145
content/concepts/understanding-xrpl/server/invariant-checking.md
Normal file
@@ -0,0 +1,145 @@
|
||||
# Invariant Checking
|
||||
|
||||
Invariant checking is a safety feature of the XRP Ledger. It consists of a set of checks, separate from normal transaction processing, that guarantee that certain _invariants_ hold true across all transactions.
|
||||
|
||||
Like many safety features, we all hope that invariant checking never actually needs to do anything. However, it can be useful to understand the XRP Ledger's invariants because they define hard limits on the XRP Ledger's transaction processing, and to recognize the problem in the unlikely event that a transaction fails because it violated an invariant check.
|
||||
|
||||
Invariants should not trigger, but they ensure the XRP Ledger's integrity from bugs yet to be discovered or even created.
|
||||
|
||||
|
||||
## Why it Exists
|
||||
|
||||
- The source code for the XRP Ledger is complicated and vast; there is a high potential for code to execute incorrectly.
|
||||
- The cost of incorrectly executing a transaction is high and not acceptable by any standards.
|
||||
|
||||
Specifically, incorrect transaction executions could create invalid or corrupt data that later consistently crashes servers in the network by sending them into an "impossible" state which could halt the entire network.
|
||||
|
||||
The processing of incorrect transaction would undermine the value of trust in the XRP Ledger. Invariant checking provides value to the entire XRP Ledger because it adds the feature of reliability.
|
||||
|
||||
|
||||
|
||||
## How it Works
|
||||
|
||||
The invariant checker is a second layer of code that runs automatically in real-time after each transaction. Before the transaction's results are committed to the ledger, the invariant checker examines those changes for correctness. If the transaction's results would break one of the XRP Ledger's strict rules, the invariant checker rejects the transaction. Transactions that are rejected this way have the result code `tecINVARIANT_FAILED` and are included in the ledger with no effects.
|
||||
|
||||
To include the transaction in the ledger with a `tec`-class code, some minimal processing is necessary. If this minimal processing still breaks an invariant, the transaction fails with the code `tefINVARIANT_FAILED` instead, and is not included in the ledger at all.
|
||||
|
||||
|
||||
## Active Invariants
|
||||
|
||||
The XRP Ledger checks all the following invariants on each transaction:
|
||||
|
||||
[[Source]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L92 "Source")
|
||||
|
||||
- [Transaction Fee Check](#transaction-fee-check)
|
||||
|
||||
[[Source]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L118 "Source")
|
||||
|
||||
- [XRP Not Created](#xrp-not-created)
|
||||
|
||||
[[Source]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L146 "Source")
|
||||
|
||||
- [Account Roots Not Deleted](#account-roots-not-deleted)
|
||||
|
||||
[[Source]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L173 "Source")
|
||||
|
||||
- [XRP Balance Checks](#xrp-balance-checks)
|
||||
|
||||
[[Source]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L197 "Source")
|
||||
|
||||
- [Ledger Entry Types Match](#ledger-entry-types-match)
|
||||
|
||||
[[Source]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L224 "Source")
|
||||
|
||||
- [No XRP Trust Lines](#no-xrp-trust-lines)
|
||||
|
||||
[[Source]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L251 "Source")
|
||||
|
||||
- [No Bad Offers](#no-bad-offers)
|
||||
|
||||
[[Source]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L275 "Source")
|
||||
|
||||
- [No Zero Escrow](#no-zero-escrow)
|
||||
|
||||
[[Source]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L300 "Source")
|
||||
|
||||
- [Valid New Account Root](#valid-new-account-root)
|
||||
|
||||
|
||||
### Transaction Fee Check
|
||||
|
||||
- **Invariant Condition(s):**
|
||||
- The [transaction cost](transaction-cost.html) amount must never be negative, nor larger than the cost specified in the transaction.
|
||||
|
||||
|
||||
### XRP Not Created
|
||||
|
||||
- **Invariant Condition(s):**
|
||||
- A transaction must not create XRP and should only destroy the XRP [transaction cost](transaction-cost.html).
|
||||
|
||||
|
||||
### Account Roots Not Deleted
|
||||
|
||||
- **Invariant Condition(s):**
|
||||
- An [account](accounts.html) cannot be deleted from the ledger except by an [AccountDelete transaction][].
|
||||
- A successful AccountDelete transaction always deletes exactly 1 account.
|
||||
|
||||
|
||||
### XRP Balance Checks
|
||||
|
||||
- **Invariant Condition(s):**
|
||||
- An account's XRP balance must be of type XRP, and it cannot be less than 0 or more than 100 billion XRP exactly.
|
||||
|
||||
|
||||
### Ledger Entry Types Match
|
||||
|
||||
- **Invariant Condition(s):**
|
||||
- Corresponding modified ledger entries should match in type and added entries should be a [valid type](ledger-object-types.html).
|
||||
|
||||
|
||||
### No XRP Trust Lines
|
||||
|
||||
- **Invariant Condition(s):**
|
||||
- [Trust lines](trust-lines-and-issuing.html) using XRP are not allowed.
|
||||
|
||||
|
||||
### No Bad Offers
|
||||
|
||||
- **Invariant Condition(s):**
|
||||
- [Offers](offer.html) should be for non-negative amounts and must not be XRP to XRP.
|
||||
|
||||
|
||||
### No Zero Escrow
|
||||
|
||||
- **Invariant Condition(s):**
|
||||
- An [escrow](escrow-object.html) entry must hold more than 0 XRP and less than 100 billion XRP.
|
||||
|
||||
|
||||
### Valid New Account Root
|
||||
|
||||
- **Invariant Condition(s):**
|
||||
- A new [account root](accountroot.html) must be the consequence of a payment.
|
||||
- A new account root must have the right starting [sequence](basic-data-types.html#account-sequence).
|
||||
- A transaction must not create more than one new [account](accounts.html).
|
||||
|
||||
|
||||
## See Also
|
||||
|
||||
- **Blog:**
|
||||
- [Protecting the Ledger: Invariant Checking](https://xrpl.org/blog/2017/invariant-checking.html)
|
||||
|
||||
- **Repository:**
|
||||
- [Invariant Check.h](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h)
|
||||
- [Invariant Check.cpp](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.cpp)
|
||||
- [System Parameters](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/SystemParameters.h#L43)
|
||||
- [XRP Amount](https://github.com/ripple/rippled/blob/develop/src/ripple/basics/XRPAmount.h#L244)
|
||||
- [Ledger Formats](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/protocol/LedgerFormats.h#L36-L94)
|
||||
|
||||
|
||||
- **Other:**
|
||||
- [Authorized Trust Lines](authorized-trust-lines.html)
|
||||
- [XRP Properties](xrp.html#xrp-properties)
|
||||
- [Calculating Balance Changes for a Transaction](https://xrpl.org/blog/2015/calculating-balance-changes-for-a-transaction.html#calculating-balance-changes-for-a-transaction)
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,3 @@
|
||||
# rippled Server
|
||||
|
||||
Placeholder for rippled server documentation.
|
||||
@@ -0,0 +1,3 @@
|
||||
# Server Modes
|
||||
|
||||
Placeholder for Server Mode documentation.
|
||||
@@ -1,10 +1,3 @@
|
||||
---
|
||||
html: transaction-queue.html
|
||||
parent: consensus-network.html
|
||||
blurb: Understand how transactions can be queued before reaching consensus.
|
||||
labels:
|
||||
- Transaction Sending
|
||||
---
|
||||
# Transaction Queue
|
||||
|
||||
The `rippled` server uses a transaction queue to help enforce the [open ledger cost](transaction-cost.html#open-ledger-cost). The open ledger cost sets a target number of transactions in a given ledger, and escalates the required transaction cost very quickly when the open ledger surpasses this size. Rather than discarding transactions that cannot pay the escalated transaction cost, `rippled` tries to put them in a transaction queue, which it uses to build the next ledger.
|
||||
@@ -72,9 +65,3 @@ The precise order of transactions in the queue decides which transactions get ad
|
||||
|
||||
- [Transaction Cost](transaction-cost.html) for information on why the transaction cost exists and how the XRP Ledger enforces it.
|
||||
- [Consensus](consensus.html) for a detailed description of how the consensus process approves transactions.
|
||||
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
@@ -0,0 +1,3 @@
|
||||
# The XRP Ledger Servers
|
||||
|
||||
Placeholder for XRPL servers documentation.
|
||||
@@ -0,0 +1,124 @@
|
||||
# Authorized Trust Lines
|
||||
|
||||
The Authorized Trust Lines feature enables issuers to create tokens that can only be held by accounts that the issuer specifically authorizes. This feature only applies to tokens, not XRP.
|
||||
|
||||
To use the Authorized Trust Lines feature, enable the `RequireAuth` flag on your issuing account. While the setting is enabled, other accounts can only hold tokens you issue if you have authorized those accounts' trust lines to your issuing account.
|
||||
|
||||
You can authorize a trust line by sending a `TrustSet` transaction from your issuing address, configuring the trust line between your account and the account to authorize. After you have authorized a trust line, you can never revoke that authorization. (You can, however, [freeze](freezing-tokens.md) that trust line if you need to.)
|
||||
|
||||
The transaction to authorize a trust line must be signed by the issuing address, which unfortunately means an increased risk exposure for that address.
|
||||
|
||||
**Caution:** You can only enable `RequireAuth` if your account has no trust lines and no Offers in the XRP Ledger, so you must decide whether or not to use it _before_ you start issuing tokens.
|
||||
|
||||
## With Stablecoin Issuing
|
||||
|
||||
With a stablecoin on the XRP Ledger and use Authorized Trust Lines, the process of onboarding a new customer might look something like the following:
|
||||
|
||||
1. The customer registers with the stablecoin issuer's systems and sends proof of their identity (also known as "Know Your Customer", or KYC, information).
|
||||
2. The customer and stablecoin issuer tell each other their XRP Ledger addresses.
|
||||
3. The customer sends a `TrustSet` transaction to create a trust line to the issuer's address, with a positive limit.
|
||||
4. The issuer sends a `TrustSet` transaction to authorize the customer's trust line.
|
||||
|
||||
**Tip:** The issuer can authorize a trust line preemptively (step 3), before the customer has created it. This creates a trust line with zero limit, so that the customer's TrustSet transaction (step 2) sets the limit on the pre-authorized trust line. _(Added by the TrustSetAuth amendment.)_
|
||||
|
||||
## As a Precaution
|
||||
|
||||
Even if you don't intend to use Authorized Trust Lines, you can enable the `RequireAuth` setting on [operational and standby accounts](../accounts/account-types.md), and then never have those accounts approve any trust lines. This prevents those accounts from issuing tokens by accident (for example, if a user accidentally trusts the wrong address). This is only a precaution, and does not stop the operational and standby accounts from transferring the _issuer's_ tokens, as intended.
|
||||
|
||||
|
||||
## Technical Details
|
||||
<!--{# TODO: split these off into one or more tutorials on using authorized trust lines, preferably with both JavaScript and Python code samples. #}-->
|
||||
|
||||
### Enabling RequireAuth
|
||||
|
||||
The following is an example of using a locally-hosted `rippled`'s `submit method` to send an `AccountSet` transaction to enable the `RequireAuth` flag: (This method works the same way regardless of whether the address is an issuing address, operational address, or standby address.)
|
||||
|
||||
Request:
|
||||
|
||||
```json
|
||||
POST http://localhost:5005/
|
||||
{
|
||||
"method": "submit",
|
||||
"params": [
|
||||
{
|
||||
"secret": "s████████████████████████████",
|
||||
"tx_json": {
|
||||
"Account": "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
|
||||
"Fee": "15000",
|
||||
"Flags": 0,
|
||||
"SetFlag": 2,
|
||||
"TransactionType": "AccountSet"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
<!--
|
||||
{% include '_snippets/secret-key-warning.md' %}
|
||||
<!--{#_ #}-->
|
||||
|
||||
## Checking Whether an Account Has RequireAuth Enabled
|
||||
|
||||
To see whether an account has the `RequireAuth` setting enabled, use the `account_info` method to look up the account. Compare the value of the `Flags` field (in the `result.account_data` object) with the bitwise flags defined for an `AccountRoot` ledger object.
|
||||
|
||||
If the result of the `Flags` value bitwise-AND the `lsfRequireAuth` flag value (`0x00040000`) is nonzero, then the account has `RequireAuth` enabled. If the result is zero, then the account has `RequireAuth` disabled.
|
||||
|
||||
## Authorizing Trust Lines
|
||||
|
||||
If you are using the Authorized Trust Lines feature, others cannot hold balances you issue unless you first authorize their trust lines to you. If you issue more than one currency, you must separately authorize trust lines for each currency.
|
||||
|
||||
To authorize a trust line, submit a `TrustSet` transaction from your issuing address, with the user to trust as the `issuer` of the `LimitAmount`. Leave the `value` (the amount to trust them for) as *0*, and enable the `tfSetfAuth` flag for the transaction.
|
||||
|
||||
The following is an example of using a locally-hosted `rippled`'s `submit` method to send a TrustSet transaction authorizing the customer address `rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn` to hold USD issued by the address `rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW`:
|
||||
|
||||
Request:
|
||||
|
||||
```json
|
||||
POST http://localhost:8088/
|
||||
|
||||
{
|
||||
"method": "submit",
|
||||
"params": [
|
||||
{
|
||||
"secret": "s████████████████████████████",
|
||||
"tx_json": {
|
||||
"Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
|
||||
"Fee": "15000",
|
||||
"TransactionType": "TrustSet",
|
||||
"LimitAmount": {
|
||||
"currency": "USD",
|
||||
"issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
||||
"value": 0
|
||||
},
|
||||
"Flags": 65536
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
<!--
|
||||
{% include '_snippets/secret-key-warning.md' %}
|
||||
<!--{#_ #}-->
|
||||
|
||||
## Checking Whether Trust Lines Are Authorized
|
||||
|
||||
To see whether a trust line has been authorized, use the `account_lines` method to look up the trust line. In the request, provide the customer's address in the `account` field and the issuer's address in the `peer` field.
|
||||
|
||||
In the response's `result.lines` array, find the object whose `currency` field indicates that it represents a trust line for the currency you want. If that object has a `peer_authorized` field with the value `true`, then the issuer (the address you used as the request's `peer` field) has authorized the trust line.
|
||||
|
||||
<!--
|
||||
## See Also
|
||||
|
||||
- **Concepts:**
|
||||
- [Deposit Authorization](depositauth.html)
|
||||
- [Freezing Issued Currencies](freezes.html)
|
||||
- **Tutorials:**
|
||||
- [Become an XRP Ledger Gateway](become-an-xrp-ledger-gateway.html)
|
||||
- **References:**
|
||||
- [account_lines method][]
|
||||
- [account_info method][]
|
||||
- [AccountSet transaction][]
|
||||
- [TrustSet transaction][]
|
||||
- [AccountRoot Flags](accountroot.html#accountroot-flags)
|
||||
- [RippleState (trust line) Flags](ripplestate.html#ripplestate-flags)
|
||||
-->
|
||||
@@ -0,0 +1,26 @@
|
||||
# Common Misunderstandings about Freezes
|
||||
|
||||
It is a common misconception that Ripple or others can freeze XRP, similar to how centralized services like PayPal can suspend your account and prevent you from accessing your funds. In reality, while the XRP Ledger does have a [freeze feature](freezing-tokens.md), it can only be used on issued tokens, not on XRP. _No one can freeze XRP.__
|
||||
|
||||
Tokens in the XRP Ledger are fundamentally different than XRP. Tokens always exist in trust lines, which _can_ be frozen. XRP exists in accounts, which _cannot_ be frozen.
|
||||
|
||||
## Isn't XRP Just Ripple's Token?
|
||||
|
||||
No, XRP is different from tokens. XRP is the only native asset on the XRP Ledger and is required to conduct transactions on the XRP Ledger. XRP has no counterparty, meaning that when someone holds XRP, they are not holding a liability, they are holding the actual currency, XRP. Due to this fact, _XRP cannot be frozen by any entity or individual._
|
||||
|
||||
## Can Ripple Freeze My Tokens? Or the XRP Ledger Foundation?
|
||||
|
||||
The XRP Ledger is decentralized so that no one party has control over it—not Ripple, not the XRP Ledger Foundation, and not anyone else.
|
||||
|
||||
The _issuer_ of a token can freeze your trust line for _that token specifically_. They can't freeze the rest of your account, or any tokens from different issuers, and they can't stop you from using the XRP Ledger.
|
||||
|
||||
Furthermore, token issuers can voluntarily and permanently _give up_ their ability to freeze tokens. This ["No Freeze"](freezing-tokens.md#no-freeze) setting is intended to allow tokens to behave more like physical cash, in that third parties can't stop you from using it.
|
||||
|
||||
|
||||
## But I Heard Ripple Froze Jed McCaleb's XRP?
|
||||
|
||||
This is a misrepresentation of events that actually happened in 2015–2016. Jed McCaleb, a Ripple founder who left the company in 2013, attempted to sell over $1 million US worth of XRP on Bitstamp, a custodial exchange. Ripple representatives argued that this sale would breach an agreement that Jed and Ripple made in 2014. At Ripple's request, [Bitstamp froze Jed's Bitstamp account](https://www.coindesk.com/markets/2015/04/02/1-million-legal-fight-ensnares-ripple-bitstamp-and-jed-mccaleb/) and took the dispute to court. The case was [eventually settled](https://www.coindesk.com/markets/2016/02/12/ripple-settles-1-million-lawsuit-with-former-executive-and-founder/) with both sides declaring they were happy with the outcome.
|
||||
|
||||
Notably, the "freeze" did not happen on the XRP Ledger and did not involve the XRP Ledger's freeze feature. Like any custodial exchange, Bitstamp has the ability to freeze its users' accounts and stop them from trading or withdrawing funds, especially if those funds are involved in a legal dispute.
|
||||
|
||||
In contrast, when trading in the XRP Ledger's decentralized exchange, you custody your own assets so no one can stop you from dealing in XRP.
|
||||
@@ -0,0 +1,93 @@
|
||||
# Freezing Tokens
|
||||
|
||||
Issuers can freeze the tokens they issue in the XRP Ledger. _This does not apply to XRP,__ which is the native asset of the XRP Ledger, not an issued token.
|
||||
|
||||
In certain cases, to meet regulatory requirements, or while investigating suspicious activity, an exchange or gateway may want to freeze token balances.
|
||||
|
||||
**Tip:** No one can freeze XRP in the XRP Ledger. However, custodial exchanges can always freeze the funds they custody at their own discretion. For more details, see [Common Misunderstandings about Freezes](common-misconceptions-about-freezes.md).
|
||||
|
||||
There are three settings related to freezes:
|
||||
|
||||
* [Individual Freeze](#individual-freeze) - Freeze one counterparty.
|
||||
* [Global Freeze](#global-freeze) - Freeze all counterparties.
|
||||
* [No Freeze](#no-freeze) - Permanently give up the ability to freeze individual counterparties, as well as the ability to end a global freeze.
|
||||
|
||||
All freeze settings can be enacted regardless of whether the balance(s) to be frozen are positive or negative. Either the token issuer or the currency holder can freeze a trust line; however, the effect is minimal when a currency holder enacts a freeze.
|
||||
|
||||
|
||||
## Individual Freeze
|
||||
|
||||
The _Individual Freeze_ feature is a setting on a trust line. When an issuer enables the Individual Freeze setting, the following rules apply to the tokens in that trust line:
|
||||
|
||||
* Payments can still occur directly between the two parties of the frozen trust line.
|
||||
* The counterparty of that trust line can no longer decrease its balance on the frozen trust line, except in direct payments to the issuer. The counterparty can only send the frozen currencies directly to the issuer.
|
||||
* The counterparty can still receive payments from others on the frozen trust line.
|
||||
* The counterparty's offers to sell the tokens in the frozen trust line are considered unfunded.
|
||||
|
||||
Reminder: Trust lines do not hold XRP. XRP cannot be frozen.
|
||||
|
||||
A financial institution can freeze the trust line linking it to a counterparty if that counterparty shows suspicious activity or violates the financial institution's terms of use. The financial institution should also freeze the counterparty in any other systems the financial institution uses that are connected to the XRP Ledger. (Otherwise, an address might still be able to engage in undesired activity by sending payments through the financial institution.)
|
||||
|
||||
An individual address can freeze its trust line to a financial institution. This has no effect on transactions between the institution and other users. It does, however, prevent other accounts, including [operational accounts](../accounts/account-types.md), from sending that financial institution's tokens to the individual account. This type of individual freeze has no effect on offers.
|
||||
|
||||
The Individual Freeze applies to a single trust line. To freeze multiple tokens with a particular counterparty, the address must enable Individual Freeze on the trust lines for each separate currency code.
|
||||
|
||||
An address cannot enable the Individual Freeze setting if it has enabled the [No Freeze](#no-freeze) setting.
|
||||
|
||||
|
||||
## Global Freeze
|
||||
|
||||
The _Global Freeze_ feature is a setting on an account. An account can enable a global freeze only on itself. When an issuer enables the Global Freeze feature, the following rules apply to all tokens they issue:
|
||||
|
||||
* All counterparties of the frozen issuer can no longer decrease the balances in their trust lines to the frozen account, except in direct payments to the issuer. (This also affects the issuer's own [operational addresses](../accounts/account-types.md).)
|
||||
* Counterparties of the frozen issuer can still send and receive payments directly to and from the issuing address.
|
||||
* All offers to sell tokens issued by the frozen address are considered unfunded.
|
||||
|
||||
Reminder: addresses cannot issue XRP. Global freezes do not apply to XRP.
|
||||
|
||||
It can be useful to enable Global Freeze on a financial institution's [issuing account](../accounts/account-types.md) if the issuer's [secret key](.../accounts/cryptographic-keys.html) is compromised, even after regaining control of a such an address. This stops the flow of funds, preventing attackers from getting away with any more money or at least making it easier to track what happened. Besides enacting a Global Freeze in the XRP Ledger, the issuer should also suspend activities in its outside systems.
|
||||
|
||||
It can also be useful to enable Global Freeze if a financial institution intends to migrate to a new [issuing account](../accounts/account-types.md), or if the financial institution intends to cease doing business. This locks the funds at a specific point in time, so users cannot trade them away for other currencies.
|
||||
|
||||
Global Freeze applies to _all_ tokens issued and held by the address. You cannot enable Global Freeze for only one currency code. If you want to have the ability to freeze some tokens and not others, you should use different addresses for each token.
|
||||
|
||||
An address can always enable the Global Freeze setting. However, if the address has enabled the [No Freeze](#no-freeze) setting, it can never _disable_ Global Freeze.
|
||||
|
||||
|
||||
## No Freeze
|
||||
|
||||
The _No Freeze_ feature is a setting on an address that permanently gives up the ability to freeze tokens arbitrarily. An issuer can use this feature to make its tokens as "more like physical money" in the sense that the issuer cannot interfere with counterparties trading the tokens among themselves.
|
||||
|
||||
Reminder: XRP already cannot be frozen. The No Freeze feature only applies to other tokens issued in the XRP Ledger.
|
||||
|
||||
The No Freeze setting has two effects:
|
||||
|
||||
* The issuer can no longer enable Individual Freeze on trust lines to any counterparty.
|
||||
* The issuer can still enact a Global Freeze, but cannot _disable_ the Global Freeze.
|
||||
|
||||
The XRP Ledger cannot force an issuer to honor the obligations that its issued funds represent, so No Freeze does stop a stablecoin issuer from defaulting on its obligations. However, No Freeze ensures that an issuer does not use the Global Freeze feature unfairly against specific users.
|
||||
|
||||
The No Freeze setting applies to all tokens issued to and from an address. If you want to be able to freeze some tokens but not others, you should use different addresses for each.
|
||||
|
||||
You can only enable the No Freeze setting with a transaction signed by your address's master key secret. You cannot use a Regular Key or a multi-signed transaction to enable No Freeze.
|
||||
|
||||
|
||||
<!--
|
||||
# See Also
|
||||
|
||||
- [GB-2014-02 New Feature: Balance Freeze](https://ripple.com/files/GB-2014-02.pdf)
|
||||
- [Freeze Code Samples](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content/_code-samples/freeze)
|
||||
- **Concepts:**
|
||||
- [Trust Lines and Issuing](trust-lines-and-issuing.html)
|
||||
- **Tutorials:**
|
||||
- [Enable No Freeze](enable-no-freeze.html)
|
||||
- [Enact Global Freeze](enact-global-freeze.html)
|
||||
- [Freeze a Trust Line](freeze-a-trust-line.html)
|
||||
- **References:**
|
||||
- [account_lines method][]
|
||||
- [account_info method][]
|
||||
- [AccountSet transaction][]
|
||||
- [TrustSet transaction][]
|
||||
- [AccountRoot Flags](accountroot.html#accountroot-flags)
|
||||
- [RippleState (trust line) Flags](ripplestate.html#ripplestate-flags)
|
||||
-->
|
||||
3
content/concepts/understanding-xrpl/tokens/fungible.md
Normal file
3
content/concepts/understanding-xrpl/tokens/fungible.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# Fungible Tokens
|
||||
|
||||
Fungible tokens topic placeholder.
|
||||
@@ -0,0 +1,31 @@
|
||||
# Batch minting
|
||||
|
||||
There are two common approaches to minting NFToken objects in batches: mint on demand and scripted minting.
|
||||
|
||||
## Mint On Demand (Lazy Minting)
|
||||
|
||||
When using a mint on demand model, you and potential customers make buy or sell offers for initial sales of a NFToken object off the XRP Ledger. When you are ready to commence the initial sale, you mint the token, create a sell offer or accept a buy offer, then complete the transaction.
|
||||
|
||||
### Benefits
|
||||
|
||||
* There is no reserve requirement for holding unsold NFToken objects.
|
||||
* You mint NFToken objects in real time when you know that it will sell.
|
||||
|
||||
### Downside
|
||||
|
||||
Any market activity prior to the initial sale of the NFToken object is not recorded on the XRP Ledger. This might not be an issue for some applications.
|
||||
|
||||
## Scripted Minting
|
||||
|
||||
Use a program or script to mint many tokens at once. You might find the XRP Ledger ticket functionality helps you submit transactions in parallel, up to a current limit of 200 transactions in one group.
|
||||
|
||||
For a practical example, see the [Batch Mint NFTokens](../../../tutorials/quickstart/batch-minting.md) tutorial.
|
||||
|
||||
### Benefits
|
||||
|
||||
* NFToken objects are minted ahead of time
|
||||
* Market activity for the initial sale of the NFToken object is captured on the ledger
|
||||
|
||||
### Downside
|
||||
|
||||
You need to retain the appropriate XRP reserve for all of the NFToken objects you mint. As a rule of thumb, this is roughly 1/12th XRP per NFToken object at the current reserve rate. In the event that you do not have sufficient XRP in reserve, your mint transactions fail until you add sufficient XRP to your account.
|
||||
@@ -0,0 +1,69 @@
|
||||
# Trading NFTokens on the XRP Ledger
|
||||
{% include '_snippets/nfts-disclaimer.md' %}
|
||||
|
||||
You can transfer `NFToken` objects between accounts on the XRP Ledger. You can offer to buy or sell a `NFToken`, or accept offers from other accounts to buy a `NFToken` you own. You can even give away a `NFToken` by offering to sell it at a price of 0. All offers are created using `NFTokenCreateOffer` transaction.
|
||||
|
||||
|
||||
## Sell Offers
|
||||
|
||||
|
||||
### Create a Sell Offer
|
||||
|
||||
As the owner of a `NFToken` object, you can create a sell offer using a `NFTokenCreateOffer` transaction with the `tfSellToken` flag. You provide the `NFTokenID` and the `Amount` you are willing to accept in payment. You can optionally specify an `Expiration` date, after which the offer is no longer valid, and a `Destination` account, which is the only account that is allowed to purchase the `NFToken`.
|
||||
|
||||
|
||||
### Accept a Sell Offer
|
||||
|
||||
To purchase a `NFToken` that is offered for sale, you use a `NFTokenAcceptOffer` transaction. You provide the owner account and specify the `NFTokenOfferID` of the `NFTokenOffer` object you choose to accept.
|
||||
|
||||
|
||||
## Buy Offers
|
||||
|
||||
|
||||
### Create a Buy Offer
|
||||
|
||||
Any account can offer to buy a `NFToken`. You can create a buy offer using `NFTokenCreateOffer` _without_ the `tfSellToken` flag. You provide the `Owner` account, `NFTokenID`, and the `Amount` of your offer.
|
||||
|
||||
|
||||
### Accept a Buy Offer
|
||||
|
||||
Use the `NFTokenAcceptOffer` transaction to transfer a `NFToken`. Provide the `NFTokenOfferID` and the owner account to complete the transaction.
|
||||
|
||||
|
||||
## Trading Modes
|
||||
|
||||
When trading a `NFToken`, you can choose between a _direct_ transaction between a buyer and seller or a _brokered_ transaction, where a third party account matches a sell and buy offer to arrange the trade.
|
||||
|
||||
Trading in direct mode gives the seller control over the transfer. The seller can either post a `NFToken` for purchase by anyone, or sell a `NFToken` to a specific destination account. The seller receives the entire purchase price for the `NFToken`.
|
||||
|
||||
In brokered mode, the seller allows a third party account to broker the sale of the `NFToken`. The broker account collects a broker fee for the transfer at an agreed upon rate. The purchase is completed in real time, paying the broker and seller from the buyer’s funds without requiring an up front investment by the broker.
|
||||
|
||||
|
||||
### When to Use Brokered Mode
|
||||
|
||||
If a `NFToken` creator has the time and patience to seek out the right buyers, the creator keeps all proceeds from the sale. This works fine for a creator who sells few `NFToken` objects at variable prices.
|
||||
|
||||
On the other hand, creators might not want to spend their time selling their creations when they could spend the time creating. Instead of handling each individual sale, the sales work can be turned over to a third-party broker account.
|
||||
|
||||
Using a broker offers several advantages. For example:
|
||||
|
||||
* The broker can act as an agent, working to maximize the selling price of the `NFToken`. If the broker is paid a percentage of the sale price, the higher the price, the more the broker earns.
|
||||
* The broker can act as a curator, organizing `NFToken` objects based on a niche market, price point, or other criteria. This can attract groups of buyers who might not otherwise discover a creator’s work.
|
||||
* The broker can act as a marketplace, similar to Opensea.io, to handle the auction process at the application layer.
|
||||
|
||||
|
||||
### Brokered Sale Workflows
|
||||
|
||||
In the most straightforward workflow, a creator mints a new `NFToken`. The creator initiates a sell offer, entering the minimum acceptable sale price and setting the broker as the destination. Potential buyers make bids for the `NFToken`, setting the broker as the destination for the bid. The broker selects a winning bid and completes the transaction, taking a broker’s fee. As a best practice, the broker then cancels any remaining buy offers for the `NFToken`.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Another potential workflow would give the creator more control over the sale. In this workflow, the creator mints a new `NFToken`. Bidders create their offers, setting the broker as the destination. The broker selects the winning bid, subtracts their broker fee, and uses `NFTokenCreateOffer` to request that the creator sign off on the offer. The creator signs the requested offer, setting the broker as the destination. The broker completes the sale using `NFTokenAcceptOffer`, retaining the broker fee. The broker cancels any remaining bids for the `NFToken` using `NFTokenCancelOffer`.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
The same workflows can be used when an owner resells a `NFToken` created by another account.
|
||||
68
content/concepts/understanding-xrpl/tokens/non-fungible.md
Normal file
68
content/concepts/understanding-xrpl/tokens/non-fungible.md
Normal file
@@ -0,0 +1,68 @@
|
||||
# Non-fungible Tokens
|
||||
{% include '_snippets/nfts-disclaimer.md' %}
|
||||
|
||||
The XRP Ledger tokens are, primarily, fungible.
|
||||
|
||||
> Fun·gi·ble /ˈfənjəbəl/ (adj)
|
||||
>
|
||||
> 1. able to replace or be replaced by another identical item; mutually interchangeable.
|
||||
|
||||
Fungible tokens can be easily traded between users for XRP or other issued assets on the XRP Ledger's decentralized exchange. This makes them ideal for payments.
|
||||
|
||||
|
||||
A good example of a fungible item might be a postage stamp. If you are standing around in 1919 and need to send a letter by airmail, you would purchase a 24-cent stamp and affix it to your envelope. If you lost that stamp, you could use a different 24-cent stamp or use 2 10-cent stamps and 2 2-cent stamps. Very fungible.
|
||||
|
||||
|
||||
|
||||
But since you are standing around in 1919, you might be offered 24-cent airmail stamps where the aeroplane on the stamp is accidentally printed upside down. These are the world famous “Inverted Jenny” stamps. Only 100 were circulated on a single sheet of stamps, making them extremely rare and sought after. The current value of each mint condition stamp is appraised at over $1.5 million dollars.
|
||||
|
||||
|
||||
|
||||
Those stamps cannot be replaced by just another other 24-cent stamp. They have become _non-fungible_.
|
||||
|
||||
The XRPL Labs team has created a framework that supports non-fungible tokens (NFTs, or “nifties” in the vernacular). Non-fungible tokens serve to encode ownership of unique physical, non-physical, or purely digital goods, such as works of art or in-game items.
|
||||
|
||||
|
||||
## NFT Extensions
|
||||
|
||||
Extensions to the XRP Ledger support two new objects and a new ledger structure.
|
||||
|
||||
The `NFToken` is a native NFT type. It has operations to enumerate, purchase, sell, and hold such tokens. An `NFToken` is a unique, indivisible unit that is not used for payments.
|
||||
|
||||
The `NFTokenPage object` contains a set of `NFToken` objects owned by the same account.
|
||||
|
||||
You create a new `NFToken` using the `NFTokenMint` transaction.
|
||||
|
||||
`NFTokenOffer` object is a new object that describes an offer to buy or sell a single `NFToken`.
|
||||
|
||||
You destroy an `NFToken` using the `NFTokenBurn` transaction.
|
||||
|
||||
|
||||
## `NFToken` Lifecycle
|
||||
|
||||
You create a NFT using the `NFTokenMint` transaction. The `NFToken` lives on the `NFTokenPage` of the issuing account. You can create an `NFTokenOffer` to sell the `NFToken`, creating an entry to the XRP Ledger. Another account can accept the `NFTokenOffer`, transferring the `NFToken` to the accepting account’s `NFTokenPage`. If the `lsfTransferable `flag is set to _true_ (0x000008) when the `NFToken` is minted, the `NFToken` can be traded multiple times between accounts. The `NFToken` can be permanently destroyed by its owner using the `NFTokenBurn` transaction.
|
||||
|
||||
|
||||
|
||||
|
||||
<!--
|
||||
## Reference
|
||||
|
||||
- [NFToken][] data type
|
||||
- Ledger Objects
|
||||
- [NFTokenOffer object][]
|
||||
- [NFTokenPage object][]
|
||||
- Transactions
|
||||
- [NFTokenMint transaction][]
|
||||
- [NFTokenCreateOffer transaction][]
|
||||
- [NFTokenCancelOffer transaction][]
|
||||
- [NFTokenAcceptOffer transaction][]
|
||||
- [NFTokenBurn transaction][]
|
||||
|
||||
|
||||
### API Methods
|
||||
|
||||
* `account_nfts`
|
||||
* `nft_sell_offers`
|
||||
* `nft_buy_offers`
|
||||
-->
|
||||
108
content/concepts/understanding-xrpl/tokens/paths.md
Normal file
108
content/concepts/understanding-xrpl/tokens/paths.md
Normal file
@@ -0,0 +1,108 @@
|
||||
# Paths
|
||||
|
||||
In the XRP Ledger, paths define a way for [tokens](tokens.md) to flow through intermediary steps as part of a payment. Paths enable [cross-currency payments](../transactions/payments/cross-currency-payments.md) by connecting sender and receiver through orders in the XRP Ledger's decentralized exchange. Paths also enable complex settlement of offsetting debts.
|
||||
|
||||
A single Payment transaction in the XRP Ledger can use multiple paths, combining liquidity from different sources to deliver the desired amount. Thus, a transaction includes a _path set_, which is a collection of possible paths to take. All paths in a path set must start with the same currency, and must also end with the same currency as each other.
|
||||
|
||||
Since XRP can be sent directly to any address, an XRP-to-XRP transaction does not use any paths.
|
||||
|
||||
## Path Steps
|
||||
|
||||
A path is made of steps that connect the sender to the receiver of the payment. Every step is either:
|
||||
|
||||
* Rippling through another address with the same currency
|
||||
* Trading tokens or XRP using an order book
|
||||
|
||||
[Rippling](rippling.md) is the process of exchanging equivalent tokens using the same currency code. In the typical case, rippling through an issuer involves reducing the tokens issued to one party and increasing the tokens issued to another party by an equal amount. The path step specifies which account to ripple through.
|
||||
|
||||
Trading tokens and possibly XRP involves going to an order book and finding the best exchange rate between the assets involved for the amount being sent. The path step specifies which currency to change to, but does not record the state of the Offers in the order book. The canonical order of transactions is not final until a ledger is validated, so you cannot know for certain which Offers a transaction will take, until after the transaction has been validated. (You can make an educated guess, since each transaction takes the best available Offers at the time it executes in the final ledger.) <!-- STYLE_OVERRIDE: will -->
|
||||
|
||||
In both types of steps, each intermediate address gains and loses approximately equal value: either a balance ripples from a trust line to another trust line in the same currency, or they exchange currencies according to a previously-placed order. In some cases, the amounts gained and lost may not be exactly equivalent, due to [transfer fees](transfer-fees.md), trust line quality settings, or rounding.
|
||||
|
||||
{{ include_svg("img/paths-examples.svg", "Diagram of three example paths") }}
|
||||
|
||||
|
||||
|
||||
# Technical Details
|
||||
|
||||
## Pathfinding
|
||||
|
||||
The `rippled` API has two methods that can be used for pathfinding. The `ripple_path_find` method does a one-time lookup of possible path sets. The `path_find` method (WebSocket only) expands on the search with follow-up responses whenever a ledger closes or the server finds a better path.
|
||||
|
||||
You can have `rippled` automatically fill in paths when you sign it, by including the `build_path` field in a request to the `sign` method or `submit` command (sign-and-submit mode). However, we recommend pathfinding separately and confirming the results before signing, to avoid surprises.
|
||||
|
||||
**Caution:** Although `rippled` is designed to search for the cheapest paths possible, it may not always find them. Untrustworthy `rippled` instances could also be modified to change this behavior for profit. The actual cost to execute a payment along a path can change between submission and transaction execution.
|
||||
|
||||
Finding paths is a very challenging problem that changes slightly every few seconds as new ledgers are validated, so `rippled` is not designed to find the absolute best path. Still, you can find several possible paths and estimate the cost of delivering a particular amount.
|
||||
|
||||
|
||||
## Implied Steps
|
||||
|
||||
By convention, several steps of a path are implied by the [fields of the Payment transaction](../transactions/payments/payment-types.md): specifically, the `Account` (sender), `Destination` (receiver), `Amount` (currency and amount to be delivered) and `SendMax` (currency and amount to be sent, if specified). The implied steps are as follows:
|
||||
|
||||
* The first step of a path is always implied to be the sender of the transaction, as defined by the transaction's `Account` field.
|
||||
* If the transaction includes a `SendMax` field with an `issuer` that is not the sender of the transaction, that issuer is implied to be the second step of the path.
|
||||
* If `issuer` of the `SendMax` _is_ the sending address, then the path starts at the sending address, and may use any of that address's trust lines for the given currency code. See [special values for `SendMax` and `Amount`](../transactions/payments/payment-types.md) for details.
|
||||
* If the `Amount` field of the transaction includes an `issuer` that is not the same as the `Destination` of the transaction, that issuer is implied to be the second-to-last step of the path.
|
||||
* Finally, last step of a path is always implied to be the receiver of a transaction, as defined by the transaction's `Destination` field.
|
||||
|
||||
|
||||
## Default Paths
|
||||
|
||||
In addition to explicitly specified paths, a transaction can execute along the _default path_. The default path is the simplest possible way to connect the [implied steps](#implied-steps) of the transaction.
|
||||
|
||||
The default path could be any of the following:
|
||||
|
||||
* If the transaction uses only one token (regardless of issuer), then the default path assumes the payment should ripple through the addresses involved. This path only works if those addresses are connected by trust lines.
|
||||
* If `SendMax` is omitted, or the `issuer` of the `SendMax` is the sender, the default path needs a trust line from the sending `Account` to the `issuer` of the destination `Amount` to work.
|
||||
* If the `SendMax` and `Amount` have different `issuer` values, and neither are the sender or receiver, the default path is probably not useful because it would need to ripple across a trust line between the two issuers. Ripple (the company) typically discourages issuers from trusting one another directly.
|
||||
* For cross-currency transactions, the default path uses the order book between the source currency (as specified in the `SendMax` field) and the destination currency (as specified in the `Amount` field).
|
||||
|
||||
The following diagram enumerates all possible default paths:
|
||||
|
||||
{{ include_svg("img/default-paths.svg", "Diagram of default paths") }}
|
||||
|
||||
You can use the `tfNoDirectRipple` flag to disable the default path. In this case, the transaction can only execute using the paths explicitly included in the transaction. Traders can use this option to take arbitrage opportunities.
|
||||
|
||||
|
||||
## Path Specifications
|
||||
|
||||
A path set is an array. Each member of the path set is another array that represents an individual _path_. Each member of a path is an object that specifies the step. A step has the following fields:
|
||||
|
||||
| Field | Value | Description |
|
||||
|:-----------|:-----------------------|:---------------------------------------|
|
||||
| `account` | String - Address | _(Optional)_ If present, this path step represents rippling through the specified address. MUST NOT be provided if this step specifies the `currency` or `issuer` fields. |
|
||||
| `currency` | String - Currency Code | _(Optional)_ If present, this path step represents changing currencies through an order book. The currency specified indicates the new currency. MUST NOT be provided if this step specifies the `account` field. |
|
||||
| `issuer` | String - Address | _(Optional)_ If present, this path step represents changing currencies and this address defines the issuer of the new currency. If omitted in a step with a non-XRP `currency`, a previous step of the path defines the issuer. If present when `currency` is omitted, indicates a path step that uses an order book between same-named currencies with different issuers. MUST be omitted if the `currency` is XRP. MUST NOT be provided if this step specifies the `account` field. |
|
||||
| `type` | Integer | **DEPRECATED** _(Optional)_ An indicator of which other fields are present. |
|
||||
| `type_hex` | String | **DEPRECATED**: _(Optional)_ A hexadecimal representation of the `type` field. |
|
||||
|
||||
In summary, the following combination of fields are valid, optionally with `type`, `type_hex`, or both:
|
||||
|
||||
- `account` by itself
|
||||
- `currency` by itself
|
||||
- `currency` and `issuer` as long as the `currency` is not XRP
|
||||
- `issuer` by itself
|
||||
|
||||
Any other use of `account`, `currency`, and `issuer` fields in a path step is invalid.
|
||||
|
||||
The `type` field, used for the binary serialization of a path set, is actually constructed through bitwise operations on a single integer. The bits are defined as follows:
|
||||
|
||||
| Value (Hex) | Value (Decimal) | Description |
|
||||
|-------------|-----------------|-------------|
|
||||
| `0x01` | 1 | A change of address (rippling): the `account` field is present. |
|
||||
| `0x10` | 16 | A change of currency: the `currency` field is present. |
|
||||
| `0x20` | 32 | A change of issuer: the `issuer` field is present. |
|
||||
|
||||
<!--
|
||||
## See Also
|
||||
|
||||
- **Concepts:**
|
||||
- [Cross-Currency Payments](cross-currency-payments.html)
|
||||
- [Decentralized Exchange](decentralized-exchange.html)
|
||||
- [Partial Payments](partial-payments.html)
|
||||
- **References:**
|
||||
- [Payment transaction][]
|
||||
- [path_find method][] (WebSocket only)
|
||||
- [ripple_path_find method][]
|
||||
-->
|
||||
100
content/concepts/understanding-xrpl/tokens/rippling.md
Normal file
100
content/concepts/understanding-xrpl/tokens/rippling.md
Normal file
@@ -0,0 +1,100 @@
|
||||
# Rippling
|
||||
|
||||
In the XRP Ledger, "rippling" describes a process of atomic net settlement between multiple connected parties who have [trust lines](../transactions/trust-lines-and-issuing.md) for the same token. Rippling is essential, because it allows users who hold tokens to send those to each other with the issuer as a passive intermediary. In a sense, rippling is like a passive, two-way exchange order with no limit and a 1:1 exchange rate for two tokens with the same currency code but different issuers.
|
||||
|
||||
<!-- [exchange order](../server/offers.md) -->
|
||||
|
||||
Rippling only occurs along the [paths](paths.md) of a payment. [Direct XRP-to-XRP payments](../transactions/payments/direct-xrp-payments.md) do not involve rippling.
|
||||
|
||||
For non-issuing accounts, rippling can be undesirable because it lets other users shift obligations between tokens with the same currency code but different issuers. The [No Ripple Flag](#the-no-ripple-flag) disables rippling by default when others open trust lines to your account, unless you enable rippling by default using the [Default Ripple flag](#the-default-ripple-flag).
|
||||
|
||||
**Caution:** When you create a trust line, you must explicitly enable the `tfSetNoRipple` flag to block rippling on your side of that trust line.
|
||||
|
||||
## Example of Rippling
|
||||
|
||||
"Rippling" occurs when more than one trust line is adjusted to make a payment. For example, if Alice owes Charlie money, and Alice also owes Bob money, then you could represent that in the XRP Ledger with trust lines like so:
|
||||
|
||||
{{ include_svg("img/noripple-01.svg", "Charlie --($10)-- Alice -- ($20) -- Bob") }}
|
||||
|
||||
If Bob wants to pay $3 to Charlie, then he could say, "Alice, take $3 of the money you owe me, and pay it to Charlie." Alice transfers some of the debt from Bob to Charlie. In the end, the trust lines work out like so:
|
||||
|
||||
{{ include_svg("img/noripple-02.svg", "Charlie --($13)-- Alice --($17)-- Bob") }}
|
||||
|
||||
We call this process, where two addresses pay each other by adjusting the balances of trust lines in between them, "rippling". This is a useful and important feature of the XRP Ledger. Rippling occurs when addresses are linked by trust lines that use the same [currency code][]. The issuer does not need to be the same: in fact, larger chains always involve changing issuers.
|
||||
|
||||
## The No Ripple Flag
|
||||
|
||||
Non-issuing accounts, especially liquidity providers who may hold balances from different issuers with different fees and policies, usually do not want their balances to ripple.
|
||||
|
||||
The **No Ripple** flag is a setting on a trust line. When two trust lines both have No Ripple enabled by the same address, payments from third parties cannot ripple through that address on those trust lines. This protects liquidity providers from having balances shift unexpectedly between different issuers using the same currency code.
|
||||
|
||||
An account can disable No Ripple on a single trust line, which can allow rippling through any pair that includes that trust line. The account can also enable rippling by default by enabling the [Default Ripple flag](#the-default-ripple-flag).
|
||||
|
||||
For example, imagine Emily has money issued by two different financial institutions, like so
|
||||
|
||||
{{ include_svg("img/noripple-03.svg", "Charlie --($10)-- Institution A --($1)-- Emily --($100)-- Institution B --($2)-- Daniel") }}
|
||||
|
||||
Now Charlie can pay Daniel by rippling through Emily's address. For example, if Charlie pays Daniel $10:
|
||||
|
||||
{{ include_svg("img/noripple-04.svg", "Charlie --($0)-- Institution A --($11)-- Emily --($90)-- Institution B --($12)-- Daniel") }}
|
||||
|
||||
This may surprise Emily, who does not know Charlie or Daniel. Even worse, if Institution A charges her higher fees to withdraw her money than Institution B, this could cost Emily money. The No Ripple flag exists to avoid this scenario. If Emily sets it on both trust lines, then payments cannot ripple through her address using those two trust lines.
|
||||
|
||||
For example:
|
||||
|
||||
{{ include_svg("img/noripple-05.svg", "Charlie --($10)-- Institution A --($1, No Ripple)-- Emily --($100, No Ripple)-- Institution B --($2)-- Daniel") }}
|
||||
|
||||
Now the above scenario, where Charlie pays Daniel while rippling through Emily's address, is no longer possible.
|
||||
|
||||
### Specifics
|
||||
|
||||
The No Ripple flag makes certain paths invalid, so that they cannot be used to make payments. A path is considered invalid if and only if it enters **and** exits an address node through trust lines where No Ripple has been enabled for that address.
|
||||
|
||||
{{ include_svg("img/noripple-06.svg", "Diagram demonstrating that No Ripple has to be set on both trust lines by the same address to do anything") }}
|
||||
|
||||
|
||||
## The Default Ripple Flag
|
||||
|
||||
The **Default Ripple** flag is an account setting that enables rippling on all _incoming_ trust lines by default. Issuers MUST enable this flag for their customers to be able to send tokens to each other.
|
||||
|
||||
The Default Ripple setting of your account does not affect trust lines that you create; only trust lines that others open to you. If you change the Default Ripple setting of your account, trust lines that were created before the change keep their existing No Ripple settings. You can use a [TrustSet transaction][] to change the No Ripple setting of a trust line to match your address's new default.
|
||||
|
||||
For more information, see Default Ripple in 'Becoming an XRP Ledger Gateway'. <!--](become-an-xrp-ledger-gateway.html#default-ripple).-->
|
||||
|
||||
|
||||
## Using No Ripple
|
||||
<!--{# TODO: move these things into their own tutorials #}-->
|
||||
|
||||
### Enabling / Disabling No Ripple
|
||||
|
||||
The No Ripple flag can only be enabled on a trust line if the address has a positive or zero balance on that trust line. This is so that the feature cannot be abused to default on the obligation the trust line balance represents. (Of course, you can still default by abandoning the address.)
|
||||
|
||||
To enable the No Ripple flag, send a `TrustSet` transaction with the `tfSetNoRipple` flag. You can disable the No Ripple flag (that is, allow rippling) with the `tfClearNoRipple` flag instead.
|
||||
|
||||
|
||||
### Looking Up No Ripple Status
|
||||
|
||||
In the case of two accounts that mutually trust each other, the No Ripple flag is tracked separately for each account.
|
||||
|
||||
Using the HTTP/WebSocket APIs or your preferred [client library](../../../references/client-libraries.md), look up trust lines with the `account_lines method`. For each trust line, the `no_ripple` field shows whether the current address has enabled the No Ripple flag on that trust line, and the `no_ripple_peer` field shows whether the counterparty has enabled the No Ripple flag.
|
||||
|
||||
<!--
|
||||
|
||||
[HTTP / WebSocket APIs](http-websocket-apis.html)
|
||||
|
||||
|
||||
|
||||
## See Also
|
||||
|
||||
- **Concepts:**
|
||||
- [Paths](paths.html)
|
||||
- **Tutorials:**
|
||||
- [Become an XRP Ledger Gateway](become-an-xrp-ledger-gateway.html)
|
||||
- **References:**
|
||||
- [account_lines method][]
|
||||
- [account_info method][]
|
||||
- [AccountSet transaction][]
|
||||
- [TrustSet transaction][]
|
||||
- [AccountRoot Flags](accountroot.html#accountroot-flags)
|
||||
- [RippleState (trust line) Flags](ripplestate.html#ripplestate-flags)
|
||||
|
||||
31
content/concepts/understanding-xrpl/tokens/token-types.md
Normal file
31
content/concepts/understanding-xrpl/tokens/token-types.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# Token Types
|
||||
|
||||
You can use tokens for a variety of purposes on the XRP Ledger.
|
||||
|
||||
## Stablecoins
|
||||
|
||||
A common model for tokens in the XRP Ledger is that an issuer holds assets of equivalent value outside of the XRP Ledger, and issues tokens representing that value on the ledger. This type of issuer is sometimes called a _gateway_ because currency can move into and out of the XRP Ledger through their service. If the assets that back a token use the same amounts and denomination as the tokens in the ledger, that token can be considered a "stablecoin" because—in theory—the exchange rate between that token and its off-ledger representation should be stable at 1:1.
|
||||
|
||||
A stablecoin issuer should offer _deposits_ and _withdrawals_ to exchange the tokens for the actual currency or asset in the world outside the XRP Ledger.
|
||||
|
||||
In practice, the XRP Ledger is a computer system that cannot enforce any rules outside of itself, so stablecoins on the XRP Ledger depend on their issuer's integrity. If you can't count on the stablecoin's issuer to redeem your tokens for the real thing on demand, then you shouldn't expect the stablecoin to retain its value. As a user, you should be mindful of who's issuing the tokens: are they reliable, lawful, and solvent? If not, it's probably best not to hold those tokens.
|
||||
|
||||
For more information on how to run a gateway, see Becoming an XRP Ledger Gateway.
|
||||
|
||||
|
||||
## Community Credit
|
||||
|
||||
Another way you can use the XRP Ledger is for "community credit", a system where individuals who know each other can use the XRP Ledger to track who owes who else how much money. A powerful feature of the XRP Ledger is that it can automatically and atomically use these debts to settle payments through rippling.
|
||||
|
||||
For example, if Asheesh owes Marcus $20, and Marcus owes Bharath $50, Bharath can "pay" Asheesh $20 by canceling that much of Marcus's debt to him in exchange for canceling Asheesh's debt to Marcus. The reverse is also possible: Asheesh can pays Bharath through Marcus by increasing their respective debts. The XRP Ledger can settle complex chains of exchanges like this in a single transaction without the accounts in the middle needing to do anything manually.
|
||||
|
||||
For more on this type of usage, see paths. <!--{# TODO: It would be nice to be able to link to a page with more illustrative examples of community credit. #}-->
|
||||
|
||||
|
||||
## Other Tokens
|
||||
|
||||
There are other use cases for tokens issued in the XRP Ledger. For example, you can create an "Initial Coin Offering" (ICO) by issuing a fixed amount of currency to a secondary address, then "throwing away the key" to the issuer.
|
||||
|
||||
**Warning:** ICOs may be [regulated as securities](https://www.sec.gov/oiea/investor-alerts-and-bulletins/ib_coinofferings) in the USA. <!-- SPELLING_IGNORE: ico, icos -->
|
||||
|
||||
Be sure to research the relevant regulations before engaging in any financial service business.
|
||||
54
content/concepts/understanding-xrpl/tokens/tokens.md
Normal file
54
content/concepts/understanding-xrpl/tokens/tokens.md
Normal file
@@ -0,0 +1,54 @@
|
||||
# Tokens
|
||||
|
||||
All assets other than XRP can be represented in the XRP Ledger as **tokens**. Standard tokens are tracked in relationships called [trust lines](trust-lines-and-issuing.html) between accounts. Tokens can represent any type of value, including "stablecoins" backed by assets that exist outside of the ledger, purely digital tokens created specifically on the XRP Ledger, community credit, and more.
|
||||
|
||||
**Note:** Tokens on the XRP Ledger have also been called "IOUs" (as in [I-owe-you](https://en.wikipedia.org/wiki/IOU)) and "issued currencies" in the past. However, these terms are not preferred because they do not cover the full range of digital assets that XRP Ledger tokens can represent.
|
||||
|
||||
Any account can issue tokens to other recipients who are willing to hold them, but you cannot unilaterally give tokens away to users who do not want them.
|
||||
|
||||
Standard tokens are fungible, meaning all units of that token are interchangeable and indistinguishable. Non-fungible tokens are also possible: see [Non-Fungible Tokens](non-fungible.md) for details of the XRP Ledger's native support.
|
||||
|
||||
Tokens can used for [cross-currency payments](../transactions/payments/cross-currency-payments.md) and can be traded in the <!-- * -->decentralized exchange.
|
||||
|
||||
<!-- * [decentralized exchange](../server/decentralized-exchange.md) -->
|
||||
|
||||
The balance on a trust line is negative or positive depending on which side you view it from. The side with the negative balance is called the "issuer" and can control some properties of how those tokens behave. When you send tokens to another account that isn't the issuer, those tokens "ripple" through the issuer and possibly other accounts using the same currency code. This is useful in some cases, but can cause unexpected and undesirable behavior in others. You can use the [No Ripple flag](rippling.md#the-no-ripple-flag) on trust lines to prevent those trust lines from rippling.
|
||||
|
||||
## Token Properties
|
||||
|
||||
Tokens in the XRP Ledger are <!--*-->fundamentally different than XRP. Tokens always exist _in trust lines_, and all transfers of tokens move along trust lines. You cannot cause someone else's account to hold more of a token than the _limit_ configured on their trust line. (You _can_ cause your own trust line to go over the limit, for example by buying more of it in the <!-- -->decentralized exchange or by decreasing the limit after you already have a positive balance.)
|
||||
|
||||
<!-- * [fundamentally different than XRP](currency-formats.md#comparison) -->
|
||||
<!-- [decentralized exchange](../servers/decentralized-exchange.md) -->
|
||||
|
||||
Tokens use decimal (base-10) math with 15 digits of precision and an exponent that allows them to express very large values (up to 9999999999999999 × 10<sup>80</sup>) and very small values (down to 1.0 × 10<sup>-81</sup>).
|
||||
|
||||
Anyone can issue tokens by sending a `Payment` transaction if the necessary trust lines are in place. You can "burn" tokens by sending them back to the issuer. In some cases, [cross-currency payments](../transactions/payments/cross-currency-payments.md) or trades can also create more tokens according to an issuer's settings.
|
||||
|
||||
Issuers can charge a [transfer fee](transfer-fees.md) that is automatically deducted when users transfer their tokens. Issuers can also define a <!-- * -->tick size for exchanges rates involving their tokens. Both issuers and regular accounts can [freeze](freezing-tokens.md) trust lines, which limits how the tokens in those trust lines can be used. (None of these things applies to XRP.)
|
||||
|
||||
<!-- * [tick size](ticksize.md) -->
|
||||
|
||||
<!--
|
||||
For a tutorial of the technical steps involved in issuing a token, see [Issue a Fungible Token](issue-a-fungible-token.html).
|
||||
|
||||
|
||||
## See Also
|
||||
|
||||
- **Concepts:**
|
||||
- [XRP](xrp.html)
|
||||
- [Cross-Currency Payments](cross-currency-payments.html)
|
||||
- [Decentralized Exchange](decentralized-exchange.html)
|
||||
- **Tutorials:**
|
||||
- [Issue a Fungible Token](issue-a-fungible-token.html)
|
||||
- [Become an XRP Ledger Gateway](become-an-xrp-ledger-gateway.html)
|
||||
- [Look Up Transaction Results](look-up-transaction-results.html)
|
||||
- [Use Specialized Payment Types](use-specialized-payment-types.html)
|
||||
- **References:**
|
||||
- [Payment transaction][]
|
||||
- [TrustSet transaction][]
|
||||
- [RippleState object](ripplestate.html)
|
||||
- [account_lines method][]
|
||||
- [account_currencies method][]
|
||||
- [gateway_balances method][]
|
||||
-->
|
||||
76
content/concepts/understanding-xrpl/tokens/transfer-fees.md
Normal file
76
content/concepts/understanding-xrpl/tokens/transfer-fees.md
Normal file
@@ -0,0 +1,76 @@
|
||||
# Transfer Fees
|
||||
|
||||
[Token](tokens.html) issuers can charge a _transfer fee_ that applies when users transfer those tokens among themselves. The sender of the transfer is debited an extra percentage based on the transfer fee, while the recipient of the transfer is credited the intended amount. The difference is the transfer fee.
|
||||
|
||||
For standard tokens, the tokens paid in the transfer fee are burned, and no longer tracked in the XRP Ledger. If the token is backed by off-ledger assets, this reduces the amount of those assets the issuer has to hold in reserve to meet its obligations in the XRP Ledger. Transfer fees are usually not appropriate for tokens that aren't backed with outside assets.
|
||||
|
||||
Non-fungible tokens :not_enabled: can also have transfer fees, but they work differently. For details, see [Non-Fungible Tokens](non-fungible-tokens.html).
|
||||
|
||||
The transfer fee does not apply when sending or receiving _directly_ to and from the issuing account, but it does apply when transferring from an [operational address][] to another user.
|
||||
|
||||
[operational address]: issuing-and-operational-addresses.html
|
||||
[issuing address]: issuing-and-operational-addresses.html
|
||||
|
||||
XRP never has a transfer fee, because it never has an issuer.
|
||||
|
||||
## Example
|
||||
|
||||
In this example, ACME Bank issues a EUR stablecoin on the XRP Ledger. ACME Bank might set the transfer fee to 1%. For the recipient of a payment to get 2 EUR.ACME, the sender must send 2.02 EUR.ACME. After the transaction, ACME's outstanding obligations in the XRP Ledger have decreased by 0.02€, which means that ACME no longer needs to hold that amount in the bank account backing its EUR stablecoin.
|
||||
|
||||
The following diagram shows an XRP Ledger payment of 2 EUR.ACME from Alice to Charlie with a transfer fee of 1%:
|
||||
|
||||
{{ include_svg("img/transfer-fees.svg", "Alice sends 2,02€, Charlie receives 2,00€, and ACME owes 0,02€ less in the XRP Ledger") }}
|
||||
|
||||
In accounting terms, Alice's, ACME's, and Charlie's balance sheets may have changed like this:
|
||||
|
||||
{{ include_svg("img/transfer-fees-balance-sheets.svg", "Alice's assets are down 2,02€, Charlie's are up 2,00€, and ACME's liabilities are down 0,02€") }}
|
||||
|
||||
|
||||
|
||||
## Transfer Fees in Payment Paths
|
||||
|
||||
<!--{# TODO: Update this for OwnerPaysFee amendment when that gets added #}-->
|
||||
|
||||
A transfer fee applies whenever an individual transfer would move tokens from one party to another (except when going to/from the issuing account directly). In more complex transactions, this can occur multiple times. Transfer fees apply starting from the end and working backwards, so that ultimately the sender of a payment must send enough to account for all fees. For example:
|
||||
|
||||
{{ include_svg("img/transfer-fees-in-paths.svg", "Diagram of cross-currency payment with transfer fees") }}
|
||||
|
||||
In this scenario, Salazar (the sender) holds EUR issued by ACME, and wants to deliver 100 USD issued by WayGate to Rosa (the recipient). FXMaker is a trader with the best offer in the order book, at a rate of 1 USD.WayGate for every 0.9 EUR.ACME. If there were no transfer fees, Salazar could deliver 100 USD to Rosa by sending 90 EUR. However, ACME has a transfer fee of 1% and WayGate has a transfer fee of 0.2%. This means:
|
||||
|
||||
* FXMaker must send 100.20 USD.WayGate for Rosa to receive 100 USD.WayGate.
|
||||
* FXMaker's current ask is 90.18 EUR.ACME to send 100.20 USD.WayGate.
|
||||
* For FXMaker to receive 90.18 EUR.ACME, Salazar must send 91.0818 EUR.ACME.
|
||||
|
||||
<!-- SPELLING_IGNORE: waygate, fxmaker -->
|
||||
|
||||
# Technical Details
|
||||
|
||||
The transfer fee is represented by a setting on the [issuing address][]. The transfer fee cannot be less than 0% or more than 100% and is rounded down to the nearest 0.0000001%. The transfer fee applies to all tokens issued by the same account. If you want to have different transfer fees for different tokens, use multiple [issuing addresses][issuing address].
|
||||
|
||||
In the [XRP Ledger protocol](protocol-reference.html), the transfer fee is specified in the `TransferRate` field, as an integer which represents the amount you must send for the recipient to get 1 billion units of the same token. A `TransferRate` of `1005000000` is equivalent to a transfer fee of 0.5%. By default, the `TransferRate` is set to no fee. The value of `TransferRate` cannot be set to less than `1000000000` ("0%" fee) or more than `2000000000` (a "100%" fee). The value `0` is special case for no fee, equivalent to `1000000000`.
|
||||
|
||||
A token issuer can submit an [AccountSet transaction][] from its [issuing address][] to change the `TransferRate` for all its tokens.
|
||||
|
||||
Anyone can check an account's `TransferRate` with the [account_info method][]. If the `TransferRate` is omitted, then that indicates no fee.
|
||||
|
||||
**Note:** The [fix1201 amendment](amendments.html), introduced in `rippled` v0.80.0 and enabled on 2017-11-14, lowered the maximum transfer fee to 100% (a `TransferRate` of `2000000000`) from an effective limit of approximately 329% (based on the maximum size of a 32-bit integer). The ledger may still contain accounts with a transfer fee setting higher than 100% because transfer fees that were already set continue to apply at their stated rate.
|
||||
|
||||
## Client Library Support
|
||||
|
||||
Some [client libraries](client-libraries.html) have convenience functions for getting and setting `TransferRate` functions.
|
||||
|
||||
**JavaScript:** Use `xrpl.percentToTransferRate()` to convert a percentage transfer fee from a string to the corresponding `TransferRate` value.
|
||||
|
||||
## See Also
|
||||
|
||||
- **Concepts:**
|
||||
- [Fees (Disambiguation)](fees.html)
|
||||
- [Transaction Cost](transaction-cost.html)
|
||||
- [Paths](paths.html)
|
||||
- **Tutorials:**
|
||||
- [Become an XRP Ledger Gateway](become-an-xrp-ledger-gateway.html)
|
||||
- **References:**
|
||||
- [account_lines method][]
|
||||
- [account_info method][]
|
||||
- [AccountSet transaction][]
|
||||
- [AccountRoot Flags](accountroot.html#accountroot-flags)
|
||||
@@ -0,0 +1,17 @@
|
||||
# About Canceling a Transaction
|
||||
|
||||
An important and intentional feature of the XRP Ledger is that a [transaction](transactions.md)'s outcome is [final](finality-of-results.md) as soon as it has been incorporated in a [ledger version](../xrpl/ledgers.md) that is validated by the [consensus process](../xrpl/consensus.md).
|
||||
|
||||
If a transaction has _not_ yet been included in a validated ledger, it might be possible to effectively cancel it by sending another transaction from the same sending address with the same `Sequence` value. If you do not want the replacement transaction to do anything, send an `AccountSet` transaction with no options.
|
||||
|
||||
**Caution:** There is no guaranteed way to cancel a valid transaction after it has been distributed to the network. The process described here might or might not work, depending on factors including how busy the network is, the network topology, and the [transaction cost](transaction-cost.md) of the proposed transaction.
|
||||
|
||||
<!-- Too many links here. -->
|
||||
|
||||
If the transaction has already been distributed to the network and proposed as a [candidate transaction](../xrpl/consensus.md#consensus-1) in servers' consensus proposals, it might be too late to cancel. It is more likely that you can successfully cancel a transaction that is [queued](../server/transaction-queue.md) or is stuck "in limbo" because its [transaction cost](transaction-cost.md) is not high enough to meet the network's current requirements. In this case, the replacement transaction can either do nothing, or do the same thing as the transaction to be canceled. The replacement transaction is more likely to succeed if its transaction cost is higher.
|
||||
|
||||
For example, if you try to submit 3 transactions with sequence numbers 11, 12, and 13, but transaction 11 gets lost somehow or does not have a high enough [transaction cost](transaction-cost.md) to be propagated to the network, then you can cancel transaction 11 by submitting an AccountSet transaction with no options and sequence number 11. This does nothing (except destroying the transaction cost for the new transaction 11), but it allows transactions 12 and 13 to become valid.
|
||||
|
||||
This approach is preferable to renumbering and resubmitting transactions 12 and 13, because it prevents transactions from being effectively duplicated under different sequence numbers.
|
||||
|
||||
In this way, an AccountSet transaction with no options is the canonical "[no-op](http://en.wikipedia.org/wiki/NOP)" transaction.
|
||||
@@ -0,0 +1,58 @@
|
||||
# Finality of Results
|
||||
|
||||
The order in which transactions apply to the consensus [ledger](../xrpl/ledgers.md) is not final until a ledger is closed and the exact transaction set is approved by the [consensus process](../xrpl/consensus.md). A transaction that succeeded initially could still fail, and a transaction that failed initially could still succeed. Additionally, a transaction that was rejected by the consensus process in one round could achieve consensus in a later round.
|
||||
|
||||
A validated ledger can include successful transactions (`tes` result codes) as well as failed transactions (`tec` result codes). No transaction with any other result is included in a ledger.
|
||||
|
||||
For any other result code, it can be difficult to determine if the result is final. The following table summarizes when a transaction's outcome is final, based on the result code from submitting the transaction:
|
||||
|
||||
| Result Code | Finality |
|
||||
|:----------------|:-----------------------------------------------------------|
|
||||
| `tesSUCCESS` | Final when included in a validated ledger |
|
||||
| Any `tec` code | Final when included in a validated ledger |
|
||||
| Any `tem` code | Final unless the protocol changes to make the transaction valid |
|
||||
| `tefPAST_SEQ` | Final when another transaction with the same sequence number is included in a validated ledger |
|
||||
| `tefMAX_LEDGER` | Final when a validated ledger has a ledger index higher than the transaction's `LastLedgerSequence` field, and no validated ledger includes the transaction |
|
||||
|
||||
Any other transaction result is potentially not final. In that case, the transaction could still succeed or fail later, especially if conditions change such that the transaction is no longer prevented from applying. For example, trying to send a non-XRP currency to an account that does not exist yet would fail, but it could succeed if another transaction sends enough XRP to create the destination account. A server might even store a temporarily-failed, signed transaction and then successfully apply it later without asking first.
|
||||
|
||||
## How can non-final results change?
|
||||
|
||||
When you initially submit a transaction, the `rippled` server tentatively applies that transaction to its current open ledger, then returns the tentative [transaction results](../transactions/transaction-results/transaction-results.md) from doing so. However, the transaction's final result might be very different than its tentative results, for several reasons:
|
||||
|
||||
- The transaction might be delayed until a later ledger version, or might never be included in a validated ledger. For the most part, the XRP Ledger follows a principle that all valid transactions should be processed as soon as possible. However, there are exceptions, including:
|
||||
|
||||
- If a proposed transaction has not been relayed to a majority of validators by the time a [consensus round](../xrpl/consensus.md) begins, it might be postponed until the next ledger version, to give the remaining validators time to fetch the transaction and confirm that it is valid.
|
||||
|
||||
- If an address sends two different transactions using the same sequence number, at most one of those transactions can become validated. If those transactions are relayed through the network in different paths, a tentatively-successful transaction that some servers saw first might end up failing because the other, conflicting transaction reached a majority of servers first.
|
||||
|
||||
- To protect the network from spam, all transactions must destroy a [transaction cost](transaction-cost.md) in XRP to be relayed throughout the XRP Ledger peer-to-peer network. If heavy load on the peer-to-peer network causes the transaction cost to increase, a transaction that tentatively succeeded might not get relayed to enough servers to achieve a consensus, or might be [queued](../server/transaction-queue.md) for later.
|
||||
|
||||
- Temporary internet outages or delays might prevent a proposed transaction from being successfully relayed before the transaction's intended expiration, as set by the `LastLedgerSequence` field. (If the transaction does not have an expiration, then it remains valid and could succeed any amount of time later, which can be undesirable in its own way.
|
||||
|
||||
<!-- See [Reliable Transaction Submission](reliable-transaction-submission.html) for details.) -->
|
||||
|
||||
- Combinations of two or more of these factors can also occur.
|
||||
|
||||
- The [order transactions apply in a closed ledger](../xrpl/ledgers.md#open-closed-and-validated-ledgers) is usually different than the order those transactions were tentatively applied to a current open ledger; depending on the transactions involved, this can cause a tentatively-successful transaction to fail or a tentatively-failed transaction to succeed. Some examples include:
|
||||
|
||||
- If two transactions would each fully consume the same <!-- * -->offer] in the decentralized exchange, whichever one comes first succeeds, and the other fails. Since the order in which those transactions apply might change, the one that succeeded can fail and the one that failed can succeed. Since offers can be partially executed, they could also still succeed, but to a greater or lesser extent.
|
||||
|
||||
<!-- * [Offer](offers.html) -->
|
||||
<!-- [decentralized exchange](decentralized-exchange.html) -->
|
||||
|
||||
- If a [cross-currency payment](./payments/cross-currency-payments.md) succeeds by consuming an <!-- * -- >Offer in the <!-- * -->decentralized exchange, but a different transaction consumes or creates offers in the same order book, the cross-currency payment might succeed with a different exchange rate than it had when it executed tentatively. If it was a [partial payment](./payments/partial-payments.md), it could also deliver a different amount.
|
||||
|
||||
- A `Payment` transaction that tentatively failed because the sender did not have enough funds might later succeed because another transaction delivering the necessary funds came first in the canonical order. The reverse is also possible: a transaction that tentatively succeeded might fail because a transaction delivering the necessary funds did not come first after being put into canonical order.
|
||||
|
||||
**Tip:** For this reason, when running tests against the XRP Ledger, be sure to wait for a ledger close in between transactions if you have several accounts affecting the same data. If you are testing against a server in stand-alone mode, you must manually close the ledger in such cases.
|
||||
|
||||
<!-- [manually close the ledger](advance-the-ledger-in-stand-alone-mode.html) -->
|
||||
|
||||
<!--
|
||||
## See Also
|
||||
|
||||
- [Look up Transaction Results](look-up-transaction-results.html)
|
||||
- [Transaction Results Reference](transaction-results.html)
|
||||
|
||||
-->
|
||||
@@ -0,0 +1,79 @@
|
||||
# Multi-Signing
|
||||
|
||||
Multi-signing in the XRP Ledger is a method of [authorizing transactions](transactions.md#authorizing-transactions) for the XRP Ledger by using a combination of multiple secret keys. You can have any combination of authorization methods enabled for your address, including multi-signing, a [master key pair](../accounts/cryptographic-keys.md#master-key-pair), and a [regular key pair](../accounts/cryptographic-keys.md#regular-key-pair). (The only requirement is that _at least one_ method must be enabled.)
|
||||
|
||||
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.
|
||||
|
||||
## SignerLists
|
||||
|
||||
Before you can multi-sign, you must create a list of which addresses can sign for you.
|
||||
|
||||
The `SignerListSet` transaction defines which addresses can authorize transactions from your address. You can include 1 to 8 addresses in a SignerList. The SignerList cannot include the sender's address and there can be no duplicate entries. You can control how many signatures are needed, in which combinations, by using the *SignerWeight* and *SignerQuorum* values of the SignerList.
|
||||
|
||||
If the `ExpandedSignerList` amendment :not_enabled: is enabled, you can include 1 to 32 addresses in a SignerList.
|
||||
|
||||
### Signer Weight
|
||||
|
||||
You can assign a weight to each signer in the SignerList. The weight represents the relative authority of the signer to other signers on the list. The higher the value, the more authorization authority. Individual weight values cannot exceed 2<sup>16</sup>-1.
|
||||
|
||||
### Signer Quorum
|
||||
|
||||
The quorum value is the minimum weight total required to authorize a transaction. The quorum must be greater than 0 but less than or equal to the sum of the weight values in the SignerList: meaning, it must be possible to achieve a quorum with the given signer weights.
|
||||
|
||||
### Wallet Locator
|
||||
|
||||
If the `ExpandedSignerList` amendment :not_enabled: is enabled, you can also add up to 256 bits of arbitrary data to each signer's entry in the list. This data is not required or used by the network, but can be used by smart contracts or other applications to identify or confirm other data about the signers.
|
||||
|
||||
### Examples Using Signer Weight and Signer Quorum
|
||||
|
||||
The weight and quorum allow you to set an appropriate level of oversight for each transaction, based on the relative trust and authority relegated to responsible participants who manage the account.
|
||||
|
||||
For a typical use case, you might have a shared account with a quorum of 1, then give all participants a weight of 1. A single approval from any one of them is all that is required to approve a transaction.
|
||||
|
||||
For a very important account, you might set the quorum to 3, with 3 participants that have a weight of 1. All of the participants must agree and approve each transaction.
|
||||
|
||||
Another account might also have a quorum of 3. You assign your CEO a weight of 3, 3 Vice Presidents a weight of 2 each, and 3 Directors a weight of 1 each. To approve a transaction for this account requires the approval of all 3 Directors (total weight of 3), 1 Vice President and 1 Director (total weight of 3), 2 Vice Presidents (total weight of 4), or the CEO (total weight of 3).
|
||||
|
||||
In each of the previous three use cases, you would disable the master key without configuring a regular key, so that multi-signing is the only way of [authorizing transactions](transactions.md#authorizing-transactions).
|
||||
|
||||
There might be a scenario where you create a multi-signing list as a "backup plan." The account owner normally uses a regular key for their transactions (not a multi-signing key). For safety, the owner adds a SignerList containing 3 friends, each with a weight of 1, and a quorum of 3. If the account owner were to lose the private key, they can ask their friends to multi-sign a transaction to replace the regular key.
|
||||
|
||||
|
||||
## Sending Multi-Signed Transactions
|
||||
|
||||
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 have a SignerList in the ledger.<!--
|
||||
[SignerList in the ledger](signerlist.html)
|
||||
|
||||
For instructions on how to do this, see [Set Up Multi-Signing](set-up-multi-signing.html).
|
||||
|
||||
-->* The transaction must include the `SigningPubKey` field as an empty string.
|
||||
* The transaction must include a `Signers` field containing an array of signatures.<!--
|
||||
](transaction-common-fields.html#signers-field)
|
||||
-->* 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](transaction-cost.md) (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.<!-- [auto-fill](transaction-common-fields.html#auto-fillable-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` method handles this automatically.)
|
||||
|
||||
<!--
|
||||
## See Also
|
||||
|
||||
- **Tutorials:**
|
||||
- [Set Up Multi-Signing](set-up-multi-signing.html)
|
||||
- [Send a Multi-Signed Transaction](send-a-multi-signed-transaction.html)
|
||||
- **Concepts:**
|
||||
- [Cryptographic Keys](cryptographic-keys.html)
|
||||
- [Special Transaction Cost for Multi-signed transactions](transaction-cost.html#special-transaction-costs)
|
||||
- **References:**
|
||||
- [SignerListSet transaction][]
|
||||
- [SignerList object](signerlist.html)
|
||||
- [sign_for method][]
|
||||
- [submit_multisigned method][]
|
||||
-->
|
||||
@@ -0,0 +1,108 @@
|
||||
# Checks
|
||||
|
||||
_(Added by the Checks amendment.)_
|
||||
|
||||
The Checks feature in the XRP Ledger allows users to create deferred payments that can be canceled or cashed by the intended recipients. Like personal paper checks, XRP Ledger Checks start with the sender of the funds creating a Check that specifies an amount and a recipient. The recipient cashes the check to pull the funds from the sender's account into the recipient's account. No money moves until the recipient cashes the Check. Because funds are not put on hold when the Check is created, cashing a Check can fail if the sender doesn't have enough funds when the recipient tries to cash it. If there's a failure cashing the check, the check's recipient can retry until the Check expires.
|
||||
|
||||
XRP Ledger Checks may have expiration times after which they may no longer be cashed. If the recipient doesn't successfully cash the Check before it expires, the Check can no longer be cashed, but the object remains in the XRP Ledger until someone cancels it. Anyone may cancel the Check after it expires. Only the sender and recipient can cancel the Check before it expires. The Check object is removed from the Ledger when the sender successfully cashes the check or someone cancels it.
|
||||
|
||||
Checks have some similarities to [escrow](escrow.md) and [payment channels](payment-channels.md), but there are some important differences between those features and checks:
|
||||
|
||||
* You can send [tokens](../../tokens/tokens.md) with checks. With payment channels and Escrow, you can only send XRP.
|
||||
|
||||
* Checks do not lock up or set aside any funds. The XRP involved in payment channels and escrow cannot be spent until it is redeemed with a claim provided by the sender (payment channels), or released by an expiration or crypto-condition (escrow).
|
||||
|
||||
* You can send XRP to yourself through escrow. You cannot send checks to yourself.
|
||||
|
||||
|
||||
**Note:** The Checks amendment changes the expiration behavior of the `OfferCreate` transaction.
|
||||
|
||||
<!-- For more information, see [Offer Expiration](offers.html#offer-expiration). -->
|
||||
|
||||
|
||||
## Why Checks?
|
||||
|
||||
Traditional paper checks allow people to transfer funds without immediately exchanging physical currency. XRP Ledger Checks allow people to exchange funds asynchronously using a process that is familiar to and accepted by the banking industry.
|
||||
|
||||
XRP Ledger Checks also solve a problem that is unique to the XRP Ledger: they allow users to reject unwanted payments or accept only part of a payment. This is useful for institutions that need to be careful about accepting payments for compliance reasons.
|
||||
|
||||
|
||||
### Use Case: Payment Authorization
|
||||
|
||||
**Problem:** To comply with regulations like BSA, KYC, AML, and CFT, financial institutions must provide documentation about the source of funds they receive. Such regulations seek to prevent the illicit transfer of funds by requiring institutions to know the source and destination of all payments processed by the institution. Because of the nature of the XRP Ledger, anyone could potentially send XRP (and, under the right circumstances, tokens) to an institution's account on the XRP Ledger. Dealing with such unwanted payments adds significant cost and time delays to these institutions' compliance departments, including potential fines or penalties. <!-- SPELLING_IGNORE: cft -->
|
||||
|
||||
<!-- [BSA, KYC, AML, and CFT](become-an-xrp-ledger-gateway.html#gateway-compliance) -->
|
||||
|
||||
**Solution:** Institutions can enable deposit authorization on their XRP Ledger accounts by setting the `asfDepositAuth` flag in an `AccountSet` transaction. This makes the account unable to receive Payment transactions. Accounts with Deposit Authorization enabled can only receive funds through Escrow, Payment Channels, or Checks. Checks are the most straightforward, familiar, and flexible way to transfer funds if Deposit Authorization is enabled.
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
Checks typically have the lifecycle described below.
|
||||
|
||||
<!--{# Diagram source: https://docs.google.com/drawings/d/1Ez8OZVB2TLH-b_kSFOAgfYqXlEQt4KaUBW6F3TJAv_Q/edit #}-->
|
||||
|
||||
[](../../../../img/checks-happy-path.png)
|
||||
|
||||
**Step 1:** To create a Check, the sender submits a `CheckCreate` transaction and specifies the recipient (`Destination`), expiration time (`Expiration`), and maximum amount that may be debited from the sender's account (`SendMax`).
|
||||
|
||||
|
||||
**Step 2:** After the CheckCreate transaction is processed, a Check object is created on the XRP Ledger. This object contains the properties of the check as defined by the transaction that created it. The object can only be modified by the sender (by canceling it with a `CheckCancel` transaction) or recipient (by canceling it or cashing it) before the expiration time passes. After the expiration time, anyone may cancel the Check.
|
||||
|
||||
**Step 3:** To cash the check, the recipient submits a `CheckCash` transaction. The recipient has two options for cashing the check:
|
||||
|
||||
* `Amount` — The recipient can use this option to specify an exact amount to cash. This may be useful for cases where the sender has padded the check to cover possible [transfer fees](../../tokens/transfer-fees.md) and the recipient wants to accept the exact amount on an invoice or other contract.
|
||||
|
||||
* `DeliverMin` — The recipient can use this option to specify the minimum amount they are willing to receive from the Check. If the recipient uses this option, the XRP Ledger attempts to deliver as much as possible and always delivers at least this amount. The transaction fails if the amount that can be credited to the recipient is not at least the requested amount.
|
||||
|
||||
If the sender has enough funds to cover the Check and the expiration time has not passed, the funds are debited from the sender's account and credited to the recipient's account, and the Check object is destroyed.
|
||||
|
||||
|
||||
|
||||
#### Expiration Case
|
||||
|
||||
In the case of expirations, Checks have the lifecycle described below.
|
||||
|
||||
<!--{# Diagram source: https://docs.google.com/drawings/d/11auqa0kVUPonqlc_RaQUfHcSkUI47xneSKpwlLxzSK0/edit #}-->
|
||||
|
||||
[](../../../../img/checks-expiration.png)
|
||||
|
||||
|
||||
All Checks start the same way, so **Steps 1 and 2** are the same.
|
||||
|
||||
**Step 3a:** If the Check expires before the recipient can cash it, the Check can no longer be cashed but the object remains in the ledger.
|
||||
|
||||
**Step 4a:** After a Check expires, anyone may cancel it by submitting a [CheckCancel][] transaction. That transaction removes the Check from the ledger.
|
||||
|
||||
<!-- SPELLING_IGNORE: 3a, 4a -->
|
||||
|
||||
|
||||
## Availability of Checks
|
||||
|
||||
The Checks amendment became enabled on the XRP Ledger Mainnet on 2020-06-18. For more information about how amendments are enabled and voted on, see [Amendment Process](../../../../amendments/amendments.md#amendment-process).
|
||||
|
||||
To check the status of an amendment on a test network or private network, use the `feature` method.
|
||||
|
||||
<!--
|
||||
## See Also
|
||||
|
||||
For more information about Checks in the XRP Ledger, see:
|
||||
|
||||
- [Transaction Reference](transaction-types.html)
|
||||
- [CheckCreate][]
|
||||
- [CheckCash][]
|
||||
- [CheckCancel][]
|
||||
- [Checks Tutorials](use-checks.html)
|
||||
- [Send a Check](send-a-check.html)
|
||||
- [Look up Checks by sender address](look-up-checks-by-sender.html)
|
||||
- [Look up Checks by recipient address](look-up-checks-by-recipient.html)
|
||||
- [Cash a Check for an exact amount](cash-a-check-for-an-exact-amount.html)
|
||||
- [Cash a Check for a flexible amount](cash-a-check-for-a-flexible-amount.html)
|
||||
- [Cancel a Check](cancel-a-check.html)
|
||||
- [Checks amendment][]
|
||||
|
||||
For more information about related features, see:
|
||||
|
||||
* [Deposit Authorization](depositauth.html)
|
||||
* [Escrow](escrow.html)
|
||||
* [Payment Channels Tutorial](use-payment-channels.html) -->
|
||||
@@ -0,0 +1,34 @@
|
||||
# Cross-Currency Payments
|
||||
|
||||
In the XRP Ledger, you can send cross-currency payments that exchange tokens, XRP, or both. Like [direct XRP payments](direct-xrp-payments.md), these payments use the `Payment transaction` type. Cross-currency payments within the XRP Ledger are fully atomic, meaning that either the payment fully executes or no part of it executes.
|
||||
|
||||
By default, cross-currency payments deliver a fixed amount to their destination at a variable cost to their source. Cross-currency payments can also be [partial payments](partial-payments.md), which deliver a variable amount to the destination within a fixed sending limit.
|
||||
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- By definition, a cross-currency payment involves at least two currencies, which means that at least one currency involved must be a non-XRP [token](../../tokens/tokens.md).
|
||||
- There must be at least one [path](../../tokens/paths.md) between the sender and receiver, and the total liquidity across all paths must be enough to execute the payment. Cross-currency payments convert from one currency to another by consuming offers in the XRP Ledger's decentralized exchange.
|
||||
|
||||
<!-- [Offers](offers.html) in the XRP Ledger's [decentralized exchange](decentralized-exchange.html). -->
|
||||
|
||||
|
||||
## Auto-Bridging
|
||||
|
||||
Cross-currency payments that exchange one token for another token can automatically use XRP to bridge the tokens, when it decreases the cost of the payment. For example, a payment sending from USD to MXN automatically converts USD to XRP and then XRP to MXN if doing so is cheaper than converting USD to MXN directly. Larger trades can use a combination of direct (USD-MXN) and auto-bridged (USD-XRP-MXN) conversions.
|
||||
|
||||
<!--
|
||||
For more information, see [Auto-Bridging](autobridging.html).
|
||||
|
||||
|
||||
## See Also
|
||||
|
||||
- **Concepts:**
|
||||
- [Tokens](tokens.html)
|
||||
- [Decentralized Exchange](decentralized-exchange.html)
|
||||
- [Paths](paths.html)
|
||||
- **References:**
|
||||
- [Payment transaction type][Payment transaction]
|
||||
- [path_find method][]
|
||||
- [ripple_path_find method][]
|
||||
- [Interpreting Metadata of Cross-Currency Payments](look-up-transaction-results.html#token-payments) -->
|
||||
@@ -0,0 +1,85 @@
|
||||
# Direct XRP Payments
|
||||
|
||||
The basis of any financial system is _transferring value_: or, in one word, payments. The simplest type of payment in the XRP Ledger is a direct XRP-to-XRP payment, which transfers XRP directly from one account in the XRP Ledger to another.
|
||||
|
||||
## About Direct XRP-to-XRP Payments
|
||||
|
||||
Generally, any address in the XRP Ledger can send XRP directly to any other address. The address on the receiving side is often called the _destination address_, and the address on the sending side is called the _source address_. To send XRP directly, the sender uses a `Payment` transaction, which can be as concise as the following:
|
||||
|
||||
```json
|
||||
{
|
||||
"TransactionType": "Payment",
|
||||
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
||||
"Destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
|
||||
"Amount": "13000000"
|
||||
}
|
||||
```
|
||||
|
||||
These transaction instructions mean: Send a payment from `rf1Bi...` to `ra5nK...` delivering exactly 13 XRP. If the transaction is successfully processed, it does exactly that. Since it usually takes about 4 seconds for each new ledger version to become [validated](../../xrpl/consensus.md), a successful transaction can be created, submitted, executed, and have a final outcome in 8 seconds or less, even if gets queued for the ledger version after the current in-progress one.
|
||||
|
||||
**Caution:** The `Payment` transaction type can also be used for some more specialized kinds of payments, including [cross-currency payments](cross-currency-payments.md) and [partial payments](partial-payments.md). In the case of partial payments, it is possible that the `Amount` shows a large amount of XRP even if the transaction only delivered a very small amount. See [partial payments exploit](partial-payments.md#partial-payments-exploit) for how to avoid crediting a customer for the wrong amount.
|
||||
|
||||
Direct XRP-to-XRP payments cannot be partial payments, but partial payments can deliver XRP after converting from a different source currency.
|
||||
|
||||
|
||||
## Funding Accounts
|
||||
|
||||
Any mathematically-valid address can receive a payment, even if the XRP Ledger has no record of that address existing beforehand, as long as the payment delivers enough XRP to meet the minimum [account reserve](../../accounts/reserves.md). If the payment would not deliver enough XRP, it fails.
|
||||
|
||||
For more information, see [Accounts](../../accounts/accounts.md#creating-accounts).
|
||||
|
||||
|
||||
## Address Reuse
|
||||
|
||||
In the XRP Ledger, addresses where you can receive payments are permanent, and have a non-trivial [reserve requirement](../../accounts/reserves.md) of XRP that they cannot spend. This means that, contrary to some other blockchain systems, it is not a good idea to use a different, disposable address for every transaction. The best practice for the XRP Ledger is to reuse the same address for multiple transactions. If you use the address regularly (especially if it's managed by an internet-connected service), you should set a [regular key](../../accounts/cryptographic-keys.md) and proactively change keys on a regular basis to reduce the risk of a key compromise.
|
||||
|
||||
As a sender, it is best not to assume that your intended recipient is using the same address from the last time you sent them a payment. Inevitably, sometimes security compromises happen and a person or business has to change addresses. Before sending money, you should ask the recipient for their current receiving address, so you don't accidentally send money to a malicious user who has taken control of a compromised old address.
|
||||
|
||||
|
||||
## How Direct XRP Payments Are Processed
|
||||
|
||||
From a relatively high level, the XRP Ledger's transaction processing engine applies a direct XRP payment as follows:
|
||||
|
||||
1. It validates the parameters of the `Payment` transaction. If the transaction is structured to send and deliver XRP, the transaction processing engine recognizes it as a direct XRP-to-XRP payment. Validation checks include:
|
||||
|
||||
- Checking that all fields are formatted correctly. For example, for direct XRP payments, the `Amount` field must be drops of XRP.
|
||||
- Checking that the sending address is a funded [account](../../accounts/accounts.md) in the XRP Ledger.
|
||||
- Checking that all provided signatures are valid for the sending address.
|
||||
- Confirming that the destination address is different than the sender address. (It is not sufficient to send to the same address with a different [destination tag](../source-and-destination-tags.md).)
|
||||
- Confirming that the sender has a high enough XRP balance to send the payment.
|
||||
|
||||
If any check fails, the payment fails.
|
||||
|
||||
2. It checks whether the receiving address is a funded account.
|
||||
|
||||
- If the receiving address is funded, the engine checks any additional requirements for receiving payments, such as [Deposit Authorization](../../accounts/deposit-authorization.md) or [`RequireDest`](../source-and-destination-tags.md#requiring-tags). If the payment does not satisfy any of these additional requirements, the payment fails.
|
||||
- If the receiving address is not funded, it checks whether the payment would deliver enough XRP to meet the minimum [account reserve](../../accounts/reserves.md). If not, the payment fails.
|
||||
|
||||
3. It debits the sending account by an amount of XRP specified by the `Amount` field plus the XRP to be destroyed for the [transaction cost](../transaction-cost.md) and credits the receiving account for the same amount.
|
||||
|
||||
If necessary, it creates a new account (`AccountRoot` object) for the receiving address. The new account's starting balance is equal to the `Amount` of the payment.
|
||||
|
||||
The engine adds a `delivered_amount` field to the [transaction's metadata](../transaction-metadata.md) to indicate how much was delivered. You should always use `delivered_amount`, **not** the `Amount` field, to avoid being tricked about how much XRP you received. (Cross-currency "Partial Payments" can deliver less XRP than stated in the `Amount` field.) For more information, see [Partial Payments](partial-payments.md).
|
||||
|
||||
|
||||
## Comparison to Other Payment Types
|
||||
|
||||
- **Direct XRP Payments** are the only way to both send and receive XRP in a single transaction. They are a good balance of speed, simplicity, and low cost.
|
||||
- [Cross-currency payments](cross-currency-payments.md) also use the `Payment` transaction type, but can send any combination of XRP and non-XRP [tokens](../../tokens/tokens.md) except XRP-to-XRP. They can also be [partial payments](partial-payments.md). Cross-currency payments are good for payments not denominated in XRP or for taking arbitrage opportunities in the decentralized exchange.
|
||||
- [Checks](checks.md) let the sender set up an obligation without transferring any money immediately. The recipient can cash it any time before it expires, but the amount is not guaranteed. Checks can send either XRP or [tokens](../../tokens/tokens.md). Checks are good for giving the recipient the autonomy to claim the payment.
|
||||
- [Escrow](escrow.md) sets aside XRP which can be claimed by its intended recipient when certain conditions are met. The XRP amount is fully guaranteed and cannot be otherwise used by the sender unless the Escrow expires. Escrow is good for smart contracts in large amounts.
|
||||
- [Payment Channels](payment-channels.md) set aside XRP. The recipient can claim XRP from the channel in bulk using signed authorizations. Individual authorizations can be verified without sending a full XRP Ledger transaction. Payment channels are good for extremely high-volume micropayments or "streaming" payments.
|
||||
|
||||
<!--
|
||||
## See Also
|
||||
|
||||
- **Concepts:**
|
||||
- [Payment System Basics](payment-system-basics.html)
|
||||
- **Tutorials:**
|
||||
- [Send XRP (Interactive Tutorial)](send-xrp.html)
|
||||
- [Monitor Incoming Payments with WebSocket](monitor-incoming-payments-with-websocket.html)
|
||||
- **References:**
|
||||
- [Payment transaction][]
|
||||
- [Transaction Results](transaction-results.html)
|
||||
- [account_info method][] - for checking XRP balances
|
||||
-->
|
||||
@@ -0,0 +1,145 @@
|
||||
# Escrow
|
||||
|
||||
Escrow is a feature of the XRP Ledger that allows you to send conditional XRP payments. These conditional payments, called _escrows_, set aside XRP and deliver it later when certain conditions are met. Conditions to successfully finish an escrow include time-based unlocks and `crypto-conditions`. Escrows can also be set to expire if not finished in time.
|
||||
|
||||
The XRP set aside in an escrow is locked up. No one can use or destroy the XRP until the escrow has been successfully finished or canceled. Before the expiration time, only the intended receiver can get the XRP. After the expiration time, the XRP can only be returned to the sender.
|
||||
|
||||
## Usage
|
||||
|
||||
<!--{# Diagram sources: https://docs.google.com/presentation/d/1C-_TLkkoQEH7KJ6Gjwa1gO6EX17SLiJ8lxvFcAl6Rxo/ #}-->
|
||||
|
||||
[](../../../../img/escrow-success-flow.png)
|
||||
|
||||
**Step 1:** To send an escrow, the sender uses an `EscrowCreate` transaction to lock up some XRP. This transaction defines a finish time, an expiration time, or both. The transaction may also define a crypto-condition that must be fulfilled to finish the escrow. This transaction must define an intended recipient for the XRP; the recipient _might_ be the same as the sender.
|
||||
|
||||
**Step 2:** After this transaction has been processed, the XRP Ledger has an Escrow object that holds the escrowed XRP. This object contains the properties of the escrow as defined by the transaction that created it. If this escrow has a finish time, no one can access the XRP before then.
|
||||
|
||||
**Step 3:** The recipient, or any other XRP Ledger address, sends an `EscrowFinish` transaction to deliver the XRP. If the correct conditions are met, this destroys the Escrow object in the ledger and credits the XRP to the intended recipient. If the escrow has a crypto-condition, this transaction must include a fulfillment for that condition. If the escrow has an expiration time that has already passed, the EscrowFinish transaction instead fails with the code [`tecNO_PERMISSION`](../transaction-results/tec-codes.html).
|
||||
|
||||
### Expiration Case
|
||||
|
||||
[](../../../../img/escrow-cancel-flow.png)
|
||||
|
||||
All escrows start the same way, so **Steps 1 and 2** are the same as in the successful case.
|
||||
|
||||
**Step 3a:** If the escrow has an expiration time, and it has not been successfully finished before then, the escrow is considered expired. It continues to exist in the XRP Ledger, but can no longer successfully finish. (Expired objects remain in the ledger until a transaction modifies them. Time-based triggers cannot change the ledger contents.)
|
||||
|
||||
**Step 4a:** The sender, or any other XRP Ledger address, sends an `EscrowCancel` transaction to cancel the expired escrow. This destroys the Escrow object in the ledger and returns the XRP to the sender.
|
||||
|
||||
<!-- SPELLING_IGNORE: 3a, 4a -->
|
||||
|
||||
|
||||
## Limitations
|
||||
|
||||
Escrow is designed as a feature to enable the XRP Ledger to be used in the `Interledger Protocol` and with other smart contracts. The current version has a modest scope to avoid complexity.
|
||||
|
||||
- Escrow only works with XRP, not tokens.
|
||||
- Escrow requires sending at least two transactions: one to create the escrow, and one to finish or cancel it. Thus, it may not be financially sensible to escrow payments for very small amounts, because the participants must destroy the [transaction cost](../transaction-cost.md) of the two transactions.
|
||||
- When using Crypto-Conditions, the [cost of the transaction to finish the escrow](#escrowfinish-transaction-cost) is higher than usual.
|
||||
- All escrows must be created with a "finish-after" time or a `crypto-condition`, or both. If the escrow does not have a finish-after time, it must have an expiration time.
|
||||
|
||||
**Note:** The _fix1571 amendment_ changed the requirements for creating an escrow. Escrows created before that amendment could provide an expiration time with no condition or finish-after time. Anyone can finish such escrows immediately (sending the funds to the intended recipient).
|
||||
|
||||
- None of the time values can be in the past when the escrow-creating transaction executes.
|
||||
- Timed releases and expirations are limited to the resolution of XRP Ledger closes. This means that, in practice, times may be rounded to approximately 5 second intervals, depending on exactly when the ledgers close.
|
||||
- The only supported `crypto-condition` type is PREIMAGE-SHA-256.
|
||||
|
||||
Escrow provides strong guarantees that are best suited for high-value, low-quantity payments. [Payment Channels](payment-channels.md) are better suited for fast, low-value payments. Of course, unconditional payments are also preferable for many use cases.
|
||||
|
||||
## State Diagram
|
||||
|
||||
The following diagram shows the states an Escrow can progress through:
|
||||
|
||||
[](../../../../img/escrow-states.png)
|
||||
|
||||
The diagram shows three different cases for three possible combinations of the escrow's "finish-after" time (`FinishAfter` field), crypto-condition (`Condition` field), and expiration time (`CancelAfter` field):
|
||||
|
||||
- **Time-based Escrow (left):** With only a finish-after time, the escrow is created in the **Held** state. After the specified time has passed, it becomes **Ready** and anyone can finish it. If the escrow has an expiration time and no one finishes it before that time passes, then the escrow becomes **Expired**. In the expired state, an escrow cannot be finished, and anyone can cancel it. If the escrow does not have a `CancelAfter` field, it never expires and cannot be canceled.
|
||||
|
||||
- **Combination Escrow (center):** If the escrow specifies both a crypto-condition (`Condition` field) _and_ a "finish-after" time (`FinishAfter` field), the escrow is **Held** until its finish-after time has passed. Then it becomes **Conditionally Ready**, and can finish it if they supply the correct fulfillment to the crypto-condition. If the escrow has an expiration time (`CancelAfter` field), and no one finishes it before that time passes, then the escrow becomes **Expired**. In the expired state, an escrow cannot be finished, and anyone can cancel it. If the escrow does not have a `CancelAfter` field, it never expires and cannot be canceled.
|
||||
|
||||
- **Conditional Escrow (right):** If the escrow specifies a crypto-condition (`Condition` field) and not a finish-after time, the escrow becomes **Conditionally Ready** immediately when it is created. During this time, anyone can finish the escrow, but only if they supply the correct fulfillment to the crypto-condition. If no one finishes the escrow before its expiration time (`CancelAfter` field), the escrow becomes **Expired**. (An escrow without a finish-after time _must_ have an expiration time.) In the expired state, the escrow can no longer be finished, and anyone can cancel it.
|
||||
|
||||
|
||||
|
||||
## Availability of Escrow
|
||||
|
||||
Conditional payments have been enabled by the ["Escrow" Amendment](../../../../amendments/known-amendments.md#escrow) to the XRP Ledger Consensus Protocol since 2017-03-31. A previous version of the same functionality was available on the XRP Ledger Test Net by the name "Suspended Payments" (SusPay) in 2016.
|
||||
|
||||
When testing in stand-alone mode, you can force the Escrow feature to be enabled locally regardless of the amendment status. Add the following stanza to your `rippled.cfg`:
|
||||
|
||||
[features]
|
||||
Escrow
|
||||
|
||||
You can check the status of the Escrow amendment using the `feature` method.
|
||||
|
||||
## EscrowFinish Transaction Cost
|
||||
|
||||
When using `crypto-conditions`, the EscrowFinish transaction must pay a [higher transaction cost](../transaction-cost.md#special-transaction-costs) because of the higher processing load involved in verifying the crypto-condition fulfillment.
|
||||
|
||||
If the escrow is purely time-locked with no crypto-condition, the EscrowFinish costs only the standard [transaction cost](../transaction-cost.html) for a reference transaction.
|
||||
|
||||
The additional transaction cost required is proportional to the size of the fulfillment. Currently, an EscrowFinish with a fulfillment requires a minimum transaction cost of **330 drops of XRP plus 10 drops per 16 bytes in the size of the fulfillment**. If the transaction is [multi-signed](../multi-signing.md), the cost of multi-signing is added to the cost of the fulfillment.
|
||||
|
||||
<!--
|
||||
[drops of XRP](basic-data-types.html#specifying-currency-amounts)
|
||||
-->
|
||||
|
||||
**Note:** The above formula is based on the assumption that the reference cost of a transaction is 10 drops of XRP.
|
||||
|
||||
If [Fee Voting](../../../xrpl/fee-voting.html) changes the `reference_fee` value, the formula scales based on the new reference cost. The generalized formula for an EscrowFinish transaction with a fulfillment is as follows:
|
||||
|
||||
```
|
||||
reference_fee * (signer_count + 33 + (fulfillment_bytes / 16))
|
||||
```
|
||||
|
||||
|
||||
## Why Escrow?
|
||||
|
||||
The age-old practice of [Escrow](https://en.wikipedia.org/wiki/Escrow) enables many kinds of financial transactions that would be considered risky otherwise, especially online. By letting a trusted third party hold the money while a transaction or evaluation period is underway, both sides can be assured that the other must hold up their end of the bargain.
|
||||
|
||||
The Escrow feature takes this idea further by replacing the third party with an automated system built into the XRP Ledger, so that the lock up and release of funds is impartial and can be automated.
|
||||
|
||||
Fully automated escrow, backed by the integrity of the XRP Ledger itself, solves important problems for Ripple, and we think there are many other use cases that escrow enables. Ripple encourages the industry to find new and unique ways to put escrow to use.
|
||||
|
||||
### Use Case: Time-based Lock-Up
|
||||
|
||||
**Background:** Ripple holds a large amount of the total XRP, which it sells methodically as a way to fund and incentivize the healthy development of the XRP Ledger and related technologies. At the same time, owning such a large chunk of XRP causes problems for the company, such as:
|
||||
|
||||
- Individuals and businesses who use the XRP Ledger worry that their investments in XRP could be diluted or devalued if Ripple were to flood the market by selling at a higher rate than usual.
|
||||
- Although flooding the market would be a long-term loss for Ripple, the possibility that the company could do so exerts downward pressure over the price of XRP, and thus decreases the value of the company's assets.
|
||||
- Ripple must carefully manage ownership of its accounts to protect against digital theft and other forms of malicious behavior, even by insiders.
|
||||
|
||||
**Solution:** By placing 55 billion XRP into time-based escrows, Ripple ensures that the supply of XRP in circulation is predictable and increases at a slow but steady rate. Others who hold XRP know that Ripple cannot flood the market, even if the company's priorities or strategy changes.
|
||||
|
||||
Placing the money into escrow does not directly protect Ripple's holdings from malicious actors, but it sharply reduces the amount of XRP that can be quickly stolen or redirected if a malicious actor gains temporary control over Ripple's XRP accounts. This reduces the risk of catastrophic losses of XRP and increases the time for Ripple to detect, prevent, and track down unintended uses of Ripple's XRP assets.
|
||||
|
||||
### Use Case: Interledger Payments
|
||||
|
||||
**Background:** In the quickly-developing world of financial technology, one of the core challenges is coordinating activities that cross multiple digital money systems, or ledgers. Many proposed solutions to this problem (including early views of the XRP Ledger!) can be reduced to creating "one ledger to rule them all." Ripple believes no single system can meet the needs of everyone in the world: in fact, some desirable features are mutually exclusive. Instead, Ripple believes that an interconnected network of ledgers—an _interledger_—is the true future of financial technology. The `Interledger Protocol` defines standards for making as many systems as possible connect securely and smoothly.
|
||||
|
||||
The most fundamental principle of inter-ledger payments is _conditional transfers_. Multi-hop payments have a risk problem: the more hops in the middle, the more places the payment can fail. Interledger solves this with the financial equivalent of a "[two-phase commit](https://en.wikipedia.org/wiki/Two-phase_commit_protocol)", where the two steps are (1) prepare conditional transfers, then (2) fulfill the conditions to execute the transfers. The Interledger project defined a `crypto-conditions` specification to standardize automated ways to define and verify conditions, and settled on SHA-256 hashes as a "common denominator" of such conditions.
|
||||
|
||||
**Solution:** The Escrow feature makes the XRP Ledger ideal for bridging multi-hop payments using the Interledger Protocol, because it natively supports transfers that deliver XRP based on PREIMAGE-SHA-256 crypto-conditions, and it executes those transfers within seconds of being presented with the matching fulfillment.
|
||||
|
||||
<!--
|
||||
|
||||
## See Also
|
||||
|
||||
For more information about Escrow in the XRP Ledger, see the following:
|
||||
|
||||
- [Escrow Tutorials](use-escrows.html)
|
||||
- [Send a Time-Held Escrow](send-a-time-held-escrow.html)
|
||||
- [Send a conditionally-held escrow](send-a-conditionally-held-escrow.html)
|
||||
- [Look up escrows by sender or receiver](look-up-escrows.html)
|
||||
- [Transaction Reference](transaction-formats.html)
|
||||
- [EscrowCreate transaction][]
|
||||
- [EscrowFinish transaction][]
|
||||
- [EscrowCancel transaction][]
|
||||
- [Ledger Reference](ledger-data-formats.html)
|
||||
- [Escrow object](escrow-object.html)
|
||||
|
||||
For more information on Interledger and how conditional transfers enable secure payments across multiple ledgers, see [Interledger Architecture](https://interledger.org/rfcs/0001-interledger-architecture/).
|
||||
|
||||
For more information on Ripple's 55-billion XRP lock-up, see [Ripple's Insights Blog](https://ripple.com/insights/ripple-to-place-55-billion-xrp-in-escrow-to-ensure-certainty-into-total-xrp-supply/).
|
||||
-->
|
||||
@@ -0,0 +1,131 @@
|
||||
# Partial Payments
|
||||
|
||||
In the default case, the `Amount` field of a `Payment` transaction in the XRP Ledger specifies the exact amount to deliver, after charging for exchange rates and [transfer fees. The "Partial Payment" flag (`tfPartialPayment`) allows a payment to succeed by reducing the amount received instead of increasing the amount sent. Partial payments are useful for returning payments without incurring additional costs to oneself.
|
||||
|
||||
<!-- (`tfPartialPayment`](payment.md#payment-flags)) -->
|
||||
<!-- [returning payments](become-an-xrp-ledger-gateway.md#bouncing-payments) -->
|
||||
|
||||
The amount of XRP used for the [transaction cost](../transaction-cost.md) is always deducted from the sender’s account, regardless of the type of transaction.
|
||||
|
||||
Partial payments can be used to exploit naive integrations with the XRP Ledger to steal money from exchanges and gateways. The [Partial Payments Exploit](#partial-payments-exploit) section of this document describes how this exploit works and how you can avoid it.
|
||||
|
||||
## Semantics
|
||||
|
||||
### Without Partial Payments
|
||||
|
||||
When sending a Payment that does not use the Partial Payment flag, the `Amount` field of the transaction specifies the exact amount to deliver, and the `SendMax` field specifies the maximum amount and currency to send. If a payment cannot deliver the full `Amount` without exceeding the `SendMax` parameter, or the full amount cannot be delivered for any other reason, the transaction fails. If the `SendMax` field is omitted from the transaction instructions, it is considered to be equal to the `Amount`. In this case, the payment can only succeed if the total amount of fees is 0.
|
||||
|
||||
In other words:
|
||||
|
||||
Amount + (fees) = (sent amount) ≤ SendMax
|
||||
|
||||
In this formula, "fees" refers to [transfer fees](../../tokens/transfer-fees.md) and currency exchange rates. The "sent amount" and the delivered amount (`Amount`) may be denominated in different currencies and converted by consuming Offers in the XRP Ledger's decentralized exchange.
|
||||
|
||||
**Note:** The `Fee` field of the transaction refers to the XRP [transaction cost](../transaction-cost.md), which is destroyed to relay the transaction to the network. The exact transaction cost specified is always debited from the sender and is completely separate from the fee calculations for any type of payment.
|
||||
|
||||
### With Partial Payments
|
||||
|
||||
When sending a Payment that has the Partial Payment flag enabled, the `Amount` field of the transaction specifies a maximum amount to deliver. Partial payments can succeed at sending _some_ of the intended value despite limitations including fees, not enough liquidity, not enough space in the receiving account's trust lines, or other reasons.
|
||||
|
||||
The optional `DeliverMin` field specifies a minimum amount to deliver. The `SendMax` field functions the same as with non-partial payments. The partial payment transaction is successful if it delivers any amount equal or greater than the `DeliverMin` field without exceeding the `SendMax` amount. If the `DeliverMin` field is not specified, a partial payment can succeed by delivering any positive amount.
|
||||
|
||||
In other words:
|
||||
|
||||
Amount ≥ (Delivered Amount) = SendMax - (Fees) ≥ DeliverMin > 0
|
||||
|
||||
### Partial Payment Limitations
|
||||
|
||||
Partial Payments have the following limitations:
|
||||
|
||||
- A partial payment cannot provide the XRP to fund an address; this case returns the result code `telNO_DST_PARTIAL`.
|
||||
- Direct XRP-to-XRP payments cannot be partial payments; this case returns the result code `temBAD_SEND_XRP_PARTIAL`.
|
||||
- However, cross-currency payments that involve XRP as one of the currencies _can_ be partial payments.
|
||||
|
||||
<!-- [result code]: transaction-results.html -->
|
||||
|
||||
### The `delivered_amount` Field
|
||||
|
||||
To help understand how much a partial payment actually delivered, the metadata of a successful Payment transaction includes a `delivered_amount` field. This field describes the amount actually delivered, in the same format as the `Amount` field.
|
||||
|
||||
<!-- [same format](basic-data-types.html#specifying-currency-amounts) -->
|
||||
|
||||
For non-partial payments, the `delivered_amount` field of the transaction metadata is equal to the `Amount` field of the transaction. When a payment delivers [tokens](../../tokens/tokens.md), the `delivered_amount` might be slightly different than the `Amount` field due to rounding.
|
||||
|
||||
The delivered amount is **not available** for transactions that meet **both** of the following criteria:
|
||||
|
||||
- Is a partial payment
|
||||
- Is included in a validated ledger before 2014-01-20
|
||||
|
||||
If both conditions are true, then `delivered_amount` contains the string value `unavailable` instead of an actual amount. If this happens, you can only determine the actual delivered amount by reading the `AffectedNodes` in the transaction's metadata. If the transaction delivered tokens and the `issuer` of the `Amount` is the same account as the `Destination` address, the delivered amount may be divided among multiple `AffectedNodes` members representing trust lines to different counterparties.
|
||||
|
||||
You can find the `delivered_amount` field in the following places:
|
||||
|
||||
| API | Method | Field |
|
||||
|-----|--------|-------|
|
||||
| JSON-RPC / WebSocket | `account_tx` method | `result.transactions` array members' `meta.delivered_amount` |
|
||||
| JSON-RPC / WebSocket | `tx` method | `result.meta.delivered_amount` |
|
||||
| JSON-RPC / WebSocket | `transaction_entry` method | `result.metadata.delivered_amount` |
|
||||
| JSON-RPC / WebSocket | `ledger` method (with transactions expanded) | `result.ledger.transactions` array members' `metaData.delivered_amount` New in: rippled 1.2.1 |
|
||||
| WebSocket | Transaction subscriptions](subscribe.md#transaction-streams) | Subscription messages' `meta.delivered_amount` New in: rippled 1.2.1 |
|
||||
| ripple-lib v1.x | `getTransaction` method | `outcome.deliveredAmount` |
|
||||
| ripple-lib v1.x | `getTransactions` method | array members' `outcome.deliveredAmount` |
|
||||
|
||||
WebSocket: http-websocket-apis.html
|
||||
JSON-RPC / WebSocket: http-websocket-apis.html
|
||||
|
||||
|
||||
<!-- [Transaction subscriptions](subscribe.md#transaction-streams) -->
|
||||
|
||||
## Partial Payments Exploit
|
||||
|
||||
If a financial institution's integration with the XRP Ledger assumes that the `Amount` field of a Payment is always the full amount delivered, malicious actors may be able to exploit that assumption to steal money from the institution. This exploit can be used against gateways, exchanges, or merchants as long as those institutions' software does not process partial payments correctly.
|
||||
|
||||
**The correct way to process incoming Payment transactions is to use [the `delivered_amount` metadata field](#the-delivered_amount-field),** not the `Amount` field. This way, an institution is never mistaken about how much it _actually_ received.
|
||||
|
||||
|
||||
### Exploit Scenario Steps
|
||||
|
||||
To exploit a vulnerable financial institution, a malicious actor does something like this:
|
||||
|
||||
1. The malicious actor sends a Payment transaction to the institution. This transaction has a large `Amount` field and has the **`tfPartialPayment`** flag enabled.
|
||||
2. The partial payment succeeds (result code `tesSUCCESS`) but actually delivers a very small amount of the currency specified.
|
||||
3. The vulnerable institution reads the transaction's `Amount` field without looking at the `Flags` field or `delivered_amount` metadata field.
|
||||
4. The vulnerable institution credits the malicious actor in an external system, such as the institution's own ledger, for the full `Amount`, despite only receiving a much smaller `delivered_amount` in the XRP Ledger.
|
||||
5. The malicious actor withdraws as much of the balance as possible to another system before the vulnerable institution notices the discrepancy.
|
||||
- Malicious actors usually prefer to convert the balance to another crypto-currency such as Bitcoin, because blockchain transactions are usually irreversible. With a withdrawal to a fiat currency system, the financial institution may be able to reverse or cancel the transaction several days after it initially executes.
|
||||
- In the case of an exchange, the malicious actor can also withdraw an XRP balance directly back into the XRP Ledger.
|
||||
|
||||
In the case of a merchant, the order of operations is slightly different, but the concept is the same:
|
||||
|
||||
1. The malicious actor requests to buy a large amount of goods or services.
|
||||
2. The vulnerable merchant invoices the malicious actor for the price of those goods and services.
|
||||
3. The malicious actor sends a Payment transaction to the merchant. This transaction has a large `Amount` field and has the **`tfPartialPayment`** flag enabled.
|
||||
4. The partial payment succeeds (result code `tesSUCCESS`) but delivers only a very small amount of the currency specified.
|
||||
5. The vulnerable merchant reads the transaction's `Amount` field without looking at the `Flags` field or `delivered_amount` metadata field.
|
||||
6. The vulnerable merchant treats the invoice as paid and provides the goods or services to the malicious actor, despite only receiving a much smaller `delivered_amount` in the XRP Ledger.
|
||||
7. The malicious actor uses, resells, or absconds with the goods and services before the merchant notices the discrepancy.
|
||||
|
||||
### Further Mitigations
|
||||
|
||||
Using [the `delivered_amount` field](#the-delivered_amount-field) when processing incoming transactions is enough to avoid this exploit. Still, additional proactive business practices can also avoid or mitigate the likelihood of this and similar exploits. For example:
|
||||
|
||||
- Add additional sanity checks to your business logic for processing withdrawals. Never process a withdrawal if the total balance you hold in the XRP Ledger does not match your expected assets and obligations.
|
||||
- Follow "Know Your Customer" guidelines and strictly verify your customers' identities. You may be able to recognize and block malicious users in advance, or pursue legal action against a malicious actor who exploits your system.
|
||||
|
||||
<!--
|
||||
## See Also
|
||||
|
||||
- **Tools:**
|
||||
- [Transaction Sender](tx-sender.html)
|
||||
- **Concepts:**
|
||||
- [Transaction Basics](transaction-basics.html)
|
||||
- **Tutorials:**
|
||||
- [Look Up Transaction Results](look-up-transaction-results.html)
|
||||
- [Monitor Incoming Payments with WebSocket](monitor-incoming-payments-with-websocket.html)
|
||||
- [Use Specialized Payment Types](use-specialized-payment-types.html)
|
||||
- [List XRP as an Exchange](list-xrp-as-an-exchange.html)
|
||||
- **References:**
|
||||
- [Payment transaction][]
|
||||
- [Transaction Metadata](transaction-metadata.html)
|
||||
- [account_tx method][]
|
||||
- [tx method][] -->
|
||||
@@ -0,0 +1,43 @@
|
||||
# Payment Channels
|
||||
|
||||
Payment Channels are an advanced feature for sending "asynchronous" XRP payments that can be divided into very small increments and settled later.
|
||||
|
||||
The XRP for a payment channel is set aside temporarily. The sender creates _Claims_ against the channel, which the recipient verifies without sending an XRP Ledger transaction or waiting for a new ledger version to be approved by [consensus](../../xrpl/consensus.md). (This is an _asynchronous_ process because it happens separate from the usual pattern of getting transactions approved by consensus.) At any time, the recipient can _redeem_ a Claim to receive an amount of XRP authorized by that Claim. Settling a Claim like this uses a standard XRP Ledger transaction, as part of the usual consensus process. This single transaction can encompass any number of transactions guaranteed by smaller Claims.
|
||||
|
||||
Because Claims can be verified individually but settled in bulk later, payment channels make it possible to conduct transactions at a rate only limited by the participants' ability to create and verify the digital signatures of those Claims. This limit is primarily based on the speed of the participants' hardware and the complexity of the signature algorithms. For maximum speed, use Ed25519 signatures, which are faster than the XRP Ledger's default secp256k1 ECDSA signatures. Research has [demonstrated the ability to create over Ed25519 100,000 signatures per second and to verify over 70,000 per second](https://ed25519.cr.yp.to/ed25519-20110926.pdf) on commodity hardware in 2011.
|
||||
|
||||
|
||||
## Why Use Payment Channels?
|
||||
|
||||
The process of using a payment channel always involves two parties, a payer and a payee. The payer is an individual person or institution using the XRP Ledger who is a customer of the payee. The payee is a person or business who receives XRP as payment for goods or services.
|
||||
|
||||
Payment Channels do not intrinsically specify anything about what you can buy and sell with them. However, the types of goods and services that are a good fit for payment channels are:
|
||||
|
||||
- Things that can be transmitted near-instantly, like digital items
|
||||
- Inexpensive things, where the cost of processing a transaction is a non-trivial part of the price
|
||||
- Things normally bought in bulk, where the exact quantity desired is not known in advance
|
||||
|
||||
|
||||
## Payment Channel Lifecycle
|
||||
|
||||
The following diagram summarizes the lifecycle of a payment channel:
|
||||
|
||||
{{ include_svg("../../../../img/paychan-flow.svg", "Payment Channel Flow Diagram") }}
|
||||
|
||||
<!--
|
||||
|
||||
## See Also
|
||||
|
||||
- **Related Concepts:**
|
||||
- [Escrow](escrow.html), a similar feature for higher-value, lower-speed conditional XRP payments.
|
||||
- **Tutorials and Use Cases:**
|
||||
- [Use Payment Channels](use-payment-channels.html), a tutorial stepping through the process of using a payment channel.
|
||||
- [Open a Payment Channel to Enable an Inter-Exchange Network](open-a-payment-channel-to-enable-an-inter-exchange-network.html)
|
||||
- **References:**
|
||||
- [channel_authorize method][]
|
||||
- [channel_verify method][]
|
||||
- [PayChannel object](paychannel.html)
|
||||
- [PaymentChannelClaim transaction][]
|
||||
- [PaymentChannelCreate transaction][]
|
||||
- [PaymentChannelFund transaction][]
|
||||
-->
|
||||
@@ -0,0 +1,26 @@
|
||||
# Payment Types
|
||||
The XRP Ledger supports point-to-point XRP payments alongside other, more specialized payment types.
|
||||
|
||||
- [Direct XRP Payments](direct-xrp-payments.md)
|
||||
|
||||
Direct XRP payments are the simplest way to send value in the XRP Ledger.
|
||||
|
||||
- [Cross-Currency Payments](cross-currency-payments.md)
|
||||
|
||||
Cross-currency payments atomically deliver a different currency than they send by converting through paths and order books.
|
||||
|
||||
- [Checks](checks.md)
|
||||
|
||||
Checks let users create deferred payments that can be canceled or cashed by the intended recipients.
|
||||
|
||||
- [Escrow](escrow.md)
|
||||
|
||||
Escrows set aside XRP and deliver it later when certain conditions are met. Escrows can depend on time limits, cryptographic conditions, or both.
|
||||
|
||||
- [Partial Payments](partial-payments.md)
|
||||
|
||||
Partial payments subtract fees from the amount sent, delivering a flexible amount. Partial payments are useful for returning unwanted payments without incurring additional costs.
|
||||
|
||||
- [Payment Channels](payment-channels.md)
|
||||
|
||||
Payment Channels enable fast, asynchronous XRP payments that can be divided into very small increments and settled later.
|
||||
@@ -0,0 +1,47 @@
|
||||
# Source and Destination Tags
|
||||
|
||||
_Source tags_ and _destination tags_ are a feature of XRP Ledger [payments](../payments/payment-types.md) that can indicate specific purposes for payments from and to multi-purpose addresses. Source and destination tags do not have direct on-ledger functionality; source and destination tags merely provide information about how off-ledger systems should process a payment. In transactions, both source and destination tags are formatted as 32-bit unsigned integers.
|
||||
|
||||
Destination tags indicate the beneficiary or destination for a payment. For example, a payment to an exchange or gateway address can use a destination tag to indicate which customer to credit for the amount of the payment in that business's own systems. A payment to a merchant could indicate what item or cart the payment is buying.
|
||||
|
||||
<!-- [exchange](list-xrp-as-an-exchange.html) or [gateway](become-an-xrp-ledger-gateway.html) -->
|
||||
|
||||
Source tags indicate the originator or source of a payment. Most commonly, a Source Tag is included so that the recipient of the payment knows where to send a return, or "bounced", payment. When returning an incoming payment, you should use the source tag from the incoming payment as the destination tag of the outgoing (return) payment.
|
||||
|
||||
The practice of giving customers the ability to send and receive transactions from your XRP Ledger address using another interface is called providing _hosted accounts_. Hosted accounts typically use source and destination tags for each customer.
|
||||
|
||||
**Tip:** An [X-address](https://xrpaddress.info/) combines a classic address with a tag into a single address that encodes both. If you are showing a deposit address to customers, it may be easier for your customers to use an X-address rather than making them keep track of two pieces of information. (The tag in an X-address acts as a source tag when sending and a destination tag when receiving.)
|
||||
|
||||
## Rationale
|
||||
|
||||
In other distributed ledgers, it is common to use different deposit addresses for each customer. In the XRP Ledger, an address must be a funded, permanent [account](../accounts/accounts.md) to receive payments. Using this approach in the XRP Ledger wastefully consumes resources of all servers in the network, and is costly because the [reserve](../accounts/reserves.md) amount must be set aside indefinitely for each address.
|
||||
|
||||
Source and destination tags provide a more lightweight way to map deposits and payments to individual customers.
|
||||
|
||||
## Use Cases
|
||||
|
||||
A business may want to use source and destination tags for several purposes:
|
||||
|
||||
- Direct mappings to customer accounts.
|
||||
- Matching return payments to the outgoing payments that prompted them.
|
||||
- Mapping payments to quotes that expire.
|
||||
- Providing disposable tags that customers can generate for specific deposits.
|
||||
|
||||
To prevent overlap while protecting privacy, a business can divide the total range of tags available into sections for each purpose, then assign tags in an unpredictable order within the range. For example, use a cryptographic hash function like [SHA-256](https://en.wikipedia.org/wiki/SHA-2), then use the [modulo operator](https://en.wikipedia.org/wiki/Modulo_operation) to map the output to the size of the relevant section. To be safe, check for collisions with old tags before using a new tag.
|
||||
|
||||
Assigning tags in numerical order provides less privacy to customers. Since all XRP Ledger transactions are public, assigning tags in this way can make it possible to guess which tags correspond to various users' addresses or to derive information about users' accounts based on the tags used.
|
||||
|
||||
|
||||
## Requiring Tags
|
||||
|
||||
For an XRP Ledger address that may receive payments intended for several customer accounts, receiving a payment _without_ a destination tag can be a problem: it is not immediately obvious which customer to credit, which can require a manual intervention and a discussion with the sender to figure out who was the intended recipient. To reduce cases like this, you can enable the `RequireDest` setting. That way, if a user forgets to include a destination tag in a payment, the XRP Ledger rejects their payment instead of giving you money you don't know what to do with. The user can then send the payment again, using the tag as they should have.
|
||||
|
||||
<!--
|
||||
|
||||
[enable the `RequireDest` setting](require-destination-tags.html)
|
||||
|
||||
## See Also
|
||||
|
||||
- [Require Destination Tags](require-destination-tags.html)
|
||||
- [XRP Ledger Businesses](xrp-ledger-businesses.html)
|
||||
- [Payment Types](payment-types.html) -->
|
||||
65
content/concepts/understanding-xrpl/transactions/tickets.md
Normal file
65
content/concepts/understanding-xrpl/transactions/tickets.md
Normal file
@@ -0,0 +1,65 @@
|
||||
# Tickets
|
||||
|
||||
_(Added by the TicketBatch amendment.)_
|
||||
|
||||
A Ticket in the XRP Ledger is a way of setting aside a sequence number for a transaction without sending it right away. Tickets allow transactions to be sent outside of the normal sequence order. One use case for this is to allow for [multi-signed transactions](multi-signing.md) where it may take a while to collect the necessary signatures: while collecting signatures for a transaction that uses a Ticket, you can still send other transactions.
|
||||
|
||||
## Background
|
||||
|
||||
[Transactions](transactions.md) have sequence numbers so that any given transaction can execute no more than once. Sequence numbers also make sure any given transaction is unique: if you send the exact same amount of money to the same person multiple times, the Sequence Number is one detail that is guaranteed to be different each time. Finally, Sequence Numbers provide an elegant way to put transactions in a consistent order, even if some of them arrive out of order when sent throughout the network.
|
||||
|
||||
However, there are some situations where sequence numbers are too limiting. For example:
|
||||
|
||||
- Two or more users share access to an account, each with the ability to send transactions independently. If these users try to send transactions around the same time without coordinating first, they may each try to use the same Sequence number for different transactions, and only one can succeed.
|
||||
- You may want to prepare and sign a transaction in advance, then save it in some secure storage so that it can be executed at any future point if certain events occur. However, if you want to continue using your account as normal in the meantime, you don't know what Sequence number the set-aside transaction will need. <!-- STYLE_OVERRIDE: will -->
|
||||
- When [multiple people must sign a transaction](multi-signing.md) to make it valid, it can be difficult to plan more than one transaction at a time. If you number the transactions with separate sequence numbers, you can't send the later-numbered transactions until everyone has signed the previous transactions; but if you use the same sequence number for each pending transactions, only one of them can succeed.
|
||||
|
||||
Tickets provide a solution to all of these problems by setting aside sequence numbers that can be used later, outside of their usual order, but still no more than once each.
|
||||
|
||||
|
||||
## Tickets Are Reserved Sequence Numbers
|
||||
|
||||
A Ticket is a record that a sequence number has been set aside to be used later. An account first sends a `TicketCreate` transaction to set aside one or more sequence numbers as Tickets; this puts a record in the ledger's state data, in the form of a `Ticket object`, for each sequence number reserved.
|
||||
|
||||
Tickets are numbered using the sequence numbers that were set aside to create them. For example, if your account's current sequence number is 101 and you create 3 Tickets, those Tickets have Ticket Sequence numbers 102, 103, and 104. Doing so increases your account's sequence number to 105.
|
||||
|
||||
{{ include_svg("../../../img/ticket-creation.svg", "Diagram: Creating three Tickets") }}
|
||||
|
||||
Later, you can send a transaction using a specific Ticket instead of a sequence number; doing so removes the corresponding Ticket from the ledger's state data and does not change your account's normal sequence number. You can also still send transactions using normal sequence numbers without using Tickets. You can use any of your available Tickets in any order at any time, but each Ticket can only be used once.
|
||||
|
||||
{{ include_svg("../../../img/ticket-usage.svg", "Diagram: Using Ticket 103.") }}
|
||||
|
||||
Continuing the above example, you can send a transaction using sequence number 105 or any of the three Tickets you created. If you send a transaction using Ticket 103, doing so deletes Ticket 103 from the ledger. Your next transaction after that can use sequence number 105, Ticket 102, or Ticket 104.
|
||||
|
||||
**Caution:** Each Ticket counts as a separate item for the [owner reserve](../accounts/reserves.md), so you must set aside 2 XRP for each Ticket. (The XRP becomes available again after you use the Ticket.) This cost can add up quickly if you create a large number of Tickets at once.
|
||||
|
||||
As with sequence numbers, sending a transaction uses up the Ticket _if and only if_ the transaction is confirmed by [consensus](../xrpl/consensus.md). However, transactions that fail to do what they were intended to do can still be confirmed by consensus with [`tec`-class result codes](./transaction-results/tec-codes.md).
|
||||
|
||||
To look up what Tickets an account has available, use the `account_objects` method.
|
||||
|
||||
## Limitations
|
||||
|
||||
Any account can create and use Tickets on any type of transaction. However, some restrictions apply:
|
||||
|
||||
- Each Ticket can only be used once. It is possible to have multiple different candidate transactions that would use the same Ticket Sequence, but only one of those candidates can be validated by consensus.
|
||||
- Each account cannot have more than 250 Tickets in the ledger at a time. You cannot create more than 250 Tickets at a time, either.
|
||||
- You _can_ use a Ticket to create more Tickets. If you do, the Ticket you used does not count towards the total number of Tickets you can have at once.
|
||||
- Each Ticket counts toward the [owner reserve](../accounts/reserves.md), so you must set aside 2 XRP for each Ticket you have not used yet. The XRP becomes available for you to use again after the Ticket is used.
|
||||
- Within an individual ledger, transactions that use Tickets execute after other transactions from the same sender. If an account has multiple transactions using Tickets in the same ledger version, those Tickets execute in order from lowest Ticket Sequence to highest. (For more information, see the documentation on consensus's [canonical order](consensus.html#calculate-and-share-validations).)
|
||||
- To "cancel" a Ticket, use the Ticket to [perform a no-op](about-canceling-a-transaction.md) `AccountSet transaction`. This deletes the Ticket so that you don't have to meet its reserve requirement.
|
||||
|
||||
|
||||
<!--
|
||||
|
||||
## See Also
|
||||
|
||||
|
||||
- **Concepts:**
|
||||
- [Multi-Signing](multi-signing.html)
|
||||
- **Tutorials:**
|
||||
- [Use Tickets](use-tickets.html)
|
||||
- **References:**
|
||||
- [TicketCreate transaction][]
|
||||
- [Transaction Common Fields](transaction-common-fields.html)
|
||||
- [Ticket object](ticket.html)
|
||||
- [account_objects method][] -->
|
||||
@@ -1,14 +1,13 @@
|
||||
---
|
||||
html: transaction-cost.html
|
||||
parent: transaction-basics.html
|
||||
blurb: The transaction cost is a small amount of XRP destroyed to send a transaction, which protects the ledger from spam. Learn how the transaction cost applies.
|
||||
parent: transactions.html
|
||||
blurb: Every transaction costs a small amount of XRP for purely practical reasons.
|
||||
labels:
|
||||
- Fees
|
||||
- Transaction Sending
|
||||
- Ledgers
|
||||
---
|
||||
# Transaction Cost
|
||||
|
||||
To protect the XRP Ledger from being disrupted by spam and denial-of-service attacks, each transaction must destroy a small amount of [XRP](xrp.html). 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.
|
||||
To protect the XRP Ledger from being disrupted by spam and denial-of-service attacks, each transaction must destroy a small amount of [XRP](../../../introduction/what-is-xrp.md). 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.
|
||||
|
||||
Every transaction must [specify how much XRP to destroy](#specifying-the-transaction-cost) to pay the transaction cost.
|
||||
|
||||
@@ -27,10 +26,11 @@ Some transactions have different transaction costs:
|
||||
|-----------------------|--------------------------|
|
||||
| [Reference Transaction](#reference-transaction-cost) (Most transactions) | 10 drops |
|
||||
| [Key Reset Transaction](#key-reset-transaction) | 0 |
|
||||
| [Multi-signed Transaction](multi-signing.html) | 10 drops × (1 + Number of Signatures Provided) |
|
||||
| [EscrowFinish Transaction with Fulfillment](escrowfinish.html) | 10 drops × (33 + (Fulfillment size in bytes ÷ 16)) |
|
||||
| [Multi-signed Transaction](multi-signing.md) | 10 drops × (1 + Number of Signatures Provided) |
|
||||
| EscrowFinish Transaction with Fulfillment | 10 drops × (33 + (Fulfillment size in bytes ÷ 16)) |
|
||||
| [AccountDelete Transaction](accounts.html#deletion-of-accounts) | 2,000,000 drops |
|
||||
|
||||
<!-- [EscrowFinish Transaction with Fulfillment](escrowfinish.html) -->
|
||||
|
||||
## Beneficiaries of the Transaction Cost
|
||||
|
||||
@@ -38,9 +38,9 @@ The transaction cost is not paid to any party: the XRP is irrevocably destroyed.
|
||||
|
||||
## Load Cost and Open Ledger Cost
|
||||
|
||||
There are two thresholds for the transaction 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](#local-load-cost), the server ignores the transaction completely.
|
||||
* 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:
|
||||
@@ -52,7 +52,10 @@ This divides transactions into roughly three categories:
|
||||
|
||||
## 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](get-started-using-http-websocket-apis.html), the server applies and relays the transaction as long as the transaction meets the un-scaled minimum transaction cost.) A transaction is very unlikely to survive [the consensus process](consensus.html) unless its `Fee` value meets the requirements of a majority of servers.
|
||||
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 meets the un-scaled minimum transaction cost.) A transaction is very unlikely to survive [the consensus process](../xrpl/consensus.md) unless its `Fee` value meets the requirements of a majority of servers.
|
||||
|
||||
<!-- [admin connection](get-started-using-http-websocket-apis.html) -->
|
||||
|
||||
|
||||
## Open Ledger Cost
|
||||
|
||||
@@ -60,7 +63,7 @@ The `rippled` server has a second mechanism for enforcing the transaction cost,
|
||||
|
||||
For each new ledger version, the server picks a soft limit on the number of transactions to be included in the open ledger, based on the number of transactions in the previous ledger. The open ledger cost is equal to the minimum un-scaled transaction cost until the number of transactions in the open ledger is equal to the soft limit. After that, the open ledger cost increases exponentially for each transaction included in the open ledger. For the next ledger, the server increases the soft limit if the current ledger contained more transactions than the soft limit, and decreases the soft limit if the consensus process takes more than 5 seconds.
|
||||
|
||||
The open ledger cost requirement is [proportional to the normal cost of the transaction](#fee-levels), not the absolute transaction cost. Transaction types that have a higher-than-normal requirement, such as [multi-signed transactions](multi-signing.html) must pay more to meet the open ledger cost than transactions which have minimum transaction cost requirements.
|
||||
The open ledger cost requirement is [proportional to the normal cost of the transaction](#fee-levels), not the absolute transaction cost. Transaction types that have a higher-than-normal requirement, such as [multi-signed transactions](multi-signing.md) 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).
|
||||
|
||||
@@ -68,11 +71,11 @@ See also: [Fee Escalation explanation in `rippled` repository](https://github.co
|
||||
|
||||
When `rippled` receives a transaction that meets the server's local load cost but not the [open ledger cost](#open-ledger-cost), the server estimates whether the transaction 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 to 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).
|
||||
|
||||
For more information on queued transactions, see [Transaction Queue](transaction-queue.html).
|
||||
For more information on queued transactions, see [Transaction Queue](../server/transaction-queue.md).
|
||||
|
||||
## Reference Transaction Cost
|
||||
|
||||
The "Reference Transaction" is the cheapest (non-free) transaction, in terms of the necessary [transaction cost](transaction-cost.html) before load scaling. Most transactions have the same cost as the reference transaction. Some transactions, such as [multi-signed transactions](multi-signing.html), require a multiple of this cost instead. When the open ledger cost escalates, the requirement is proportional to the basic cost of the transaction.
|
||||
The "Reference Transaction" is the cheapest (non-free) transaction, in terms of the necessary [transaction cost](transaction-cost.md) before load scaling. Most transactions have the same cost as the reference transaction. Some transactions, such as [multi-signed transactions](multi-signing.md), 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
|
||||
|
||||
@@ -81,35 +84,36 @@ _Fee levels_ represent the proportional difference between the minimum cost and
|
||||
| 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](multi-signing.html) with 4 signatures | 50 | 256 | 100 | 512 |
|
||||
| [Key reset transaction](transaction-cost.html#key-reset-transaction) | 0 | (Effectively infinite) | N/A | (Effectively infinite) |
|
||||
| [EscrowFinish transaction](escrowfinish.html) with 32-byte preimage. | 350 | 256 | 700 | 512 |
|
||||
| [Multi-signed transaction](multi-signing.md) with 4 signatures | 50 | 256 | 100 | 512 |
|
||||
| [Key reset transaction](transaction-cost.md#key-reset-transaction) | 0 | (Effectively infinite) | N/A | (Effectively infinite) |
|
||||
| EscrowFinish transaction with 32-byte preimage. | 350 | 256 | 700 | 512 |
|
||||
|
||||
<!-- [EscrowFinish transaction](escrowfinish.html) -->
|
||||
|
||||
## Querying the Transaction Cost
|
||||
|
||||
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).
|
||||
|
||||
You can use the [fee method][] to check the open ledger cost.
|
||||
If the `FeeEscalation` amendment is enabled, you can use the `fee` method to check the open ledger cost.
|
||||
|
||||
### server_info
|
||||
|
||||
The [server_info method][] 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:
|
||||
The `server_info` method 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`**
|
||||
|
||||
|
||||
### server_state
|
||||
|
||||
The [server_state method][] returns a direct representation of `rippled`'s internal load calculations. In this case, the effective load rate is the ratio of the current `load_factor` to the `load_base`. The `validated_ledger.base_fee` parameter reports the minimum transaction cost in [drops of XRP](basic-data-types.html#specifying-currency-amounts). This design enables `rippled` to calculate the transaction cost using only integer math, while still allowing a reasonable amount of fine-tuning for server load. The actual calculation of the transaction cost is as follows:
|
||||
The `server_state` method returns a direct representation of `rippled`'s internal load calculations. In this case, the effective load rate is the ratio of the current `load_factor` to the `load_base`. The `validated_ledger.base_fee` parameter reports the minimum transaction cost in drops of XRP. This design enables `rippled` to calculate the transaction cost using only integer math, while still allowing a reasonable amount of fine-tuning for server load. The actual calculation of the transaction cost is as follows:
|
||||
|
||||
**Current Transaction Cost in Drops = (`base_fee` × `load_factor`) ÷ `load_base`**
|
||||
|
||||
|
||||
<!-- [drops of XRP](basic-data-types.md#specifying-currency-amounts) -->
|
||||
|
||||
## Specifying the Transaction Cost
|
||||
|
||||
Every signed transaction must include the transaction cost in the [`Fee` field](transaction-common-fields.html). Like all fields of a signed transaction, this field cannot be changed without invalidating the signature.
|
||||
Every signed transaction must include the transaction cost in the [`Fee` field](transaction-common-fields.md). Like all fields of a signed transaction, this field cannot be changed without invalidating the signature.
|
||||
|
||||
As a rule, the XRP Ledger executes transactions _exactly_ as they are signed. (To do anything else would be difficult to coordinate across a decentralized consensus network, at the least.) As a consequence of this, every transaction destroys the exact amount of XRP specified by the `Fee` field, even if the specified amount is much more than the current minimum transaction cost for any part of the network. The transaction cost can even destroy XRP that would otherwise be set aside for an account's [reserve requirement](reserves.html).
|
||||
|
||||
@@ -118,47 +122,50 @@ Before signing a transaction, we recommend [looking up the current load-based tr
|
||||
|
||||
### Automatically Specifying the Transaction Cost
|
||||
|
||||
The `Fee` field is one of the things that can be [auto-filled](transaction-common-fields.html#auto-fillable-fields) when creating a transaction. In this case, the auto-filling software provides a suitable `Fee` value based on the current load in the peer-to-peer network. However, there are several drawbacks and limitations to automatically filling in the transaction cost in this manner:
|
||||
The `Fee` field is one of the things that can be [auto-filled](transaction-common-fields.md#auto-fillable-fields) when creating a transaction. In this case, the auto-filling software provides a suitable `Fee` value based on the current load in the peer-to-peer network. However, there are several drawbacks and limitations to automatically filling in the transaction cost in this manner:
|
||||
|
||||
- If the network's transaction cost goes up between auto-filling and submitting the transaction, the transaction may not be confirmed.
|
||||
- To prevent a transaction from getting stuck in a state of being neither definitively confirmed or rejected, be sure to provide a `LastLedgerSequence` parameter so it eventually expires. Alternatively, you can try to [cancel a stuck transaction](about-canceling-a-transaction.html) by reusing the same `Sequence` number. See [reliable transaction submission](reliable-transaction-submission.html) for best practices.
|
||||
- To prevent a transaction from getting stuck in a state of being neither definitively confirmed or rejected, be sure to provide a `LastLedgerSequence` parameter so it eventually expires. Alternatively, you can try to [cancel a stuck transaction](about-canceling-a-transaction.md) by reusing the same `Sequence` number.
|
||||
|
||||
<!-- See [reliable transaction submission](reliable-transaction-submission.html) for best practices. -->
|
||||
|
||||
- You have to be careful that the automatically provided value isn't too high. You don't want to burn a large fee to send a small transaction.
|
||||
- If you are using `rippled`, you can also use the `fee_mult_max` and `fee_div_max` parameters of the [sign method][] 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` method to set a limit to the load scaling you are willing to sign.
|
||||
- Some client libraries (like [xrpl.js](https://js.xrpl.org/) and [xrpl-py](https://xrpl-py.readthedocs.io/)) have configurable maximum `Fee` values, and raise an error instead of signing a transaction whose `Fee` value is higher than the maximum.
|
||||
- You cannot auto-fill from an offline machine nor when [multi-signing](multi-signing.html).
|
||||
|
||||
|
||||
## Transaction Costs and Failed Transactions
|
||||
|
||||
Since the purpose of the transaction cost is to protect the XRP Ledger peer-to-peer 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, to affect the shared global ledger, a transaction must be included in a validated ledger. Thus, `rippled` servers try to include failed transactions in ledgers, with [`tec` status codes](transaction-results.html) ("tec" stands for "Transaction Engine - Claimed fee only").
|
||||
Since the purpose of the transaction cost is to protect the XRP Ledger peer-to-peer 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, to affect the shared global ledger, a transaction must be included in a validated ledger. Thus, `rippled` servers try to include failed transactions in ledgers, with [`tec` status codes](./transaction-results/transaction-results.md) ("tec" stands for "Transaction Engine - Claimed fee only").
|
||||
|
||||
The transaction cost is only debited from the sender's XRP balance when the transaction actually becomes included in a validated ledger. This is true whether the transaction is considered successful or fails with a `tec` code.
|
||||
|
||||
If a transaction's failure is [final](finality-of-results.html), the `rippled` server does not relay it to the network. The transaction does not get included in a validated ledger, so it cannot have any effect on anyone's XRP balance.
|
||||
If a transaction's failure is [final](finality-of-results.md), the `rippled` server does not relay it to the network. The transaction does not get included in a validated ledger, so it cannot have any effect on anyone's XRP balance.
|
||||
|
||||
### Insufficient XRP
|
||||
|
||||
When a `rippled` server initially evaluates a transaction, it rejects the transaction with the error code `terINSUF_FEE_B` if the sending account does not have a high enough XRP balance to pay the XRP transaction cost. Since this is a `ter` (Retry) code, the `rippled` server retries the transaction without relaying it to the network, until the transaction's outcome is [final](finality-of-results.html).
|
||||
When a `rippled` server initially evaluates a transaction, it rejects the transaction with the error code `terINSUF_FEE_B` if the sending account does not have a high enough XRP balance to pay the XRP transaction cost. Since this is a `ter` (Retry) code, the `rippled` server retries the transaction without relaying it to the network, until the transaction's outcome is [final](finality-of-results.md).
|
||||
|
||||
When a transaction has already been distributed to the network, but the account does not have enough XRP to pay the transaction cost, the result code `tecINSUFF_FEE` occurs instead. In this case, the account pays all the XRP it can, ending with 0 XRP. This can occur because `rippled` decides whether to relay the transaction to the network based on its in-progress ledger, but transactions may be dropped or reordered when building the consensus ledger.
|
||||
|
||||
|
||||
## Key Reset Transaction
|
||||
|
||||
As a special case, an account can send a [SetRegularKey](setregularkey.html) transaction with a transaction cost of `0`, as long as the account's [`lsfPasswordSpent` flag](accountroot.html) is disabled. This transaction must be signed by the account's _master key pair_. Sending this transaction enables the `lsfPasswordSpent` flag.
|
||||
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 pair_. 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 more XRP to it.
|
||||
|
||||
The [`lsfPasswordSpent` flag](accountroot.html) starts out disabled. It gets enabled when you send a SetRegularKey transaction signed by the master key pair. It gets disabled again when the account receives a [Payment](payment.html) of XRP.
|
||||
The `lsfPasswordSpent` flag starts out disabled. It gets enabled when you send a SetRegularKey transaction signed by the master key pair. It gets disabled again when the account receives a payment of XRP.
|
||||
|
||||
`rippled` prioritizes key reset transactions above other transactions even though the nominal transaction cost of a key reset transaction is zero.
|
||||
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
|
||||
|
||||
The XRP Ledger has a mechanism for changing the minimum transaction cost to account for long-term changes in the value of XRP. Any changes have to be approved by the consensus process. See [Fee Voting](fee-voting.html) for more information.
|
||||
|
||||
The XRP Ledger has a mechanism for changing the minimum transaction cost to account for long-term changes in the value of XRP. Any changes have to be approved by the consensus process. See [Fee Voting](../xrpl/fee-voting.md) for more information.
|
||||
|
||||
<!--
|
||||
## See Also
|
||||
|
||||
- **Concepts:**
|
||||
@@ -172,8 +179,4 @@ The XRP Ledger has a mechanism for changing the minimum transaction cost to acco
|
||||
- [server_info method][]
|
||||
- [FeeSettings object](feesettings.html)
|
||||
- [SetFee pseudo-transaction][]
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
-->
|
||||
@@ -0,0 +1,17 @@
|
||||
# Transaction History
|
||||
|
||||
In the XRP Ledger, transaction history is tracked by a "thread" of transactions linked by a transaction's identifying hash and the ledger index. The `AccountRoot` ledger object has the identifying hash and ledger of the transaction that most recently modified it; the metadata of that transaction includes the previous state of the `AccountRoot` node, so it is possible to iterate through the history of a single account this way. This transaction history includes any transactions that modify the `AccountRoot` node directly, including:
|
||||
|
||||
- Transactions sent by the account, because they modify the account's `Sequence` number. These transactions also modify the account's XRP balance because of the transaction cost.
|
||||
- Transactions that modified the account's XRP balance, including incoming `Payment` transactions and other types of transactions such as `PaymentChannelClaim` and `EscrowFinish`.
|
||||
|
||||
The _conceptual_ transaction history of an account also includes transactions that modified the account's owned objects and non-XRP balances. These objects are separate ledger objects, each with their own thread of transactions that affected them. If you have an account's full ledger history, you can follow it forward to find the ledger objects created or modified by it. A "complete" transaction history includes the history of objects owned by a transaction, such as:
|
||||
|
||||
- `RippleState` objects (Trust Lines) connected to the account.
|
||||
- `DirectoryNode` objects, especially the owner directory tracking the account's owned objects.
|
||||
- `Offer` objects, representing the account's outstanding currency-exchange orders in the decentralized exchange
|
||||
- `PayChannel` objects, representing asynchronous payment channels to and from the account
|
||||
- `Escrow` objects, representing held payments to or from the account that are locked by time or a crypto-condition.
|
||||
- `SignerList` objects, representing lists of addresses that can authorize transactions for the account by multi-signing.
|
||||
|
||||
For more information on each of these objects, see the Ledger Format Reference.
|
||||
@@ -1,20 +1,12 @@
|
||||
---
|
||||
html: transaction-malleability.html
|
||||
parent: consensus-network.html
|
||||
blurb: Be aware of ways transactions could be changed to have a different hash than expected.
|
||||
labels:
|
||||
- Security
|
||||
- Transaction Sending
|
||||
---
|
||||
# Transaction Malleability
|
||||
|
||||
A transaction is "malleable" if it can be changed in any way after being signed, without the keys to sign it. In the XRP Ledger, the **functionality** of a signed transaction cannot change, but in some circumstances a third party _could_ change the signature and identifying hash of a transaction.
|
||||
A transaction is "malleable" if it can be changed in any way after being signed, without the keys to sign it. In the XRP Ledger, the _functionality_ of a signed transaction cannot change, but in some circumstances a third party _could_ change the signature and identifying hash of a transaction.
|
||||
|
||||
If vulnerable software submits malleable transactions and assumes they can only execute under the original hash, it may lose track of transactions. In the worst case, malicious actors could take advantage of this to steal money from the vulnerable system.
|
||||
|
||||
On the XRP Ledger mainnet, only **multi-signed transactions** can be malleable, if they have more signatures than necessary, or if an authorized signer provides an additional signature beyond what is necessary. Good operational security can protect against these problems. See [Mitigations for Multi-Signature Malleability](#mitigations-for-multi-signature-malleability) for guidelines.
|
||||
On the XRP Ledger mainnet, only _multi-signed_ transactions can be malleable, if they have more signatures than necessary, or if an authorized signer provides an additional signature beyond what is necessary. Good operational security can protect against these problems. See [Mitigations for Multi-Signature Malleability](#mitigations-for-multi-signature-malleability) for guidelines.
|
||||
|
||||
Before 2014, single-signed transactions could be malleable due to properties of the default signing algorithm, ECDSA with the secp256k1 curve. For compatibility with legacy signing tools, it was possible to create and submit malleable single-signed transactions until the [RequireFullyCanonicalSig amendment][] became enabled on 2020-07-03. (Transactions [signed with Ed25519 keys](cryptographic-keys.html#signing-algorithms) were never vulnerable to this problem.)
|
||||
Before 2014, single-signed transactions could be malleable due to properties of the default signing algorithm, ECDSA with the secp256k1 curve. For compatibility with legacy signing tools, it was possible to create and submit malleable single-signed transactions until the RequireFullyCanonicalSig amendment became enabled on 2020-07-03. (Transactions [signed with Ed25519 keys](../accounts/cryptographic-keys.md#signing-algorithms) were never vulnerable to this problem.)
|
||||
|
||||
|
||||
|
||||
@@ -22,8 +14,8 @@ Before 2014, single-signed transactions could be malleable due to properties of
|
||||
|
||||
In the XRP Ledger, a transaction cannot execute unless:
|
||||
|
||||
- All [fields of a transaction](transaction-common-fields.html) are signed, except the signature itself.
|
||||
- The key pair(s) used to sign the transaction are [authorized to send transactions on behalf of that account](transaction-basics.html#authorizing-transactions).
|
||||
- All [fields of a transaction](transaction-common-fields.md) are signed, except the signature itself.
|
||||
- The key pair(s) used to sign the transaction are [authorized to send transactions on behalf of that account](transaction-basics.md#authorizing-transactions).
|
||||
- The signature is _canonical_ and matches the transaction instructions.
|
||||
|
||||
Any change to the signed fields, no matter how small, would invalidate the signature, so no part of the transaction can be malleable except for the signature itself. In most cases, any change to a signature itself also invalidates the signature, but there are some specific exceptions, described below.
|
||||
@@ -44,9 +36,9 @@ An ECDSA signature consists of two integers, called R and S. The secp256k1 _grou
|
||||
|
||||
Thus, to have _fully_ canonical signatures, one must choose which of the two possibilities is preferred and declare the other to be invalid. The creators of the XRP Ledger decided arbitrarily to prefer the _smaller_ of the two possible values, `S` or `N-S`. A transaction is considered _fully canonical_ if it uses the preferred (smaller) value of `S`, and follows all the normal rules for being canonical. To calculate a fully-canonical ECDSA signature, one must compare S and N-S to determine which is smaller, then use that value in the `Signature` field of the transaction.
|
||||
|
||||
With the [RequireFullyCanonicalSig amendment][] (enabled in 2020), all transactions must use _fully canonical_ signatures only.
|
||||
With the RequireFullyCanonicalSig amendment (enabled in 2020), all transactions must use _fully canonical_ signatures only.
|
||||
|
||||
Between 2014 and 2020, the XRP Ledger was compatible with legacy software that did not always generate fully canonical signatures, but used a flag on transactions called [**`tfFullyCanonicalSig`**](transaction-common-fields.html#global-flags) to protect compatible software from transaction malleability. This flag, which compatible signing software enables by default, required that the transaction use a _fully-canonical_ signature to be valid. Now that the [RequireFullyCanonicalSig amendment][] is enabled, the flag is no longer necessary, but there is no harm in enabling it anyway.
|
||||
Between 2014 and 2020, the XRP Ledger was compatible with legacy software that did not always generate fully canonical signatures, but used a flag on transactions called [**`tfFullyCanonicalSig`**](transaction-common-fields.md#global-flags) to protect compatible software from transaction malleability. This flag, which compatible signing software enables by default, required that the transaction use a _fully-canonical_ signature to be valid. Now that the RequireFullyCanonicalSig amendment is enabled, the flag is no longer necessary, but there is no harm in enabling it anyway.
|
||||
|
||||
|
||||
### Malleability with Multi-Signatures
|
||||
@@ -68,8 +60,8 @@ Even if your authorized signers are not intentionally malicious, confusion or po
|
||||
- Do not collect more signatures than necessary.
|
||||
- Either appoint one party to assemble a transaction after collecting the necessary number of signatures, or instruct signers pass the transaction instructions forward to be signed in a set order.
|
||||
- Do not add unnecessary or untrusted signers to your multi-signing lists, even if the `weight` values associated with their keys are insufficient to authorize a transaction.
|
||||
- Be prepared for the possibility that a transaction executes with a different hash and set of signatures than you expected. Carefully monitor your account's sent transactions (for example, using the [account_tx method][]).
|
||||
- Monitor the `Sequence` number of your account (for example, using the [account_info method][]). This number always increases by exactly one when your account sends a transaction successfully, and never any other way. If the number does not match what you expect, you should check your recent transactions to confirm why. (Aside from malleable transactions, there are other ways this could happen, too. Perhaps you configured another application to send transactions for you. Maybe a malicious user gained access to your secret key. Or perhaps your application lost data and forgot about a transaction you sent already.)
|
||||
- Be prepared for the possibility that a transaction executes with a different hash and set of signatures than you expected. Carefully monitor your account's sent transactions (for example, using the `account_tx` method).
|
||||
- Monitor the `Sequence` number of your account (for example, using the `account_info method`). This number always increases by exactly one when your account sends a transaction successfully, and never any other way. If the number does not match what you expect, you should check your recent transactions to confirm why. (Aside from malleable transactions, there are other ways this could happen, too. Perhaps you configured another application to send transactions for you. Maybe a malicious user gained access to your secret key. Or perhaps your application lost data and forgot about a transaction you sent already.)
|
||||
- If you re-create transactions to be multi-signed, _do not_ change the `Sequence` number unless you have manually confirmed that the intended actions have not already executed.
|
||||
- Confirm that the `tfFullyCanonicalSig` flag is enabled before signing.
|
||||
|
||||
@@ -78,9 +70,9 @@ For greater security, these guidelines provide multiple layers of protection.
|
||||
|
||||
## Exploit With Malleable Transactions
|
||||
|
||||
If the software you use to interface with the XRP Ledger sends malleable transactions, a malicious actor may be able to trick your software into losing track of a transaction's final outcome and potentially (in the worst case) sending equivalent payments multiple times.
|
||||
If the software you use to interface with the XRP Ledger sends malleable transactions, a malicious actor might be able to trick your software into losing track of a transaction's final outcome and potentially (in the worst case) sending equivalent payments multiple times.
|
||||
|
||||
If you use single-signatures only, you are not vulnerable to this exploit. If you use multi-signatures, you may be vulnerable if you or your signers provide more signatures than necessary.
|
||||
If you use single-signatures only, you are not vulnerable to this exploit. If you use multi-signatures, you might be vulnerable if you or your signers provide more signatures than necessary.
|
||||
|
||||
### Exploit Scenario Steps
|
||||
|
||||
@@ -122,7 +114,9 @@ The process to exploit a vulnerable system follows a series of steps like the fo
|
||||
|
||||
If the transaction included the `LastLedgerSequence` field, this would occur after the specified ledger index has passed.
|
||||
|
||||
If the transaction omitted the `LastLedgerSequence` field, this could be wrong in another way: if no other transaction from the same sender uses the same `Sequence` number, then the transaction could theoretically succeed later regardless of how much time has passed. (See [Reliable Transaction Submission](reliable-transaction-submission.html) for details.)
|
||||
If the transaction omitted the `LastLedgerSequence` field, this could be wrong in another way: if no other transaction from the same sender uses the same `Sequence` number, then the transaction could theoretically succeed later regardless of how much time has passed.
|
||||
|
||||
<!-- (See [Reliable Transaction Submission](reliable-transaction-submission.html) for details.) -->
|
||||
|
||||
8. The vulnerable system takes action assuming that the transaction has failed.
|
||||
|
||||
@@ -130,7 +124,7 @@ The process to exploit a vulnerable system follows a series of steps like the fo
|
||||
|
||||
Worse, the vulnerable system might construct a new transaction to replace the transaction, picking new `Sequence`, `LastLedgerSequence`, and `Fee` parameters based on the current state of the network, but keeping the rest of the transaction the same as the original. If this new transaction is also malleable, the system could be exploited in the same way an indefinite number of times.
|
||||
|
||||
|
||||
<!--
|
||||
## See Also
|
||||
|
||||
- **Concepts:**
|
||||
@@ -144,8 +138,4 @@ The process to exploit a vulnerable system follows a series of steps like the fo
|
||||
- [Transaction Common Fields - Global Flags](transaction-common-fields.html#global-flags)
|
||||
- [Transaction Results](transaction-results.html)
|
||||
- [Serialization Format](serialization.html)
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
-->
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,20 @@
|
||||
---
|
||||
html: tes-success.html
|
||||
parent: transaction-results.html
|
||||
blurb: tesSUCCESS is the only code that indicates a transaction succeeded.
|
||||
labels:
|
||||
- Transaction Sending
|
||||
---
|
||||
# tes Success
|
||||
|
||||
The code `tesSUCCESS` is the only code that indicates a transaction succeeded. This does not always mean it accomplished what you expected it to do. (For example, an `OfferCancel` can "succeed" even if there is no offer for it to cancel.) The `tesSUCCESS` result uses the numerical value 0.
|
||||
|
||||
| Code | Explanation |
|
||||
|:-----------|:----------------------------------------------------------------|
|
||||
| `tesSUCCESS` | The transaction was applied and forwarded to other servers. If this appears in a validated ledger, then the transaction's success is final. |
|
||||
|
||||
<!--{# common link defs #}
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
-->
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,151 @@
|
||||
---
|
||||
html: transaction-structure.html
|
||||
parent: transactions.html
|
||||
blurb: Transactions allow accounts to modify the XRP Ledger.
|
||||
labels:
|
||||
- Ledgers
|
||||
---
|
||||
# Transaction Structure
|
||||
|
||||
All transactions follow a similar structure. If you understand how to send one type of transaction, other transactions make sense as well.
|
||||
|
||||
The type of a transaction (`TransactionType` field) is the most fundamental information about a transaction. This indicates what type of operation the transaction is supposed to do.
|
||||
|
||||
Each transaction type has a set of common fields, coupled with additional fields relevant to the type of action it causes.
|
||||
|
||||
## Transaction Common Fields
|
||||
|
||||
Every transaction has the same set of common fields, plus additional fields based on the transaction type. Field names are case-sensitive. The common fields for all transactions are:
|
||||
|
||||
| Field | JSON Type | [Internal Type][] | Description |
|
||||
|:---------------------|:-----------------|:------------------|:-----------------|
|
||||
| `Account` | String | AccountID | _(Required)_ The unique address of the [account](../accounts/accounts.md) that initiated the transaction. |
|
||||
| `TransactionType` | String | UInt16 | _(Required)_ The type of transaction. Valid types include: `Payment`, `OfferCreate`, `OfferCancel`, `TrustSet`, `AccountSet`, `AccountDelete`, `SetRegularKey`, `SignerListSet`, `EscrowCreate`, `EscrowFinish`, `EscrowCancel`, `PaymentChannelCreate`, `PaymentChannelFund`, `PaymentChannelClaim`, and `DepositPreauth`. |
|
||||
| `Fee` | String | Amount | _(Required; [auto-fillable][])_ Integer amount of XRP, in drops, to be destroyed as a cost for distributing this transaction to the network. Some transaction types have different minimum requirements.<!-- See [Transaction Cost][] for details. -->|
|
||||
| `Sequence` | Number | UInt32 | _(Required; [auto-fillable][])_ The [sequence number](../../../../references/protocol-reference/data-types/basic-data-types.html#account-sequence) of the account sending the transaction. A transaction is only valid if the `Sequence` number is exactly 1 greater than the previous transaction from the same account. The special case `0` means the transaction is using a [Ticket](tickets.html) instead _(Added by the TicketBatch amendment.)_. |
|
||||
| [`AccountTxnID`](#accounttxnid) | String | Hash256 | _(Optional)_ Hash value identifying another transaction. If provided, this transaction is only valid if the sending account's previously-sent transaction matches the provided hash. |
|
||||
| [`Flags`](#flags-field) | Number | UInt32 | _(Optional)_ Set of bit-flags for this transaction. |
|
||||
| `LastLedgerSequence` | Number | UInt32 | _(Optional; strongly recommended)_ Highest ledger index this transaction can appear in. Specifying this field places a strict upper limit on how long the transaction can wait to be validated or rejected. <!-- See [Reliable Transaction Submission](reliable-transaction-submission.html) for more details. -->|
|
||||
| [`Memos`](#memos-field) | Array of Objects | Array | _(Optional)_ Additional arbitrary information used to identify this transaction. |
|
||||
| [`Signers`](#signers-field) | Array | Array | _(Optional)_ Array of objects that represent a [multi-signature](multi-signing.html) which authorizes this transaction. |
|
||||
| `SourceTag` | Number | UInt32 | _(Optional)_ Arbitrary integer used to identify the reason for this payment, or a sender on whose behalf this transaction is made. Conventionally, a refund should specify the initial payment's `SourceTag` as the refund payment's `DestinationTag`. |
|
||||
| `SigningPubKey` | String | Blob | _(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. |
|
||||
| `TicketSequence` | Number | UInt32 | _(Optional)_ The sequence number of the [ticket](tickets.html) to use in place of a `Sequence` number. If this is provided, `Sequence` must be `0`. Cannot be used with `AccountTxnID`. |
|
||||
| `TxnSignature` | String | Blob | _(Automatically added when signing)_ The signature that verifies this transaction as originating from the account it says it is from. |
|
||||
|
||||
[auto-fillable]: #auto-fillable-fields
|
||||
|
||||
Removed in: rippled 0.28.0: The `PreviousTxnID` field of transactions was replaced by the [`AccountTxnID`](#accounttxnid) field. This String / Hash256 field is present in some historical transactions. This is unrelated to the field also named `PreviousTxnID` in some [ledger objects](../../../../references/protocol-reference/ledger-data/ledger-data-formats.md).
|
||||
|
||||
|
||||
## AccountTxnID
|
||||
|
||||
The `AccountTxnID` field lets you chain your transactions together, so that a current transaction is not valid unless the previous transaction sent from the same account has a specific transaction hash. <!-- ][identifying hash]. -->
|
||||
|
||||
Unlike the `PreviousTxnID` field, which tracks the last transaction to _modify_ an account (regardless of sender), the `AccountTxnID` tracks the last transaction _sent by_ an account. To use `AccountTxnID`, you must first enable the [`asfAccountTxnID`](../../../../references/protocol-reference/transactions/transaction-types/accountset.md#accountset-flags) flag, so that the ledger keeps track of the ID for the account's previous transaction. (`PreviousTxnID`, by comparison, is always tracked.)
|
||||
|
||||
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 have 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.
|
||||
|
||||
The `AccountTxnID` field cannot be used on transactions that use [Tickets](tickets.html). Transactions that use `AccountTxnID` cannot be placed in the [transaction queue](../server/transaction-queue.html).
|
||||
|
||||
|
||||
|
||||
## Auto-fillable Fields
|
||||
|
||||
Some fields can be automatically filled in before a transaction is signed, either by a `rippled` server or by a [client library](../../../references/client-libraries.md). Auto-filling values requires an active connection to the XRP Ledger to get the latest state, so it cannot be done offline. The details can vary by library, but auto-filling always provides suitable values for at least the following fields:
|
||||
|
||||
* `Fee` - Automatically fill in the `Transaction Cost` based on the network.
|
||||
|
||||
**Note:** When using `rippled`'s `sign` command, you can limit the maximum possible auto-filled value, using the `fee_mult_max` and `fee_mult_div` parameters.)
|
||||
|
||||
* `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](../../../../references/protocol-reference/transactions/transaction-types/payment.md#paths) of the `Payment` transaction type can also be automatically filled in.
|
||||
|
||||
|
||||
## Flags Field
|
||||
|
||||
The `Flags` field can contain various options that affect how a transaction should behave. The options are represented as binary values that can be combined with bitwise-or operations to set multiple flags at once.
|
||||
|
||||
To check whether a transaction has a given flag enabled, use the bitwise-and operator on the flag's value and the `Flags` field. A result of zero indicates the flag is disabled, and a result equal to the flag value indicates the flag is enabled. (Any other result indicates you performed the wrong operation.)
|
||||
|
||||
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.
|
||||
|
||||
Bits that are not defined as flags MUST be 0. (The fix1543 amendment enforces this rule on some transaction types. Most transaction types enforce this rule by default.)
|
||||
|
||||
### Global Flags
|
||||
|
||||
The only flag that applies globally to all transactions is as follows:
|
||||
|
||||
| Flag Name | Hex Value | Decimal Value | Description |
|
||||
|:----------------------|:-----------|:--------------|:--------------------------|
|
||||
| `tfFullyCanonicalSig` | `0x80000000` | 2147483648 | **DEPRECATED** No effect. (If the RequireFullyCanonicalSig amendment is not enabled, this flag enforces a [fully-canonical signature](transaction-malleability.md#alternate-secp256k1-signatures).) |
|
||||
|
||||
When using the `sign` method (or `submit` method in "sign-and-submit" mode), `rippled` adds a `Flags` field with `tfFullyCanonicalSig` enabled unless the `Flags` field is already present. The `tfFullyCanonicalSig` flag is not automatically enabled if `Flags` is explicitly specified. The flag is not automatically enabled when using the `sign_for` method to add a signature to a multi-signed transaction.
|
||||
|
||||
**Note:** The `tfFullyCanonicalSig` flag was used from 2014 until 2020 to protect against [transaction malleability](transaction-malleability.md) while maintaining compatibility with legacy signing software. The RequireFullyCanonicalSig amendment ended compatibility with such legacy software and made the protections the default for all transactions. If you are using a [parallel network](../networks/parallel-networks.md) that does not have RequireFullyCanonicalSig enabled, you should always enable the `tfFullyCanonicalSig` flag to protect against transaction malleability.
|
||||
|
||||
### Flag Ranges
|
||||
|
||||
A transaction's `Flags` field can contain flags that apply at different levels or contexts. Flags for each context are limited to the following ranges:
|
||||
|
||||
| Range Name | Bit Mask | Description |
|
||||
|:-----------------|:-------------|:-------------------------------------------|
|
||||
| Universal Flags | `0xff000000` | Flags that apply equally to all transaction types. |
|
||||
| Type-based Flags | `0x00ff0000` | Flags with different meanings depending on the [transaction type](transaction-types.md) that uses them. |
|
||||
| Reserved Flags | `0x0000ffff` | Flags that are not currently defined. A transaction is only valid if these flags are disabled. |
|
||||
|
||||
**Note:** The `AccountSet` transaction type has [its own non-bitwise flags](../../../../references/protocol-reference/transactions/transaction-types/accountset.html#accountset-flags), which serve a similar purpose to type-based flags. [Ledger objects](../../../../references/protocol-reference/ledger-data/ledger-object-types/ledger-object-types.md) also have a `Flags` field with different bitwise flag definitions.
|
||||
|
||||
|
||||
## Memos Field
|
||||
|
||||
The `Memos` field includes arbitrary messaging data with 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][] | Description |
|
||||
|:-------------|:-------|:------------------|:---------------------------------|
|
||||
| `MemoData` | String | Blob | Arbitrary hex value, conventionally containing the content of the memo. |
|
||||
| `MemoFormat` | String | Blob | Hex value representing characters allowed in URLs. Conventionally containing information on how the memo is encoded, for example as a [MIME type](http://www.iana.org/assignments/media-types/media-types.xhtml). |
|
||||
| `MemoType` | String | Blob | Hex value representing characters allowed in URLs. Conventionally, a unique relation (according to [RFC 5988](http://tools.ietf.org/html/rfc5988#section-4)) that defines the format of this memo. |
|
||||
|
||||
The `MemoType` and `MemoFormat` fields should only consist of the following characters: `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~:/?#[]@!$&'()*+,;=%`
|
||||
|
||||
The `Memos` field is limited to no more than 1 KB in size (when serialized in binary format).
|
||||
|
||||
Example of a transaction with a Memos field:
|
||||
|
||||
```json
|
||||
{
|
||||
"TransactionType": "Payment",
|
||||
"Account": "rMmTCjGFRWPz8S2zAUUoNVSQHxtRQD4eCx",
|
||||
"Destination": "r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV",
|
||||
"Memos": [
|
||||
{
|
||||
"Memo": {
|
||||
"MemoType": "687474703a2f2f6578616d706c652e636f6d2f6d656d6f2f67656e65726963",
|
||||
"MemoData": "72656e74"
|
||||
}
|
||||
}
|
||||
],
|
||||
"Amount": "1"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Signers Field
|
||||
|
||||
The `Signers` field contains a [multi-signature](multi-signing.html), 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 | Description |
|
||||
|:----------------|:-------|:------------------|:--------------------------------|
|
||||
| `Account` | String | AccountID | The address associated with this signature, as it appears in the signer list. |
|
||||
| `TxnSignature` | String | Blob | A signature for this transaction, verifiable using the `SigningPubKey`. |
|
||||
| `SigningPubKey` | String | Blob | 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`](../../../../references/protocol-reference/ledger-data/ledger-object-types/accountroot.md#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](transaction-cost.md) 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.
|
||||
|
||||
|
||||
229
content/concepts/understanding-xrpl/transactions/transactions.md
Normal file
229
content/concepts/understanding-xrpl/transactions/transactions.md
Normal file
@@ -0,0 +1,229 @@
|
||||
---
|
||||
html: transactions.html
|
||||
parent: understanding-xrpl.html
|
||||
blurb: Transactions allow accounts to modify the XRP Ledger.
|
||||
labels:
|
||||
- Ledgers
|
||||
---
|
||||
# Transactions
|
||||
|
||||
_Transactions_ allow accounts to modify the XRP Ledger.
|
||||
|
||||
Transactions can do more than transfer currency. In addition to supporting various payment types, transactions in the XRP Ledger can rotate cryptographic keys, manage other settings, and trade in the XRP Ledger's decentralized exchange.
|
||||
|
||||
## Transaction Structure
|
||||
|
||||
### Example Unsigned Transaction
|
||||
|
||||
Here is an example of an unsigned `Payment` transaction in JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"TransactionType" : "Payment",
|
||||
"Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
||||
"Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
|
||||
"Amount" : {
|
||||
"currency" : "USD",
|
||||
"value" : "1",
|
||||
"issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
|
||||
},
|
||||
"Fee": "12",
|
||||
"Flags": 2147483648,
|
||||
"Sequence": 2,
|
||||
}
|
||||
```
|
||||
|
||||
| Field Name | Description |
|
||||
|-----------------|-------------|
|
||||
| TransactionType | Send a Payment. |
|
||||
| Account | The account sending the funds. |
|
||||
| Destination | The account receiving the funds. |
|
||||
| Amount | The amount and type of currency. |
|
||||
| currency | Currency type to transfer. |
|
||||
| value | Quantity of currency to transfer. |
|
||||
| issuer | Account that originally issued the currency. |
|
||||
| Fee | Transaction fee, in drops (millionths of one XRP). |
|
||||
| Flags | Additional standard settings for the transaction. |
|
||||
| Sequence | Unique sequence number for the transaction. |
|
||||
|
||||
### Signing and Submitting Transactions
|
||||
|
||||
Sending a transaction to the XRP Ledger involves several steps:
|
||||
|
||||
1. Create an [unsigned transaction in JSON format](#example-unsigned-transaction).
|
||||
2. Use one or more signatures to [authorize the transaction](#authorizing-transactions).
|
||||
3. Submit a transaction to an XRP Ledger server (usually a [`rippled` instance](server-modes.html)). 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](consensus.html) determines which provisional transactions get included in the next validated ledger.
|
||||
5. The servers apply those transactions to the previous ledger in a canonical order and share their results.
|
||||
6. If enough trusted validators created the exact same ledger, that ledger is declared _validated_ and the <!-- * --> results of the transactions in that ledger are immutable.
|
||||
|
||||
<!-- * [results of the transactions](transaction-results.html) -->
|
||||
|
||||
### Example Executed Transaction Response with Metadata
|
||||
|
||||
After a transaction has been executed, the XRP Ledger adds <!-- * --> metadata to show the transaction's final outcome and all the changes that the transaction made to the shared state of the XRP Ledger.
|
||||
|
||||
<!-- * [metadata](transaction-metadata.html) -->
|
||||
|
||||
You can check a transaction's status using the API, for example using the `tx` command.
|
||||
|
||||
The results of a transaction, including all its metadata, are not final until the transaction appears in a **validated** ledger.
|
||||
|
||||
Example response from the `tx` command:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 6,
|
||||
"status": "success",
|
||||
"type": "response",
|
||||
"result": {
|
||||
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
||||
"Amount": {
|
||||
"currency": "USD",
|
||||
"issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
||||
"value": "1"
|
||||
},
|
||||
"Destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
|
||||
"Fee": "10",
|
||||
"Flags": 2147483648,
|
||||
"Sequence": 2,
|
||||
"SigningPubKey": "03AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB",
|
||||
"TransactionType": "Payment",
|
||||
"TxnSignature": "3045022100D64A32A506B86E880480CCB846EFA3F9665C9B11FDCA35D7124F53C486CC1D0402206EC8663308D91C928D1FDA498C3A2F8DD105211B9D90F4ECFD75172BAE733340",
|
||||
"date": 455224610,
|
||||
"hash": "33EA42FC7A06F062A7B843AF4DC7C0AB00D6644DFDF4C5D354A87C035813D321",
|
||||
"inLedger": 7013674,
|
||||
"ledger_index": 7013674,
|
||||
"meta": {
|
||||
"AffectedNodes": [
|
||||
{
|
||||
"ModifiedNode": {
|
||||
"FinalFields": {
|
||||
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
||||
"Balance": "99999980",
|
||||
"Flags": 0,
|
||||
"OwnerCount": 0,
|
||||
"Sequence": 3
|
||||
},
|
||||
"LedgerEntryType": "AccountRoot",
|
||||
"LedgerIndex": "13F1A95D7AAB7108D5CE7EEAF504B2894B8C674E6D68499076441C4837282BF8",
|
||||
"PreviousFields": {
|
||||
"Balance": "99999990",
|
||||
"Sequence": 2
|
||||
},
|
||||
"PreviousTxnID": "7BF105CFE4EFE78ADB63FE4E03A851440551FE189FD4B51CAAD9279C9F534F0E",
|
||||
"PreviousTxnLgrSeq": 6979192
|
||||
}
|
||||
},
|
||||
{
|
||||
"ModifiedNode": {
|
||||
"FinalFields": {
|
||||
"Balance": {
|
||||
"currency": "USD",
|
||||
"issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
|
||||
"value": "2"
|
||||
},
|
||||
"Flags": 65536,
|
||||
"HighLimit": {
|
||||
"currency": "USD",
|
||||
"issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
|
||||
"value": "0"
|
||||
},
|
||||
"HighNode": "0000000000000000",
|
||||
"LowLimit": {
|
||||
"currency": "USD",
|
||||
"issuer": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
|
||||
"value": "100"
|
||||
},
|
||||
"LowNode": "0000000000000000"
|
||||
},
|
||||
"LedgerEntryType": "RippleState",
|
||||
"LedgerIndex": "96D2F43BA7AE7193EC59E5E7DDB26A9D786AB1F7C580E030E7D2FF5233DA01E9",
|
||||
"PreviousFields": {
|
||||
"Balance": {
|
||||
"currency": "USD",
|
||||
"issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
|
||||
"value": "1"
|
||||
}
|
||||
},
|
||||
"PreviousTxnID": "7BF105CFE4EFE78ADB63FE4E03A851440551FE189FD4B51CAAD9279C9F534F0E",
|
||||
"PreviousTxnLgrSeq": 6979192
|
||||
}
|
||||
}
|
||||
],
|
||||
"TransactionIndex": 0,
|
||||
"TransactionResult": "tesSUCCESS"
|
||||
},
|
||||
"validated": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Identifying Transactions
|
||||
|
||||
Every signed transaction has a unique `"hash"` that identifies it. The server provides the hash in the response when you submit the transaction; you can also look up a transaction in an account's transaction history with the `account_tx` command.
|
||||
|
||||
The transaction hash can be used as a "proof of payment," since anyone can <!-- * --> look up the transaction by its hash to verify its final status.
|
||||
|
||||
<!-- * [look up the transaction by its hash](look-up-transaction-results.html) -->
|
||||
|
||||
<!--
|
||||
{% include '_snippets/setfee_uniqueness_note.md' %}
|
||||
<!--_ -->
|
||||
|
||||
|
||||
## Claimed Cost Justification
|
||||
|
||||
Although it might seem unfair to charge a [transaction cost](transaction-cost.md) for a failed transaction, the `tec` class of errors exists for good reasons:
|
||||
|
||||
* Transactions submitted after the failed one do not have to have their Sequence values renumbered. Incorporating the failed transaction into a ledger uses up the transaction's sequence number, preserving the expected sequence.
|
||||
* Distributing the transaction throughout the network increases network load. Enforcing a cost makes it harder for attackers to abuse the network with failed transactions.
|
||||
* The transaction cost is generally very small in real-world value, so it should not harm users unless they are sending large quantities of transactions.
|
||||
|
||||
## Authorizing Transactions
|
||||
|
||||
In the decentralized XRP Ledger, a digital signature proves that a transaction is authorized to do 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.
|
||||
|
||||
Transactions are authorized by any of the following signature types:
|
||||
|
||||
* A single signature from the master private key that is mathematically associated with the sending address. You can disable or enable the master key pair using an `AccountSet` transaction.
|
||||
* A single signature that matches the regular private key associated with the address. You can add, remove, or replace a regular key pair using a `SetRegularKey` transaction.
|
||||
* A [multi-signature](multi-signing.md) that matches a list of signers owned by the address. You can add, remove, or replace a list of signers using a `SignerListSet` transaction.
|
||||
|
||||
Any signature type can authorize any type of transaction, with the following exceptions:
|
||||
|
||||
* Only the master private key can <!-- * -->disable the master public key.
|
||||
* Only the master private key can permanently give up the ability to freeze.
|
||||
* You can never remove the last method of signing transactions from an address.
|
||||
|
||||
<!-- [disable the master public key](accountset.html) -->
|
||||
|
||||
For more information about master and regular key pairs, see [Cryptographic Keys](../accounts/cryptographic-keys.md).
|
||||
|
||||
<!--{# Add this reference after signatures concept doc is published. For more information about signatures, see [Understanding Signatures](concept-signatures.html). #}-->
|
||||
|
||||
<!--
|
||||
|
||||
## See Also
|
||||
|
||||
- **Concepts:**
|
||||
- [Payment Types](payment-types.html)
|
||||
- [Consensus Network](consensus-network.html)
|
||||
- **Tutorials:**
|
||||
- [Set Up Secure Signing](set-up-secure-signing.html)
|
||||
- [Send XRP](send-xrp.html)
|
||||
- [Look Up Transaction Results](look-up-transaction-results.html)
|
||||
- [Monitor Incoming Payments with WebSocket](monitor-incoming-payments-with-websocket.html)
|
||||
- [Cancel or Skip a Transaction](cancel-or-skip-a-transaction.html)
|
||||
- [Reliable Transaction Submission](reliable-transaction-submission.html)
|
||||
- **References:**
|
||||
- [Transaction Common Fields](transaction-common-fields.html)
|
||||
- [Transaction Types](transaction-types.html)
|
||||
- [Transaction Metadata](transaction-metadata.html)
|
||||
- [account_tx method][]
|
||||
- [tx method][]
|
||||
- [submit method][]
|
||||
- [submit_multisigned method][]
|
||||
|
||||
-->
|
||||
|
||||
@@ -0,0 +1,80 @@
|
||||
# Trust Lines and Issuing
|
||||
|
||||
Trust lines are structures in the XRP Ledger for holding [tokens](../tokens/tokens.md). Trust lines enforce the XRP Ledger's rule that you cannot cause someone else to hold a token they don't want. This precaution is necessary to enable the XRP Ledger's use case for [community credit](../tokens/tokens.md#community-credit) among other benefits.
|
||||
|
||||
Each "trust line" is a _bidirectional_ relationship consisting of:
|
||||
|
||||
- The identifiers for the **two [accounts](../accounts/accounts.md)** that the trust line connects.
|
||||
- A single, shared **balance**, which is positive from the perspective of one account and negative from the other perspective.
|
||||
- The account with a negative balance is generally considered the "issuer" of the tokens. However, in the APIs<!-- [APIs](http-websocket-apis.md)-->, the name `issuer` can refer to either side.
|
||||
- Various **settings** and metadata. _Each_ of the two accounts can control its own settings on the trust line.
|
||||
- Most importantly, each side sets a **limit** on the trust line, which is 0 by default. Each account's balance (from its perspective on the trust line) can't go above that account's limit, except [through that account's own actions](#going-below-the-limit).
|
||||
|
||||
Each trust line is specific to a given currency code. Two accounts can have any number of trust lines between them for different currency codes, but only one shared trust line for any particular currency code.
|
||||
|
||||
|
||||
## Creation
|
||||
|
||||
Any account can unilaterally "trust" another account to issue a token by sending a `TrustSet` transaction with a nonzero limit and their own settings. This creates a line with a zero balance, and sets the other side's settings to the default.
|
||||
|
||||
Trust lines can be implicitly created by some transactions, such as when you buy a token in the decentralized exchange.<!-- ](decentralized-exchange.html). --> In this case, the trust line uses entirely default settings.
|
||||
|
||||
|
||||
## Going Below the Limit
|
||||
|
||||
There are three cases where you can hold a balance that is _greater_ than your limit on that trust line:
|
||||
|
||||
1. When you acquire more of that token through trading. <!--](decentralized-exchange.html).-->
|
||||
2. When you decrease the limit on a trust line that has a positive balance.
|
||||
3. When you acquire more of that token by [cashing a Check](payments/checks.md). (_Requires the CheckCashMakesTrustLine amendment :not_enabled:_)
|
||||
|
||||
|
||||
## Trust Line Settings
|
||||
|
||||
In addition to the shared balance, each account has its own settings on the trust line, which consist of the following:
|
||||
|
||||
- The **Limit**, a number from 0 to the maximum token amount.<!--](currency-formats.html).--> Payments and other accounts' actions cannot cause the trust line's balance (from this account's perspective) to go over the limit. The default is `0`.
|
||||
- **Authorized**: A true/false value used with Authorized Trust Lines<!--](authorized-trust-lines.html)--> to allow the other side to hold tokens this account issues. The default is `false`. Once set to `true`, this cannot be changed back.
|
||||
- **No Ripple**: A true/false value to control whether tokens can [ripple](../tokens/rippling.md) through this trust line. The default depends on the account's "Default Ripple" setting; for new accounts, "Default Ripple" is off which means that `true` is the default for No Ripple. Usually, issuers should allow rippling and non-issuers should disable rippling unless they are using trust lines for community credit.
|
||||
- **Freeze**: A true/false value indicating whether an [individual freeze](../tokens/freezing-tokens.md#individual-freeze) is in effect on this trust line. The default is `false`.
|
||||
- **Quality In** and **Quality Out** settings, which allow the account to value tokens issued by the other account on this trust line at less (or more) than face value. For example, if a stablecoin issuer charges a 3% fee for withdrawing tokens for the equivalent off-ledger assets, you could use these settings to value those tokens at 97% of face value. The default, `0`, represents face value.
|
||||
|
||||
|
||||
## Reserves and Deletion
|
||||
|
||||
Since a trust line occupies space in the ledger, [a trust line increases the XRP your account must hold in reserve](../accounts/reserves.md). Either or both accounts in the trust line may be charged the reserve for the trust line, depending on the status of the trust line: if any of your settings are not the default, or if you hold a positive balance, it counts as one item toward your owner reserve.
|
||||
|
||||
Generally, this means that the account that created the trust line is responsible for the reserve and the issuer is not.
|
||||
|
||||
Trust lines are automatically deleted if both sides' settings are in the default state and the balance is 0. This means that, to delete a trust line, you need to:
|
||||
|
||||
1. Send a `TrustSet` transaction to set your settings to the defaults.
|
||||
2. Offload any positive balance you have on the trust line. You could do this by sending a [payment](payments/cross-currency-payments.md), or by selling the currency in the decentralized exchange. <!--](decentralized-exchange.html). -->
|
||||
|
||||
If your balance is negative (you are the issuer) or the other side's settings are not in the default state, you cannot cause the trust line to be totally deleted, but you can make it so that it does not count towards your owner reserve by following the same steps.
|
||||
|
||||
Since the **Authorized** setting cannot be turned off after it has been turned on, it does not count toward the trust line's default state.
|
||||
|
||||
### Free Trust Lines
|
||||
[[Source]](https://github.com/ripple/rippled/blob/72377e7bf25c4eaee5174186d2db3c6b4210946f/src/ripple/app/tx/impl/SetTrust.cpp#L148-L168)
|
||||
|
||||
Since trust lines are a powerful feature of the XRP Ledger, there is a special feature to make an account's first two trust lines "free".
|
||||
|
||||
When an account creates a new trust line, if the account owns at most 2 items in the ledger including the new line, the account's owner reserve is treated as zero instead of the normal amount. This allows the transaction to succeed even if the account does not hold enough XRP to meet the increased reserve requirement for owning objects in the ledger.
|
||||
|
||||
When an account owns 3 or more objects in the ledger, the full owner reserve applies.
|
||||
|
||||
<!--
|
||||
## See Also
|
||||
|
||||
- **Concepts:**
|
||||
- [Decentralized Exchange](decentralized-exchange.html)
|
||||
- [Rippling](rippling.html)
|
||||
- **Tutorials:**
|
||||
- [Become an XRP Ledger Gateway](become-an-xrp-ledger-gateway.html)
|
||||
- **References:**
|
||||
- [account_lines method][] - Look up trust lines attached to a given account
|
||||
- [gateway_balances method][] - Look up an issuer's total balance issued
|
||||
- [RippleState object](ripplestate.html) - The data format for trust lines in the ledger's state data.
|
||||
- [TrustSet transaction][] - The transaction to create or modify trust lines.
|
||||
-->
|
||||
19
content/concepts/understanding-xrpl/understanding-xrpl.md
Normal file
19
content/concepts/understanding-xrpl/understanding-xrpl.md
Normal file
@@ -0,0 +1,19 @@
|
||||
# Understanding the XRP Ledger
|
||||
|
||||
The XRP Ledger leverages block chain technology to provide a decentralized system for facilitating and recording transactions for items of value, known as tokens. Individuals and businesses conduct business on the XRP ledger using secure accounts.
|
||||
|
||||
## [XRP Ledger Ecosystem](xrpl-ecosystem.html)
|
||||
|
||||
Learn more about the inner workings of the XRP Ledger ecosystem.
|
||||
|
||||
## [Transactions](transactions.html)
|
||||
|
||||
Learn about the different types of transaction.
|
||||
|
||||
## [Tokens](tokens.html)
|
||||
|
||||
Learn about tokens that you can exchange on the XRP Ledger, including fungible and non-fungible tokens.
|
||||
|
||||
## [Accounts](accounts.html)
|
||||
|
||||
Learn details of the structure of accounts and how they can be configured for specific business purposes.
|
||||
@@ -1,54 +1,24 @@
|
||||
---
|
||||
html: consensus-principles-and-rules.html
|
||||
parent: consensus-network.html
|
||||
parent: consensus.html
|
||||
blurb: The rules and principles of the consensus algorithm that allow users to transfer funds (including fiat currencies, digital currencies and other forms of value) across national boundaries as seamlessly as sending an email.
|
||||
labels:
|
||||
- Blockchain
|
||||
---
|
||||
# Consensus Principles and Rules
|
||||
|
||||
<!-- Not sure if this is a standalone topic or if the contents needs to be incorporated throughout the consensus section. -->
|
||||
|
||||
The XRP Ledger is a universal payment system enabling users to transfer funds across national boundaries as seamlessly as sending an email. Like other peer-to-peer payment networks such as Bitcoin, the XRP Ledger enables peer-to-peer transaction settlement across a decentralized network of computers. Unlike other digital currency protocols, the XRP Ledger allows users to denominate their transactions with any currency they prefer, including fiat currencies, digital currencies and other forms of value, in addition to XRP (the native asset of the XRP Ledger).
|
||||
|
||||
The XRP Ledger's technology enables near real-time settlement (three to six seconds) and contains a decentralized exchange, where payments automatically use the cheapest currency trade orders available to bridge currencies.
|
||||
|
||||
## Background
|
||||
|
||||
### Mechanics
|
||||
## How Consensus Works
|
||||
|
||||
At the core, the XRP Ledger is a shared database that records information such as accounts, balances, and offers to trade assets. Signed instructions called "transactions" cause changes such as creating accounts, making payments, and trading assets.
|
||||
|
||||
As a cryptographic system, the owners of XRP Ledger accounts are identified by _cryptographic identities_, which correspond to public/private key pairs. Transactions are authorized by cryptographic signatures matching these identities. Every server processes every transaction according to the same deterministic, known rules. Ultimately, the goal is for every server in the network to have a complete copy of the exact same ledger state, without needing a single central authority to arbitrate transactions.
|
||||
|
||||
|
||||
### The Double Spend Problem
|
||||
|
||||
The "double spend" problem is a fundamental challenge to operating any sort of payment system. The problem comes from the requirement that when money is spent in one place, it can't also be spent in another place. More generally, the problem occurs when you have any two transactions such that either one is valid but not both together.
|
||||
|
||||
Suppose Alice, Bob, and Charlie are using a payment system, and Alice has a balance of $10. For the payment system to be useful, Alice must be able to send her $10 to Bob, or to Charlie. However, if Alice tries to send $10 to Bob and also send $10 to Charlie at the same time, that's where the double spend problem comes in.
|
||||
|
||||
If Alice can send the "same" $10 to both Charlie and Bob, the payment system ceases to be useful. The payment system needs a way to choose which transaction should succeed and which should fail, in such a way that all participants agree on which transaction has happened. Either of those two transactions is equally valid on its own. However, different participants in the payment system may have a different view of which transaction came first.
|
||||
|
||||
Conventionally, payment systems solve the double spend problem by having a central authority track and approve transactions. For example, a bank decides to clear a check based on the issuer's available balance, of which the bank is the sole custodian. In such a system, all participants follow the central authority's decisions.
|
||||
|
||||
Distributed ledger technologies, like the XRP Ledger, have no central authority. They must solve the double spend problem in some other way.
|
||||
|
||||
|
||||
## How Consensus Works
|
||||
|
||||
### Simplifying the Problem
|
||||
|
||||
Much of the double spend problem can be solved by well-known rules such as prohibiting an account from spending funds it does not have. In fact, the double spend problem can be reduced to putting transactions in order.
|
||||
|
||||
Consider the example of Alice trying to send the same $10 to both Bob and Charlie. If the payment to Bob is known to be first, then everyone can agree that she has the funds to pay Bob. If the payment to Charlie is known to be second, then everyone can agree that she cannot send those funds to Charlie because the money has already been sent to Bob.
|
||||
|
||||
We can also order transactions by deterministic rules. Because transactions are collections of digital information, it's trivial for a computer to sort them.
|
||||
|
||||
This would be enough to solve the double spend problem without a central authority, but it would require us to have every transaction that would ever occur (so that we could sort them) before we could be certain of the results of any transaction. Obviously, this is impractical. <!-- STYLE_OVERRIDE: obviously -->
|
||||
|
||||
If we could collect transactions into groups and agree on those groupings, we could sort the transactions within that group. As long as every participant agrees on which transactions are to be processed as a unit, they can use deterministic rules to solve the double spend problem without any need for a central authority. The participants each sort the transactions and apply them in a deterministic way following the known rules. The XRP Ledger solves the double-spend problem in exactly this way.
|
||||
|
||||
The XRP Ledger allows multiple conflicting transactions to be in the agreed group. The group of transactions is executed according to deterministic rules, so whichever transaction comes first according to the sorting rules succeeds and whichever conflicting transaction comes second fails.
|
||||
|
||||
### Consensus Rules
|
||||
|
||||
The primary role of consensus is for participants in the process to agree on which transactions are to be processed as a group to resolve the double spend problem. There are four reasons this agreement is easier to achieve than might be expected:
|
||||
@@ -110,6 +80,7 @@ Real-world systems, however, face operational conditions in which both kinds of
|
||||
|
||||
The XRP Ledger's consensus algorithm provides a robust alternative to proof of work systems, without consuming computational resources needlessly. Byzantine failures are possible, and do happen, but the consequence is only minor delays. In all cases, the XRP Ledger's consensus algorithm reports results as reliable only when they in fact are.
|
||||
|
||||
<!--
|
||||
## See Also
|
||||
|
||||
- **Concepts:**
|
||||
@@ -126,7 +97,7 @@ The XRP Ledger's consensus algorithm provides a robust alternative to proof of w
|
||||
- [validator_list_sites method][]
|
||||
- [validators method][]
|
||||
- [consensus_info method][]
|
||||
|
||||
-->
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
@@ -1,15 +1,16 @@
|
||||
---
|
||||
html: consensus-protections.html
|
||||
parent: consensus-network.html
|
||||
blurb: Learn how the XRP Ledger Consensus Protocol is protected against various problems and attacks that may occur in a decentralized financial system.
|
||||
parent: consensus.html
|
||||
blurb: The XRP Ledger is designed to protect itself against both malicious actors and unexpected network errors.
|
||||
labels:
|
||||
- Blockchain
|
||||
- Ledgers
|
||||
---
|
||||
# Consensus Protections Against Attacks and Failure Modes
|
||||
|
||||
The XRP Ledger Consensus Protocol is a _byzantine fault tolerant_ consensus mechanism, which means it's designed to work even if all kinds of things can go wrong: participants depend on an unreliable open network to communicate, and malicious actors may be attempting to control or interrupt the system at any given time. On top of that, the set of participants in the XRP Ledger Consensus Protocol isn't known in advance and can change over time.
|
||||
# Consensus Protections
|
||||
|
||||
Confirming transactions quickly while maintaining [the desired properties of the network](intro-to-consensus.html#consensus-protocol-properties) is a complex challenge, and it's impossible to build a perfect system. The XRP Ledger Consensus Protocol is designed to work as well as it can in most situations, and to fail as gracefully as possible in the situations where it can't.
|
||||
The XRP Ledger Consensus Protocol is a _byzantine fault tolerant_ consensus mechanism, which means it is designed to work even if all kinds of things can go wrong: participants depend on an unreliable open network to communicate, and malicious actors might be attempting to control or interrupt the system at any given time. On top of that, the set of participants in the XRP Ledger Consensus Protocol is not known in advance, and can change over time.
|
||||
|
||||
Confirming transactions quickly while maintaining the desired properties of the network is a complex challenge. It is impossible to build a perfect system. The XRP Ledger Consensus Protocol is designed to work as well as it can in most situations, and to fail as gracefully as possible in the situations where it cannot.
|
||||
|
||||
This page describes some of the types of challenges that the XRP Ledger Consensus Protocol faces and how it handles them.
|
||||
|
||||
@@ -23,9 +24,9 @@ _Validators_ are servers that actively contribute to the process of deciding eac
|
||||
- Behaving maliciously as a result of pressure from outside factors, such as threats from an oppressive government.
|
||||
- Accidentally sending confusing or malformed messages due to a bug or outdated software.
|
||||
|
||||
In general, consensus can continue without problems as long as only a small percentage (less than about 20%) of trusted validators are misbehaving at a given time. (For the exact percentages and the math behind them, see the latest [Consensus Research](consensus-research.html).)
|
||||
In general, consensus can continue without problems as long as only a small percentage (less than about 20%) of trusted validators are misbehaving at a given time. (For the exact percentages and the math behind them, see the latest [Consensus Research](consensus-research.md).)
|
||||
|
||||
If more than about 20% of validators are unreachable or not behaving properly, the network fails to reach a consensus. During this time, new transactions can be tentatively processed, but new ledger versions cannot be validated, so those transactions' final outcomes are not certain. In this situation, it would become immediately obvious that the XRP Ledger is unhealthy, prompting intervention from human participants who can decide whether to wait, or reconfigure their set of trusted validators.
|
||||
If more than about 20% of validators are unreachable or not behaving properly, the network fails to reach a consensus. During this time, new transactions can be tentatively processed, but new ledger versions cannot be validated, so those transactions' final outcomes are not certain. In this situation, it would become immediately obvious that the XRP Ledger is unhealthy, prompting intervention from human participants who can decide whether to wait or reconfigure their set of trusted validators.
|
||||
|
||||
The only way to confirm an invalid transaction would be to get at least 80% of trusted validators to approve of the transaction and agree on its exact outcome. (Invalid transactions include those spending money that has already been spent, or otherwise breaking the rules of the network.) In other words, a large majority of trusted validators would have to _collude_. With dozens of trusted validators run by different people and businesses in different parts of the world, this would be very difficult to achieve intentionally.
|
||||
|
||||
@@ -43,7 +44,7 @@ As with any software system, bugs (or intentionally malicious code) in the imple
|
||||
|
||||
## Sybil Attacks
|
||||
|
||||
A _[Sybil attack](https://en.wikipedia.org/wiki/Sybil_attack)_ is an attempt to take control of a network using a large number of fake identities. In the XRP Ledger, a Sybil attack would take the form of running a large number of validators, then convincing others to trust those validators. This sort of attack is theoretically possible, but would be very difficult to do because human intervention is necessary for validators to become trusted.
|
||||
A [Sybil attack](https://en.wikipedia.org/wiki/Sybil_attack) is an attempt to take control of a network using a large number of fake identities. In the XRP Ledger, a Sybil attack would take the form of running a large number of validators, then convincing others to trust those validators. This sort of attack is theoretically possible, but would be very difficult to do because human intervention is necessary for validators to become trusted.
|
||||
|
||||
No matter how many validating servers a would-be attacker runs, those servers have no say on what the existing participants consider validated unless those participants choose to trust the attacker's validators. Other servers only listen to the validators they are configured to trust, either through a validator list or explicit configuration. (See [validator overlap requirements](#validator-overlap-requirements) for a summary of how the default validator list works.)
|
||||
|
||||
@@ -63,12 +64,4 @@ By default, XRP Ledger servers are configured to use a validator list site run b
|
||||
|
||||
Technically, if you run a server, you can configure your own list site or explicitly choose validators to trust on an individual basis, but Ripple does not recommended doing so. If your chosen set of validators does not have enough overlap with others, your server may diverge from the rest of the network, and you could lose money by taking action based on your server's divergent state.
|
||||
|
||||
Research is ongoing to design an improved consensus protocol that allows more heterogeneous validator lists. For more information, see the [Consensus Research](consensus-research.html) page.
|
||||
|
||||
|
||||
## See Also
|
||||
|
||||
- For an **intro-level overview** of consensus, see [Intro to Consensus](intro-to-consensus.html).
|
||||
- For a **detailed description** of the consensus protocol, see [Consensus](consensus.html).
|
||||
- For an explanation of the **design decisions and background** behind the consensus protocol, see [Consensus Principles and Rules](consensus-principles-and-rules.html).
|
||||
- For **academic research** exploring the properties and limitations of the protocol, see [Consensus Research](consensus-research.html).
|
||||
Research is ongoing to design an improved consensus protocol that allows more heterogeneous validator lists. For more information, see the [Consensus Research](consensus-research.md) page.
|
||||
@@ -1,10 +1,11 @@
|
||||
---
|
||||
html: consensus-research.html
|
||||
parent: consensus-network.html
|
||||
blurb: Scholarly articles on consensus algorithms and related research.
|
||||
parent: consensus.html
|
||||
blurb: Ripple researches both the theoretical and the practical limits of the XRP Ledger's consensus protocols.
|
||||
labels:
|
||||
- Blockchain
|
||||
- Ledgers
|
||||
---
|
||||
|
||||
# Consensus Research
|
||||
|
||||
Ripple researches both the theoretical and the practical limits of the XRP Ledger's consensus protocols, and explores other ideas in the same space. The following table lists scholarly articles published by Ripple:
|
||||
@@ -13,6 +14,4 @@ Ripple researches both the theoretical and the practical limits of the XRP Ledge
|
||||
|---|---|---|---|
|
||||
| 2018-02-20 | [Cobalt: BFT Governance in Open Networks](https://arxiv.org/abs/1802.07240) | MacBrough | Introduces a novel atomic broadcast algorithm called Cobalt that allows more flexibility in consensus UNLs. |
|
||||
| 2018-02-20 | [Analysis of the XRP Ledger Consensus Protocol](https://arxiv.org/abs/1802.07242) | Chase, MacBrough | A detailed and updated analysis of the XRP Ledger consensus algorithm and its safety and liveness properties. |
|
||||
| 2014 | [The Ripple Protocol Consensus Algorithm](https://ripple.com/files/ripple_consensus_whitepaper.pdf) | Schwartz, Youngs, Britto | Introduces the consensus algorithm behind the XRP Ledger. |
|
||||
|
||||
<!-- SPELLING_IGNORE: bft, liveness -->
|
||||
| 2014 | [The Ripple Protocol Consensus Algorithm](https://ripple.com/files/ripple_consensus_whitepaper.pdf) | Schwartz, Youngs, Britto | Introduces the consensus algorithm behind the XRP Ledger. |
|
||||
@@ -1,11 +1,12 @@
|
||||
---
|
||||
html: consensus.html
|
||||
parent: consensus-network.html
|
||||
blurb: Understand the role of consensus in the XRP Ledger.
|
||||
html: consensus-structure.html
|
||||
parent: consensus.html
|
||||
blurb: Understand the design decisions for consensus in the XRP Ledger.
|
||||
labels:
|
||||
- Blockchain
|
||||
---
|
||||
# Consensus
|
||||
|
||||
# Consensus Structure
|
||||
|
||||
_Written by Dave Cohen, David Schwartz, and Arthur Britto._
|
||||
|
||||
60
content/concepts/understanding-xrpl/xrpl/consensus.md
Normal file
60
content/concepts/understanding-xrpl/xrpl/consensus.md
Normal file
@@ -0,0 +1,60 @@
|
||||
---
|
||||
html: consensus.html
|
||||
parent: validation.html
|
||||
blurb: Consensus is the validation process for new entries to the XRP Ledger.
|
||||
labels:
|
||||
- Ledgers
|
||||
---
|
||||
|
||||
# Consensus
|
||||
|
||||
This topic describes the consensus process used to validate each ledger version as it is added to the XRP Ledger block chain.
|
||||
|
||||
Consensus is the most important property of any decentralized payment system. In traditional centralized payment systems, one authoritative administrator gets the final say in how and when payments occur. Decentralized systems, by definition, do not have an administrator to do that. Instead, decentralized systems like the XRP Ledger define a set of rules all participants follow. Every participant can agree on the exact same series of events and their outcome at any point in time. This set of rules is known as a _consensus protocol_.
|
||||
|
||||
## Consensus Process
|
||||
|
||||
The consensus process gathers proposed transactions on the XRP Ledger and generates a new ledger version with agreed upon changes.
|
||||
|
||||
The peer-to-peer XRP Ledger network includes a specialized type of server called a _validator_. Validators collaborate to propose and confirm transactions that generate a new ledger version.
|
||||
|
||||
Starting with the last validated ledger version, validators distribute a new ledger version based on transaction requests they have received. The proposed ledgers all have the same sequence number (previous sequence number plus one).
|
||||
|
||||
[](img/consensus1-proposed-ledgers.png)
|
||||
|
||||
Validators then incorporate new transactions from other trusted validators, and remove transactions that are not recognized by other nodes. When 80% of the validator nodes agree on the transactions to include in the new ledger, all proposed ledger versions are dropped and a new one is created with the agreed upon transactions.
|
||||
|
||||
[](img/consensus2-agreed-transactions.png)
|
||||
|
||||
The XRP Ledger creates the new ledger version, including changes in state information based on the agreed upon transactions, the parent hash, the current available XRP, flags, and the close time. The ledger calculates the unique hash of the ledger version based on its own updated information.
|
||||
|
||||
[](img/consensus3-updates.png)
|
||||
|
||||
The XRP Ledger's technology enables near real-time settlement (three to six seconds).
|
||||
|
||||
## Consensus Protocol Properties
|
||||
|
||||
The XRP Ledger Consensus Protocol, is designed with these important properties:
|
||||
|
||||
- Everyone who uses the XRP Ledger can agree on the current state, and which transactions occurred in which order.
|
||||
- All valid transactions are processed without needing a central operator or having a single point of failure.
|
||||
- The ledger can make progress, even if some participants join, leave, or behave inappropriately.
|
||||
- If too many participants are unreachable or misbehaving, the network fails to make progress, rather than diverging or confirming invalid transactions.
|
||||
- Confirming transactions does not require wasteful or competitive use of resources, unlike most other blockchain systems.
|
||||
|
||||
These properties are sometimes summarized as the following principles, in order of priority: **Correctness, Agreement, Forward Progress**.
|
||||
|
||||
## Consensus Rules
|
||||
|
||||
The primary role of consensus is for participants in the process to agree on which transactions are to be processed as a group to resolve the double spend problem (where an account attempts to use the same funds for two separate transactions). There are four reasons this agreement is easier to achieve than might be expected:
|
||||
|
||||
1. If there is no reason a transaction should not be included in such a group of transactions, all honest participants agree to include it. If all participants already agree, consensus has no work to do.
|
||||
2. If there is any reason at all a transaction should not be included in such a group of transactions, all honest participants are willing to exclude it. If the transaction is still valid, there is no reason not to include it in the next round, and they should all agree to include it then.
|
||||
3. It is extremely rare for a participant to particularly care how the transactions were grouped. Agreement is easiest when everyone’s priority is reaching agreement and only challenging when there are diverging interests.
|
||||
4. Deterministic rules can be used even to form the groupings, leading to disagreement only in edge cases. For example, if there are two conflicting transactions in a round, deterministic rules can be used to determine which is included in the next round.
|
||||
|
||||
Every participant’s top priority is correctness. They must first enforce the rules to be sure nothing violates the integrity of the shared ledger. For example, a transaction that is not properly signed must never be processed (even if other participants want it to be processed). However, every honest participant’s second priority is agreement. A network with possible double spends has no utility at all, so every honest participant values agreement above everything but correctness.
|
||||
|
||||
For more in-depth information on how consensus works, see [Consensus Structure](consensus-structure.html)
|
||||
|
||||
This protocol is still evolving, as is our knowledge of its limits and possible failure cases. For academic research on the protocol itself, see [Consensus Research](consensus-research.html).
|
||||
34
content/concepts/understanding-xrpl/xrpl/double-spend.md
Normal file
34
content/concepts/understanding-xrpl/xrpl/double-spend.md
Normal file
@@ -0,0 +1,34 @@
|
||||
---
|
||||
html: double-spend.html
|
||||
parent: consensus.html
|
||||
blurb: Consensus protocols are a solution to the double-spend problem.
|
||||
labels:
|
||||
- Ledgers
|
||||
---
|
||||
# The Double-spend Problem
|
||||
|
||||
Consensus protocols are a solution to the _double-spend problem_: the challenge of preventing someone from successfully spending the same digital money twice. The hardest part about this problem is putting transactions in order: without a central authority, it can be difficult to resolve disputes about which transaction comes first when you have two or more mutually exclusive transactions sent around the same time.
|
||||
|
||||
The double-spend problem is a fundamental challenge to operating any sort of payment system. The problem comes from the requirement that when money is spent in one place, it can't also be spent in another place. More generally, the problem occurs when you have any two transactions such that either one is valid but not both together.
|
||||
|
||||
Suppose Alice, Bob, and Charlie are using a payment system, and Alice has a balance of $10. For the payment system to be useful, Alice must be able to send her $10 to Bob, or to Charlie. However, if Alice tries to send $10 to Bob and also send $10 to Charlie at the same time, that's where the double spend problem comes in.
|
||||
|
||||
If Alice can send the "same" $10 to both Charlie and Bob, the payment system ceases to be useful. The payment system needs a way to choose which transaction should succeed and which should fail, in such a way that all participants agree on which transaction has happened. Either of those two transactions is equally valid on its own. However, different participants in the payment system may have a different view of which transaction came first.
|
||||
|
||||
Conventionally, payment systems solve the double spend problem by having a central authority track and approve transactions. For example, a bank decides to clear a check based on the issuer's available balance, of which the bank is the sole custodian. In such a system, all participants follow the central authority's decisions.
|
||||
|
||||
Distributed ledger technologies, like the XRP Ledger, have no central authority. They must solve the double spend problem using a consensus protocol.
|
||||
|
||||
## Simplifying the Problem
|
||||
|
||||
Much of the double spend problem can be solved by well known rules such as prohibiting an account from spending funds it does not have. In fact, the double spend problem can be reduced to putting transactions in order.
|
||||
|
||||
Consider the example of Alice trying to send the same $10 to both Bob and Charlie. If the payment to Bob is known to be first, then everyone can agree that she has the funds to pay Bob. If the payment to Charlie is known to be second, then everyone can agree that she cannot send those funds to Charlie because the money has already been sent to Bob.
|
||||
|
||||
We can also order transactions by deterministic rules. Because transactions are collections of digital information, it's trivial for a computer to sort them.
|
||||
|
||||
This would be enough to solve the double spend problem without a central authority, but it would require us to have every transaction that would ever occur (so that we could sort them) before we could be certain of the results of any transaction. Of course, that would be impractical.
|
||||
|
||||
If we could collect transactions into groups and agree on those groupings, we could sort the transactions within that group. As long as every participant agrees on which transactions are to be processed as a unit, they can use deterministic rules to solve the double spend problem without any need for a central authority. The participants each sort the transactions and apply them in a deterministic way following the known rules. The XRP Ledger solves the double-spend problem in exactly this way.
|
||||
|
||||
The XRP Ledger allows multiple conflicting transactions to be in the agreed group. The group of transactions is executed according to deterministic rules, so whichever transaction comes first according to the sorting rules succeeds and whichever conflicting transaction comes second fails.
|
||||
@@ -1,16 +1,15 @@
|
||||
---
|
||||
html: fee-voting.html
|
||||
parent: consensus-network.html
|
||||
blurb: How validators vote on fees (transaction cost and reserve requirements).
|
||||
parent: consensus.html
|
||||
blurb: Validators can vote for changes in the cost of transactions and reserve requirements.
|
||||
labels:
|
||||
- Fees
|
||||
- XRP
|
||||
- Ledgers
|
||||
---
|
||||
# Fee Voting
|
||||
|
||||
Validators can vote for changes to basic [transaction cost](transaction-cost.html) as well as [reserve requirements](reserves.html). If the preferences in a validator's configuration are different than the network's current settings, the validator expresses its preferences to the network periodically. If a quorum of validators agrees on a change, they can apply a change that takes effect thereafter. Validators may do this for various reasons, especially to adjust to long-term changes in the value of XRP.
|
||||
Validators can vote for changes to basic transaction cost as well as reserve requirements. If the preferences in a validator's configuration are different than the network's current settings, the validator expresses its preferences to the network periodically. If a quorum of validators agrees on a change, they can apply a change that takes effect thereafter. Validators may do this for various reasons, especially to adjust to long-term changes in the value of XRP.
|
||||
|
||||
Operators of [`rippled` validators](run-rippled-as-a-validator.html) can set their preferences for the transaction cost and reserve requirements in the `[voting]` stanza of the `rippled.cfg` file.
|
||||
Operators of `rippled` validators can set their preferences for the transaction cost and reserve requirements in the `[voting]` stanza of the `rippled.cfg` file.
|
||||
|
||||
**Caution:** Insufficient requirements, if adopted by a consensus of trusted validators, could expose the XRP Ledger peer-to-peer network to denial-of-service attacks.
|
||||
|
||||
@@ -53,19 +52,4 @@ The maximum possible values for the fees are limited by the internal data types
|
||||
- **Concepts:**
|
||||
- [Amendments](amendments.html)
|
||||
- [Transaction Cost](transaction-cost.html)
|
||||
- [Reserves](reserves.html)
|
||||
- [Transaction Queue](transaction-queue.html)
|
||||
- **Tutorials:**
|
||||
- [Configure `rippled`](configure-rippled.html)
|
||||
- **References:**
|
||||
- [fee method][]
|
||||
- [server_info method][]
|
||||
- [FeeSettings object](feesettings.html)
|
||||
- [SetFee pseudo-transaction][]
|
||||
|
||||
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
- [Reserves](reserves.html)
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
html: invariant-checking.html
|
||||
parent: consensus-network.html
|
||||
parent: consensus.html
|
||||
blurb: Understand what Invariant Checking is, why it exists, how it works, and what invariant checks are active.
|
||||
labels:
|
||||
- Blockchain
|
||||
@@ -130,6 +130,7 @@ The XRP Ledger checks all the following invariants on each transaction:
|
||||
- A new account root must have the right starting [sequence](basic-data-types.html#account-sequence).
|
||||
- A transaction must not create more than one new [account](accounts.html).
|
||||
|
||||
<!--
|
||||
|
||||
## See Also
|
||||
|
||||
@@ -148,6 +149,7 @@ The XRP Ledger checks all the following invariants on each transaction:
|
||||
- [Authorized Trust Lines](authorized-trust-lines.html)
|
||||
- [XRP Properties](xrp.html#xrp-properties)
|
||||
- [Calculating Balance Changes for a Transaction](https://xrpl.org/blog/2015/calculating-balance-changes-for-a-transaction.html#calculating-balance-changes-for-a-transaction)
|
||||
-->
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
html: ledger-close-times.html
|
||||
parent: open-closed-validated-ledgers.html
|
||||
blurb: How the XRP Ledger calculates a unique close time value for each ledger version.
|
||||
labels:
|
||||
- Ledgers
|
||||
---
|
||||
|
||||
# Ledger Close Times
|
||||
|
||||
<!-- this topic needs illustrations -->
|
||||
|
||||
The time that a ledger version closes is recorded in the `close_time` field of the ledger header. To make it easier for the network to reach a consensus on an exact close time, this value is rounded to a number of seconds based on the close time resolution, currently 10 seconds. If rounding would cause a ledger's close time to be the same as (or earlier than) its parent ledger's, the child ledger has its close time set to the parent's close time plus 1. This guarantees that the close times of validated ledgers are strictly increasing. <!-- STYLE_OVERRIDE: a number of -->
|
||||
|
||||
Since new ledger versions usually close about every 3 to 5 seconds, these rules result in a loose pattern where ledger close times end in :00, :01, :02, :10, :11, :20, :21, and so on. Times ending in 2 are less common and times ending in 3 are very rare, but both occur when more ledgers randomly happen to close within a 10-second window.
|
||||
|
||||
Generally speaking, the ledger cannot make any time-based measurements that are more precise than the close time resolution. For example, to check if an object has passed an expiration date, the rule is to compare it to the close time of the parent ledger. (The close time of a ledger is not yet known when executing transactions to go into that ledger.) This means that, for example, an Escrow could successfully finish at a real-world time that is up to 10 seconds later than the time-based expiration specified in the Escrow object.
|
||||
|
||||
### Example
|
||||
|
||||
The following examples demonstrate the rounding behavior of ledger close times, from the perspective of an example validator, following a ledger with the close time **12:00:00**:
|
||||
|
||||
**Current consensus round**
|
||||
|
||||
1. A validator notes that it was **12:00:03** when the ledger closed and entered consensus. The validator includes this close time in its proposals.
|
||||
2. The validator observes that most other validators (on its UNL) proposed a close time of 12:00:02, and one other proposed a close time of 12:00:03. It changes its proposed close time to match the consensus of **12:00:02**.
|
||||
3. The validator rounds this value to the nearest close time interval, resulting in **12:00:00**.
|
||||
4. Since 12:00:00 is not greater than the previous ledger's close time, the validator adjusts the close time to be exactly 1 second after the previous ledger's close time. The result is an adjusted close time of **12:00:01**.
|
||||
5. The validator builds the ledger with these details, calculates the resulting hash, and confirms in the validation step that others did the same.
|
||||
|
||||
Non-validating servers do all the same steps, except they do not propose their recorded close times to the rest of the network.
|
||||
|
||||
**Next consensus round**
|
||||
|
||||
1. The next ledger enters consensus at **12:00:04** according to most validators.
|
||||
2. This rounds down again, to a close time of **12:00:00**.
|
||||
3. Since this is not greater than the previous ledger's close time of 12:00:01, the adjusted close time is **12:00:02**.
|
||||
|
||||
**Next consensus round after that**
|
||||
|
||||
1. The ledger after that enters consensus at **12:00:05** according to most validators.
|
||||
2. This rounds up, based on the close time resolution, to **12:00:10**.
|
||||
3. Since this value is larger than the previous ledger's close time, it does not need to be adjusted. **12:00:10** becomes the official close time.
|
||||
71
content/concepts/understanding-xrpl/xrpl/ledger-structure.md
Normal file
71
content/concepts/understanding-xrpl/xrpl/ledger-structure.md
Normal file
@@ -0,0 +1,71 @@
|
||||
---
|
||||
html: ledger-structure.html
|
||||
parent: ledgers.html
|
||||
blurb: A closer look at the elements to be found in each XRP Ledger entry.
|
||||
labels:
|
||||
- Ledgers
|
||||
---
|
||||
|
||||
# XRP Ledger Structure
|
||||
|
||||
The XRP Ledger is a block chain system, linking immutable data blocks in a meaningful sequence. This topic examines the data blocks that make up the XRPL block chain.
|
||||
|
||||
The XRP Ledger processes transactions in blocks called _ledger versions_. Each ledger version contains state data, a transaction set, and metadata.
|
||||
|
||||
The main job of the XRP Ledger Consensus Protocol is to agree on a set of transactions to apply to the previous ledger, apply them in a well defined order, then confirm that all validators get the same results. When this happens successfully, a ledger version is considered _validated_, and final. From there, the process continues by building the next ledger version.
|
||||
|
||||
[](img/ledger.png)
|
||||
|
||||
Each data block in the XRPL chain is a _ledger version_. A ledger version is comprised of the following elements.
|
||||
|
||||
The _ledger index_ identifies the ledger version position in the chain at the time of its validation. It builds on the version with an index that is one lower, back to the starting point known as the _genesis ledger_. This forms a public history of all transactions and results.
|
||||
|
||||
[](img/ledger1-sequence-number.png)
|
||||
|
||||
Each ledger version also identifies itself with a unique 64-character hexidecimal _hash number_.
|
||||
|
||||
[](img/ledger2-unique-hash.png)
|
||||
|
||||
Ledger versions are largely defined as the difference between the current version and its _parent version_, identified by its unique hash number.
|
||||
|
||||
[](img/ledger3-parent-version.png)
|
||||
|
||||
Every change made from version to version is the result of a validated transaction. The ledger version stores information about transactions in its scope.
|
||||
|
||||
[](img/ledger4-transactions.png)
|
||||
|
||||
The ledger version contains _state data_ for all accounts, along with some miscellaneous housekeeping information. 99% or more of the data tends to be the same from version to version. While every rippled server keeps a copy of the entire ledger history, each ledger version saves only the updates to the state data.
|
||||
|
||||
[](img/ledger5-state-data.png)
|
||||
|
||||
Every transaction has a minor cost that removes a small amount of XRP from the available pool. The ledger version keeps track of the full amount of _available XRP_ still in circulation, in drops. The number of actual XRP in circulation is smaller than the amount in the ledger due to some XRP having been sent to "black hole" accounts where the access information is unknown, either by default or design.
|
||||
|
||||
[](img/ledger6-available-zrp.png)
|
||||
|
||||
_Close Flags_ is a bit map of flags related to the close of the ledger. Currently, the only flag defined is **sLCF_NoConsensusTime** (value 1). It means that validators disagreed on the close time, but otherwise built the same ledger, so they have decided to "agree to disagree" on the close time. Other flags might be defined in future amendments to the XRP Ledger.
|
||||
|
||||
[](img/ledger7-close-flags.png)
|
||||
|
||||
_Close Time_ is the official timestamp when the final validated ledger version is created and closed.
|
||||
|
||||
[](img/ledger8-close-time.png)
|
||||
|
||||
80% or more of the validators in the server's Unique Node List must agree on the contents of the ledger. Once it is validated, it is immutable. The ledger can only be changed by subsequent transactions.
|
||||
|
||||
[](img/ledger.png)
|
||||
|
||||
|
||||
## Tree Format
|
||||
|
||||
<!-- This needs an illustration -->
|
||||
|
||||
As its name might suggest, a ledger's state tree is a tree data structure. Each object in the state tree is identified by a 256-bit object ID. In JSON, a ledger object's ID is the `index` field, which contains a 64-character hexadecimal string like `"193C591BF62482468422313F9D3274B5927CA80B4DD3707E42015DD609E39C94"`. Every object in the state tree has an ID that you can use to look up that object; every transaction has an identifying hash that you can use to look up the transaction in the transaction tree. Do not confuse the `index` (ID) of a ledger object with the `ledger_index` (sequence number) of a ledger.
|
||||
|
||||
**Tip:** Sometimes, an object in the ledger's state tree is called a _ledger node_. For example, transaction metadata returns a list of `AffectedNodes`. Do not confuse this with a _node_ (server) in the peer-to-peer network.
|
||||
|
||||
In the case of transactions, the identifying hash is based on the signed transaction instructions. When you look up the transaction, its contents contain the results and metadata of the transaction, which are not taken into account when generating the hash.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
26
content/concepts/understanding-xrpl/xrpl/ledgers.md
Normal file
26
content/concepts/understanding-xrpl/xrpl/ledgers.md
Normal file
@@ -0,0 +1,26 @@
|
||||
---
|
||||
html: ledgers.html
|
||||
parent: understanding-xrpl.html
|
||||
blurb: The XRP Ledger is a blockchain that records transactions of XRP and other tokens between accounts.
|
||||
labels:
|
||||
- Ledgers
|
||||
---
|
||||
|
||||
# Ledgers
|
||||
|
||||
The XRP Ledger is a global distributed blockchain that is open to all. 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 managing a ledger database that can only be updated according to very specific rules.
|
||||
|
||||
Each instance of `rippled` keeps a full copy of the ledger. The peer-to-peer network of `rippled` servers distributes candidate transactions to all other `rippled` servers. The consensus process determines which transactions are applied to each new version of the ledger.
|
||||
|
||||
The shared global ledger is a series of individual ledger versions that `rippled` keeps in its internal database. Every ledger version has a Ledger Index value that identifies the order of ledger versions. Each permanent, closed ledger version has a unique, identifying hash value.
|
||||
|
||||
At any given time, a `rippled` instance has an in-progress _open_ ledger, a number of _closed_ ledgers that have not yet been approved, and any number of ledgers that have been _validated_ by consensus. Only the validated ledgers are certain to be correct and immutable. The following table summarizes the difference:
|
||||
|
||||
A single ledger version consists of three parts:
|
||||
|
||||
* 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 version to create this version. Transactions are the _only_ way to change the ledger.
|
||||
* A **state tree** - All the ledger objects that contain the settings, balances, and objects in the ledger as of this version.
|
||||
|
||||
See [Ledger Structure](ledger-structure.html) for a complete description of the elements of an XRP Ledger object.
|
||||
|
||||
@@ -1,10 +1,11 @@
|
||||
---
|
||||
html: negative-unl.html
|
||||
parent: consensus-network.html
|
||||
blurb: Understand how Negative UNL improves the ledger's resilience during partial outages.
|
||||
parent: consensus.html
|
||||
blurb: Negative UNL improves the network's ability to make progress during a partial outage.
|
||||
labels:
|
||||
- Blockchain
|
||||
- Ledgers
|
||||
---
|
||||
|
||||
# Negative UNL
|
||||
|
||||
_Added by the [NegativeUNL Amendment](known-amendments.html#negativeunl)._
|
||||
@@ -117,7 +118,7 @@ This mechanism has several useful properties:
|
||||
|
||||
### Filtering Validations
|
||||
|
||||
During [the validation step of the consensus process](consensus.html#validation), validators in the parent ledger's Negative UNL are disabled. Each server calculates an "effective UNL" consisting of its configured UNL with the disabled validators removed, and recalculates its quorum. (The quorum is always at least 80% of the effective UNL and at least 60% of the configured UNL.) If a disabled validator sends validation votes, servers track those votes for purposes of calculating the disabled validator's reliability measurement, but they do not use those votes towards determining whether a ledger version has achieved a consensus.
|
||||
During the validation step of the consensus process, validators in the parent ledger's Negative UNL are disabled. Each server calculates an "effective UNL" consisting of its configured UNL with the disabled validators removed, and recalculates its quorum. (The quorum is always at least 80% of the effective UNL and at least 60% of the configured UNL.) If a disabled validator sends validation votes, servers track those votes for purposes of calculating the disabled validator's reliability measurement, but they do not use those votes towards determining whether a ledger version has achieved a consensus.
|
||||
|
||||
**Note:** The Negative UNL adjusts the _total_ trusted validators that the quorum is calculated from, not the quorum directly. The quorum is a percentage but the number of votes is a whole number, so reducing the total trusted validators does not always change the number of votes required to reach a quorum. For example, if there are 15 total validators, 80% is 12 validators exactly. If you reduce the total to 14 validators, 80% is 11.2 validators, which means that it still requires 12 validators to reach a quorum.
|
||||
|
||||
@@ -179,8 +180,3 @@ The following example demonstrates how the Negative UNL affects the consensus pr
|
||||
- [UNLModify pseudo-transaction][]
|
||||
- [ledger_entry method][]
|
||||
- [consensus_info method][]
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
html: open-closed-validated-ledgers.html
|
||||
parent: validation.html
|
||||
blurb: Ledger objects have one of three states — open, closed, or validated.
|
||||
labels:
|
||||
- Ledgers
|
||||
---
|
||||
|
||||
# Open, Closed, and Validated Ledgers
|
||||
|
||||
The `rippled` server makes a distinction between ledger versions that are open, closed, and validated. A server has one open ledger, any number of closed but unvalidated ledgers, and an immutable history of validated ledgers.
|
||||
|
||||
The following table summarizes the difference:
|
||||
|
||||
| Ledger Type: | Open | Closed | Validated |
|
||||
|:---------------------------------|:----------------------------|:-------------------------------------------|:--|
|
||||
| **Purpose:** | Temporary workspace | Proposed next state | Confirmed previous state |
|
||||
| **Number used:** | 1 | Any number, but usually 0 or 1 | One per ledger index, growing over time |
|
||||
| **Can contents change?** | Yes | No, but the whole ledger could be replaced | Never |
|
||||
| **Transactions are applied in:** | The order they are received | Canonical order | Canonical order |
|
||||
|
||||
The XRP Ledger never "closes" an open ledger to convert it into a closed ledger. Instead, the server throws away the open ledger, creates a new closed ledger by applying transactions on top of a previous closed ledger, then creates a new open ledger using the latest closed ledger as a base.
|
||||
|
||||
For an open ledger, servers apply transactions in the order those transactions appear, but different servers might see transactions different orders. Since there is no central timekeeper to decide which transaction was actually first, servers can disagree on the exact order of transactions that were sent around the same time. The process for calculating a closed ledger version that is eligible for [validation](consensus.html#validation) is different than the process of building an open ledger from proposed transactions in the order they arrive. To create a "closed" ledger, each XRP Ledger server starts with a set of transactions and a previous, or "parent", ledger version. The server puts the transactions in a canonical order, then applies them to the previous ledger in that order. The canonical order is designed to be deterministic, efficient, and hard to game.
|
||||
|
||||
An open ledger is only used as a temporary workspace. The temporary results might vary from the validated ledger.
|
||||
|
||||
## See Also
|
||||
|
||||
- For more information on how the XRP Ledger calculates unique close times for each ledger see [Ledger Close Times](ledger-close-times.html)
|
||||
|
||||
- For more information about ledger headers, ledger object IDs, and ledger object types, see [Ledger Data Formats](ledger-data-formats.html)
|
||||
- For information on how servers track the history of changes to ledger state, see [Ledger History](ledger-history.html)
|
||||
21
content/concepts/understanding-xrpl/xrpl/validation.md
Normal file
21
content/concepts/understanding-xrpl/xrpl/validation.md
Normal file
@@ -0,0 +1,21 @@
|
||||
---
|
||||
html: validation.html
|
||||
parent: ledgers.html
|
||||
blurb: The XRP Ledger's consensus mechanism facilitates approval of ledgers by trusted validators.
|
||||
labels:
|
||||
- Ledgers
|
||||
---
|
||||
|
||||
# Validation
|
||||
|
||||
Each participant in the XRP Ledger network chooses a set of _validators_, servers specifically configured to participate actively in consensus. The validators are run by different parties who are expected to behave honestly. More importantly, you choose that are not likely to collude with one another to break the rules. This list is sometimes called a _Unique Node List_, or UNL.
|
||||
|
||||
As the network progresses, each server listens to its trusted validators. When a large enough percentage of them agree that a set of transactions should occur, the server declares a consensus. If they do not agree, validators modify their proposals to more closely match the other trusted validators, repeating the process in several rounds until they reach consensus.
|
||||
|
||||
[](img/consensus-rounds.svg)
|
||||
|
||||
It does not matter if a small proportion of validators do not work properly every time. As long as fewer than 20% of trusted validators are faulty, consensus can continue unimpeded; confirming an invalid transaction would require over 80% of trusted validators to collude. If more than 20% but less than 80% of trusted validators are faulty, the network stops making progress.
|
||||
|
||||
For more information on how consensus works, see [Consensus](consensus-concept.html).
|
||||
|
||||
For a longer exploration of how the XRP Ledger Consensus Protocol responds to various challenges, attacks, and failure cases, see [Consensus Protections](consensus-protections.html).
|
||||
53
content/concepts/understanding-xrpl/xrpl/xrpl-ecosystem.md
Normal file
53
content/concepts/understanding-xrpl/xrpl/xrpl-ecosystem.md
Normal file
@@ -0,0 +1,53 @@
|
||||
# Understanding the XRPL Ecosystem
|
||||
|
||||
The XRP Ledger is a layered ecosystem of software projects that power and enable the Internet of Value. It is impossible to list every project, tool, and business that interacts with the XRP Ledger. This page highlights some core projects.
|
||||
|
||||
- The base of the ledger is a peer-to-peer network of always-on servers sharing transactions, engaging in the consensus process and coordinating transactions.
|
||||
|
||||
- Programming libraries provide methods to interact with the XRP Ledger.
|
||||
|
||||
- Middleware provides indirect access to XRP Ledger data.
|
||||
|
||||
- Apps and Services provide user-level interaction with the XRP Ledger.
|
||||
|
||||
|
||||
## rippled: The Core Server
|
||||
|
||||
The peer-to-peer network at the heart of the XRP Ledger requires a highly reliable, efficient server to enforce the rules of consensus and transaction processing. Ripple manages and publishes a reference implementation of this server software, called `rippled` (pronounced "ripple-dee"). The server is available under a permissive open-source license. Anyone can inspect and modify their own instance of the server, and re-publish with few restrictions.
|
||||
|
||||
[](../../../img/ecosystem1-peer-to-peer.png)
|
||||
|
||||
Every XRPL instance of `rippled` syncs to the same network and has access to all communications across the network. Every `rippled` server on the network keeps a complete copy of the latest state data for the entire XRP Ledger. Each server stores a slice of recent transactions and a record of the changes those transactions made. Every server processes every transaction independently, while verifying that its outcome matches the rest of the network. Servers can be configured to keep more ledger history and to participate in the _consensus_ process as a _validator_.
|
||||
|
||||
`rippled` APIs allow users to look up data, administer the server, and submit transactions.
|
||||
|
||||
## Programming Libraries
|
||||
|
||||
Programming libraries are not strictly required to access XRP Ledger data, since you can use HTTP or WebSocket to connect to the `rippled` APIs directly. Libraries simplify some of the common work of accessing the `rippled` APIs, and convert the data into forms that are easier to understand and program in the programming language of the library.
|
||||
|
||||
[](../../../img/ecosystem2-programming-libraries.png)
|
||||
|
||||
## Middleware
|
||||
|
||||
Middleware services are programs that consume XRP Ledger APIs on one side and provide their own APIs on the other side. They provide a layer of abstraction to make it easier to build higher level applications by providing some common functionality as a service.
|
||||
|
||||
[](../../../img/ecosystem3-middleware.png)
|
||||
|
||||
Unlike programming libraries, which start and shut down with the program that imports them, middleware services typically stay running indefinitely. Middleware services can have their own databases and configuration files.
|
||||
|
||||
The Data API is an example of a middleware service on top of the XRP Ledger. The Data API collects and transforms XRP Ledger data so that you can query by time, filter by data type, or perform data analysis.
|
||||
|
||||
XRP-API is another middleware service. XRP-API manages secret keys, and provides a more convenient RESTful interface to the XRP Ledger for apps in any programming language.
|
||||
|
||||
## Apps and Services
|
||||
|
||||
Apps and services provide a way for users and devices to connect to the XRP Ledger. At this level, exchanges list XRP, gateways issue other currencies for use in the decentralized exchange, and wallets provide user interfaces for buying, selling, or holding XRP. Many other possibilities exist, including additional services layered even higher.
|
||||
|
||||
[](../../../img/ecosystem4-apps.png)
|
||||
|
||||
One way to build applications that are compatible with not only XRP but also other ways of denominating value is to use the Interledger Protocol with settlement in XRP.
|
||||
|
||||
There are many other examples of projects using XRP and adjacent technologies to interact with users.
|
||||
|
||||
<!-- For some examples, see [Businesses](businesses.html), [Exchanges](exchanges.html), and [Wallets](wallets.html).
|
||||
-->
|
||||
@@ -161,7 +161,9 @@ targets:
|
||||
# the updates to ledger_entry aren't translated either
|
||||
"ledger_entry.html#get-paychannel-object": "ledger_entry.html"
|
||||
"reliable-transaction-submission.html#ledger-gaps": "reliable-transaction-submission.html#レジャーのギャップ"
|
||||
# "transaction-common-fields.html#memos-field": "transaction-common-fields.html#memosフィールド"
|
||||
# Fix links from untranslated NFT transaction references:
|
||||
"transaction-common-fields.html#flags-field": "transaction-common-fields.html#flagsフィールド"
|
||||
"transaction-common-fields.html#memos-field": "transaction-common-fields.html#memosフィールド"
|
||||
"basic-data-types.html#specifying-ledgers": "basic-data-types.html#レジャーの指定"
|
||||
# Fix links from untranslated build-a-desktop-wallet-in-python.html:
|
||||
"subscribe.html#ledger-stream": "subscribe.html#レジャーストリーム"
|
||||
@@ -173,6 +175,10 @@ targets:
|
||||
# Fix links from untranslated common-misconceptions-about-freezes.html
|
||||
# Not updated to have the table. The top-level of the page is pretty close.
|
||||
"currency-formats.html#comparison": "currency-formats.html"
|
||||
# Fix links from untranslated NFToken tx refs to translated NFToken page
|
||||
"nftoken.html#nftoken-flags": "nftoken.html#nftoken-フラグ"
|
||||
"nftoken.html#taxon": "nftoken.html#分類群"
|
||||
"basic-data-types.html#addresses": "basic-data-types.html#アドレス"
|
||||
# Fix links from untranslated Clio server_info:
|
||||
"peer-protocol.html#node-key-pair": "peer-protocol.html#ノードキーペア"
|
||||
"transaction-cost.html#local-load-cost": "transaction-cost.html#ローカル負荷コスト"
|
||||
@@ -185,11 +191,6 @@ targets:
|
||||
"transaction-basics.html#authorizing-transactions": "transaction-basics.html#トランザクションの識別"
|
||||
# Fix link from untranslated account_nfts.html
|
||||
"nftoken.html#nftokentaxon": "nftoken.html#分類群"
|
||||
# Fix links from untranslated NFT API methods:
|
||||
"transaction-common-fields.html#flags-field": "transaction-common-fields.html#flagsフィールド"
|
||||
"nftoken.html#nftoken-flags": "nftoken.html#nftoken-フラグ"
|
||||
"basic-data-types.html#addresses": "basic-data-types.html#アドレス"
|
||||
"nftokenoffer.html#nftokenoffer-flags": "nftokenoffer.html#nftokenoffer-フラグ"
|
||||
|
||||
pages:
|
||||
|
||||
@@ -397,7 +398,7 @@ pages:
|
||||
- xrp-testnet-faucet.html
|
||||
- run-rippled-as-a-validator.html
|
||||
- build-run-rippled-in-reporting-mode.html
|
||||
- intro-to-consensus.html
|
||||
#- intro-to-consensus.html
|
||||
- public-api-methods.html
|
||||
top_nav_hero_image: top-nav-hero-docs
|
||||
popular_pages: #TODO: find a way so this isn't a partial duplicate of top_nav_shortcuts?
|
||||
@@ -406,7 +407,7 @@ pages:
|
||||
- xrp-testnet-faucet.html
|
||||
- run-rippled-as-a-validator.html
|
||||
- build-run-rippled-in-reporting-mode.html
|
||||
- intro-to-consensus.html
|
||||
#- intro-to-consensus.html
|
||||
- public-api-methods.html
|
||||
blurb: Explore XRP Ledger documentation and everything you need to know to start building and integrating with the ledger.
|
||||
top_nav_blurb: Dive into XRP Ledger technology and start integrating.
|
||||
@@ -434,7 +435,7 @@ pages:
|
||||
- xrp-testnet-faucet.html
|
||||
- run-rippled-as-a-validator.html
|
||||
- build-run-rippled-in-reporting-mode.html
|
||||
- intro-to-consensus.html
|
||||
# - intro-to-consensus.html
|
||||
- public-api-methods.html
|
||||
top_nav_hero_image: top-nav-hero-docs
|
||||
popular_pages: #TODO: find a way so this isn't a partial duplicate of top_nav_shortcuts?
|
||||
@@ -443,7 +444,7 @@ pages:
|
||||
- xrp-testnet-faucet.html
|
||||
- run-rippled-as-a-validator.html
|
||||
- build-run-rippled-in-reporting-mode.html
|
||||
- intro-to-consensus.html
|
||||
# - intro-to-consensus.html
|
||||
blurb: Dive into XRP Ledger technology and start integrating. #TODO: translate
|
||||
filters:
|
||||
- labels
|
||||
@@ -474,7 +475,7 @@ pages:
|
||||
html: introduction.html
|
||||
parent: concepts.html
|
||||
template: pagetype-category.html.jinja
|
||||
blurb: Learn the "what" and "why" of the XRP Ledger.
|
||||
blurb: This is a quick introduction to the principal features of the XRP Ledger (XRPL). Read this to get a high level understanding of the XRPL, then you can read more about areas of particular interest. The XRP Ledger is a blockchain that permanently records digital transactions of tokens between accounts. The sections below expand on the concepts introduced in that sentence.
|
||||
targets:
|
||||
- en
|
||||
|
||||
@@ -485,41 +486,142 @@ pages:
|
||||
blurb: XRP Ledgerとは「何なのか」、「なぜなのか」を学びましょう。
|
||||
targets:
|
||||
- ja
|
||||
|
||||
- md: concepts/introduction/what-is-xrpl.md
|
||||
parent: introduction.html
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
|
||||
- md: concepts/introduction/what-is-xrp.md
|
||||
parent: introduction.html
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
|
||||
- md: concepts/introduction/txn-and-requests.md
|
||||
parent: introduction.html
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
|
||||
# Supplanted by the new xrp-ledger-overview.html landing page.
|
||||
# TODO: fully replace. https://github.com/XRPLF/xrpl-dev-portal/issues/1202
|
||||
# - md: concepts/introduction/xrp-ledger-overview.md
|
||||
# targets:
|
||||
# - en
|
||||
#
|
||||
# - md: concepts/introduction/xrp-ledger-overview.ja.md
|
||||
# targets:
|
||||
# - ja
|
||||
|
||||
- md: concepts/introduction/intro-to-consensus.md
|
||||
- name: Understanding the XRP Ledger
|
||||
html: understanding-xrpl.html
|
||||
parent: concepts.html
|
||||
template: pagetype-category.html.jinja
|
||||
blurb: This is an in-depth discussion of all elements of the XRP Ledger.
|
||||
targets:
|
||||
- en
|
||||
- en
|
||||
- ja
|
||||
|
||||
- md: concepts/introduction/intro-to-consensus.ja.md
|
||||
targets:
|
||||
- ja
|
||||
- md: concepts/understanding-xrpl/xrpl/ledgers.md
|
||||
parent: understanding-xrpl.html
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
|
||||
- md: concepts/introduction/xrp.md
|
||||
targets:
|
||||
- en
|
||||
- md: concepts/understanding-xrpl/xrpl/ledger-structure.md
|
||||
parent: ledgers.html
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
|
||||
- md: concepts/introduction/xrp.ja.md
|
||||
targets:
|
||||
- ja
|
||||
- md: concepts/understanding-xrpl/xrpl/validation.md
|
||||
parent: ledgers.html
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
|
||||
- md: concepts/introduction/software-ecosystem.md
|
||||
targets:
|
||||
- en
|
||||
- md: concepts/understanding-xrpl/xrpl/consensus.md
|
||||
parent: validation.html
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
|
||||
- md: concepts/introduction/software-ecosystem.ja.md
|
||||
targets:
|
||||
- ja
|
||||
- md: concepts/understanding-xrpl/xrpl/consensus-structure.md
|
||||
parent: consensus.html
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
|
||||
- md: concepts/understanding-xrpl/xrpl/double-spend.md
|
||||
parent: consensus.html
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
|
||||
- md: concepts/understanding-xrpl/xrpl/consensus-principles-and-rules.md
|
||||
parent: consensus.html
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
|
||||
- md: concepts/understanding-xrpl/xrpl/consensus-protections.md
|
||||
parent: consensus.html
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
|
||||
- md: concepts/understanding-xrpl/xrpl/fee-voting.md
|
||||
parent: consensus.html
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
|
||||
- md: concepts/understanding-xrpl/xrpl/negative-unl.md
|
||||
parent: consensus.html
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
|
||||
- md: concepts/understanding-xrpl/xrpl/invariant-checking.md
|
||||
parent: consensus.html
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
|
||||
- md: concepts/understanding-xrpl/xrpl/consensus-research.md
|
||||
parent: consensus.html
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
|
||||
- md: concepts/understanding-xrpl/xrpl/open-closed-validated-ledgers.md
|
||||
parent: validation.html
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
|
||||
- md: concepts/understanding-xrpl/xrpl/ledger-close-times.md
|
||||
parent: open-closed-validated-ledgers.html
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
|
||||
- md: concepts/understanding-xrpl/transactions/transactions.md
|
||||
parent: understanding-xrpl.html
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
|
||||
- md: concepts/understanding-xrpl/transactions/transaction-structure.md
|
||||
parent: transactions.html
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
|
||||
- md: concepts/understanding-xrpl/transactions/transaction-metadata-concept.md
|
||||
parent: transactions.html
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
|
||||
# - md: concepts/understanding-xrpl/transactions/transaction-cost.md
|
||||
# parent: transactions.html
|
||||
# targets:
|
||||
# - en
|
||||
# - ja
|
||||
#
|
||||
- name: Payment System Basics
|
||||
html: payment-system-basics.html
|
||||
parent: concepts.html
|
||||
@@ -593,9 +695,9 @@ pages:
|
||||
targets:
|
||||
- ja
|
||||
|
||||
- md: concepts/payment-system-basics/ledgers.md
|
||||
targets:
|
||||
- en
|
||||
# - md: concepts/payment-system-basics/ledgers.md
|
||||
# targets:
|
||||
# - en
|
||||
|
||||
# TODO: translation needs to be updated based on ledgers.md
|
||||
- md: concepts/payment-system-basics/ledgers.ja.md
|
||||
@@ -610,9 +712,9 @@ pages:
|
||||
targets:
|
||||
- ja
|
||||
|
||||
- md: concepts/payment-system-basics/transaction-basics/transaction-cost.md
|
||||
targets:
|
||||
- en
|
||||
# - md: concepts/payment-system-basics/transaction-basics/transaction-cost.md
|
||||
# targets:
|
||||
# - en
|
||||
|
||||
- md: concepts/payment-system-basics/transaction-basics/transaction-cost.ja.md
|
||||
targets:
|
||||
@@ -716,7 +818,6 @@ pages:
|
||||
targets:
|
||||
- en
|
||||
|
||||
# TODO: Outdated translation
|
||||
- md: concepts/tokens/tokens.ja.md
|
||||
targets:
|
||||
- ja
|
||||
@@ -734,7 +835,7 @@ pages:
|
||||
html: issued-currencies.html
|
||||
template: pagetype-redirect.html.jinja
|
||||
redirect_url: tokens.html
|
||||
blurb: 誰もがXRP Ledger上でデジタル価値を表すトークンを作ることができます。
|
||||
blurb: XRP Ledgerでは、XRP以外の通貨はすべて発行済み通貨とされます。XRP Ledgerで発行済み通貨がどのように機能するか説明します。
|
||||
targets:
|
||||
- ja
|
||||
|
||||
@@ -757,17 +858,11 @@ pages:
|
||||
- md: concepts/tokens/non-fungible-tokens.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: concepts/tokens/non-fungible-tokens.ja.md
|
||||
targets:
|
||||
- ja
|
||||
|
||||
- md: concepts/tokens/non-fungible-token-transfers.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: concepts/tokens/non-fungible-token-transfers.ja.md
|
||||
targets:
|
||||
- ja
|
||||
|
||||
- md: concepts/tokens/nftoken-batch-minting.md
|
||||
@@ -862,139 +957,139 @@ pages:
|
||||
targets:
|
||||
- ja
|
||||
|
||||
- name: Consensus Network
|
||||
html: consensus-network.html
|
||||
parent: concepts.html
|
||||
template: pagetype-category.html.jinja
|
||||
blurb: The XRP Ledger uses a consensus algorithm to resolve the double spend problem and choose which transactions to execute in which order. Consensus also governs rules of transaction processing.
|
||||
targets:
|
||||
- en
|
||||
|
||||
- name: コンセンサスネットワーク
|
||||
html: consensus-network.html
|
||||
parent: concepts.html
|
||||
template: pagetype-category.html.jinja
|
||||
blurb: XRP Ledgerはコンセンサスアルゴリズムを使用して、二重支払いの問題を解決し、どのトランザクションをどのような順番で実行するか選択します。コンセンサスは、トランザクション処理のルールを左右します。
|
||||
targets:
|
||||
- ja
|
||||
|
||||
- md: concepts/consensus-network/consensus.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: concepts/consensus-network/consensus.ja.md
|
||||
targets:
|
||||
- ja
|
||||
|
||||
- md: concepts/consensus-network/consensus-principles-and-rules.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: concepts/consensus-network/consensus-principles-and-rules.ja.md
|
||||
targets:
|
||||
- ja
|
||||
|
||||
- md: concepts/consensus-network/consensus-protections.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: concepts/consensus-network/consensus-protections.ja.md
|
||||
targets:
|
||||
- ja
|
||||
|
||||
- md: concepts/consensus-network/invariant-checking.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: concepts/consensus-network/invariant-checking.ja.md
|
||||
targets:
|
||||
- ja
|
||||
|
||||
- md: concepts/consensus-network/negative-unl.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: concepts/consensus-network/negative-unl.ja.md
|
||||
targets:
|
||||
- ja
|
||||
|
||||
- md: concepts/consensus-network/transaction-queue.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: concepts/consensus-network/transaction-queue.ja.md
|
||||
targets:
|
||||
- ja
|
||||
|
||||
- md: concepts/consensus-network/about-canceling-a-transaction.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: concepts/consensus-network/about-canceling-a-transaction.ja.md
|
||||
targets:
|
||||
- ja
|
||||
|
||||
- md: concepts/consensus-network/transaction-malleability.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: concepts/consensus-network/transaction-malleability.ja.md
|
||||
targets:
|
||||
- ja
|
||||
|
||||
- md: concepts/consensus-network/amendments/amendments.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: concepts/consensus-network/amendments/amendments.ja.md
|
||||
targets:
|
||||
- ja
|
||||
|
||||
- md: concepts/consensus-network/amendments/known-amendments.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: concepts/consensus-network/amendments/known-amendments.ja.md
|
||||
targets:
|
||||
- ja
|
||||
|
||||
- md: concepts/consensus-network/fee-voting.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: concepts/consensus-network/fee-voting.ja.md
|
||||
targets:
|
||||
- ja
|
||||
|
||||
- md: concepts/consensus-network/consensus-research.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: concepts/consensus-network/consensus-research.ja.md
|
||||
targets:
|
||||
- ja
|
||||
|
||||
# TODO: add pseudo-transactions concept page
|
||||
|
||||
- md: concepts/consensus-network/parallel-networks.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: concepts/consensus-network/parallel-networks.ja.md
|
||||
targets:
|
||||
- ja
|
||||
|
||||
- md: concepts/consensus-network/federated-sidechains.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: concepts/consensus-network/federated-sidechains.ja.md
|
||||
targets:
|
||||
- ja
|
||||
|
||||
- md: concepts/xrpl-servers/xrpl-servers.md
|
||||
targets:
|
||||
- en
|
||||
# - name: Consensus Network
|
||||
# html: consensus-network.html
|
||||
# parent: concepts.html
|
||||
# template: pagetype-category.html.jinja
|
||||
# blurb: The XRP Ledger uses a consensus algorithm to resolve the double spend problem and choose which transactions to execute in which order. Consensus also governs rules of transaction processing.
|
||||
# targets:
|
||||
# - en
|
||||
#
|
||||
# - name: コンセンサスネットワーク
|
||||
# html: consensus-network.html
|
||||
# parent: concepts.html
|
||||
# template: pagetype-category.html.jinja
|
||||
# blurb: XRP Ledgerはコンセンサスアルゴリズムを使用して、二重支払いの問題を解決し、どのトランザクションをどのような順番で実行するか選択します。コンセンサスは、トランザクション処理のルールを左右します。
|
||||
# targets:
|
||||
# - ja
|
||||
#
|
||||
# - md: concepts/consensus-network/consensus.md
|
||||
# targets:
|
||||
# - en
|
||||
#
|
||||
# - md: concepts/consensus-network/consensus.ja.md
|
||||
# targets:
|
||||
# - ja
|
||||
#
|
||||
# - md: concepts/consensus-network/consensus-principles-and-rules.md
|
||||
# targets:
|
||||
# - en
|
||||
#
|
||||
# - md: concepts/consensus-network/consensus-principles-and-rules.ja.md
|
||||
# targets:
|
||||
# - ja
|
||||
#
|
||||
# - md: concepts/consensus-network/consensus-protections.md
|
||||
# targets:
|
||||
# - en
|
||||
#
|
||||
# - md: concepts/consensus-network/consensus-protections.ja.md
|
||||
# targets:
|
||||
# - ja
|
||||
#
|
||||
# - md: concepts/consensus-network/invariant-checking.md
|
||||
# targets:
|
||||
# - en
|
||||
#
|
||||
# - md: concepts/consensus-network/invariant-checking.ja.md
|
||||
# targets:
|
||||
# - ja
|
||||
#
|
||||
# - md: concepts/consensus-network/negative-unl.md
|
||||
# targets:
|
||||
# - en
|
||||
#
|
||||
# - md: concepts/consensus-network/negative-unl.ja.md
|
||||
# targets:
|
||||
# - ja
|
||||
#
|
||||
# - md: concepts/consensus-network/transaction-queue.md
|
||||
# targets:
|
||||
# - en
|
||||
#
|
||||
# - md: concepts/consensus-network/transaction-queue.ja.md
|
||||
# targets:
|
||||
# - ja
|
||||
#
|
||||
# - md: concepts/consensus-network/about-canceling-a-transaction.md
|
||||
# targets:
|
||||
# - en
|
||||
#
|
||||
# - md: concepts/consensus-network/about-canceling-a-transaction.ja.md
|
||||
# targets:
|
||||
# - ja
|
||||
#
|
||||
# - md: concepts/consensus-network/transaction-malleability.md
|
||||
# targets:
|
||||
# - en
|
||||
#
|
||||
# - md: concepts/consensus-network/transaction-malleability.ja.md
|
||||
# targets:
|
||||
# - ja
|
||||
#
|
||||
# - md: concepts/consensus-network/amendments/amendments.md
|
||||
# targets:
|
||||
# - en
|
||||
#
|
||||
# - md: concepts/consensus-network/amendments/amendments.ja.md
|
||||
# targets:
|
||||
# - ja
|
||||
#
|
||||
# - md: concepts/consensus-network/amendments/known-amendments.md
|
||||
# targets:
|
||||
# - en
|
||||
#
|
||||
# - md: concepts/consensus-network/amendments/known-amendments.ja.md
|
||||
# targets:
|
||||
# - ja
|
||||
#
|
||||
# - md: concepts/consensus-network/fee-voting.md
|
||||
# targets:
|
||||
# - en
|
||||
#
|
||||
# - md: concepts/consensus-network/fee-voting.ja.md
|
||||
# targets:
|
||||
# - ja
|
||||
#
|
||||
# - md: concepts/consensus-network/consensus-research.md
|
||||
# targets:
|
||||
# - en
|
||||
#
|
||||
# - md: concepts/consensus-network/consensus-research.ja.md
|
||||
# targets:
|
||||
# - ja
|
||||
#
|
||||
# # TODO: add pseudo-transactions concept page
|
||||
#
|
||||
# - md: concepts/consensus-network/parallel-networks.md
|
||||
# targets:
|
||||
# - en
|
||||
#
|
||||
# - md: concepts/consensus-network/parallel-networks.ja.md
|
||||
# targets:
|
||||
# - ja
|
||||
#
|
||||
# - md: concepts/consensus-network/federated-sidechains.md
|
||||
# targets:
|
||||
# - en
|
||||
#
|
||||
# - md: concepts/consensus-network/federated-sidechains.ja.md
|
||||
# targets:
|
||||
# - ja
|
||||
#
|
||||
# - md: concepts/xrpl-servers/xrpl-servers.md
|
||||
# targets:
|
||||
# - en
|
||||
|
||||
- name: rippledサーバー
|
||||
html: xrpl-servers.html
|
||||
@@ -1066,22 +1161,6 @@ pages:
|
||||
- en
|
||||
- ja
|
||||
|
||||
- md: concepts/interoperability/xrpl-interoperability.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: concepts/interoperability/intro-to-evm-sidechain.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- name: Hooks
|
||||
html: https://xrpl-hooks.readme.io/
|
||||
parent: xrpl-interoperability.html
|
||||
blurb: Smart contract proposal for the XRP Ledger.
|
||||
targets:
|
||||
- en
|
||||
|
||||
|
||||
# Redirect old "the-rippled-server.html"
|
||||
- name: The rippled Server
|
||||
html: the-rippled-server.html
|
||||
@@ -1174,7 +1253,7 @@ pages:
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
|
||||
|
||||
- md: tutorials/get-started/get-started.md
|
||||
targets:
|
||||
- en
|
||||
@@ -2093,35 +2172,37 @@ pages:
|
||||
- en
|
||||
- ja
|
||||
|
||||
- name: Interoperability - EVM Sidechain
|
||||
html: evm-sidechains.html
|
||||
parent: tutorials.html
|
||||
blurb: Learn how to interact with the EVM Sidechain Devnet.
|
||||
template: pagetype-category.html.jinja
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
|
||||
- md: tutorials/interoperability/get-started-evm-sidechain.md
|
||||
- name: Amendments
|
||||
longer_name: Amendments
|
||||
template: page-references.html.jinja
|
||||
html: amendments-top.html
|
||||
parent: docs.html
|
||||
top_nav_grouping: Article Types
|
||||
sidebar: disabled
|
||||
blurb: The amendment process and known amendments to XRPL protocols.
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: tutorials/interoperability/connect-metamask-to-xrpl-evm-sidechain.md
|
||||
- md: amendments/amendments.md
|
||||
parent: amendments-top.html
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: tutorials/interoperability/join-evm-sidechain-devnet.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: tutorials/interoperability/evm-sidechain-validator-security.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: tutorials/interoperability/evm-sidechain-run-a-validator-node.md
|
||||
# - md: amendments/amendments.ja.md
|
||||
# parent: amendments-top.html
|
||||
# targets:
|
||||
# - ja
|
||||
|
||||
- md: amendments/known-amendments.md
|
||||
parent: amendments-top.html
|
||||
targets:
|
||||
- en
|
||||
|
||||
# - md: concepts/consensus-network/amendments/known-amendments.ja.md
|
||||
# parent: amendments-top.html
|
||||
# targets:
|
||||
# - ja
|
||||
|
||||
# References -------------------------------------------------------------------
|
||||
|
||||
- name: References
|
||||
@@ -2294,17 +2375,11 @@ pages:
|
||||
- md: references/protocol-reference/ledger-data/ledger-object-types/nftokenoffer.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: references/protocol-reference/ledger-data/ledger-object-types/nftokenoffer.ja.md
|
||||
targets:
|
||||
- ja
|
||||
|
||||
- md: references/protocol-reference/ledger-data/ledger-object-types/nftokenpage.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: references/protocol-reference/ledger-data/ledger-object-types/nftokenpage.ja.md
|
||||
targets:
|
||||
- ja
|
||||
|
||||
- md: references/protocol-reference/ledger-data/ledger-object-types/offer.md
|
||||
@@ -2449,41 +2524,27 @@ pages:
|
||||
- md: references/protocol-reference/transactions/transaction-types/nftokenacceptoffer.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: references/protocol-reference/transactions/transaction-types/nftokenacceptoffer.ja.md
|
||||
targets:
|
||||
- ja
|
||||
|
||||
- md: references/protocol-reference/transactions/transaction-types/nftokenburn.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: references/protocol-reference/transactions/transaction-types/nftokenburn.ja.md
|
||||
targets:
|
||||
- ja
|
||||
|
||||
- md: references/protocol-reference/transactions/transaction-types/nftokencanceloffer.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: references/protocol-reference/transactions/transaction-types/nftokencanceloffer.ja.md
|
||||
targets:
|
||||
- ja
|
||||
|
||||
- md: references/protocol-reference/transactions/transaction-types/nftokencreateoffer.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: references/protocol-reference/transactions/transaction-types/nftokencreateoffer.ja.md
|
||||
targets:
|
||||
- ja
|
||||
|
||||
|
||||
- md: references/protocol-reference/transactions/transaction-types/nftokenmint.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: references/protocol-reference/transactions/transaction-types/nftokenmint.ja.md
|
||||
targets:
|
||||
- ja
|
||||
|
||||
- md: references/protocol-reference/transactions/transaction-types/offercancel.md
|
||||
|
||||
BIN
img/consensus1-proposed-ledgers.png
Normal file
BIN
img/consensus1-proposed-ledgers.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 558 KiB |
BIN
img/consensus2-agreed-transactions.png
Normal file
BIN
img/consensus2-agreed-transactions.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 595 KiB |
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user