diff --git a/content/concepts/decentralized-exchange/autobridging.ja.md b/content/concepts/decentralized-exchange/autobridging.ja.md deleted file mode 100644 index 9a35f5ecda..0000000000 --- a/content/concepts/decentralized-exchange/autobridging.ja.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -html: autobridging.html -parent: decentralized-exchange.html -blurb: オートブリッジングは、コストが下がる場合はXRPを仲介として使用してオーダーブックを自動的に接続します。 -labels: - - XRP - - 分散型取引所 ---- -# オートブリッジング - -XRP Ledgerの[分散型取引所](decentralized-exchange.html)で、XRP以外の2種類の通貨を交換する[オファー](offers.html)があった場合、合成されたオーダーブックで[XRP](xrp.html)が中間通貨として使用されることがあります。これは _オートブリッジング_ によるものです。この機能は、通貨を直接交換するよりも安く済む場合にXRPを使用し、あらゆる通貨ペアの流動性を向上させる役割を担います。XRP Ledgerのネイティブ暗号資産であるというXRPの特性によりこのように機能します。オファーを実行する際は、直接オファーとオートブリッジングオファーを組み合わせることで全体として最良の為替レートを実現できます。 - -例: _AnitaはGBPを売却してBRLを購入するオファーを発行しました。このような一般的ではない通貨マーケットでは、オファーがあまりない場合があります。良いレートのオファーが1件ありますが、Anitaの取引を満たすのに十分な量ではありません。ただしGBPとXRPおよびBRLとXRPの間には、それぞれアクティブで競争力のあるマーケットが存在します。XRP Ledgerのオートブリッジングシステムは、あるトレーダーからXRPをGBPで購入し、そのXRPを別のトレーダーに支払ってBRLを購入することで、Anitaのオファーを履行できる方法を見つけます。AnitaはGBPとBRLを直接交換するマーケットでの少額オファーを、GBP対XRPのオファーとXRP対BRLのオファーをペアリングしてより良い複合レートと組み合わせて、最適なレートを自動的に得ることができます。_ - -オートブリッジングは、あらゆる[OfferCreateトランザクション][]で自動的に行われます。[Paymentトランザクション](payment.html)ではオートブリッジングはデフォルトでは _行われません_ が、path-findingにより同様の効果のある[パス](paths.html)を検索できます。 - -## 関連項目 - -- [Dev Blog: Introducing Autobridging](https://xrpl.org/blog/2014/introducing-offer-autobridging.html) - -- [オファーの優先度](offers.html#オファーの優先度) - -- [ペイメントパス](paths.html) - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/decentralized-exchange/autobridging.md b/content/concepts/decentralized-exchange/autobridging.md deleted file mode 100644 index 519c72f2fa..0000000000 --- a/content/concepts/decentralized-exchange/autobridging.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -html: autobridging.html -parent: decentralized-exchange.html -blurb: Autobriding automatically connects order books using XRP as an intermediary when it reduces costs. -labels: - - XRP - - Decentralized Exchange ---- -# Auto-Bridging - -Any [Offer](offers.html) in the XRP Ledger's [decentralized exchange](decentralized-exchange.html) that would exchange two non-XRP currencies could potentially use [XRP](xrp.html) as an intermediary currency in a synthetic order book. This is because of _auto-bridging_, which serves to improve liquidity across all currency pairs by using XRP when doing so is cheaper than trading those currencies directly. This works because of XRP's nature as a native cryptocurrency to the XRP Ledger. Offer execution can use a combination of direct and auto-bridged offers to achieve the best total exchange rate. - -Example: _Anita places an offer to sell GBP and buy BRL. She might find that this uncommon currency market has few offers. There is one offer with a good rate, but it has insufficient quantity to satisfy Anita's trade. However, both GBP and BRL have active, competitive markets to XRP. The XRP Ledger's auto-bridging system finds a way to complete Anita's offer by purchasing XRP with GBP from one trader, then selling the XRP to another trader to buy BRL. Anita automatically gets the best rate possible by combining the small offer in the direct GBP:BRL market with the better composite rates created by pairing GBP:XRP and XRP:BRL offers._ - -Auto-bridging happens automatically on any [OfferCreate transaction][]. [Payment transactions](payment.html) _do not_ use auto-bridging by default, but path-finding can find [paths](paths.html) that have the same effect. - -## See Also - -- [Dev Blog: Introducing Autobridging](https://xrpl.org/blog/2014/introducing-offer-autobridging.html) - -- [Offer Preference](offers.html#offer-preference) - -- [Payment Paths](paths.html) - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/decentralized-exchange/decentralized-exchange.md b/content/concepts/decentralized-exchange/decentralized-exchange.md deleted file mode 100644 index bf4a460810..0000000000 --- a/content/concepts/decentralized-exchange/decentralized-exchange.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -html: decentralized-exchange.html -parent: concepts.html -template: pagetype-category.html.jinja -blurb: The XRP Ledger contains a fully-functional exchange where users can trade tokens for XRP or each other. -targets: - - en ---- -# Decentralized Exchange - -The XRP Ledger has possibly the world's oldest _decentralized exchange_ (sometimes abbreviated "DEX"), operating continuously since the XRP Ledger's launch in 2012. The exchange allows users to buy and sell [tokens](tokens.html) for XRP or other tokens, with minimal [fees](fees.html) charged to the network itself (not paid out to any party). - -**Caution:** Anyone can [issue a token](issue-a-fungible-token.html) with any currency code or ticker symbol they want and sell it in the decentralized exchange. Always perform due diligence before buying a token, and pay attention to the issuer. Otherwise, you might give up something of value and receive worthless tokens in exchange. - -## Structure - -The XRP Ledger's decentralized exchange consists of an unlimited number of currency pairs, tracked on-demand when users make trades. A currency pair can consist of XRP and a token or two different tokens; tokens are always identified by the combination of an issuer and a currency code. Therefore, it is possible to trade between two tokens with the same currency code and different issuers, or the same issuer and different currency codes. - -As with all changes to the XRP Ledger, you need to send a [transaction](transaction-basics.html) to make a trade. A trade in the XRP Ledger is called an [Offer](offers.html). An Offer is effectively a [_limit order_](https://en.wikipedia.org/wiki/Order_(exchange)#Limit_order) to buy or sell a specific amount of one currency (XRP or a token) for a specific amount of another. When the network executes an Offer, if there are any matching Offers for the same currency pair, they are consumed starting with the best exchange rate first. - -An Offer can be fully or partially filled; if it's not fully filled right away, it becomes a passive Offer object in the ledger for the remaining amount. Later on, other Offers or [Cross-currency payments](cross-currency-payments.html) can match and consume the Offer. Because of this, Offers can execute at better than their requested exchange rate when initially placed, or at exactly their stated exchange rate later on (aside from minor differences to account for rounding). - -Offers can be manually or automatically canceled after being placed. For details on this and other properties of Offers, see [Offers](offers.html). - -When trading two tokens, [auto-bridging](autobridging.html) improves exchange rates and liquidity by automatically trading token-to-XRP and XRP-to-token when doing so is cheaper than trading directly token-to-token. - -### Example Trade - -{{ include_svg("img/decentralized-exchange-example-trade.svg", "Diagram: Partially filled offer to buy a token for XRP.") }} - -The above diagram shows an example trade in the decentralized exchange. In this example, a trader named Tran places an Offer to buy 100 tokens with the currency code FOO issued by a fictional business called WayGate. (For brevity, "FOO.WayGate" refers to these tokens.) Tran specifies that he is willing to spend up to 1000 XRP for the full total. When Tran's transaction is processed, the following things happen: - -1. The network calculates the exchange rate of Tran's Offer, by dividing the amount to buy by the amount to pay. -0. The network finds the order book for the reverse of Tran's Offer: in this case, that means the order book for selling FOO.WayGate and buying XRP. This order book already has several existing Offers from other traders for varying amounts and exchange rates. -0. Tran's Offer "consumes" matching Offers, starting with the best exchange rate and working its way down, until either Tran's Offer has been fully filled, or there are no more Offers whose exchange rate is equal or better than the rate specified in Tran's Offer. In this example, only 22 FOO.WayGate are available at the requested rate or better. The consumed Offers are removed from the order book. -0. Tran receives the amount of FOO.WayGate that the trade was able to acquire, from the various traders who had previous placed orders to sell it. These tokens go to Tran's [trust line](trust-lines-and-issuing.html) to WayGate for FOO. (If Tran did not already have that trust line, one is automatically created.) -0. In return, those traders receive XRP from Tran according to their stated exchange rates. -0. The network calculates the remainder of Tran's Offer: since the original Offer was to buy 100 FOO.WayGate and so far Tran has received 22, the remainder is 78 FOO.WayGate. Using the original exchange rate, that means that the rest of Tran's Offer is now to buy 78 FOO.WayGate for 780 XRP. -0. The resulting "remainder" gets placed onto the order book for trades going the same direction as Tran's: selling XRP and buying FOO.WayGate. - -Later transactions, including ones executed immediately after Tran's in the _same_ ledger, use the updated order books for their trades, so they can consume part or all of Tran's Offer until it's fully filled or Tran cancels it. - -**Note:** The canonical order transactions execute in when a ledger is closed and validated is not the same as the order those transactions were sent. When multiple transactions affect the same order book in the same ledger, the final results of those transactions may be very different than the tentative results calculated at the time of transaction submission. For more details on when transactions' results are or are not final, see [Finality of Results](finality-of-results.html). - - -## Limitations - -The decentralized exchange is designed with the following limitations: - -Because trades are only executed each time a new ledger closes (approximately every 3-5 seconds), the XRP Ledger is not suitable for [high-frequency trading](https://en.wikipedia.org/wiki/High-frequency_trading). The order transactions execute within a ledger is designed to be unpredictable, to discourage [front-running](https://en.wikipedia.org/wiki/Front_running). - -The XRP Ledger does not natively represent concepts such as market orders, stop orders, or trading on leverage. Some of these may be possible with creative use of custom tokens and Offer properties. - -As a decentralized system, the XRP Ledger does not have any information on the actual people and organizations behind the [accounts](accounts.html) involved in trading. Therefore, the ledger itself cannot implement restrictions around who can or cannot participate in trading, and users and issuers must take care to follow any relevant laws to regulate trading tokens that represent various types of underlying assets. Features such as [freezes](freezes.html) and [authorized trust lines](authorized-trust-lines.html) are intended to help issuers comply with relevant laws and regulations. - -## See Also - -- **Concepts:** - - See [Offers](offers.html) for details on how trades work in the XRP Ledger. - - See [Tokens](tokens.html) for an overview of how various types of value can be represented in the XRP Ledger. -- **References:** - - [account_offers method][] to look up Offers placed by an account - - [book_offers method][] to look up Offers to buy or sell a given currency pair - - [OfferCreate transaction][] to place a new Offer or replace an existing Offer - - [OfferCancel transaction][] to cancel an existing Offer - - [Offer object][] for the data structure of passive Offers in the ledger - - [DirectoryNode object][] for the data structure that tracks all the Offers for a given currency pair and exchange rate. - - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/decentralized-exchange/offers.ja.md b/content/concepts/decentralized-exchange/offers.ja.md deleted file mode 100644 index b3de2cedd3..0000000000 --- a/content/concepts/decentralized-exchange/offers.ja.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -html: offers.html -parent: decentralized-exchange.html -blurb: オファーはXRP Ledgerの通貨取引オーダーの形態です。オファーのライフサイクルと特性について説明します。 -labels: - - 分散型取引所 ---- -# オファー - -XRP Ledgerの分散型取引所では、通貨の取引注文は「オファー」と呼ばれます。オファーはXRPと発行済み通貨の取引、または発行済み通貨間の取引（同一通貨コードだがイシュアーが異なる発行済み通貨を含む）を行うことができます。（同一コードでイシュアーが異なる通貨は、[rippling](rippling.html)によって取引することもできます。） - -- オファーを作成するには、[OfferCreateトランザクション][]を送信します。 -- 即時に履行されないオファーはレジャーデータの[Offerオブジェクト](offer.html)になります。その後のオファーとPaymentにより、レジャーのOfferオブジェクトは消費されます。 -- [複数通貨間の支払い](cross-currency-payments.html)はオファーを消費して流動性を提供します。 - - -## オファーのライフサイクル - -OfferCreateトランザクションの処理時に、このトランザクションは一致するオファーまたはクロスオファーを可能な限り自動的に消費します。（既存のオファーのレートが要求よりも良い場合には、オファーの作成者は`TakerGets`の全額よりも低い額を支払い、`TakerPays`を全額を受領できます。）それにより`TakerPays`の額を完全に満たせない場合、オファーはレジャーのOfferオブジェクトになります。（[OfferCreateフラグ](offercreate.html#offercreateフラグ)を使用してこの動作を変更できます。） - -既存のオファーに対応する追加のOfferCreateトランザクション、またはオファーを使用してペイメントパスを接続する[Paymentトランザクション][]のいずれかにより、レジャー上のオファーは履行されます。オファーの部分的な履行と、部分的な資金化が可能です。1つのトランザクションで、レジャーのオファーを最大850件まで消費できます。（この数を超えるとメタデータが大きくなり過ぎて、[`tecOVERSIZE`](tec-codes.html)となります。） - -オファーの`TakerGets`パラメーターで指定された通貨をいくらかでも（ゼロ以外のプラスの額）保有している限り、オファーを作成できます。オファーは、`TakerPays`の額が満たされるまで、`TakerGets`の額を上限として保有している通貨を売却します。オファーによって誰かに負債が発生することはありません。 - -レジャーにすでに記録されているオファーにクロスするオファーを出した場合、関連する額に関係なく古いオファーは自動的に取り消されます。 - -次の場合には、オファーは一時的または永久に _資金化されない_ 可能性があります。 - -* 作成者に`TakerGets`の通貨がない場合。 - * 作成者がその通貨を取得すると、オファーに資金が再び供給されます。 -* オファーに資金を供給するために必要な通貨が[凍結されたトラストライン](freezes.html)で保有されている場合。 - * トラストラインの凍結が解除されると、オファーに資金が再び供給されます。 -* オファーに必要な新しいトラストラインの準備金として十分な額のXRPを作成者が保有していない場合。（[オファーとトラスト](#オファーとトラスト)を参照してください。） - * 作成者がXRPをさらに取得するか、または必要準備金が減額されると、オファーに資金が再び供給されます。 -* オファーに指定されている有効期限が最新の閉鎖済みレジャーの閉鎖時刻よりも前である場合。（[オファーの有効期限](#オファーの有効期限)を参照してください。） - -資金化されないオファーはレジャーに無期限で残ることがありますが、特に影響はありません。次の方法でのみ、オファーはレジャーから*完全に*削除されます。 - -* Paymentトランザクションまたは対応するOfferCreateトランザクションにより全額が請求される。 -* OfferCancelトランザクションまたはOfferCreateトランザクションによりオファーが明示的に取り消される。 -* 同じアカウントからのOfferCreateトランザクションが以前のオファーにクロスする。（この場合、古いオファーが自動的に取り消されます。） -* トランザクションの処理中にオファーへの資金が供給されていないことが判明する。一般的に、オファーがオーダーブックの先中で最も有利なレートであったことが原因です。 - * これには、オファーのいずれかの側が、`rippled`の精度でサポートされているよりも0に近いことが検出されるケースも含まれます。 - -### 資金化されていないオファーの追跡 - -すべてのオファーの資金化状況の追跡は、コンピューターにとって負荷の高い処理となることがあります。特に積極的に取引しているアドレスでは大量のオファーがオープンです。1つの残高が、さまざまな通貨を購入する多数のオファーの資金化の状況に影響することがあります。このため、`rippled`ではオファーの検出と削除を積極的に行なっていません。 - -クライアントアプリケーションでオファーの資金化の状況をローカルで追跡できます。このためには、最初に[book_offersメソッド][]を使用してオーダーブックを取得し、次にオファーの`taker_gets_funded`フィールドを調べます。次に`transactions`ストリームを[サブスクライブ](subscribe.html)し、トランザクションメタデータを監視してどのオファーが変更されるかを確認します。 - - -## オファーとトラスト - -トラストラインの限度額（[TrustSet](trustset.html)を参照）はオファーに影響しません。つまり、オファーを使用して、イシュアーの信用できる最大精算額を上回る額を取得できます。 - -ただし、XRP以外の残高を保有するには、それらの残高を発行するアドレスへのトラストラインが必要です。オファーが受け入れられると、必要なトラストラインが自動的に作成され、その限度額が0に設定されます。[アカウントが保有する必要のある準備金はトラストラインによって増加する](reserves.html)ため、新しいトラストラインを必要とするオファーがある場合、そのトラストラインの準備金として十分なXRPをアドレスに保有する必要があります。 - -トラストラインはあなたが信用するイシュア―を示し、限度額の範囲内でそのイシュア―のイシュアンスを支払いとして受領します。オファーは特定通貨を取得するための明示的な指示であるため、これらの限度額を超えることができます。 - - -## オファーの優先度 - -既存のオファーは為替レート（「オファークオリティ」とも呼ばれます）によってグループにまとめられます。為替レートは、`TakerGets`と`TakerPays`の比率として計算されます。為替レートが高いオファーが優先的に処理されます。（つまり、オファーを受け入れる人は、支払われる通貨額に対して可能な限り多くを受領します。）同じ為替レートのオファーは、最も古いレジャーバージョンで出されたオファーに基づいて受け入れられます。 - -同じ為替レートのオファーが同じレジャーバージョンに記録されている場合、オファーの処理順序は[レジャーへトランザクションを適用する](https://github.com/ripple/rippled/blob/5425a90f160711e46b2c1f1c93d68e5941e4bfb6/src/ripple/app/consensus/LedgerConsensus.cpp#L1435-L1538 "Source: Applying transactions")ための[正規の順序](https://github.com/ripple/rippled/blob/release/src/ripple/app/misc/CanonicalTXSet.cpp "Source: Transaction ordering")によって決定します。この動作は確定的かつ効率的であり、操作することが困難であるように設計されています。 - - -## オファーの有効期限 - -トランザクションの伝搬と確定には時間がかかることがあるため、レジャーのタイムスタンプからオファーの有効性を判断します。オファーが有効期限切れとなるのは、有効期限が最新の検証済みレジャーよりも前の場合だけです。つまり、`Expiration`フィールドが指定されているオファーが「アクティブ」であると見なされるのは、ローカルクロックに関係なく、その有効期限が最新の検証済みレジャーのタイムスタンプよりも後である場合です。 - -閉鎖時刻が有効期限と同じかそれよりも後である完全な検証済みレジャーが作成されたら、`Expiration`が指定されているオファーの最終的な処理を即時に判断できます。 - -**注記:** レジャーを変更できるのは新しいトランザクションだけであることから、有効期限切れのオファーは、非アクティブになった後でもレジャーに残ることがあります。このオファーは資金化されていないと見なされ特に影響はありませんが、（[ledger_entry](ledger_entry.html)コマンドなどの）実行結果に、引き続き表示される可能性があります。後に、サーバーが処理中に有効期限切れのオファーを検出すると、このオファーは別のトランザクション（別のOfferCreateなど）の結果として最終的に削除されることがあります。 - -OfferCreateトランザクションが最初にレジャーに追加された時点で、このトランザクションに指定されている`Expiration`時刻をすでに経過していた場合は、トランザクションはオファーを実行しません。このようなトランザクションの結果コードは、[Checks Amendment][]が有効であるかどうかによって異なります。Checks Amendmentが有効な場合、トランザクションの結果コードは`tecEXPIRED`です。それ以外の場合、トランザクションの結果コードは`tesSUCCESS`です。いずれの場合でも、このトランザクションには、[トランザクションコスト](transaction-cost.html)として支払われたXRPを消却する以外に影響はありません。 - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/decentralized-exchange/offers.md b/content/concepts/decentralized-exchange/offers.md deleted file mode 100644 index 206e05deec..0000000000 --- a/content/concepts/decentralized-exchange/offers.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -html: offers.html -parent: decentralized-exchange.html -blurb: Offers are the XRP Ledger's form of currency trading orders. Understand their lifecycle and properties. -labels: - - Decentralized Exchange ---- -# Offers - -In the XRP Ledger's [decentralized exchange](decentralized-exchange.html), trade orders are called "Offers". Offers can trade XRP with [tokens](tokens.html), or tokens for other tokens, including tokens with the same currency code but different issuers. (Tokens with the same code but different issuers can also sometimes be exchanged through [rippling](rippling.html).) - -- To create an Offer, send an [OfferCreate transaction][]. -- Offers that aren't fully filled immediately become [Offer objects](offer.html) in the ledger data. Later Offers and Payments can consume the Offer object from the ledger. -- [Cross-currency payments](cross-currency-payments.html) consume Offers to provide liquidity. However, they never create Offer objects in the ledger. - -## Lifecycle of an Offer - -An [OfferCreate transaction][] is an instruction to conduct a trade, either between two tokens, or a token and XRP. Every such transaction contains a buy amount (`TakerPays`) and a sell amount (`TakerGets`). When the transaction is processed, it automatically consumes matching or crossing Offers to the extent possible. If that does not completely fill the new Offer, then the remainder becomes an Offer object in the ledger. - -The Offer object waits in the ledger until other Offers or cross-currency payments fully consume it. The account that placed the Offer is called the Offer's _owner_. You can cancel your own Offers at any time, using the dedicated [OfferCancel transaction][], or as an option of the [OfferCreate transaction][]. - -While you have an Offer in the ledger, it sets aside some of your XRP toward the [owner reserve](reserves.html). When the Offer gets removed, for any reason, that XRP is freed up again. - -### Variations - -- **Buy vs. Sell:** By default, Offers are "buy" Offers and are considered fully filled when you have acquired the entire "buy" (`TakerPays`) amount. (You may spend less than you expected while receiving the specified amount.) By contrast, a "Sell" Offer is only considered fully filled when you have spent the entire "sell" (`TakerGets`) amount. (You may receive more than you expected while spending the specified amount.) This is only relevant if the Offer _initially_ executes at better than its requested exchange rate: after the Offer gets placed into the ledger, it only ever executes at _exactly_ the requested exchange rate. -- An **Immediate or Cancel** Offer is not placed into the ledger, so it only trades up to the amount that matches existing, matching Offers at the time the transaction is processed. -- A **Fill or Kill** Offer is not placed into the ledger, _and_ it is canceled if the full amount is not filled when it initially executes. This is similar to "Immediate or Cancel" except it _cannot_ be partially filled. -- A **Passive** Offer does not consume matching Offers that have the exact same exchange rate (going the other direction), and instead is placed directly into the ledger. You can use this to create an exact peg between two assets. Passive Offers still consume other Offers that have a _better_ exchange rate going the other way. - - -### Funding Requirements - -When you try to place an Offer, the transaction is rejected as "unfunded" if you don't have at least some of the asset that the trade would sell. More specifically: - -**To sell a token,** you must either: - -- Hold any positive amount of that token, _or_ -- Be the token's issuer. - -However, you don't need to hold the full amount specified in the Offer. Placing an Offer does not lock up your funds, so you can place multiple Offers to sell the same tokens (or XRP), or place an Offer and hope to get enough tokens or XRP to fully fund it later. - -**To sell XRP,** you must hold enough XRP to meet all the [reserve requirements](reserves.html), including the reserve for the Offer object to be placed in the ledger and for the trust line to hold the token you are buying. As long as you have any XRP left over after setting aside the reserve amount, you can place the Offer. - -When another Offer matches yours, both Offers execute to the extent that their owners' funds permit at the the time. If there are matching Offers and you run out of funds before yours is fully filled, the remainder of your Offer is canceled. An Offer can't make your balance of a token negative, unless you are the issuer of that token. (If you are the issuer, you can use Offers to issue new tokens up to the total amount specified in your Offers; tokens you issue are represented as negative balances from your perspective.) - -If you place an Offer that crosses any of your own Offers that exist in the ledger, the old, crossed Offers are automatically canceled regardless of the amounts involved. - -It is possible for an Offer to become temporarily or permanently _unfunded_ in the following cases: - -- If the owner no longer has any of the sell asset. - - The Offer becomes funded again when the owner obtains more of that asset. -- If the sell asset is a token in a [frozen trust line](freezes.html). - - The Offer becomes funded again when the trust line is no longer frozen. -- If the Offer needs to create a new trust line, but the owner does not have enough XRP for the increased [reserve](reserves.html). (See [Offers and Trust](#offers-and-trust).) - - The offer becomes funded again when the owner obtains more XRP, or the reserve requirements decrease. -- If the Offer is expired. (See [Offer Expiration](#offer-expiration).) - -An unfunded Offer stays on the ledger until a transaction removes it. Ways that an Offer can be removed from the ledger include: - -- A matching Offer or [Cross-currency payment](cross-currency-payments.html) fully consumes the Offer. -- The owner explicitly cancels the Offer. -- The owner implicitly cancels the Offer by sending a new Offer that crosses it. -- The Offer is found to be unfunded or expired during transaction processing. Typically this means that another Offer tried to consume it and could not. - - This includes cases where the remaining amount that can be paid out by the Offer rounds down to zero. - -### Tracking Unfunded Offers - -Tracking the funding status of all Offers can be computationally taxing. In particular, addresses that are actively trading may have a large number of Offers open. A single balance can affect the funding status of many Offers. Because of this, the XRP Ledger does not _proactively_ find and remove unfunded or expired Offers. - -A client application can locally track the funding status of Offers. To do this, first retrieve an order book using the [book_offers method][] and check the `taker_gets_funded` field of Offers. Then, [subscribe](subscribe.html) to the `transactions` stream and watch the transaction metadata to see which Offers are modified. - - -## Offers and Trust - -The limit values of [trust lines](trust-lines-and-issuing.html) do not affect Offers. In other words, you can use an Offer to acquire more than the maximum amount you trust an issuer for. - -However, holding tokens still requires a trust line to the issuer. When an Offer is consumed, it automatically creates any necessary trust lines, setting their limits to 0. Because [trust lines increase the reserve an account must hold](reserves.html), any Offers that would require a new trust line also require the address to have enough XRP to meet the reserve for that trust line. - -Trust line limits protect you from receiving more of a token as payment than you want. Offers can go beyond those limits because they are an explicit statement of how much of the token you want. - - -## Offer Preference - -Existing Offers are grouped by exchange rate, which is measured as the ratio between `TakerGets` and `TakerPays`. Offers with a higher exchange rate are taken preferentially. (That is, the person accepting the offer receives as much as possible for the amount of currency they pay out.) Offers with the same exchange rate are taken on the basis of which offer was placed first. - -When Offers execute in the same ledger block, the order in which they execute is determined by the [canonical order](https://github.com/ripple/rippled/blob/release/src/ripple/app/misc/CanonicalTXSet.cpp "Source code: Transaction ordering") in which the transactions were [applied to the ledger](https://github.com/ripple/rippled/blob/5425a90f160711e46b2c1f1c93d68e5941e4bfb6/src/ripple/app/consensus/LedgerConsensus.cpp#L1435-L1538 "Source code: Applying transactions"). This behavior is designed to be deterministic, efficient, and hard to game. - - -## Offer Expiration - -When you place an Offer, you can optionally add an expiration time to it. By default, Offers don't expire. You can't create a new Offer that is already expired. - -Expiration times are specified down to the second, but the exact, real-world time when an Offer expires is less precise. An Offer is expired if it has an expiration time that is _earlier than or equal to_ the close time of the previous ledger. Otherwise, the Offer can still execute, even if the real-world time is later than the Offer's expiration. In other words, an Offer is still "active" if its expiration time is later than the close time of the latest validated ledger, regardless of what your clock says. - -This is a consequence of how the network reaches agreement. For the entire peer-to-peer network to reach a consensus, all servers must agree which Offers are expired when executing transactions. Individual servers may have slight differences in their internal clock settings, so they might not reach the same conclusions about which Offers were expired if they each used the "current" time. The close time of a ledger is not known until after the transactions in that ledger have been executed, so servers use the official close time of the _previous_ ledger instead. The [close times of ledgers are rounded](ledgers.html#ledger-close-times), which further increases the potential difference between real-world time and the time used to determine if an Offer is expired. - -**Note:** Expired Offers remain in the ledger data until a transaction removes them. Until then, they can continue to appear in data retrieved from the API (for example, using the [ledger_entry method][]). Transactions automatically delete any expired and unfunded Offers they find, usually while executing Offers or cross-currency payments that would have matched or canceled them. The owner reserve associated with an Offer is only made available again when the Offer is actually deleted. - - -## See Also - -- **Concepts:** - - [Tokens](tokens.html) - - [Paths](paths.html) -- **References:** - - [account_offers method][] - - [book_offers method][] - - [OfferCreate transaction][] - - [OfferCancel transaction][] - - [Offer object](offer.html) - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/decentralized-exchange/ticksize.ja.md b/content/concepts/decentralized-exchange/ticksize.ja.md deleted file mode 100644 index 59009f1a97..0000000000 --- a/content/concepts/decentralized-exchange/ticksize.ja.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -html: ticksize.html -parent: decentralized-exchange.html -blurb: 発行者は、為替レートのごくわずかな差を超えて、頻繁な取引を抑制するためにオーダーブックで通貨のカスタムチックサイズを設定することができます。 -labels: - - 分散型取引所 - - トークン ---- -# ティックサイズ - -_（[TickSize Amendment][]が必要です。）_ - -オファーがオーダーブックに対して発行されると、そのオファーに関係する通貨のイシュアーによって設定された`TickSize`の値に基づいて、為替レートが切り捨てられます。トレーダーがXRPと発行済み通貨を交換するオファーを出した場合は、その発行済み通貨のイシュアーからの`TickSize`が適用されます。トレーダーが2種類の発行済み通貨を交換するオファーを出した場合は、小さい方の`TickSize`の値（有効数字の桁数が少ない値）がこのオファーに適用されます。いずれの通貨にも`TickSize`が設定されていない場合、デフォルトが適用されます。 - -オーダーブックにオファーが発行されると、`TickSize` によりオファーの為替レートの _有効数字_ の桁数が切り捨てられます。イシュアーは[AccountSetトランザクション][]を使用して`TickSize`を`3`～`15`の整数に設定できます。為替レートは有効数字と指数で表されますが、`TickSize`は指数には影響しません。これにより、XRP Ledgerでは価値が大きく異なる資産（ハイパーインフレ通貨と希少通貨など）間の為替レートを表せます。イシュアーが設定する`TickSize`が小さいほど、トレーダーはより多くの増分をオファーして、既存のオファーよりも高い為替レートと見えるようにする必要があります。 - -`TickSize`は、オファーの即時に実行可能な部分には影響しません。（この理由から、`tfImmediateOrCancel`が指定されたOfferCreateトランザクションは`TickSize` の値の影響を受けません。）オファーを完全に実行できない場合、トランザクション処理エンジンは`TickSize`に基づいて為替レートを計算して切り捨てを行います。次にエンジンは、切り捨てた後の為替レートに一致するように、「重要性が低い」側からのオファーの残額を丸めます。デフォルトのOfferCreateトランザクション（「買い」オファー）の場合、`TakerPays`の額（購入額）が丸められます。`tfSell`フラグが有効な場合（「売り」オファー）`TakerGets`の額（売却額）が丸められます。 - -イシュアーが`TickSize`を有効化、無効化、または変更する場合、以前の設定で発行されたオファーはその影響を受けません。 - -## 参照項目 - -- [Dev Blog: Introducing the TickSize Amendment](https://ripple.com/dev-blog/ticksize-amendment-open-voting/#ticksize-amendment-overview) - -- [AccountSetトランザクション][] - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/decentralized-exchange/ticksize.md b/content/concepts/decentralized-exchange/ticksize.md deleted file mode 100644 index 37dc4f3a9d..0000000000 --- a/content/concepts/decentralized-exchange/ticksize.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -html: ticksize.html -parent: decentralized-exchange.html -blurb: Issuers can set custom tick sizes for currencies to reduce churn in order books over miniscule differences in exchange rates. -labels: - - Decentralized Exchange - - Tokens ---- -# Tick Size - -_(Added by the [TickSize amendment][].)_ - -When an Offer is placed into an order book, its exchange rate is truncated based on the `TickSize` values set by the issuers of the currencies involved in the Offer. When trading XRP and a token, the `TickSize` from the token's issuer applies. When trading two tokens, the Offer uses the smaller `TickSize` value (that is, the one with fewer significant digits). If neither token has a `TickSize` set, the default behavior applies. - -The `TickSize` value truncates the number of _significant digits_ in the exchange rate of an offer when it gets placed in an order book. Issuers can set `TickSize` to an integer from `3` to `15` using an [AccountSet transaction][]. The exchange rate is represented as significant digits and an exponent; the `TickSize` does not affect the exponent. This allows the XRP Ledger to represent exchange rates between assets that vary greatly in value (for example, a highly inflated currency compared to a rare commodity). The lower the `TickSize` an issuer sets, the larger the increment traders must offer to be considered a higher exchange rate than the existing Offers. - -The `TickSize` does not affect the part of an Offer that can be executed immediately. (For that reason, OfferCreate transactions with `tfImmediateOrCancel` are unaffected by `TickSize` values.) If the Offer cannot be fully executed, the transaction processing engine calculates the exchange rate and truncates it based on `TickSize`. Then, the engine rounds the remaining amount of the Offer from the "less important" side to match the truncated exchange rate. For a default OfferCreate transaction (a "buy" Offer), the `TakerPays` amount (the amount being bought) gets rounded. If the `tfSell` flag is enabled (a "sell" Offer) the `TakerGets` amount (the amount being sold) gets rounded. - -When an issuer enables, disables, or changes the `TickSize`, Offers that were placed under the previous setting are unaffected. - -## See Also - -- [Dev Blog: Introducing the TickSize Amendment](https://xrpl.org/blog/2017/ticksize-voting.html#ticksize-amendment-overview) -- **References:** - - [AccountSet transaction][] - - [book_offers method][] - - [OfferCreate transaction][] - - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/interoperability/intro-to-evm-sidechain.md b/content/concepts/interoperability/intro-to-evm-sidechain.md deleted file mode 100644 index f524937667..0000000000 --- a/content/concepts/interoperability/intro-to-evm-sidechain.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -html: intro-to-evm-sidechain.html -parent: xrpl-interoperability.html -blurb: Introduction to the EVM compatible XRP Ledger Sidechain -labels: - - Interoperability -status: not_enabled ---- -# Introduction to EVM Compatible XRP Ledger Sidechain - -The Etherium Virtual Machine (EVM) compatible XRP Ledger sidechain is a secure and fast public blockchain that brings all kinds of web3 applications to the XRP Ledger community. - -- Explorer: [https://evm-sidechain.xrpl.org](https://evm-sidechain.xrpl.org/) -- Public RPC: [https://rpc.evm-sidechain.xrpl.org](https://evm-sidechain.xrpl.org/) - - -The EVM Sidechain is a powerful latest generation blockchain with the following features: - -- Supports up to 1000 transactions per second, thus handling large loads and throughput. -- Has a low transaction confirmation time, on average, as a block is produced every 5 seconds. -- Once a block is added to the chain and confirmed, it is considered final (1 block finalization time). -- Provides full Ethereum Virtual Machine (EVM) compatibility, enabling you to connect your wallet and interact or deploy smart contracts written in Solidity. - -## Consensus - -The EVM Sidechain runs on a proof-of-stake (PoS) consensus algorithm. Staking is when you pledge your coins to be used for verifying transactions. The proof-of-stake model allows you to stake cryptocurrency (also referred to as "coins") and create your own validator nodes. Your coins are locked up while you stake them, but you can unstake them if you want to trade your coins. - -In a proof-of-stake blockchain, mining power depends on the amount of coins a validator is staking. Participants who stake more coins are more likely to be chosen to add new blocks. - -If you are interested in staking cryptocurrency and running your own validator, see [Join EVM Sidechain Devnet](join-evm-sidechain-devnet.html) for more information. - -The underlying technology for the XRP Ledger EVM Sidechain consensus is [Tendermint](https://tendermint.com/), a Byzantine-Fault Tolerant engine for building blockchains. - -The blockchain uses the `cosmos-sdk` library on top of Tendermint to create and customize the blockchain using its built-in modules. The EVM sidechain uses the [Ethermint](https://github.com/evmos/ethermint) `cosmos-sdk` module, which provides EVM compatibility - -## Interoperability Using the EVM Sidechain - -The EVM sidechain is directly connected to XRP Ledger through the XRP Ledger bridge ([https://bridge.devnet.xrpl.](https://bridge.devnet.xrpl.org/). Through this bridge component, you can move your XRP to the EVM Sidechain and use its features. - -## See Also - -[Get Started with EVM Sidechain](get-started-evm-sidechain.html) \ No newline at end of file diff --git a/content/concepts/interoperability/xrpl-interoperability.md b/content/concepts/interoperability/xrpl-interoperability.md deleted file mode 100644 index 9dd397f3ea..0000000000 --- a/content/concepts/interoperability/xrpl-interoperability.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -html: xrpl-interoperability.html -parent: concepts.html -blurb: Learn about capabilities that bring programmability and ability to interact with other chains to the XRP Ledger. -template: pagetype-category.html.jinja -labels: - - Interoperability -status: not_enabled ---- -# Interoperability - -The XRP Ledger is known for its transaction throughput, speed, and low fees. With the addition of programmabilty and interoperability, developers can access features such as smart contracts and can build apps with cross-chain interoperability. - diff --git a/content/concepts/introduction/intro-to-consensus.ja.md b/content/concepts/introduction/intro-to-consensus.ja.md deleted file mode 100644 index ab7545a9f4..0000000000 --- a/content/concepts/introduction/intro-to-consensus.ja.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -html: intro-to-consensus.html -parent: introduction.html -blurb: XRP Ledgerのコンセンサスメカニズムについて基本的な理解を深めましょう。 -labels: - - ブロックチェーン -top_nav_grouping: 人気ページ ---- -# コンセンサスについて - - _コンセンサス_ は、分散型決済システムの最も重要な特性です。従来の中央集権型決済システムでは、権限のある1人の管理者が決済の方法とタイミングについて最終的な決定権を持ちます。分散型システムでは、その名が示すとおり、そのような管理者は存在しません。その代わりに、XRP Ledgerのような分散型システムでは、参加者は定められた一連のルールに従うことになっているため、同じ一連のイベントとその結果についていつでも合意することができます。この一連のルールは、 _コンセンサスプロトコル_ と呼ばれます。 - - -## コンセンサスプロトコルの特性 - -従来のデジタル資産と異なり、XRP Ledgerでは、コンセンサスプロトコルを使用します。このプロトコルは、XRP Ledger コンセンサスプロトコルと呼ばれ、次の重要な特性を持つように設計されています。 - -- XRP Ledgerを使用するユーザーは誰でも、最新の台帳や、どのような取引がどのような順番で発生したかについて同意することができます。 -- 中央のオペレーター無しに、有効な取引を処理することができます。また、障害が1か所に集中することもありません。 -- 一部の参加者が不適切に参加、退去、または行動した場合でも、取引の処理は続行します。 -- 多数の参加者がアクセスできない場合や、多数が不適切に行動している場合は、無効な取引を分離したり確認したりする代わりに、ネットワークは処理を停止します。 -- 取引の確認のために、リソースを無駄に使ったり取り合う必要もありません。この点は、他の一般的なブロックチェーンシステムとは異なります。 - -これらの特性は、次の3原則としてまとめられます。優先順位の高い順に示します。**正確さ、合意、処理の継続** - -このプロトコルはまだ発展段階にあり、その限界と起こり得る障害についての知識もまだ蓄積中です。プロトコル自体に関する学術研究については、[コンセンサスリサーチ](consensus-research.html)を参照してください。 - -## 背景 - -コンセンサスプロトコルは、_二重支払いの問題_、つまり同じデジタルマネーを2回使用することを防ぐという課題に対する解決策です。この問題において最も困難なのは、取引を順序立てる点です。中央管理者がいない中で、同時に複数の相互排他的取引が送信されたときに、先に到着したのはどの取引なのかという紛争を解決するのは困難です。二重支払いの問題や、XRP Ledger コンセンサスプロトコルでこの問題を解決する方法、およびそれに伴うトレードオフと制限事項の詳細な分析については、[コンセンサスの原理とルール](consensus-principles-and-rules.html)を参照してください。 - - -## レジャー（台帳）履歴 - -XRP Ledgerは、「レジャーバージョン」、または略して「レジャー」と呼ばれるブロックで取引を処理します。レジャーの各バージョンには、次の3つの部分が含まれています。 - -- レジャーに保存されているすべての残高とオブジェクトの現在の状態。 -- このレジャーにつながる、以前のレジャーに適用された一連の取引。 -- レジャーインデックスや、その内容を一意に識別する[暗号化ハッシュ](https://en.wikipedia.org/wiki/Cryptographic_hash_function)、およびこのレジャーを構築するための基盤として使用された親レジャーに関する情報など、現行のレジャーバージョンに関するメタデータ。 - -[![図1: レジャーバージョンの構造（取引、状態、およびメタデータを含む）](img/anatomy-of-a-ledger-simplified.ja.png)](img/anatomy-of-a-ledger-simplified.ja.png) - - -レジャーの各バージョンには _レジャーインデックス_ としての番号が付けられており、インデックスが1つ前のレジャーバージョンを基に新たな情報を追加する形で作成されています。一番最初まで遡ると、レジャーインデックスが1の _ジェネシスレジャー_ と呼ばれる出発点に戻ります。[¹](#footnote-1)これにより、Bitcoinや他のブロックチェーン技術と同様に、すべての取引とその結果についての公開履歴が形成されます。多くのブロックチェーン技術とは異なり、XRP Ledgerの新しい「ブロック」には現在の状態がすべて含まれているため、現在起こっている内容を把握するために履歴全体を収集する必要はありません。[²](#footnote-2) - -XRP Ledger コンセンサスプロトコルの主な役割は、前のレジャーに適用する一連の新しい取引に合意し、それらを明確に定義された順序で適用した上で、全員が同じ結果を得たことを確認することです。これが正常に行われると、レジャーバージョンは _検証済み_ 、および確定したとみなされます。続いて、次のレジャーバージョンが構築されます。 - - -## 信頼に基づく検証 - -XRP Ledgerのコンセンサスメカニズムは、小さな信頼が大きな効果を生み出すという基本的な原理に支えられています。ネットワークの各参加者は、一連の _バリデータ_ （検証者）を選択します。バリデータは常に誠実に行動することが期待されるさまざまな当事者によって運営されており、[コンセンサスにアクティブに参加するように特別に設定されたサーバー](run-rippled-as-a-validator.html)上に存在します。さらに重要なことは、選択された一連のバリデータが互いに共謀して同じ方法を使ってルールを破ることはないということです。この一連バリデータのリストは、_ユニークノードリスト_（UNL）とも呼ばれます。 - -ネットワークが更新する中で、各サーバーは信頼できるバリデータ[³](#footnote-3)をモニターします。十分な数のバリデータが、一連の取引の発生を確認し、特定のレジャーにその結果が反映されたことに同意した場合、サーバーによってコンセンサスが宣言されます。バリデータ間で同意が得られない場合、バリデータは信頼する他のバリデータとの間での意見の一致に向けて提案を修正します。このプロセスは、コンセンサスに達するまで何度か繰り返されます。 - -[![図2: コンセンサスラウンドバリデータは信頼する他のバリデータとの間での意見の一致に向けて提案を修正します。](img/consensus-rounds.ja.png)](img/consensus-rounds.ja.png) - -常に正しく行動しないバリデータが一部存在しても問題ありません。信頼できるバリデータのうち、正しく行動しないバリデータの割合が20%未満である場合は、制限なくコンセンサスは継続します。また、無効な取引を確認するには、信頼できるバリデータの80%以上が合意する必要があります。信頼できるバリデータのうち、正しく行動しないバリデータの割合が20%以上80%未満である場合、ネットワークは停止します。 - -XRP Ledger コンセンサスプロトコルで、さまざまな課題や攻撃、失敗の事例にどのように対応するかについての詳細な説明については、[攻撃と失敗モードに対するコンセンサスの保護](consensus-protections.html)を参照してください。 - - -## 関連項目 - -- XRP Ledger コンセンサスプロトコルの仕組みの詳細に関する記事は、[コンセンサスネットワークの概念](consensus-network.html)を参照してください。 -- 独自のバリデータを実行する手順については、[バリデータとしての`rippled`の実行](run-rippled-as-a-validator.html)を参照してください。 -- XRP Ledgerの分散化に関するRippleの目標および計画については、[分散化戦略についてのアップデート (Ripple Dev Blog)](https://ripple.com/dev-blog/decentralization-strategy-update/)を参照してください。 - - - ----- - -## 脚注 - -1. XRP Ledgerの運用開始当初に起きた事故により、[1～32569番目までのレジャーが失われました](http://web.archive.org/web/20171211225452/https://forum.ripple.com/viewtopic.php?f=2&t=3613)。（この損失はレジャー履歴の第1週目に発生しています。）このため、現存する一番最初のレジャーは番号32570のレジャーです。XRP Ledgerの状態はすべてのレジャーバージョンに記録されるため、履歴がなくても継続することができます。新しいテストネットワークでは、レジャーインデックス1から始まります。 - -2. Bitcoinでは、現在の状態は「UTXO」（Unspent Transaction Outputの略）と呼ばれることもあります。XRP Ledgerとは異なり、BitcoinサーバーではすべてのUTXOを把握し、新しい取引を処理できるように、トランザクション（取引）履歴全体をダウンロードする必要があります。2018年現在、Bitcoinの新しいサーバーでこれを行う必要がないように、最新のUTXOのサマリーを定期的に提供するようコンセンサスメカニズムを修正する提案がいくつかあります。EthereumはXRP Ledgerと類似したアプローチを使用しており、各ブロックには、 _状態ルート_ と呼ばれる現在の状態のサマリーがありますが、Ethereumは巨大な状態データを蓄積しているため同期するにはXRP Ledgerよりもより多くの時間を要します。 - -3. 信頼できるバリデータをモニターするにあたり、サーバーが直接それに接続する必要はありません。XRP Ledgerのピアツーピアネットワークでは、サーバーが公開鍵によって互いを識別し、他のサーバーからのデジタル署名付きメッセージを中継する _ゴシッププロトコル_ によってモニターします。 diff --git a/content/concepts/introduction/intro-to-consensus.md b/content/concepts/introduction/intro-to-consensus.md deleted file mode 100644 index 278162fec2..0000000000 --- a/content/concepts/introduction/intro-to-consensus.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -html: intro-to-consensus.html -parent: introduction.html -blurb: Develop a basic understanding of the XRP Ledger's consensus mechanism. -labels: - - Blockchain -top_nav_grouping: Popular Pages ---- -# Introduction to Consensus - -_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, don't have an administrator to do that. Instead, decentralized systems like the XRP Ledger define a set of rules all participants follow, so every participant can agree on the exact same series of events and their outcome at any point in time. We call this set of rules a _consensus protocol_. - - -## Consensus Protocol Properties - -The XRP Ledger uses a consensus protocol unlike any digital asset that came before it. This protocol, known as the XRP Ledger Consensus Protocol, is designed to have the following important properties: - -- Everyone who uses the XRP Ledger can agree on the latest state, and which transactions have 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**. - -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). - -## Background - -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. For a detailed analysis of the double-spend problem, how the XRP Ledger Consensus Protocol solves this problem, and the tradeoffs and limitations involved, see [Consensus Principles and Rules](consensus-principles-and-rules.html). - - -## Ledger History - -The XRP Ledger processes transactions in blocks called "ledger versions", or "ledgers" for short. Each ledger version contains three pieces: - -- The current state of all balances and objects stored in the ledger. -- The set of transactions that have been applied to the previous ledger to result in this one. -- Metadata about the current ledger version, such as its ledger index, a [cryptographic hash](https://en.wikipedia.org/wiki/Cryptographic_hash_function) that uniquely identifies its contents, and information about the parent ledger that was used as a basis for building this one. - -{{ include_svg("img/anatomy-of-a-ledger-simplified.svg", "Figure 1: Anatomy of a ledger version, which includes transactions, state, and metadata") }} - -Each ledger version is numbered with a _ledger index_ and builds on a previous ledger version whose index is one less, going all the way back to a starting point called the _genesis ledger_ with ledger index 1.[¹](#footnote-1) Like Bitcoin and other blockchain technologies, this forms a public history of all transactions and their results. Unlike many blockchain technologies, each new "block" in the XRP Ledger contains the entirety of the current state, so you don't need to collect the entire history to know what's happening now.[²](#footnote-2) - -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 everyone got 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. - - -## Trust-Based Validation - -The core principle behind the XRP Ledger's consensus mechanism is that a little trust goes a long way. Each participant in the network chooses a set of _validators_, servers [specifically configured to participate actively in consensus](run-rippled-as-a-validator.html), run by different parties who are expected to behave honestly most of the time. More importantly, the set of chosen validators should not be likely to collude with one another to break the rules in the exact same way. This list is sometimes called a _Unique Node List_, or UNL. - -As the network progresses, each server listens to its trusted validators[³](#footnote-3); as long as a large enough percentage of them agree that a set of transactions should occur and that a given ledger is the result, the server declares a consensus. If they don't agree, validators modify their proposals to more closely match the other validators they trust, repeating the process in several rounds until they reach a consensus. - -{{ include_svg("img/consensus-rounds.svg", "Figure 2: Consensus rounds. Validators revise their proposals to match other validators they trust") }} - -It's OK if a small proportion of validators don't work properly all the time. As long as fewer than 20% of trusted validators are faulty, consensus can continue unimpeded; and 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 a longer exploration of how the XRP Ledger Consensus Protocol responds to various challenges, attacks, and failure cases, see [Consensus Protections Against Attacks and Failure Modes](consensus-protections.html). - - -## See Also - -- [Consensus Network Concepts](consensus-network.html) for several articles describing the mechanics of the XRP Ledger Consensus Protocol in greater depth. -- [Run `rippled` as a Validator](run-rippled-as-a-validator.html) for instructions on running your own validator. -- [Decentralization Strategy Update (Ripple Dev Blog)](https://xrpl.org/blog/2017/decent-strategy-update.html) for a description of Ripple's goals and plans for decentralizing the XRP Ledger. - - - ----- - -## Footnotes - -1. Due to a mishap early in the XRP Ledger's history, [ledgers 1 through 32569 were lost](http://web.archive.org/web/20171211225452/https://forum.ripple.com/viewtopic.php?f=2&t=3613). (This loss represents approximately the first week of ledger history.) Thus, ledger #32570 is the earliest ledger available anywhere. Because the XRP Ledger's state is recorded in every ledger version, the ledger can continue without the missing history. New test networks still start with ledger index 1. - -2. In Bitcoin, the current state is sometimes called the set of "UTXOs" (unspent transaction outputs). Unlike the XRP Ledger, a Bitcoin server must download the entire transaction history to know the full set of UTXOs and process new transactions. As of 2018, there have been some proposals to modify Bitcoin's consensus mechanism to periodically summarize the latest UTXOs so new servers would not need to do this. Ethereum uses a similar approach to the XRP Ledger, with a summary of the current state (called a _state root_) in each block, but syncing takes longer because Ethereum stores a large amount of state data. - -3. A server does not need a direct connection to its trusted validators to hear from them. The XRP Ledger peer-to-peer network uses a _gossip protocol_ where servers identify each other by public keys and relay digitally-signed messages from others. diff --git a/content/concepts/introduction/software-ecosystem.ja.md b/content/concepts/introduction/software-ecosystem.ja.md deleted file mode 100644 index 978a74cbc7..0000000000 --- a/content/concepts/introduction/software-ecosystem.ja.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -html: software-ecosystem.html -parent: introduction.html -blurb: XRP Ledgerソフトウェアで注目されている特性と、それらがどう組み合わさっているのか大まかに紹介します。 ---- -# ソフトウェアエコシステム - -XRP Ledgerは、「価値のインターネット」を推進および実現可能にするソフトウェアプロジェクトの、深く階層化されたエコシステムの土台となるものです。XRP Ledgerとやり取りするプロジェクト、ツール、ビジネスをすべて挙げることはできないため、このページでは、一部のカテゴリーのみを取り上げ、[xrpl.org](https://xrpl.org)で説明されている主要プロジェクトを重点的にご紹介します。 - -## スタックレベル - -[![4層からなるエコシステムの図: 最下層にはXRP Ledgerのピアツーピアネットワーク、その上にプログラミングライブラリー、次にミドルウェア、そして最上層にアプリとサービスがあります。](img/ecosystem.ja.png)](img/ecosystem.ja.png) - -- [XRP Ledgerの基盤](#rippled-コアサーバー)は、トランザクションを共有し、[コンセンサスプロセス](consensus.html)に関与し、[トランザクション](transaction-basics.html)を処理する常時接続のサーバーのピアツーピアネットワークです。XRP Ledgerエコシステム内の他のすべてのものが、最終的にこのピアツーピアネットワーク上に直接、または間接的に構築されます。 - -- [_プログラミングライブラリー_](#プログラミングライブラリー)は、さらに上位のソフトウェアに存在し、プログラムコードに直接インポートされます。また、XRP Ledgerにアクセスするためのルーチンの実装があらかじめ作成され、組み込まれています。 - -- [_ミドルウェア_](#ミドルウェア)は、XRP Ledgerデータへの間接アクセスを可能にします。多くの場合、この層のアプリケーションには、独自のデータストレージと処理が存在します。 - -- [_アプリとサービス_](#アプリとサービス)は、XRP Ledgerでのユーザーレベルのやり取りや、さらに上位のアプリやサービスに対する基盤を提供します。 - - -### rippled: コアサーバー - -XRP Ledgerの中心であるピアツーピアネットワークは、コンセンサスとトランザクションプロセスのルールを実行するために、信頼性が高く、効率のよいサーバーを必要とします。Rippleでは、このサーバーソフトウェアのリファレンス実装である[**`rippled`**](xrpl-servers.html)（発音は「リップルディー」）を管理および公開しています。このサーバーは、[一般利用が可能なオープンソースライセンス](https://github.com/ripple/rippled/blob/develop/LICENSE.md)の下で使用できるため、誰でもこのサーバーの自身のインスタンスを検証し、変更することができます。また、いくつかの制限の下でそれを再公開することができます。 - -`rippled`の各インスタンスは、（[Test Netなどの並列ネットワーク](parallel-networks.html)に従うように構成されていない限り）同じネットワークに同期され、ネットワーク全体のあらゆる通信にアクセスできます。ネットワーク上の各`rippled`サーバーは、最近のトランザクションの一部と、それらのトランザクションで行われた変更の記録とともに、XRP Ledger全体の最新の状態データの完全なコピーを保持します。また、各サーバーは各トランザクションを単独で処理すると同時に、そのトランザクションの結果が残りのネットワークに一致するか検証します。サーバーは、より多くの[レジャー履歴](ledger-history.html)を保持したり、[バリデータ](rippled-server-modes.html#バリデータを運用する理由)としてコンセンサスプロセスに参加するように構成することができます。 - -このサーバーは、データの検索、サーバーの管理、トランザクションの送信を行うための[`rippled` API](http-websocket-apis.html)をユーザーに公開します。 - -### プログラミングライブラリー - -プログラミングライブラリーは、XRP Ledgerデータにアクセスするために必ずしも必要なわけではありません。HTTPまたはWebSocketを使用すれば、[`rippled` API](http-websocket-apis.html)に直接接続できるためです。ライブラリーは、`rippled` APIにアクセスする際の一般的な作業の一部を簡素化し、データをライブラリー内のプログラミング言語で理解しやすく、かつプログラミングしやすい形式に変換します。 - -[JavaScript用のxrpl.js](get-started-using-javascript.html)は、長年にわたって使用され、かつ十分なサポートがある、XRP Ledgerにアクセスするためのライブラリーです。多くの[ミドルウェアサービス](#ミドルウェア)が、このような[プログラミングライブラリー](client-libraries.html)を内部で使用しています。 - -### ミドルウェア - -ミドルウェアサービスは、一方ではXRP Ledger APIを利用し、もう一方では独自のAPIを提供するプログラムです。抽象化層を提供して、いくつかの一般的な機能をサービスとして提供することで上位のアプリケーションを容易に構築できるようにします。 - -[プログラムライブラリー](#プログラミングライブラリー)は、インポートしたプログラムによって新規にインスタンス化されたりシャットダウンされたりしますが、ミドルウェアはそれと異なり、多くの場合は無期限に実行され続け、独自のデータベース（リレーショナルSQLデータベースなど）や構成ファイルを持つことがあります。 - -XRP Ledger上のミドルウェアサービスの例として、[Data API](data-api.html)が挙げられます。Data APIは、XRP Ledgerデータを収集して変換することで、時間での照会、データタイプでの絞り込み、およびデータ分析を可能にします。 - -ミドルウェアサービスのもう1つの例は[XRP-API](xrp-api.html)です。XRP-APIは秘密鍵を管理し、あらゆるプログラミング言語のアプリに対してより使いやすいXRP LedgerへのRESTfulインターフェイスを提供します。 - - -### アプリとサービス - -最上層は、最もエキサイティングなことが起こる場所です。アプリとサービスは、XRP Ledgerに接続するための手段をユーザーとデバイスに提供します。この層では、[取引所がXRPを上場](list-xrp-as-an-exchange.html)したり、分散型取引所で使用するために[ゲートウェイが他の通貨を発行](become-an-xrp-ledger-gateway.html)したり、あるいはXRPを購入、売却、または単にHODLing保持するためにウォレットがユーザーインターフェイスを提供したりします。さらに高階層にサービスを追加するなど、他にも多くの可能性があります。 - -XRPだけでなく、通貨価値を表す他のさまざまな方法と互換性のあるアプリケーションを構築するには、XRPでの決済に[Interledger Protocol][]を使用するのが最適です。 - -XRPと周辺テクノロジーを使用してユーザーとやり取りするプロジェクトには、他にも多くの例があります。 例については[XRP Ledger ビジネス](businesses.html)か、[エキスチェンジ](exchanges.html)か、[ウォレット](wallets.html)を参照してください。 - - -## 関連項目 - -- [RippleX](https://ripplex.io/) -- [技術に関するよくある質問](technical-faq.html) -- [XRPChat Links & Resources](https://www.xrpchat.com/links/) - ゲートウェイと取引所、ウォレットとストレージ、アプリなどの最新のリストが記載されています。 - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/introduction/software-ecosystem.md b/content/concepts/introduction/software-ecosystem.md deleted file mode 100644 index 65eca8650a..0000000000 --- a/content/concepts/introduction/software-ecosystem.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -html: software-ecosystem.html -parent: introduction.html -blurb: Get an overview of what XRP Ledger software is out there and how it fits together. -labels: - - Core Server ---- -# Software Ecosystem - -The XRP Ledger is home to a deep, layered ecosystem of software projects powering and enabling an Internet of Value. It's impossible to list every project, tool, and business that interacts with the XRP Ledger, so this page only lists a few categories and highlights some central projects that are documented here on [xrpl.org](https://xrpl.org). - -## Stack Levels - -{{ include_svg("img/ecosystem.svg", "Ecosystem diagram with the four layers: XRP Ledger peer-to-peer network on the bottom, Programming Libraries above that, Middleware next, and Apps and Services at the top") }} - -- The [basis of the XRP Ledger](#rippled-the-core-server) is a peer-to-peer network of always-on servers sharing transactions, engaging in the [consensus process](consensus.html) and processing [transactions](transaction-basics.html). Everything else in the XRP Ledger ecosystem is ultimately built on top of this peer-to-peer network, directly or indirectly. - -- [_Programming Libraries_](#programming-libraries) exist in higher level software, where they are imported directly into program code, and contain methods to access the XRP Ledger. - -- [_Middleware_](#middleware) provides indirect access to XRP Ledger data. Applications in this layer often have their own data storage and processing. - -- [_Apps and Services_](#apps-and-services) provide user-level interaction with the XRP Ledger, or provide a basis for even higher-level apps and services. - - -### 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`**](xrpl-servers.html) (pronounced "ripple-dee"). The server is available under [a permissive open-source license](https://github.com/ripple/rippled/blob/develop/LICENSE.md), so anyone can inspect and modify their own instance of the server, and re-publish with few restrictions. - -Every instance of `rippled` syncs to the same network (unless it's configured to follow a [parallel network such as a test net](parallel-networks.html)) 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, along with a slice of recent transactions and a record of the changes those transactions made, and 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](ledger-history.html) and to participate in the consensus process as a [validator](rippled-server-modes.html#validators). - -This server exposes [`rippled` APIs](http-websocket-apis.html) for users to look up data, administer the server, and submit transactions. - -### Programming Libraries - -[Programming libraries](client-libraries.html) are not strictly required to access XRP Ledger data, since you can use HTTP or WebSocket to connect to the [`rippled` APIs](http-websocket-apis.html) 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 with in the programming language of the library. - -[xrpl.js for JavaScript](get-started-using-javascript.html) (formerly called "ripple-lib") is the longest-standing, most well-supported library for accessing the XRP Ledger. Many [middleware services](#middleware) use programming libraries like this internally. - -### Middleware - -Middleware services are programs that consume the 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. - -Unlike [programming libraries](#programming-libraries), which are instantiated fresh and shut down with the program that imports them, middleware services typically stay running indefinitely, and may have their own databases (relational SQL databases or otherwise) and configuration files. - -The [Data API](data-api.html) 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](xrp-api.html) 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 - -Atop the stack is where the truly exciting things happen. Apps and services provide a way for users and devices to connect to the XRP Ledger. At this level, [exchanges list XRP](list-xrp-as-an-exchange.html), [gateways issue other currencies](become-an-xrp-ledger-gateway.html) for use in the decentralized exchange, and wallets provide user interfaces for buying, selling, or HODLing holding XRP. Many other possibilities exist, including additional services layered even higher. - -A great way to build applications that are compatible with not only XRP but lots of 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). - - -## See Also - -- [RippleX](https://ripplex.io/) -- [Technical FAQ](technical-faq.html) -- [XRPChat Links & Resources](https://www.xrpchat.com/links/) - Includes updated lists of gateways and exchanges, wallets and storage, apps, and more. - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/introduction/xrp-ledger-overview.ja.md b/content/concepts/introduction/xrp-ledger-overview.ja.md deleted file mode 100644 index 8a0018d074..0000000000 --- a/content/concepts/introduction/xrp-ledger-overview.ja.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -html: xrp-ledger-overview.html -parent: introduction.html -blurb: XRP Ledgerの基本機能を簡単に紹介します。 -labels: - - ブロックチェーン - - XRP ---- -# XRP Ledgerの概要 - -**XRP Ledger**は、ピアツーピア・サーバーのネットワーク機能を備えた分散型の暗号台帳です。XRP Ledgerは**XRP**の土台となるものであり、世界中で使用されている様々な通貨の橋渡しをするために設計されたデジタル資産です。RippleはXRP Ledgerの開発を主導し、_「価値のインターネット」_（情報が移動するようにお金が移動する世界）の実現に向けて鍵となる役割を果たすと期待されるXRPを推進しています。 - -## 決済のためのデジタル資産 - -XRPはXRP Ledger固有のデジタル資産です。暗号鍵を持ち、インターネットに接続できる人は誰でも、XRPを受け取り、保持し、任意の人に送ることができます。XRPは他の通貨での取引をも容易にできる魅力的なブリッジ通貨として開発されました。XRPには次のような多くの特性があり、これにより他の多くのユースケースでも魅力的な資産となっています。 - -- **[耐検閲性のある取引処理][]:** どの特定の個人もXRP取引の成功・不成功を勝手に決定することはできませんし、一度完了した取引を組み戻すこともできません。ネットワークに参加するユーザーは、ネットワークを健全に保っている限り、XRPを数秒で送受信できます。 -- **[高速で効率的なConsensusアルゴリズム][]:** XRP LedgerのConsensusアルゴリズムは、最大1500件/秒のスループットで取引を処理し、4秒から5秒で完了します。これらの特性により、XRPは、他の上位デジタル資産の少なくとも10倍の優位性をもっています。 -- **[限定されたXRP供給量][]:** XRP Ledgerが開始された時、1000億XRPが発行され、今後さらにXRPが発行されることはありません。（各XRPは、小数第6位まで再分割でき、総計10万兆（10の17乗）_drop_（XRPの最小単位）となります。）取引に必要なコストを支払うために少額のXRPが毎回消却され、使用可能なXRPの供給量は時間とともにゆっくりと減少していきます。 -- **[責任あるソフトウェアガバナンス][]:** Rippleでは、世界に通用する技術をもった常勤の開発チームが、XRP Ledgerの基礎となるソフトウェアを保守し、継続的に改良しています。Rippleは、技術の担い手として、さらに技術に対する支援者として、世界中の政府および金融機関と建設的な関係を築いています。 -- **[安全で適応性のある暗号技術][]:** XRP Ledgerは、ECDSA（Bitcoinが使用しているものと同じアルゴリズム）などの業界標準のデジタル署名システムを利用しています。またEd25519などの最新の効率的なアルゴリズムもサポートしています。XRP Ledgerのソフトウェアは拡張性に富み、最先端の暗号技術の進歩に合わせてアルゴリズムを追加したり消却にしたりすることが可能です。 -- **[スマートコントラクト用の最新機能][]:** Escrow、ChecksおよびPayment Channelなどの機能は、[Interledgerプロトコル](https://interledger.org/)を含む最新の金融アプリケーションをサポートしています。この拡張機能のツールボックスには、ネットワークの修正プロセスや、取引の不変性を担保するチェックを分けて行うなどの安全機能が備わっています。 -- **[台帳上の分散型取引所][]:** XRP Ledgerには、それ自体でXRPを便利に使うための機能すべてに加え、ユーザー任意の通貨建ての債務を追跡し取引するための多機能な会計システムや、プロトコルに組み込まれた両替機能などがあります。XRP Ledgerは、通貨間の長い支払いパスや、複数通貨の一元的決済を確実に処理し、XRPを活用することで分散型ネットワークに存在する信頼のギャップを解消しています。 - -## 耐検閲性のある取引処理 -[耐検閲性のある取引処理]: #耐検閲性のある取引処理 - -XRPは、Bitcoinや他の暗号資産と同様に新しい通貨の一種です。 - -- これらの**分散型デジタル資産**はそれぞれのコンピューターシステム上に存在し、これを管理する中央管理者はいません。システムが十分に分散されている限り、取引を組み戻したり、残高を凍結したり、他のユーザーが分散型デジタル資産を使用することを阻止したりすることはできません。これらの資産はもともとデジタルであるため、離れた場所からもオンラインで使用できます。 - -これは物理的な通貨と中央集権型デジタル通貨の良い部分を併せ持っていることを意味します。2009年にBitcoinが発明されるまでは、すべての通貨は次の2つのカテゴリに分類できました。 - -- **物理的な硬貨および紙幣**。これは、中央の管理者を経由せずに、個人が決済するために使用できます。ただし、物理的なものであるためオンラインでは使用できず、長距離のビジネスで使うには時間がかかり不便です。 -- **中央集権型デジタル通貨**。これには、取引を承認する管理者が必要です。管理者には、取引の検閲や組み戻しの権限、また一部の個人がデジタル通貨を使用することを許可しない権限もあります。デジタル通貨の運営者は、誰かが利用規約に違反したことが判明した場合、その個人の通貨を凍結したり没収したりすることもできます。ただし、これらの通貨の残高はデジタルであるためオンラインで使用でき、離れた場所の取引にも便利です。 - -**注記:** XRP Ledgerのユーザーは、XRP Ledgerで発行されたXRP以外の通貨であれば凍結 _できます_ 。詳細は、[凍結についての資料](freezes.html)を参照してください。 - -信頼できるバリデータノードから構成されるXRP Ledgerのシステムでは、人手をほとんどかけることなく、他の分散型システムよりも優れた権限の分散が可能です。不特定多数の参加者間でのConsensusを完全に自動化しているシステムは、議決権の集中のリスクに晒されます。例えば、Bitcoinの採掘は、電気代が安い場所に偏って集中しています。Rippleは、様々な地域の異なる組織によって運営される別個のバリデータリストを管理しています。そのためXRP Ledgerは検閲などの外部の圧力に対してプルーフ・オブ・ワークによる採掘よりも高い耐性を持つことができます。推奨されるバリデータを分散させるためのRippleの対応策の詳細は、[分散化戦略についてのアップデート](https://xrpl.org/blog/2017/decent-strategy-update.html)を参照してください。 - -XRP Ledgerの検閲機能の詳細は、[取引検閲の検知](transaction-censorship-detection.html)を参照してください。 - - -## 高速で効率的なConsensusアルゴリズム -[高速で効率的なConsensusアルゴリズム]: #高速で効率的なconsensusアルゴリズム - -XRP Ledgerが多くの暗号資産と最も異なっている点は、BitcoinやEthereumなど他のほとんどのシステムが行う「採掘」の時間と労力を必要とせず、独自のConsensusアルゴリズムを使用していることです。「プルーフ・オブ・ワーク」または「プルーフ・オブ・ステーク」の代わりに、XRP LedgerのConsensusアルゴリズムでは、すべての参加者が重複する「信頼されるバリデータ」のリストを持ち、どの取引がどの順序で発生したかについて効率的に合意するシステムとなっています。2018年の初めの時点で、Bitcoinネットワークが取引ごとに使用する電力量は、米国の一世帯の住宅で1日に使用される量よりも多く、さらに取引の承認には何時間もかかっています。1つのXRP取引で使用される電力量はごく少量であり、承認には4秒から5秒しかかかりません。 - -さらに、XRP Ledgerのそれぞれの新しい「台帳バージョン」（「ブロック」と同義）には、すべての残高が完全かつ最新の状態で保持されているため、サーバーは、何時間もかけてすべての取引履歴をダウンロードして再処理する必要がなく、数分でネットワークと同期することができます。 - -XRP LedgerのConsensusアルゴリズムの動作方法の詳細は、[XRP Ledger Consensusプロセス](consensus.html)を参照してください。XRP LedgerがこのConsensusアルゴリズムを使用する理由の背景は、[Consensusの原理とルール](consensus-principles-and-rules.html)を参照してください。 - - -## 限定されたXRP供給量 -[限定されたXRP供給量]: #限定されたxrp供給量 - -戦争および政変と並んで、超インフレは通貨が消滅する主な原因の1つです。バリデータが分散しているため、XRPは政治的要因に対してはある程度の耐性があります。一方、超インフレに対しては、XRP Ledgerのルールにより簡潔なソリューションで対応しています。つまりXRPのトータル供給量の限定です。発行量を増やすメカニズムがそもそもないため、XRPが超インフレに悩まされる可能性は非常に低くなります。 - -市場に出回るXRPの供給量は、次のいくつかの要因によって変化 _します_。 - -- XRP Ledgerで取引を送信すると、毎回少額のXRPが消却されます。送信者は消却する額を選択できますが、予想される取引の処理作業とネットワークの混雑度に応じて一定の最低額が設定されています。ネットワークが混み合っている場合、より多くのXRPを消却するよう選択している取引は、取引キューの前に割り込むことができます。これはスパム防止策で、XRP Ledgerネットワークに対する[DDoS](https://en.wikipedia.org/wiki/Denial-of-service_attack)攻撃にかかるコストは極めて高額になります。詳細は、[取引コスト](transaction-cost.html)を参照してください。 -- XRP Ledgerの各アカウントは、少額のXRPを準備しておく必要があります。これもスパム防止策で、台帳データが必要以上に増えてしまうことを防ぎます。XRP Ledgerのバリデータは、実世界でのXRPの価値の変動に対応する目的で、準備金として必要なXRPの金額を変更するために投票決議を行うことができます。（この投票が前回発生したのは2021年の9月であり、このときは[必要な準備金が20 XRPから10 XRPに減少しました](https://xrpl.org/blog/2021/reserves-lowered.html)。）必要な準備金が減少すると、以前は準備金によって使用できなくなっていた部分のXRPが再び使用可能になります。 -- Ripple（会社）は、大量のXRPをEscrowに保有しています。毎月の初めに、Rippleで使用するために10億XRPがEscrowから引き出されます。（RippleはXRPを使用してXRP Ledgerエコシステムの成長を促し、また一部のXRPを機関投資家に売却しています。Rippleはまた、取引所での取引総量のうちのわずかな比率に限定して、プログラムに従って取引所でXRPを売却しています。Rippleは[XRP市場レポート](https://ripple.com/insights/q1-2018-xrp-markets-report/)で四半期ごとに売上高を公開しています。）毎月の終わりに、Rippleが売却や譲渡をせずに残っているXRPがあればEscrowに戻し、54か月保管します。RippleのEscrowポリシーの詳細は、[RippleはXRPの総供給量の確実性を確保するために550億XRPをエスクローに預託することを発表しました](https://ripple.com/insights/ripple-to-place-55-billion-xrp-in-escrow-to-ensure-certainty-into-total-xrp-supply/)を参照してください。Escrow機能の技術的詳細は、[Escrow](escrow.html)を参照してください。 - - - -## 責任あるソフトウェアガバナンス -[責任あるソフトウェアガバナンス]: #責任あるソフトウェアガバナンス - -ソフトウェアの水準は、そのソフトウェアを作成して管理する開発者によって決まります。Rippleは、XRP Ledgerソフトウェア、特にコアサーバーである`rippled`の保守および改良に専念する優秀な常勤エンジニアチームを雇用しています。[`rippled`のソースコード](https://github.com/ripple/rippled/)は、XRP Ledgerエコシステムの他の多くの部分と同様に、一般利用が可能なオープンソースライセンスを有するソフトウェアとして公開されています。Rippleのエンジニアは、次のようなソフトウェアエンジニアリングのベストプラクティスに従っています。 - -- 慎重で徹底的なコードレビュープロセス -- 包括的なコードカバレッジと単体テスト -- 潜在的な脆弱性およびメモリーリークの自動チェックの定期的な実行 -- 専門家組織による外部レビューヘの定期的な委託 - -巨額のXRPを長期にわたって保持する義務がある組織として、Rippleは、XRPが法に準拠して持続的かつ建設的な方法で広く使用されるために努力する強い自発的なインセンティブを持っています。「価値のインターネット」というRippleの理想と同じ目標を持つ企業に対して、Rippleは技術的なサポートを提供します。Rippleはまた、世界中の立法当局や規制当局と協力し、デジタル資産および関連ビジネスを管理する合理的な法律の実施に向けて誘導しています。 - - -## 安全で適応性のある暗号技術 -[安全で適応性のある暗号技術]: #安全で適応性のある暗号技術 - -暗号技術は分散システムにおいて最も重要な部分の1つであり、小さな技術的問題が一瞬にして世界中の悪意あるハッカーによる盗難につながる危険性を秘めています。XRP Ledgerは、取引の署名および検証のための業界標準の技術と、何年もの間、数千億USドルにも相当する価値を保護することに成功してきたアルゴリズムを使用しています。また、XRP Ledgerにはマルチ署名機能が備わっているため、バックアップとして多要素認証や複数のユーザー間で分割キーを使用できます。さらに暗号技術の飛躍的な進歩によって古いアルゴリズムが時代遅れになり、新しいアルゴリズムが導入される場合でも、ユーザーはそのままキーを使い続けることができます。 - -詳細は、[暗号鍵](cryptographic-keys.html)および[マルチ署名](multi-signing.html)を参照してください。 - - -## スマートコントラクト用の最新機能 -[スマートコントラクト用の最新機能]: #スマートコントラクト用の最新機能 - -[XRP決済](direct-xrp-payments.html)による単純な価値の移動に加え、XRP Ledgerには「価値のインターネット」に特化した拡張機能があります。この拡張機能により、XRP上にビルドされたアプリケーションは、以前は実用的でなかったり実現不可能だったりしたサービスや機能を提供できるようになります。ネットワーク自体のなかで「スマートコントラクト」としてのアプリケーションを実行するのではなく、XRP Ledgerでは、コントラクトを処理するためのツールを提供しつつ、実行環境またはコンテナが適切であれば、すべての場所でアプリケーションを実行することができます。この「シンプルにする」というアプローチは、柔軟でスケーラブル、かつ強力です。 - -XRP Ledgerの拡張機能として次のものがあります。 - -- [Payment Channel](use-payment-channels.html)により、非同期の残高を署名の作成、検証とほぼ同時に変更することができます。 -- [Escrow](escrow.html)により、宣言した時間が経過するまで、または暗号条件が満たされるまで、XRPはロックされます。 -- [DepositAuth](depositauth.html)により、ユーザーは自分に対して送金できる相手か、送金できない相手かを決めることができます。 -- [分散型取引所](#台帳上の分散型取引所)により、ユーザーは台帳上で債務およびXRPを取引することができます。 -- [Invariant Checking](https://xrpl.org/blog/2017/invariant-checking.html)により、独立したレイヤーで取引実行時のバグから取引を保護することができます。 -- [Amendment](amendments.html)により、現行機能にスムーズにアップグレードすることができ、移行に際してエコシステムに被害を及ぼしたり、不確定要素を発生させることなく、継続して技術を発展させることができます。 - - -## 台帳上の分散型取引所 -[台帳上の分散型取引所]: #台帳上の分散型取引所 - -XRP Ledgerを他の暗号資産ネットワークとは異なるものにしている最も大きな特徴は、XRP Ledger上に完全な取引機能が含まれている点です。このシステム内で、事業者（通常は「ゲートウェイ」と言います）は希望の通貨を顧客に自由に発行でき、その顧客はその特定ゲートウェイによってXRPに発行された通貨や他のゲートウェイによって発行された通貨を自由に取引できます。このようにXRP Ledgerでは、取引注文によって流動性を確保しつつ、複数通貨間の一元的な取引を実行することができます。 - -分散型取引所がどのように機能するかの詳細は、[分散型取引所](decentralized-exchange.html)を参照してください。ゲートウェイビジネスモデルの詳細は、[Become an XRP Ledger Gateway](become-an-xrp-ledger-gateway.html)を参照してください。 diff --git a/content/concepts/introduction/xrp-ledger-overview.md b/content/concepts/introduction/xrp-ledger-overview.md deleted file mode 100644 index b6a93e53e1..0000000000 --- a/content/concepts/introduction/xrp-ledger-overview.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -html: xrp-ledger-overview.html -parent: introduction.html -blurb: Get a quick and concise introduction to key features of the XRP Ledger. -labels: - - Blockchain - - XRP ---- -# XRP Ledger Overview - -The **XRP Ledger** is an online system for payments, powered by a community without a central leader. Anyone can connect their computer to the peer-to-peer network that manages the ledger. The XRP Ledger is the home of **XRP**, a digital asset designed to bridge the world's many currencies. The XRP Ledger is one part of the developing _Internet of Value_: a world in which money moves the way information does today. - -## The Digital Asset for Payments - -XRP is a digital asset native to the XRP Ledger. Anyone with a cryptographic key and an internet connection can receive, hold, and send XRP to anyone else. XRP's creators have developed it to be a desirable bridge currency that can enable trades in any other currency. XRP has many properties which make it an appealing asset for many other use cases, too: - -- **[Censorship-Resistant Transaction Processing][]:** No single party decides which XRP transactions succeed or fail, and no one can "roll back" a transaction after it completes. As long as those who choose to participate in the network keep it healthy, they can send and receive XRP in seconds. -- **[Fast, Efficient Consensus Algorithm][]:** The XRP Ledger's consensus algorithm settles transactions in 4 to 5 seconds, and can process up to 1500 transactions per second. These properties put XRP far ahead of other top digital assets. -- **[Finite XRP Supply][]:** When the XRP Ledger began, 100 billion XRP were created, and no more XRP will ever be created. (Each XRP is divisible down to 6 decimal places, for a grand total of 100 quadrillion (10^17) _drops_ of XRP.) The available supply of XRP decreases slowly over time as small amounts are destroyed to pay transaction costs. -- **[Responsible Software Governance][]:** A team of full-time, world-class developers at Ripple maintain and continually improve the XRP Ledger's underlying software. Ripple acts as a steward for the technology and an advocate for its interests, and builds constructive relationships with governments and financial institutions worldwide. -- **[Secure, Adaptable Cryptography][]:** The XRP Ledger relies on industry standard digital signature systems like ECDSA (the same scheme used by Bitcoin) but also supports modern, efficient algorithms like Ed25519. The extensible nature of the XRP Ledger's software makes it possible to add and disable algorithms as the state of the art in cryptography advances. -- **[Modern Features for Smart Contracts][]:** Features like Escrow, Checks, and Payment Channels support cutting-edge financial applications including the [Interledger Protocol](https://interledger.org/). This toolbox of advanced features comes with safety features like a process for amending the network and separate checks against invariant constraints. -- **[On-Ledger Decentralized Exchange][]:** In addition to all the features that make XRP useful on its own, the XRP Ledger also has a fully-functional accounting system for tracking and trading obligations denominated in any way users want, and an exchange built into the protocol. The XRP Ledger can settle long, cross-currency payment paths and exchanges of multiple currencies in atomic transactions, bridging gaps of trust with XRP. - -## Censorship-Resistant Transaction Processing -[Censorship-Resistant Transaction Processing]: #censorship-resistant-transaction-processing - -XRP is part of a new class of money which includes Bitcoin and other cryptocurrencies: - -- These **Decentralized digital assets** exist in computer systems without a central administrator. As long as the system is sufficiently decentralized, no one can roll back transactions, freeze balances, or block someone from using a decentralized digital asset. These assets are natively digital, so they can be used online across any distance. - -This combines qualities of physical and centralized digital money. Prior to the invention of Bitcoin in 2009, all currencies could be divided into those two categories: - -- **Physical coins and paper money**, which individuals can use to do business without going through a central party. As physical objects, they cannot be used online, and doing business long-distance is slow and inconvenient. -- **Centralized digital currencies**, which need an administrator to confirm transactions. The administrator also has the power to censor or roll back transactions, or disallow some individuals from using the digital currency. If the operator of a digital currency decides someone has violated its terms of service, it can freeze or even confiscate that person's money. However, as digital balances, these currencies can be used online and are convenient across long distances. - -**Note:** Users of the XRP Ledger _can_ freeze non-XRP currencies issued in the XRP Ledger. For more information, see the [Freeze documentation](freezes.html). - -The XRP Ledger's system of trusted validators uses a small amount of human interaction to achieve better distribution of authority than other decentralized systems. Fully-automated systems for reaching consensus from an unknown set of participants are vulnerable to concentrations of voting power. For example, Bitcoin mining is disproportionately concentrated in places with cheap electricity. As Ripple curates a list of distinct validators run by different entities in different jurisdictions, the XRP Ledger can become more resistant to censorship and outside pressures than proof-of-work mining. For more information on Ripple's plan to decentralize the recommended set of validators, see the [Decentralization Strategy Update](https://xrpl.org/blog/2017/decent-strategy-update.html). - -For more information about the XRP Ledger's ability to detect censorship, see [Transaction Censorship Detection](transaction-censorship-detection.html). - - -## Fast, Efficient Consensus Algorithm -[Fast, Efficient Consensus Algorithm]: #fast-efficient-consensus-algorithm - -The XRP Ledger's biggest difference from most cryptocurrencies is that it uses a unique consensus algorithm that does not require the time and energy of "mining", the way Bitcoin, Ethereum, and almost all other such systems do. Instead of "proof of work" or even "proof of stake", The XRP Ledger's consensus algorithm uses a system where every participant has an overlapping set of "trusted validators" and those trusted validators efficiently agree on which transactions happen in what order. As of early 2018, the amount of electricity the Bitcoin network uses per transaction is more than a family home in the USA uses in an entire day, and confirming the transaction takes hours. A single XRP transaction uses a negligible amount of electricity, and takes 4 or 5 seconds to confirm. - -Furthermore, each new "ledger version" in the XRP Ledger (the equivalent of a "block") contains the full current state of all balances, so a server can synchronize with the network in minutes instead of spending hours downloading and re-processing the full transaction history. - -For more information on how the XRP Ledger's consensus algorithm works, see [The XRP Ledger Consensus Process](consensus.html). For background on why the XRP Ledger uses this consensus algorithm, see [Consensus Principles and Rules](consensus-principles-and-rules.html). - - -## Finite XRP Supply -[Finite XRP Supply]: #finite-xrp-supply - -Alongside war and political turmoil, hyperinflation is one of the leading causes of death for currencies. While the decentralized system of validators provides XRP with some resistance to political factors, the rules of the XRP Ledger provide a simpler solution to hyperinflation: the total supply of XRP is finite. Without a mechanism to create more, it becomes much less likely that XRP could suffer hyperinflation. - -The supply of XRP available to the general public _does_ change due to a few factors: - -- Sending transactions in the XRP Ledger destroys a small amount of XRP. Senders choose how much to destroy, with the minimum based on the expected work of processing the transaction and how busy the network is. If the network is busy, potential transactions that promise to destroy more XRP can cut in front of the transaction queue. This is an anti-spam measure to make it prohibitively expensive to [DDoS](https://en.wikipedia.org/wiki/Denial-of-service_attack) the XRP Ledger network. For more information, see [Transaction Cost](transaction-cost.html). -- Each account in the XRP Ledger must hold a small amount of XRP in reserve. This is an anti-spam measure to disincentivize making the ledger data occupy too much space. XRP Ledger validators can vote to change the amount of XRP required as a reserve, to compensate for changes in XRP's real-world value. (The last time this happened was in September 2021, when [the reserve requirement decreased from 20 XRP to 10 XRP](https://xrpl.org/blog/2021/reserves-lowered.html).) If the reserve requirement decreases, XRP that was previously locked up by the reserve becomes available again. -- Ripple (the company) holds a large reserve of XRP in escrow. At the start of each month, 1 billion XRP is released from escrow for Ripple to use. (Ripple uses XRP to incentivize growth in the XRP Ledger ecosystem and sells XRP to institutional investors. Ripple also sells XRP programmatically on exchanges, limited to a small percentage of overall exchange volume. Ripple publishes sales figures quarterly in the [XRP Markets Report](https://ripple.com/insights/q1-2018-xrp-markets-report/).) At the end of each month, any remaining XRP the company does not sell or give away is stored into escrow for a 54-month period. For more information on Ripple's escrow policy, see [Ripple Escrows 55 Billion XRP for Supply Predictability](https://ripple.com/insights/ripple-to-place-55-billion-xrp-in-escrow-to-ensure-certainty-into-total-xrp-supply/). For more information on the technical capabilities of the Escrow feature, see [Escrow](escrow.html). - - -## Responsible Software Governance -[Responsible Software Governance]: #responsible-software-governance - -Any piece of software can only be as good as the developers who code and manage it. Ripple employs a team of world-class engineers dedicated full-time to maintaining and improving the XRP Ledger software, especially the core server, `rippled`. The [source code for `rippled`](https://github.com/ripple/rippled/) is available to the public with a permissive open-source license, as are many other parts of the XRP Ledger ecosystem. Ripple engineers follow best practices for software engineering, including: - -- A famously strict and thorough code review process -- Comprehensive code coverage and unit tests -- Regularly running automated checks for potential vulnerabilities and memory leaks -- Regularly commissioning external reviews by professional organizations - -As an entity that is obligated to hold large amounts of XRP for the long term, Ripple has a strong incentive to ensure that XRP is widely used in ways that are legal, sustainable, and constructive. Ripple provides technical support to businesses whose goals align with Ripple's ideal of an Internet of Value. Ripple also cooperates with legislators and regulators worldwide to guide the implementation of sensible laws governing digital assets and associated businesses. - - -## Secure, Adaptable Cryptography -[Secure, Adaptable Cryptography]: #secure-adaptable-cryptography - -Cryptography is one of the hardest parts of any distributed system, and a mistake can lead to money stolen by malicious actors anywhere in the world. The XRP Ledger uses industry-standard schemes for signing and verifying transactions, algorithms that have successfully protected hundreds of billions of US dollars' worth of value for many years. The XRP Ledger also layers multi-signing functionality so you can use multi-factor authorization or split keys across multiple people as a backup, and provides new algorithms with a path to migrate the keys you use if a breakthrough in cryptography makes the old algorithms obsolete. - -For more information, see [Cryptographic Keys](cryptographic-keys.html) and [Multi-Signing](multi-signing.html). - - -## Modern Features for Smart Contracts -[Modern Features for Smart Contracts]: #modern-features-for-smart-contracts - -Besides direct value transfer with [XRP payments](direct-xrp-payments.html), the XRP Ledger has advanced features specialized for the Internet of Value. This allows applications built on XRP to provide services and functionality that would have been impractical or impossible in the past. Rather than running applications as "smart contracts" in the network itself, the XRP Ledger provides tools for settling contracts, while letting the applications themselves run anywhere, in whatever environment or container is appropriate. This "keep it simple" approach is flexible, scalable, and powerful. - -A sample of advanced features in the XRP Ledger: - -- [Payment Channels](use-payment-channels.html) allow asynchronous balance changes as fast as you can create and validate signatures. -- [Escrow](escrow.html) locks up XRP until a declared time passes or cryptographic condition is met. -- [DepositAuth](depositauth.html) lets users decide who can send them money and who can't. -- A [Decentralized Exchange](#on-ledger-decentralized-exchange) lets users trade obligations and XRP on-ledger. -- [Invariant Checking](https://xrpl.org/blog/2017/invariant-checking.html) provides an independent layer of protections against bugs in transaction execution. -- [Amendments](amendments.html) provide smooth upgrades to the existing feature set, so the technology can continue to evolve without fracturing the ecosystem or causing uncertainty around times of transition. - - -## On-Ledger Decentralized Exchange -[On-Ledger Decentralized Exchange]: #on-ledger-decentralized-exchange - -One of the biggest features that sets the XRP Ledger apart from other cryptocurrency networks is that it also contains a full currency exchange that runs on the XRP Ledger. Within this system, businesses (typically called "gateways") can freely issue any currency they want to customers, and those customers can freely trade tokens for XRP or other tokens. The XRP Ledger can execute atomic cross-currency transactions this way, using orders in the exchange to provide liquidity. - -For more information on how the decentralized exchange works, see [Decentralized Exchange](decentralized-exchange.html). For more information on the gateway business model, see the [Become an XRP Ledger Gateway](become-an-xrp-ledger-gateway.html). diff --git a/content/concepts/introduction/xrp.ja.md b/content/concepts/introduction/xrp.ja.md deleted file mode 100644 index ec8220adfe..0000000000 --- a/content/concepts/introduction/xrp.ja.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -html: xrp.html -parent: introduction.html -blurb: 送金のためのデジタルアセットである、XRPの使い方と特性について学びましょう。 -labels: - - XRP ---- -# XRP - -**XRP**は、XRP Ledgerのネイティブ暗号資産です。XRP Ledgerのすべての[アカウント](accounts.html)間で相互にXRPを送金できます。アカウントは、最小限度額のXRPを[準備金](reserves.html)として保有する必要があります。XRP Ledgerアドレス間にてXRPの直接送金が可能で、ゲートウェイや流動性プロバイダーを必要としません。このため、XRPは便利なブリッジ通貨となりました。 - -XRP Ledgerの高度機能の一部（[Escrow](escrow.html)や[Payment Channel](use-payment-channels.html)など）は、XRPでのみ使えます。オーダーブックの[オートブリッジング](autobridging.html)は、XRPを使用して、2つの発行済み通貨のオーダーブックをXRPオーダーブックにマージして、合成された一つのオーダーブックを作成することで、分散型取引所の流動性を高めます。（たとえば、オートブリッジングによりUSD:XRPオーダーとXRP:EURオーダーがマッチングされ、USD:EURオーダーブックとなります。） - -XRPはまた、ネットワークのスパムの防御対策としても機能します。すべてのXRP Ledgerアドレスには、XRP Ledger維持管理コストを支払うために少額のXRPが必要です。[トランザクションコスト](transaction-cost.html)と[準備金](reserves.html)は、XRP建ての中立的な手数料であり、どの当事者にも支払われません。レジャーのデータフォーマットで、XRPは[AccountRootオブジェクト](accountroot.html)に保管されます。 - -XRPのユースケース、メリット、最新情報についての詳細は、[XRPポータル](https://ripple.com/xrp/)を参照してください。 - -## XRPの特性 - -一番最初のレジャーにて1000億XRPが発行され、これ以上新しいXRPは作成できません。XRPは、[トランザクションコスト](transaction-cost.html)によって消却されるか、またはキーの所有者がいないアドレスに送金すると失われることがあります。このため、XRPは本質的にはやや[デフレ通貨](https://en.wikipedia.org/wiki/Deflation)です。XRPがなくなることを心配する必要はありません。現時点の消却のペースでは、すべてのXRPが消却されるまでに約7万年かかります。またXRPの総供給量の変化に伴い、XRPの[価格と手数料が調整される可能性があります](fee-voting.html)。 - -技術的には、XRPは0.000001 XRPの単位まで正確に計算され、「Drop」と呼ばれます。[`rippled`API](http-websocket-apis.html)では、XRPの量は常にXRPのdrop単位で指定する必要があります。たとえば1 XRPは`1000000` dropと表されます。詳細については、[通貨フォーマットのリファレンス](currency-formats.html)を参照してください。 diff --git a/content/concepts/introduction/xrp.md b/content/concepts/introduction/xrp.md deleted file mode 100644 index 09f85a8a42..0000000000 --- a/content/concepts/introduction/xrp.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -html: xrp.html -parent: introduction.html -blurb: Learn about the uses and properties of XRP, the digital asset for payments. -labels: - - XRP ---- -# XRP - -**XRP** is the native cryptocurrency of the XRP Ledger. All [accounts](accounts.html) in the XRP Ledger can send XRP among one another and must hold a minimum amount of XRP as a [reserve](reserves.html). XRP can be sent directly from any XRP Ledger address to any other. This helps make XRP a convenient bridge currency. - -Some advanced features of the XRP Ledger, such as [Escrow](escrow.html) and [Payment Channels](use-payment-channels.html), only work with XRP. Order book [auto-bridging](autobridging.html) uses XRP to deepen liquidity for tokens in the decentralized exchange by using XRP as an intermediary when doing so is cheaper. (For example, auto-bridging matches USD:XRP and XRP:EUR orders to augment USD:EUR order books.) - -XRP also serves as a protective measure against spamming the network. All XRP Ledger addresses need a small amount of XRP to offset the costs of maintaining the XRP Ledger. The [transaction cost](transaction-cost.html) and [reserve](reserves.html) are neutral fees denominated in XRP and not paid to any party. In the ledger's data format, XRP is stored in [AccountRoot objects](accountroot.html). - -Some of the desirable properties of XRP come from the nature of the XRP Ledger and its [consensus process](consensus.html). The XRP Ledger does not require mining and the consensus process does not require multiple confirmations for immutability, which makes the XRP Ledger faster and more efficient at processing transactions than Bitcoin and other top cryptocurrencies. - - -## XRP Properties - -The very first ledger contained 100 billion XRP, and no new XRP can be created. XRP can be destroyed by [transaction costs](transaction-cost.html) or lost by sending it to addresses for which no one holds a key, so XRP is slightly [deflationary](https://en.wikipedia.org/wiki/Deflation) by nature. No need to worry about running out, though: at the current rate of destruction, it would take at least 70,000 years to destroy all XRP, and XRP [prices and fees can be adjusted](fee-voting.html) as the total supply of XRP changes. - -In technical contexts, XRP is measured precisely to the nearest 0.000001 XRP, called a "drop" of XRP. The [`rippled` APIs](http-websocket-apis.html) require all XRP amounts to be specified in drops of XRP. For example, 1 XRP is represented as `1000000` drops. For more detailed information, see the [currency format reference](currency-formats.html). - -## History - -### XRP Sales - -The XRP Ledger was built over 2011 – early 2012 by Jed McCaleb, Arthur Britto and David Schwartz. In September 2012, Jed and Arthur, along with Chris Larsen formed Ripple (the company, called OpenCoin Inc. at the time) and decided to gift 80 billion XRP to Ripple in exchange for Ripple developing on the XRP Ledger. Since then, the company has regularly sold XRP, used it to strengthen XRP markets and improve network liquidity, and incentivized development of the greater ecosystem. In 2017, the company [placed 55 billion XRP in escrow](https://ripple.com/insights/ripple-escrows-55-billion-xrp-for-supply-predictability/) to ensure that the amount entering the general supply [grows predictably](https://ripple.com/insights/ripple-to-place-55-billion-xrp-in-escrow-to-ensure-certainty-into-total-xrp-supply/) for the foreseeable future. Ripple's [XRP Market Performance site](https://ripple.com/xrp/market-performance/) reports how much XRP the company has available and locked in escrow at present. - -### Naming - -Originally, the XRP Ledger was called "Ripple" for the way the technology allowed payments [to ripple through multiple hops and currencies](rippling.html). For the native asset built into the ledger, the creators chose the ticker symbol "XRP" from the term "ripple credits" or "ripples" and the X prefix for non-national currencies in the ISO 4217 standard. The company registered itself as "Ripple Labs". The name "XRP" came to be used to refer to the asset in all contexts, to avoid confusion with the similar names for the technology and company, and eventually the company shortened its own name to "Ripple". In May 2018, [the community selected a new "X" symbol](https://twitter.com/xrpsymbol/status/1006925937571713025) to represent XRP to differentiate it from the triskelion logo that had previously been used for both the company and the digital asset. - -| XRP "X" Logo | Ripple triskelion | -|:---------------------------------------|:------------------------------------| -| !["X" logo](assets/img/xrp-x-logo.png) | ![Triskelion](img/ripple-triskelion.png) | - - -The smallest, indivisible unit of XRP was named a "drop" at the suggestion of Ripple forum member ThePiachu. An early alternative term was a "jed", after Jed McCaleb. - -## See Also - -- [Send XRP (Interactive Tutorial)](send-xrp.html) -- [List XRP In Your Exchange](list-xrp-as-an-exchange.html) -- [Currency Formatting in rippled APIs](currency-formats.html#) diff --git a/content/concepts/payment-system-basics/accounts/accounts.ja.md b/content/concepts/payment-system-basics/accounts/accounts.ja.md deleted file mode 100644 index 7854e4af52..0000000000 --- a/content/concepts/payment-system-basics/accounts/accounts.ja.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -html: accounts.html -parent: payment-system-basics.html -blurb: XRP Ledgerのアカウントについて説明します。アカウントはトランザクションを送信でき、XRPを保有できます。 -labels: - - アカウント - - 支払い ---- -# アカウント - -XRP Ledgerの「アカウント」は、XRPの所有者と[トランザクション](transaction-formats.html)の送信者を表します。アカウントの主な要素は次のとおりです。 - -- 識別用の**アドレス**。例えば、`rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn` - - **注記:** XRPコミュニティは、取引所およびウォレットで[宛先タグ](https://xrpl.org/source-and-destination-tags.html)の代わりに使用できる新しいフォーマット、**X**アドレスを[提案](https://github.com/XRPLF/XRPL-Standards/issues/6)（これをサポートする[コーデック](https://github.com/xrp-community/xrpl-tagged-address-codec)も開発）しました。これらの「パック化」したアドレスは、`r`ではなく`X`で開始します。詳細は、[XRPL 𝗫-address format](https://xrpaddress.info/)のサイトを参照してください。 - -- **XRPの残高**。このXRPの一部は、[準備金](reserves.html)用に確保されています。 -- **シーケンス番号**。このアカウントから送信されるトランザクションがすべて、正しい順序で、それぞれ1回のみ適用されるようにします。トランザクションを実行するには、トランザクションのシーケンス番号と送金元のシーケンス番号が一致する必要があります。その後も、トランザクションが適用されている限り、アカウントのシーケンス番号は1ずつ増加します。（関連項目: [基本的なデータタイプ: アカウントシーケンス](basic-data-types.html#アカウントシーケンス)） -- このアカウントと残高に影響を及ぼした**取引の履歴**。 -- [トランザクションの承認](transaction-basics.html#トランザクションの承認)方法。以下に例を示します。 - - アカウント固有のマスターキーのペア。（[無効](accountset.html)にできますが、変更はできません。） - - [ローテーションで使用](setregularkey.html)できる「レギュラー」キーペア。 - - [マルチ署名](multi-signing.html)の署名者のリスト。（アカウントのコアデータとは別に保存されます。） - -アカウントのコアデータは、レジャーのデータツリーの[AccountRoot](accountroot.html)レジャーのオブジェクトタイプに保存されます。アカウントは、他の複数のタイプのデータの所有者（または部分的な所有者）になることもできます。 - -**ヒント:** XRP Ledgerの「アカウント」は、財務上の用途（例:「銀行口座」）やコンピューター上の用途（例:「UNIXアカウント」）で使用されます。XRP以外の通貨および資産はXRP Ledgerアカウント自体には保存されません。そのような資産はそれぞれ、両当事者を結ぶ「トラストライン」と呼ばれる会計関係に保存されます。 - -### アカウントの作成 - -「アカウント作成」専用のトランザクションはありません。Paymentトランザクション でまだアカウントを所有していない数学的に有効なアドレスに[アカウントの準備金](reserves.html)以上のXRPが送信されると、[Paymentトランザクション][]で自動的に新しいアカウントが作成されます。これはアカウントの _資金提供_ と呼ばれ、レジャーに[AccountRootオブジェクト](accountroot.html)が作成されます。それ以外のトランザクションでアカウントを作成することはできません。 - -**注意:** アカウントを資金提供することによって、そのアカウントに対して特別な権限を持つことには**なりません**。アカウントのアドレスに対応するシークレットキーを持っている人なら誰でも、アカウントとそれに含まれるすべてのXRPの完全制御権を持っています。一部のアドレスでは、誰もシークレットキーを持っていない場合があります。その場合、アカウントは[ブラックホール](#特別なアドレス)になり、XRPは永久に失われます。 - -XRP Ledgerでアカウントを取得する一般的な方法は次のとおりです。 - -1. ランダム性の強いソースからキーペアを生成し、そのキーペアのアドレスを計算します。（例えば、[wallet_proposeメソッド][]を使用して計算することができます。） - -2. XRP Ledgerにアカウントをすでに持っているユーザーに、生成したアドレスにXRPを送信してもらいます。 - - - 例えば、一般の取引所でXRPを購入し、その取引所から、指定したアドレスにXRPを引き出すことができます。 - - **注意:** 自身のXRP Ledgerアドレスで初めてXRPを受け取る場合は[アカウントの準備金](reserves.html)（現在は10 XRP）を支払う必要があります。この金額のXRPは無期限に使用できなくなります。一方で、一般の取引所では通常、顧客のXRPはすべて、共有されたいくつかのXRP Ledgerアカウントに保有されているため、顧客はその取引所で個々のアカウントの準備金を支払う必要はありません。引き出す前に、XRP Ledgerに直接アカウントを保有することが、金額に見合う価値があるかどうかを検討してください。 - -## アドレス - -{% include '_snippets/data_types/address.ja.md' %} - -有効なアドレスに資金供給することで、そのアドレスを[XRP Ledgerのアカウントにする](#アカウントの作成)ことができます。[レギュラーキー](setregularkey.html)または[署名者リスト](multi-signing.html)のメンバーを表すために資金供給されていないアドレスを使用することもできます。資金供給されたアカウントのみがトランザクションの送信者になることができます。 - -キーペアを始め、有効なアドレスの作成は、厳密な数学的演算です。キーペアの生成と、そのアドレスの計算は完全にオフラインで行うことができます。XRP Ledgerやその他の関係者と通信する必要はありません。公開鍵からアドレスへの変換には一方向のハッシュ関数が含まれるため、公開鍵がアドレスと一致することは確認できますが、アドレスのみから公開鍵を導出することはできません。（このことが、署名付きのトランザクションに送信者の公開鍵 _と_ アドレスが含まれる理由の1つとなっています。） - -XRP Ledgerアドレスの計算方法の技術的な詳細は、[アドレスのエンコード](#アドレスのエンコード)を参照してください。 - - -### 特別なアドレス - -XRP Ledgerでは、過去の使用という点で、一部のアドレスに特別な意味があります。多くの場合、これらのアドレスは「ブラックホール」アドレスです。つまり、このアドレスは既知のシークレットキーから派生したものではありません。アドレスのみからシークレットキーを推測することは事実上不可能なため、ブラックホールアドレスが保有しているXRPは永久に失われます。 - -| アドレス | 名前 | 意味 | ブラックホール? | -|-----------------------------|------|---------|-------------| -| rrrrrrrrrrrrrrrrrrrrrhoLvTp | ACCOUNT_ZERO | 値`0`を[base58][]形式にエンコードしたXRP Ledgerのアドレス。ピアツーピア通信では、このアドレスは、XRPの発行者として`rippled`で使用されます。 | はい | -| rrrrrrrrrrrrrrrrrrrrBZbvji | ACCOUNT_ONE | 値`1`を[base58][]形式にエンコードしたXRP Ledgerのアドレス。レジャーの[RippleState項目](ripplestate.html)では、このアドレスは、トラストライン残高の発行者のプレースホルダーとして使用されます。 | はい | -| rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh | ジェネシスアカウント | `rippled`で新しいジェネシスレジャーが一から開始される場合（例えば、スタンドアロンモード）、このアカウントはすべてのXRPを保持します。このアドレスは、シード値「masterpassphrase」から生成されており、この値は[ハードコーディング](https://github.com/ripple/rippled/blob/94ed5b3a53077d815ad0dd65d490c8d37a147361/src/ripple/app/ledger/Ledger.cpp#L184)されています。 | いいえ | -| rrrrrrrrrrrrrrrrrNAMEtxvNvQ | Ripple名予約のブラックホール | 以前は、Rippleでは、このアカウントにXRPを送信してRipple名を予約するようユーザーに求めていました。 | はい | -| rrrrrrrrrrrrrrrrrrrn5RM1rHd | NaNアドレス | 以前のバージョンの[ripple-lib](https://github.com/XRPLF/xrpl.js)では、XRP Ledgerの[base58][]文字列エンコード形式を使用して、値[NaN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN)をエンコードするときにこのアドレスを生成しました。 | はい | - - -## アカウントの削除 - -[DeletableAccounts amendment](known-amendments.html#deletableaccounts)（有効2020-05-08）では、アカウントの削除は可能になりました。 - -削除するには、アカウントが次の要件を満たしている必要があります。 - -- アカウントの`Sequence`番号に256を加えた値が、現在の[レジャーインデックス][]未満であること。 -- アカウントが次のタイプの[レジャーオブジェクト](ledger-object-types.html)のいずれにも（送金元または受取人として）関連付けられていないこと。 - - `Escrow` - - `PayChannel` - - `RippleState` - - `Check` -- アカウントがレジャー内に所有するオブジェクトが1000個未満であること。 -- [AccountDeleteトランザクション][]では、少なくとも1アイテムの[所有者準備金](reserves.html)（現在2 XRP）に相当する特別な[トランザクションコスト][]を支払う必要があります。 - -アカウントは、削除した後、通常の[アカウント作成](#アカウントの作成)方法でレジャーに再作成できます。削除後に再作成されたアカウントと、初めて作成されたアカウントに違いはありません。 - -Bitcoinやその他の多くの暗号資産とは異なり、新バージョンのXRP Ledgerの公開レジャーチェーンにはそれぞれレジャーの全状態が含まれており、新規アカウントが増えるごとにサイズが大きくなります。そのため、XRP Ledgerの新規アカウントは必要な場合以外は作成しないでください。アカウントを削除することで、アカウントの[準備金](reserves.html)である10 XRPの一部を復元できますが、そのためには少なくとも2 XRPを消却する必要があります。 - -多くのユーザーに代わって価値を送受信する金融機関などは、XRP Ledgerでは1つ（または少数）のアカウントのみを使用し、顧客との間の個別の決済を区別するために[**ソースタグ**と**宛先タグ**](source-and-destination-tags.html)を使用できます。 - - - - -## トランザクション履歴 - -XRP Ledgerでは、トランザクション（取引）履歴をトランザクションの「スレッド」によって追跡することができます。これはトランザクションの識別用のハッシュとレジャーインデックスにリンクされています。`AccountRoot`レジャーオブジェクトには、それを最後に修正したトランザクションの識別用のハッシュとレジャーが含まれます。そのトランザクションのメタデータには、`AccountRoot`ノードの前の状態が含まれているため、この方法で1つのアカウントの履歴を繰り返すことができます。このトランザクション履歴には、`AccountRoot`ノードを直接変更するトランザクションが含まれます。以下に例を示します。 - -- アカウントによって送信されるトランザクション。アカウントの`Sequence`番号が変更されるため。このようなトランザクションでは、[トランザクションコスト](transaction-cost.html)によりアカウントのXRP残高も変更されます。 -- アカウントのXRP残高を変更したトランザクション。例えば、着信する[Paymentトランザクション][]や他のタイプの取引（例:[PaymentChannelClaim][]や[EscrowFinish][]）。 - -アカウントの _概念的な_ トランザクション履歴には、アカウントの所有オブジェクトとXRP以外の残高を変更したトランザクションも含まれます。これらのオブジェクトは別個のレジャーオブジェクトであり、それぞれに影響を及ぼした独自のトランザクションスレッドが含まれます。アカウントのレジャーの履歴全体がある場合は、それをたどって、その履歴によって作成または変更されたレジャーオブジェクトを見つけることができます。「完全」なトランザクション履歴には、トランザクションで所有されているオブジェクトの履歴が含まれます。例を以下に示します。 - -- `RippleState`オブジェクト（トラストライン）。アカウントに関連付けられています。 -- `DirectoryNode`オブジェクト（特にアカウントの所有オブジェクトを追跡する所有者ディレクトリ）。 -- `Offer`オブジェクト。分散型取引所でのアカウントの未処理の取引注文を表すオブジェクト。 -- `PayChannel` アカウントとの間の非同期のPayment Channelを表すオブジェクト。 -- `Escrow` 時間または暗号条件によってロックされ、アカウントとの間の保留中の支払いを表すオブジェクト。 -- `SignerList` [マルチ署名](multi-signing.html)によってアカウントのトランザクションを承認できるアドレスのリストを表すオブジェクト。 - -これらの各オブジェクトの詳細は、[レジャーフォーマットのリファレンス](ledger-data-formats.html)を参照してください。 - - -## アドレスのエンコード - -**ヒント:** これらの技術的な詳細は、XRP Ledgerとの互換性を保つために低レベルのライブラリソフトウェアを構築しているユーザーのみを対象としています。 - -[[ソース]](https://github.com/ripple/rippled/blob/35fa20a110e3d43ffc1e9e664fc9017b6f2747ae/src/ripple/protocol/impl/AccountID.cpp#L109-L140 "Source") - -XRP Ledgerのアドレスは、[base58][]_形式のディクショナリ_`rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz`を使用してエンコードされています。XRP Ledgerはbase58でいくつかのタイプのキーをエンコードするため、それらを区別するためにエンコードされたデータの前に1バイトの「タイププレフィクス」（「バージョンプレフィクス」とも呼ばれます）を付けます。タイププレフィクスによりアドレスは通常、base58形式の異なる文字で始まります。 - -次の図は、キーとアドレスの関係を示しています。 - -[![マスター公開鍵 + プレフィクスの種類 → アカウントID + チェックサム → アドレス](img/address-encoding.ja.png)](img/address-encoding.ja.png) - -公開鍵からXRP Ledgerアドレスを計算する式は次のとおりです。コード例全体については、[`encode_address.js`](https://github.com/XRPLF/xrpl-dev-portal/blob/master/content/_code-samples/address_encoding/js/encode_address.js)を参照してください。パスフレーズまたはシード値から公開鍵を導出するプロセスについては、[鍵の導出](cryptographic-keys.html#鍵導出)を参照してください。 - -1. 次の必須アルゴリズムをインポートします。SHA-256、RIPEMD160、base58。base58のディクショナリーを設定します。 - - 'use strict'; - const assert = require('assert'); - const crypto = require('crypto'); - const R_B58_DICT = 'rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz'; - const base58 = require('base-x')(R_B58_DICT); - - assert(crypto.getHashes().includes('sha256')); - assert(crypto.getHashes().includes('ripemd160')); - -2. 33バイトのECDSA secp256k1公開鍵、または32バイトのEd25519公開鍵で始めます。Ed25519キーの場合は、キーの前にバイト`0xED`を付けます。 - - const pubkey_hex = - 'ED9434799226374926EDA3B54B1B461B4ABF7237962EAE18528FEA67595397FA32'; - const pubkey = Buffer.from(pubkey_hex, 'hex'); - assert(pubkey.length == 33); - -3. 公開鍵のSHA-256ハッシュの[RIPEMD160](https://en.wikipedia.org/wiki/RIPEMD)ハッシュを計算します。この値は「Account ID」です。 - - const pubkey_inner_hash = crypto.createHash('sha256').update(pubkey); - const pubkey_outer_hash = crypto.createHash('ripemd160'); - pubkey_outer_hash.update(pubkey_inner_hash.digest()); - const account_id = pubkey_outer_hash.digest(); - -4. アカウントIDのSHA-256ハッシュのSHA-256ハッシュを計算します。最初の4バイトを使用ます。この値が「チェックサム」です。 - - const address_type_prefix = Buffer.from([0x00]); - const payload = Buffer.concat([address_type_prefix, account_id]); - const chksum_hash1 = crypto.createHash('sha256').update(payload).digest(); - const chksum_hash2 = crypto.createHash('sha256').update(chksum_hash1).digest(); - const checksum = chksum_hash2.slice(0,4); - -5. ペイロードとチェックサムを連結します。連結バッファーのbase58値を計算します。この結果が、該当のアドレスになります。 - - const dataToEncode = Buffer.concat([payload, checksum]); - const address = base58.encode(dataToEncode); - console.log(address); - // rDTXLQ7ZKZVKz33zJbHjgVShjsBnqMBhmN - - -## 関連項目 - -- **コンセプト:** - - [準備金](reserves.html) - - [暗号鍵](cryptographic-keys.html) - - [発行アドレスと運用アドレス](issuing-and-operational-addresses.html) -- **リファレンス:** - - [account_infoメソッド][] - - [wallet_proposeメソッド][] - - [AccountSetトランザクション][] - - [Paymentトランザクション][] - - [AccountRootオブジェクト](accountroot.html) -- **チュートリアル:** - - [アカウント設定の管理（カテゴリー）](manage-account-settings.html) - - [WebSocketを使用した着信ペイメントの監視](monitor-incoming-payments-with-websocket.html) - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-system-basics/accounts/accounts.md b/content/concepts/payment-system-basics/accounts/accounts.md deleted file mode 100644 index d23cbb1677..0000000000 --- a/content/concepts/payment-system-basics/accounts/accounts.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -html: accounts.html -parent: payment-system-basics.html -blurb: Learn about accounts in the XRP Ledger. Accounts can send transactions and hold XRP. -labels: - - Accounts - - Payments ---- -# Accounts - -An "Account" in the XRP Ledger represents a holder of XRP and a sender of [transactions](transaction-formats.html). The core elements of an account are: - -- An identifying **address**, such as `rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn`. (This is a "classic address", as opposed to the [X-Address format](#addresses).) -- An **XRP balance**. Some of this XRP is set aside for the [Reserve](reserves.html). -- A **sequence number**, which helps make sure any transactions this account sends are applied in the correct order and only once each. 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. (See also: [Basic Data Types: Account Sequence](basic-data-types.html#account-sequence).) -- A **history of transactions** that affected this account and its balances. -- One or more ways to [authorize transactions](transaction-basics.html#authorizing-transactions), possibly including: - - A master key pair intrinsic to the account. (This can be [disabled](accountset.html) but not changed.) - - A "regular" key pair that [can be rotated](setregularkey.html). - - A signer list for [multi-signing](multi-signing.html). (Stored separately from the account's core data.) - -In the ledger's data tree, an account's core data is stored in the [AccountRoot](accountroot.html) 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 aren't stored in an XRP Ledger Account itself; each such asset is stored in an accounting relationship called a "Trust Line" that connects two parties. - -### Creating Accounts - -There is not a dedicated "create account" transaction. The [Payment transaction][] automatically creates a new account if the payment sends XRP equal to or greater than the [account reserve](reserves.html) to a mathematically-valid address that does not already have an account. This is called _funding_ an account, and creates an [AccountRoot object](accountroot.html) 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's possible that no one has the secret key, in which case the account is a [black hole](#special-addresses) 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](reserves.html) (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. - -## Addresses - -{% include '_snippets/data_types/address.md' %} - -Any valid address can [become an account in the XRP Ledger](#creating-accounts) by being funded. You can also use an address that has not been funded to represent a [regular key](setregularkey.html) or a member of a [signer list](multi-signing.html). 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). - - -### 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 | - - -## Deletion of Accounts - -The [DeletableAccounts amendment](known-amendments.html#deletableaccounts) (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](ledger-object-types.html) (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](reserves.html) for one item (currently 2 XRP). - -After an account has been deleted, it can be re-created in the ledger through the normal method of [creating accounts](#creating-accounts). An account that has been deleted and re-created is no different than an account that has been 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](submit.html) 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](reserves.html) 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**](source-and-destination-tags.html) to distinguish payments from and to their customers while only using one (or a handful) of accounts in the XRP Ledger. - - - - -## 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](transaction-cost.html). -- 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](multi-signing.html). - -For more information on each of these objects, see the [Ledger Format Reference](ledger-data-formats.html). - - -## 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. - -The following diagram shows the relationship between keys and addresses: - -{{ include_svg("img/address-encoding.svg", "Master Public Key + Type Prefix → Account ID + Checksum → Address") }} - -The formula for calculating an XRP Ledger address from a public key is as follows. For the complete example code, see [`encode_address.js`](https://github.com/XRPLF/xrpl-dev-portal/blob/master/content/_code-samples/address_encoding/js/encode_address.js). For the process of deriving a public key from a passphrase or seed value, see [Key Derivation](cryptographic-keys.html#key-derivation). - -1. Import required algorithms: SHA-256, RIPEMD160, and base58. Set the dictionary for base58. - - 'use strict'; - const assert = require('assert'); - const crypto = require('crypto'); - const R_B58_DICT = 'rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz'; - const base58 = require('base-x')(R_B58_DICT); - - assert(crypto.getHashes().includes('sha256')); - assert(crypto.getHashes().includes('ripemd160')); - -2. Start with a 33-byte ECDSA secp256k1 public key, or a 32-byte Ed25519 public key. For Ed25519 keys, prefix the key with the byte `0xED`. - - const pubkey_hex = - 'ED9434799226374926EDA3B54B1B461B4ABF7237962EAE18528FEA67595397FA32'; - const pubkey = Buffer.from(pubkey_hex, 'hex'); - assert(pubkey.length == 33); - -3. Calculate the [RIPEMD160](https://en.wikipedia.org/wiki/RIPEMD) hash of the SHA-256 hash of the public key. This value is the "Account ID". - - const pubkey_inner_hash = crypto.createHash('sha256').update(pubkey); - const pubkey_outer_hash = crypto.createHash('ripemd160'); - pubkey_outer_hash.update(pubkey_inner_hash.digest()); - const account_id = pubkey_outer_hash.digest(); - -4. Calculate the SHA-256 hash of the SHA-256 hash of the Account ID; take the first 4 bytes. This value is the "checksum". - - const address_type_prefix = Buffer.from([0x00]); - const payload = Buffer.concat([address_type_prefix, account_id]); - const chksum_hash1 = crypto.createHash('sha256').update(payload).digest(); - const chksum_hash2 = crypto.createHash('sha256').update(chksum_hash1).digest(); - const checksum = chksum_hash2.slice(0,4); - -5. Concatenate the payload and the checksum. Calculate the base58 value of the concatenated buffer. The result is the address. - - const dataToEncode = Buffer.concat([payload, checksum]); - const address = base58.encode(dataToEncode); - console.log(address); - // rDTXLQ7ZKZVKz33zJbHjgVShjsBnqMBhmN - - -## See Also - -- **Concepts:** - - [Reserves](reserves.html) - - [Cryptographic Keys](cryptographic-keys.html) - - [Issuing and Operational Addresses](issuing-and-operational-addresses.html) -- **References:** - - [account_info method][] - - [wallet_propose method][] - - [AccountSet transaction][] - - [Payment transaction][] - - [AccountRoot object](accountroot.html) -- **Tutorials:** - - [Manage Account Settings (Category)](manage-account-settings.html) - - [Monitor Incoming Payments with WebSocket](monitor-incoming-payments-with-websocket.html) - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-system-basics/accounts/cryptographic-keys.ja.md b/content/concepts/payment-system-basics/accounts/cryptographic-keys.ja.md deleted file mode 100644 index ac1b15920a..0000000000 --- a/content/concepts/payment-system-basics/accounts/cryptographic-keys.ja.md +++ /dev/null @@ -1,249 +0,0 @@ ---- -html: cryptographic-keys.html -parent: accounts.html -blurb: 暗号鍵を使用してトランザクションを承認し、XRP Ledgerがトランザクションを実行できるようにします。 -labels: - - セキュリティ - - スマートコントラクト ---- -# 暗号鍵 - -XRP Ledgerでは、[トランザクション](transaction-basics.html)による一連の具体的なアクションの実行が承認されていることを、デジタル署名によって証明します。署名されたトランザクションのみがネットワークに送信され、検証済みレジャーに含まれます。 - -すべてのデジタル署名は、トランザクションの送信側アカウントに関連付けられている暗号鍵ペアに基づいています。キーペアはXRP Ledgerでサポートされている[暗号化署名アルゴリズム](#署名アルゴリズム)を使用して生成できます。キーペアの生成に使用されたアルゴリズムの種類にかかわらず、キーペアは[マスターキーペア](#マスターキーペア)、[レギュラーキーペア](#レギュラーキーペア)、または[署名者リスト](multi-signing.html)のメンバーとして使用できます。 - -**警告:** 秘密鍵のセキュリティを適切に維持することが重要です。デジタル署名は、あなたがトランザクション送信する権限を有していることをXRP Ledgerに対して検証できる唯一の手段であり、レジャーに提出されたトランザクションの取り消しや無効化を行う権限を有する管理者は存在しません。お使いのXRP Ledgerアカウントの秘密鍵があなた以外の何者かに知られた場合、その人物はあなたと同様にデジタル署名を作成し、トランザクションを承認することができます。 - -## キーの生成 - -[`wallet_propose`](wallet_propose.html)メソッドを使用してキーペアを生成します。以下は、`wallet_propose`の応答例です。 - -``` -{ - "result": { - "account_id": "rDGnaDqJczDAjrKHKdhGRJh2G7zJfZhj5q", - "key_type": "secp256k1", - "master_key": "COON WARN AWE LUCK TILE WIRE ELI SNUG TO COVE SHAM NAT", - "master_seed": "sstV9YX8k7yTRzxkRFAHmX7EVqMfX", - "master_seed_hex": "559EDD35041D3C11F9BBCED912F4DE6A", - "public_key": "aBQXEw1vZD3guCX3rHL8qy8ooDomdFuxZcWrbRZKZjdDkUoUjGVS", - "public_key_hex": "0351BDFB30E7924993C625687AE6127034C4A5EBA78A01E9C58B0C46E04E3A4948" - }, - "status": "success", - "type": "response" -} -``` - -この応答には、キーペア（さまざまなフォーマットのシードと公開鍵）と`account_id`が含まれています。 - -**シード** - -_シード_ 値は、アカウントの実際の秘密鍵（および公開鍵）を[導出する](#鍵導出)ために使用されるコンパクトな値です。`master_key`、`master_seed`、および`master_seed_hex`はすべて、同じシード値を表しますが、フォーマットが異なります。これらのいずれのフォーマットも、[`rippled` API](http-websocket-apis.html)や[その他のXRPLソフトウェア](software-ecosystem.html)で[トランザクションに署名](transaction-basics.html#トランザクションへの署名とトランザクションの送信)するときに使用することができます。キーの先頭に`master_`が付いていますが、このシードが表すキーが必ずしもアカウントのマスターキーであるとは限りません。キーペアは、レギュラーキーだけでなく、マルチ署名のリストのメンバーとしても使用できます。 - -シード値はアカウントのその他のあらゆる情報の基盤であるため、慎重に保護する必要があります。アドレスのシード値を知っている人なら誰でも、事実上そのアドレスを完全に制御できます。 - -**秘密鍵** - -`wallet_propose`応答には、秘密鍵（ _プライベートキー_ とも呼ばれます）の値が明示的に示されていません。トランザクションに署名できるソフトウェアであれば、シード値から[秘密鍵を導出](#鍵導出)可能であると考えられます。 - -**公開鍵** - -`public_key`と`public_key_hex`はいずれも、同一値の公開鍵を表します。公開鍵は、鍵導出の一環として秘密鍵から導出されます。公開鍵を使用すると、トランザクション署名の真正性を検証できますが、それ以上の署名を作成することはできません。 - -**account_id** - -`account_id`は[公開鍵から生成され](accounts.html#アドレスのエンコード)、アカウントがXRP Ledgerに作成される*可能性*を示します。`account_id`が存在していても、`account_id`が最初の XRPでの支払いを受領するまでは、実際のアカウントはXRP Ledgerに存在しません。さらに`account_id`は、資金を供給するトランザクションを受領して、アカウントが作成されるまでは、トランザクションを送信することができません。 - -ただし、（資金供給されたアカウントのない）`account_id`は、既存の別のアカウントのトランザクションを承認する際に[レギュラーキー](#レギュラーキーペア)または[署名者リストのメンバー](multi-signing.html)として使用できます。 - -資金供給されたアカウントを作成してレジャーに保管するには、`account_id`が、[必要準備金](reserves.html)を満たすのに十分なXRPを供給する[`Payment`トランザクションを受領する](payment.html#アカウントの作成)必要があります。 - -`wallet_propose`応答についての詳細は、[`wallet_propose`](wallet_propose.html)を参照してください。 - -生成されたキーペアは、[マスターキーペア](#マスターキーペア)、[レギュラーキーペア](#レギュラーキーペア)、または[署名者リストメンバー](multi-signing.html)のいずれかとして使用できます。 - -**キータイプ** - -`key_type`フィールドは、このキーペアの生成に使用された[暗号化署名アルゴリズム](#署名アルゴリズム)を示します。[wallet_proposeメソッド][]を使用したキーペアの生成を要求するときに、`key_type`を指定できます。 - - -## マスターキーペア - -マスターキーペアは秘密鍵と公開鍵で構成されます。マスターキーペアの秘密鍵は、レギュラーキーペアで署名できるすべてのトランザクションに署名できるほか、以下の操作の実行に使用できる唯一の鍵でもあります。 - -* [マスター公開鍵を無効にする](accountset.html)。 - -* [凍結](freezes.html#no-freeze)機能を永久に放棄する。 - -* トランザクションコストが0の[Key Resetトランザクション](transaction-cost.html#key-resetトランザクション)を送信する。 - -アカウントのマスターキーペアは、マスターキーペアによるトランザクションへの署名が承認されているアカウントの`account_id`と同じ[`wallet_propose`](wallet_propose.html)応答にて生成されます。マスターキーペアは同じ応答内で生成されるため、アドレスに[固有に関連付け](accounts.html#アドレスのエンコード)られています。このアドレスは、公開鍵から導出されます。 - -これは、同様に`wallet_propose`メソッドを使用して生成されても、レギュラーキーペアとしてアカウントに明示的に割り当てられる必要があるレギュラーキーペアとは対照的です。レギュラーキーペアは明示的に割り当てられるため、トランザクションの署名が承認されているアカウントのアドレスには固有に関連付けられません。詳細は、[レギュラーキーペア](#レギュラーキーペア)を参照してください。 - -**注意:** マスターキーペアは変更できませんが、無効にできます。つまり、マスターシードまたは秘密鍵が漏えいした場合は、変更するのではなく、[無効にする](accountset.html)必要があります。 - -マスターキーペアは変更できないため、漏えいが発生した場合には無効化せざるを得ません。[マスターキーペアをオフラインで保管](offline-account-setup.html)し、代わりにアカウントのトランザクションの署名用にレギュラーキーペアを設定することを強くお勧めします。 - -マスターキーペアをオフラインで保管する際には、不正使用者がアクセスできる場所にマスター秘密鍵を保管しないようにします。たとえば、インターネットに一切接続されない物理的に隔離されたマシンに保管したり、紙に記入して安全な場所に保管します。一般的には、インターネットと相互にやり取りをするコンピュータプログラムがアクセスできる範囲内には保管しません。マスターキーペアは、緊急時（漏えいの恐れがある場合や実際に漏えいが発生した場合にレギュラーキーペアを変更するなど）に限り、最も信頼できるデバイスでのみ使用することが理想的です。 - - -## レギュラーキーペア - -XRP Ledgerでは、アカウントのマスターキーペアをオフラインで保管し、その後のトランザクションには _レギュラーキーペア_ と呼ばれるセカンダリキーペアで署名することができます。レギュラーキーペアのシードまたは秘密鍵が漏えいした場合は、キーペアを削除または交換できます。その際に、アカウントのキーペア以外の設定を変更する必要はありません。これにより、アカウントの設定や他のアカウントとの関係を再設定する手間が省けます。レギュラーキーペアを積極的にローテーションすることも可能です。（アカウントのアドレスに固有に関連付けられているアカウントのマスターキーペアでは、このような操作は実行できません。） - -レギュラーキーペアとして使用するキーペアは、[`wallet_propose`](wallet_propose.html)メソッドを使用して生成します。ただし、サポートするアカウントの`account_id`と同時に生成され、それに固有に関連付けられている[マスターキーペア](#マスターキーペア)とは異なり、レギュラーキーペアと、このキーペアがトランザクションの署名に使用されるアカウントとの関係を明示的に作成する必要があります。レギュラーキーペアをアカウントに割り当てるには、[`SetRegularKey`](setregularkey.html)メソッドを使用します。 - -レギュラーキーペアの割り当てに関するチュートリアルについては、[レギュラーキーペアの割り当て](assign-a-regular-key-pair.html)を参照してください。 - -レギュラーキーペアを割り当てたアカウントには、次の2つのキーペアが関連付けられることになります。 - -* アカウントの`account_id`に固有に関連付けられるマスターキーペア。オフラインで保管します。 -* アカウントに明示的に割り当てられ、アカウントのトランザクションの署名に使用されるレギュラーキーペア。 - -レギュラーキーペアをアカウントに割り当てて、[マスターキーペア](#マスターキーペア)で署名されるトランザクションを除く、すべてのトランザクションの署名にそのレギュラーキーペアを使用できます。 - -レギュラーキーペアはいつでも削除または変更できます。つまり、レギュラーキーペアの秘密鍵が漏えいした（ただしマスターキーペアの秘密鍵の漏えいは発生していない）場合、レギュラーキーペアを削除または変更するだけでアカウントの制御を取り戻すことができます。 - -レギュラーキーペアの変更または削除のチュートリアルについては、[レギュラーキーペアの割り当て](assign-a-regular-key-pair.html)を参照してください。 - - -## 署名アルゴリズム - -暗号鍵ペアは常に特定の署名アルゴリズムに関連付けられています。署名アルゴリズムは、秘密鍵と公開鍵の間の数学的関係を定義します。暗号化署名アルゴリズムには、現在の暗号技術では、秘密鍵を使用して対応する公開鍵を「簡単に」計算できるものの、公開鍵から対応する秘密鍵を計算することは実質的に不可能であるという特性があります。 - -XRP Ledgerでは次の暗号化署名アルゴリズムがサポートされています。 - -| キータイプ | アルゴリズム | 説明 | -|-------------|-----------|---| -| `secp256k1` | 楕円曲線[secp256k1](https://en.bitcoin.it/wiki/Secp256k1)を使用する[ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) | これはBitcoinで使用されているスキームです。XRP Ledgerではデフォルトでこのキータイプが使用されます。 | -| `ed25519` | 楕円曲線[Ed25519](https://ed25519.cr.yp.to/)を使用する[EdDSA](https://tools.ietf.org/html/rfc8032) | パフォーマンスに優れ、その他の便利な特性を備えた新しいアルゴリズムです。Ed25519公開鍵はsecp256k1鍵よりも1バイト短いため、`rippled`ではEd25519公開鍵の先頭に`0xED`バイトが追加されます。これにより、両方の公開鍵タイプは33バイトになります。 | - -[wallet_proposeメソッド][]を使用してキーペアを生成するときには、キーの生成に使用する暗号化署名アルゴリズムを選択するため`key_type`を指定できます。デフォルト以外のキータイプを生成した場合は、トランザクションに署名する際に`key_type`も指定する必要があります。 - -XRP Ledgerでは、サポートされているさまざまなタイプのキーペアは、マスターキーペア、レギュラーキーペア、署名者リストメンバーとして互換的に使用できます。[アドレス生成](accounts.html#アドレスのエンコード)プロセスは、secp256k1キーペアとEd25519キーペアでは同一です。 - -**注記:** 現時点では、Ed25519キーで[Payment Channelクレーム](use-payment-channels.html)に署名することはできません。これはバグです。 - -### 将来のアルゴリズム - -今後、暗号技術の発展に対応するため、XRP Ledgerには新しい暗号化署名アルゴリズムが必要になるでしょう。例えば、[Shorのアルゴリズム](https://en.wikipedia.org/wiki/Shor's_algorithm)（または類似のアルゴリズム）を使用する量子コンピューターの実用化が間近となり、楕円曲線暗号が解読される可能性が生じた場合、XRP Ledger開発者は容易に解読できない暗号化署名アルゴリズムを追加できます。2019年半ばの時点で、確実な第一選択肢となる「耐量子」署名アルゴリズムはなく、量子コンピューターはまだ脅威となるほど実用的ではないため、現時点では特定のアルゴリズムを追加する予定はありません。 - - -## 鍵導出 - -キーペアを導出するプロセスは、署名アルゴリズムによって異なります。いずれの場合も、キーは長さが16バイト（128ビット）の _シード_ 値から生成されます。シード値は完全にランダムにする（推奨）か、[SHA-512ハッシュ][ハッシュ]を取得して最初の16バイトを保持することで特定のパスフレーズから導出することができます（[SHA-512ハーフ][]と同様ですが、出力の256ビットではなく128ビットのみを保持します）。 - -### サンプルコード - -ここで説明する鍵導出プロセスは、さまざまなプログラミング言語で複数の場所に実装されています。 - -- C++: `rippled`コードベース: - - [シード定義](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/Seed.h) - - [汎用キー & Ed25519鍵導出](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/impl/SecretKey.cpp) - - [secp256k1鍵導出](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/impl/SecretKey.cpp) -- Python 3: [このリポジトリのコードサンプルセクション]({{target.github_forkurl}}/blob/{{target.github_branch}}/content/_code-samples/key-derivation/py/key_derivation.py)。 -- JavaScript: [`ripple-keypairs`](https://github.com/ripple/ripple-keypairs/)パッケージ。 - -### Ed25519鍵導出 -[[ソース]](https://github.com/ripple/rippled/blob/fc7ecd672a3b9748bfea52ce65996e324553c05f/src/ripple/protocol/impl/SecretKey.cpp#L203 "Source") - -[![パスフレーズ → シード → 秘密鍵 → プレフィクス + 公開鍵](img/key-derivation-ed25519.ja.png)](img/key-derivation-ed25519.ja.png) - -1. シード値の[SHA-512ハーフ][]を計算します。32バイトの秘密鍵が導出されます。 - - **ヒント:** 32バイトの数値はすべて、有効なEd25519秘密鍵です。ただし、秘密鍵として使用する上で安全なのは、十分ランダムに選択された数値のみです。 - -2. Ed25519公開鍵を計算するには、[Ed25519](https://ed25519.cr.yp.to/software.html)の標準公開鍵を導出して、32バイトの公開鍵を導出します。 - - **注意:** 暗号化アルゴリズムの場合と同様に、可能な場合は必ず、公的に監査された既知の標準実装を使用します。例えば、[OpenSSL](https://www.openssl.org/)には、コア関数であるEd25519やsecp256k1が実装されています。 - -3. Ed25519公開鍵を示すには、32バイトの公開鍵の前にシングルバイトのプレフィクス`0xED`を付加し、33バイトにします。 - - トランザクションに署名するコードを実装している場合は、プレフィクス`0xED`を削除し、実際の署名プロセスに32バイトキーを使用します。 - -4. アカウントの公開鍵を[base58][]にシリアル化する場合は、アカウントの公開鍵プレフィクス`0x23`を使用します。 - - バリデータの一時キーにEd25519を使用することはできません。 - -### secp256k1鍵導出 - -[[ソース]](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/impl/SecretKey.cpp "Source") - -[![パスフレーズ → シード → ルートキーペア → 仲介銀行（機関）キーペア → マスターキーペア](img/key-derivation-secp256k1.ja.png)](img/key-derivation-secp256k1.ja.png) - -XRP Ledgerアカウントキーでのsecp256k1鍵導出に、Ed25519鍵導出よりも多くの手順が含まれる理由は次のとおりです。 - -- 32バイトの数値がすべて、有効なsecp256k1秘密鍵であるとは限りません。 -- XRP Ledgerのリファレンス実装には、単一のシード値からキーペアのファミリーを導出するための、未使用の不完全なフレームワークがあります。 - -シード値からXRP Ledgerのsecp256k1アカウントキーペアを導出する手順は次のとおりです。 - -1. 次のように、シード値から「ルートキーペア」を計算します。 - - 1. 以下を順番に連結して、合計20バイトにします。 - - - シード値（16バイト） - - 「ルートシーケンス」値（4バイト）。ビッグエンディアンの符号なし整数。ルートシーケンスの開始値として0を使用します。 - - 2. 連結された（シード+ルートシーケンス）値の[SHA-512ハーフ][]を計算します。 - - 3. 結果が有効なsecp256k1秘密鍵でない場合は、ルートシーケンスを1増やして最初からやり直します。[[ソース]](https://github.com/ripple/rippled/blob/fc7ecd672a3b9748bfea52ce65996e324553c05f/src/ripple/crypto/impl/GenerateDeterministicKey.cpp#L103 "Source") - - 有効なsecp256k1鍵は0であってはならず、 _secp256k1グループ_ の数値順よりも低くなければなりません。secp256k1グループの順序は、定数`0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141`です。 - - 4. 有効なsecp256k1秘密鍵を使用して、secp256k1曲線で標準ECDSA公開鍵を導出し、ルート公開鍵を導出します。（暗号化アルゴリズムの場合と同様に、可能な場合は必ず、公的に監査された既知の標準実装を使用します。例えば、[OpenSSL](https://www.openssl.org/)には、コア関数であるEd25519およびsecp256k1が実装されています。） - - **ヒント:** バリデータではこのルートキーペアを使用します。バリデータのキーペアを計算する場合は、ここで停止できます。この2つのタイプの公開鍵を区別するには、バリデータの公開鍵の[base58][]シリアル化でプレフィクス`0x1c`を使用します。 - -2. ルート公開鍵を33バイトの圧縮形式に変換します。 - - ECDSA公開鍵の非圧縮形式は、32バイト整数のペア（X座標とY座標）で構成されます。圧縮形式は、X座標と1バイトのプレフィクスのみで構成されます。Y座標が偶数の場合は`0x02`、Y座標が奇数の場合は`0x03`です。 - - 非圧縮形式の公開鍵を圧縮形式に変換するには、`openssl`コマンドラインツールを使用します。例えば、非圧縮の公開鍵がファイル`ec-pub.pem`にある場合は、次のような圧縮形式を出力できます。 - - $ openssl ec -in ec-pub.pem -pubin -text -noout -conv_form compressed - -3. 次のように、圧縮されたルート公開鍵から「仲介銀行（機関）キーペア」を導出します。 - - 1. 以下を順番に連結して、合計40バイトにします。 - - 圧縮されたルート公開鍵（33バイト） - - `0x00000000000000000000000000000000` (4バイトのゼロ)（この値は、同じファミリーの異なるメンバーの導出に使用することを目的としていましたが、実際には値0のみが使用されます。） - - 「キーシーケンス」値（4バイト）。ビッグエンディアンの符号なし整数。キーシーケンスの開始値として0を使用します。 - - 2. 連結された値の[SHA-512ハーフ][]を計算します。 - - 3. 結果が有効なsecp256k1秘密鍵でない場合は、キーシーケンスを1増やし、アカウントの仲介銀行（機関）キーペアの導出をやり直します。 - - 4. 有効なsecp256k1秘密鍵を使用して、secp256k1曲線で標準ECDSA公開鍵を導出し、仲介銀行（機関）公開鍵を導出します。（暗号化アルゴリズムの場合と同様に、可能な場合は必ず、公的に監査された既知の標準実装を使用します。例えば、[OpenSSL](https://www.openssl.org/)には、コア関数であるEd25519およびsecp256k1が実装されています。） - -4. 仲介銀行（機関）公開鍵をルート公開鍵に追加して、マスター公開鍵ペアを導出します。同様に、仲介銀行（機関）秘密鍵をルート秘密鍵に追加して秘密鍵を導出します。 - - - ECDSA秘密鍵は非常に大きな整数値であるため、secp256k1グループ順序を法として2つの秘密鍵を合計することで、2つの秘密鍵の合計を計算できます。 - - - ECDSA公開鍵は楕円曲線上の点であるため、楕円曲線の数値を使用して点の合計値を計算する必要があります。 - -5. 以前と同様に、マスター公開鍵を33バイトの圧縮形式に変換します。 - -6. アカウントの公開鍵を[base58][]形式にシリアル化する場合は、アカウントの公開鍵プレフィクス`0x23`を使用します。 - - アカウントの公開鍵からそのアドレスに変換するための情報とサンプルコードについては、[アドレスのエンコード](accounts.html#アドレスのエンコード)を参照してください。 - - -## 関連項目 - -- **コンセプト:** - - [発行アドレスと運用アドレス](issuing-and-operational-addresses.html) -- **チュートリアル:** - - [レギュラーキーペアの割り当て](assign-a-regular-key-pair.html) - - [レギュラーキーペアの変更または削除](change-or-remove-a-regular-key-pair.html) -- **リファレンス:** - - [SetRegularKeyトランザクション][] - - [AccountRootレジャーオブジェクト](accountroot.html) - - [wallet_proposeメソッド][] - - [account_infoメソッド][] - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-system-basics/accounts/cryptographic-keys.md b/content/concepts/payment-system-basics/accounts/cryptographic-keys.md deleted file mode 100644 index 70a78fd443..0000000000 --- a/content/concepts/payment-system-basics/accounts/cryptographic-keys.md +++ /dev/null @@ -1,259 +0,0 @@ ---- -html: cryptographic-keys.html -parent: accounts.html -blurb: Use cryptographic keys to approve transactions so the XRP Ledger can execute them. -labels: - - Smart Contracts - - Security ---- -# Cryptographic Keys - -In the XRP Ledger, a digital signature _authorizes_ a [transaction](transaction-basics.html) 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](#master-key-pair), [regular key pair](#regular-key-pair) or a member of a [signer list](multi-signing.html), 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](client-libraries.html) 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](#signing-algorithms) 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.) - -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](#key-derivation) 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](transaction-basics.html#signing-and-submitting-transactions) in the [`rippled` APIs](http-websocket-apis.html) and some [other XRP Ledger software](software-ecosystem.html). 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](#key-derivation) 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](accounts.html) 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](source-and-destination-tags.html) 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](accounts.html#creating-accounts) that funds its [reserve requirement](reserves.html). 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](#regular-key-pair) or a [member of a signer list](multi-signing.html). - -### Key Type - -The XRP Ledger supports more than one [cryptographic signing algorithm](#signing-algorithms). 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](accounts.html#address-encoding). 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](offline-account-setup.html) 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](transaction-basics.html#authorizing-transactions). - -- Disable the master key pair. - -- Permanently give up the ability to [freeze](freezes.html#no-freeze). - -- Send a special [key reset transaction](transaction-cost.html#key-reset-transaction) with a transaction cost of 0 XRP. - -A regular key or [multi-signature](multi-signing.html) 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](accounts.html#deletion-of-accounts) 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](#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](#special-permissions). 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. - -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](accounts.html#address-encoding) 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. - - -## 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](accounts.html#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][] - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-system-basics/accounts/depositauth.ja.md b/content/concepts/payment-system-basics/accounts/depositauth.ja.md deleted file mode 100644 index 7408e6c080..0000000000 --- a/content/concepts/payment-system-basics/accounts/depositauth.ja.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -html: depositauth.html -parent: accounts.html -blurb: DepositAuth設定をすると、アカウントは着信ペイメントをデフォルトでブロックします。 -labels: - - セキュリティ - - 支払い ---- -# Deposit Authorization - -_（[DepositAuth Amendment][]が必要です。）_ - -Deposit Authorization は、XRP Ledgerの[アカウント](accounts.html)のオプション機能です。Deposit Authorizationが有効な場合、トランザクションはそのトランザクションの送信者がアカウント自体でない限り、アカウントへはどのような資産も送信できません。これには、XRPと発行済み通貨の送金が含まれます。 - -デフォルトでは、新しいアカウントではDepositAuthが無効になっています。 - -## 背景 - -金融サービスの規制やライセンスによっては、企業や組織に対して、受領するすべてのトランザクションの送信者を把握するよう義務付けています。これは、自由に生成できる偽名で参加者を識別し、デフォルトですべてのアドレスからあらゆる宛先への支払いを可能とするXRP Ledgerのような分散型システムとっては課題となります。 - -Deposit Authorizationフラグにより、XRP Ledgerを使用するユーザーが分散型レジャーの基本的な特性を変えずにこのような規制に準拠するためのオプションを採用しました。Deposit Authorizationが有効な場合、アカウントはトランザクションを送信することで明示的に承認した資金のみを受領できます。Deposit Authorizationを使用するアカウントの所有者は、アカウントに資金を入金するトランザクションを送信する _前に_ 、資金の送金元の確認に必要なデューディリジェンス（確認調査）を実施できます。 - -Deposit Authorizationを有効にすると、[Checks](known-amendments.html#checks)、[Escrow](escrow.html)、および[Payment Channel](known-amendments.html#paychan)から資金を受領できます。このような「二段階」トランザクションモデルでは、最初に送金元は資金の送金を承認するトランザクションを送信し、次に送金先は資金受領を承認するトランザクションを送信します。 - -Deposit Authorizationが有効になっている場合に[Paymentトランザクション][]から資金を受領するには、このような支払の送金元を[事前承認](#事前承認)する必要があります。_（[DepositPreauth Amendment][]が必要です。）_ - -## 推奨される使い方 - -Deposit Authorizationを最大限に活用するため、以下の実施を推奨します。 - -- XRP残高が常に最低[必要準備金](reserves.html)を上回るようにする。 -- DefaultRippleフラグをデフォルトの状態（無効）にしておく。トラストラインに対して[Rippling](rippling.html)を有効にしない。TrustSetトランザクションを送信するときには常に[`tfSetNoRipple`フラグ](trustset.html)を使用する。 -- [オファー](offercreate.html)を行わない。このようなトランザクションの実行にあたり、消費される一致オファーを事前に把握することは不可能です。 - -## 詳細なセマンティクス - -Deposit Authorizationが有効化されているアカウントの特徴は次のとおりです。 - -- [Paymentトランザクション][]の送信先には**できません**。ただし**以下の例外**は除きます。 - - 送金先により、支払の送金元が[事前承認](#事前承認)されている場合。_（[DepositPreauth Amendment][]が必要です）_ - - アカウントのXRP残高がアカウントの最低[必要準備金](reserves.html)以下で、XRP PaymentのAmountがアカウントの最低準備金（現時点では10 XRP）以下である場合は、このアカウントを送金先に指定できます。これにより、アカウントがトランザクションを送信することも、XRPを受領することもできずに操作不可能な状態になるのを防ぎます。この場合、アカウントの所有者の準備金は関係ありません。 -- **以下に該当する場合にのみ**[PaymentChannelClaimトランザクション][]からXRPを受領できます。 - - PaymentChannelClaimトランザクションの送金元がPayment Channelの送金先である場合。 - - PaymentChannelClaimトランザクションの送金先がPaymentChannelClaimの送金元を[事前承認している](#事前承認)場合。_（[DepositPreauth Amendment][]が必要です）_ -- **以下に該当する場合にのみ**[EscrowFinishトランザクション][]からXRPを受領できます。 - - EscrowFinishトランザクションの送金元がEscrowの送金先である場合。 - - EscrowFinishトランザクションの送金先がEscrowFinishの送金元を[事前承認している](#事前承認)場合。_（[DepositPreauth Amendment][]が必要です）_ -- [CheckCash][]トランザクションを送信してXRPまたは発行済み通貨を受領**できます**。 _（[Checks Amendment][]が必要です:有効ではありません:）_ -- [OfferCreateトランザクション][]を送信してXRPまたは発行済み通貨を受領**できます**。 - - 即時には完全に実行されないOfferCreateトランザクションがアカウントから送信される場合、このアカウントは、後でオファーが他のアカウントの[Payment][]トランザクションと[OfferCreate][]トランザクションによって消費される時点で、注文済みXRPと発行済み通貨のリマインダーを受信する**ことがあります**。 -- アカウントが[NoRippleフラグ](rippling.html)を有効にせずにトラストラインを作成している場合、またはDefaultRippleフラグを有効にして通貨を発行した場合は、アカウントはRipplingの結果として、[Paymentトランザクション][]でそれらのトラストラインの発行済み通貨を受領**できます**。このようなトランザクションの送金先にすることはできません。 -- 一般的に、以下のすべての条件に該当する場合は、XRP LedgerのアカウントはXRP LedgerでXRP以外の通貨を受領**できません**。（このルールは、DepositAuthフラグに特有のものではありません。） - - アカウントにより、ゼロ以外の限度を指定したトラストラインが作成されていない。 - - アカウントが、その他のアカウントにより作成されたトラストラインで通貨を発行していない。 - - アカウントがまだオファーを出していない。 - -以下の表に、トランザクションタイプ別にDepositAuthが有効または無効な状態での入金の可否をまとめました。 - -{% include '_snippets/depositauth-semantics-table.html' %} - - - -## Deposit Authorizationの有効化または無効化 - -アカウントのDeposit Authorizationを有効にするには、`SetFlag`フィールドに`asfDepositAuth`の値（9）を設定した[AccountSetトランザクション][]を送信します。アカウントのDeposit Authorizationを無効にするには、`ClearFlag`フィールドに`asfDepositAuth`の値（9）を設定した[AccountSetトランザクション][]を送信します。AccountSetフラグについての詳細は、[AccountSetフラグ](accountset.html)を参照してください。 - -## AccountのDepositAuthの有効化の確認 - -アカウントのDeposit Authorizationの有効化の状態を確認するには、[account_infoメソッド][]を使用してアカウントを調べます。`Flags`フィールド（`result.account_data`オブジェクト）の値を、[AccountRootレジャーオブジェクトのビット単位フラグ](accountroot.html)と比較します。 - -`Flags`値と`lsfDepositAuth`フラグ値（0x01000000）のビット単位のANDの結果がゼロ以外の場合、アカウントではDepositAuthが有効になっています。結果がゼロの場合、アカウントではDepositAuthが無効になっています。 - -## 事前承認 - -_（[DepositPreauth Amendment][]が必要です。）_ - -DepositAuthが有効なアカウントは、特定の送金元を _事前承認_ することにより、DepositAuthが有効になっていても、これらの送金元からの支払を受領することができます。これにより、特定の送金元からの資金の直接送金が可能となり、受取人はトランザクションごとに個別にアクションを実行する必要がなくなります。事前承認はDepositAuthの使用にあたり必須の要件ではありませんが、事前承認により特定の操作を実行しやすくなります。 - -事前承認は通貨に依存しません。特定の通貨のみについてアカウントを事前承認することはできません。 - -特定の送金元を事前承認するには、`Authorize`フィールドに事前承認する別のアカウントのアドレスを指定した[DepositPreauthトランザクション][]を送信します。事前承認を取り消すには、当該アカウントのアドレスを`Unauthorize`フィールドに指定します。通常どおり、`Account`フィールドには自分自身のアドレスを指定します。現在DepositAuthを有効にしていない場合でも、アカウントを事前承認または承認解除できます。他のアカウントに設定した事前認証ステータスは保存されますが、DepositAuthを有効にしない限り、このステータスの影響はありません。アカウントがアカウント自体を事前認証することはできません。事前認証は一方向であり、反対方向の支払には影響しません。 - -別のアカウントを事前認証すると、レジャーに[DepositPreauthオブジェクト](depositpreauth-object.html)が追加されます。これにより、認証を提供するアカウントの[所有者準備金](reserves.html#所有者準備金)が増加します。アカウントで事前承認が取り消されると、オブジェクトが削除され、準備金はこれに伴い減少します。 - -DepositPreauthトランザクションの処理が完了すると、承認済みアカウントからあなたのアカウントに資金を送金できるようになります。これは、以下のトランザクションタイプのいずれかを使用してDepositAuthを有効にしている場合にも該当します。 - -- [Payment][] -- [EscrowFinish][] -- [PaymentChannelClaim][] - -事前承認は、DepositAuthが有効なアカウントへのその他の送金方法には影響しません。詳しいルールについては、[詳細なセマンティクス](#詳細なセマンティクス)を参照してください。 - -### 承認の確認 - -[deposit_authorizedメソッド][]を使用して、特定のアカウントに対し別のアカウントへの入金が許可されているかどうかを確認できます。このメソッドは次の2点を確認します。 - -- 送金先アカウントがDeposit Authorizationを必要としているかどうか。（承認を必要としていない場合は、すべての送金元アカウントが承認済みとみなされます。） -- 送金元アカウントに対し、送金先への送金が事前承認されているかどうか。 - - -## 関連項目 - -- [DepositPreauthトランザクション][]リファレンス。 -- [DepositPreauthレジャーオブジェクトタイプ](depositpreauth-object.html)。 -- [`rippled` API](http-websocket-apis.html)の[deposit_authorizedメソッド][]。 -- [Authorized Trust Lines](authorized-trust-lines.html)機能（`RequireAuth`フラグ）により、アカウントが発行したXRP以外の通貨を保有できる取引相手が制限されます。 -- `DisallowXRP`フラグは、アカウントがXRPを受領してはならないことを示します。これはDeposit Authorizationよりもソフトな保護機能であり、XRP Ledgerにより強制されません。（クライアントアプリケーションはこのフラグに従うか、または少なくともこのフラグについて警告します。） -- 送信トランザクションが[Destinationタグ](become-an-xrp-ledger-gateway.html#source-and-destination-tags)を指定している場合には、`RequireDest`フラグは、アカウントが通貨額のみを受領できることを示します。これにより、ユーザーが支払の目的を指定し忘れることがなくなりますが、恣意的な送金先タグを作成できる不明な送金元から受取人が保護されるわけではありません。 -- [Partial Payment](partial-payments.html)により、アカウントは不要な支払を返金できます。この際、[送金手数料](transfer-fees.html)と為替レートは送金額には追加されず、送金された金額から差し引かれます。 - - - -[DepositPreauth Amendment]: known-amendments.html#depositpreauth -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-system-basics/accounts/depositauth.md b/content/concepts/payment-system-basics/accounts/depositauth.md deleted file mode 100644 index 2d7644436d..0000000000 --- a/content/concepts/payment-system-basics/accounts/depositauth.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -html: depositauth.html -parent: accounts.html -blurb: The DepositAuth setting lets an account block incoming payments by default. -labels: - - Payments - - Security ---- -# Deposit Authorization - -_(Added by the [DepositAuth amendment][].)_ - -Deposit Authorization is an optional [account](accounts.html) setting in the XRP Ledger. If enabled, Deposit Authorization blocks all transfers from strangers, including transfers of XRP and [tokens](tokens.html). 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](escrow.html) 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](known-amendments.html#checks), [Escrow](escrow.html), and [Payment Channels](known-amendments.html#paychan). 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](reserves.html). -- Keep the Default Ripple flag in its default (disabled) state. Do not enable [rippling](rippling.html) on any trust lines. When sending [TrustSet transactions][], always use the [`tfSetNoRipple` flag](trustset.html). -- Do not place [Offers](offercreate.html). It is impossible to know in advance which matching offers will be consumed to execute such a trade. - -## 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](reserves.html), 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](rippling.html) 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](accountroot.html). - -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](depositpreauth-object.html) to the ledger, which increases the [owner reserve](reserves.html#owner-reserves) 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: - -- 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. - - - -[DepositPreauth amendment]: known-amendments.html#depositpreauth -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-system-basics/accounts/multi-signing.ja.md b/content/concepts/payment-system-basics/accounts/multi-signing.ja.md deleted file mode 100644 index 93d0511ece..0000000000 --- a/content/concepts/payment-system-basics/accounts/multi-signing.ja.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -html: multi-signing.html -parent: accounts.html -blurb: マルチ署名を使用することで、トランザクション送信時のセキュリティが強化されます。 -labels: - - スマートコントラクト - - セキュリティ ---- -# マルチ署名 - -マルチ署名は、複数のシークレットキーを組み合わせて使用してXRP Ledgerの[トランザクションを承認する](transaction-basics.html#トランザクションの承認)手法です。アドレスで有効な承認手法（マルチ署名、[マスターキーペア](cryptographic-keys.html#マスターキーペア)、[レギュラーキーペア](cryptographic-keys.html#レギュラーキーペア)など）を自由に組み合わせて使用できます。（唯一の要件は、 _少なくとも1つの_ 手法を有効にする必要があることです。） - -マルチ署名には次のメリットがあります。 - -* 複数のデバイスからのキーを要求できます。これにより、不正使用者があなたの代わりにトランザクションを送信するには複数のマシンを悪用しなければならなくなります。 -* 複数のユーザー間で1つのアドレスの管理を共有できます。この場合、各ユーザーが、そのアドレスからトランザクションを送信する際に必要な複数のキーのいずれか1つだけを所有します。 -* あなたのアドレスからトランザクションを送信できる権限を、複数ユーザーのグループに委任できます。委任を受けた各ユーザーは、あなたが通常の方法で署名できない場合にあなたのアドレスを制御できます。 -* その他のメリットもあります。 - -## 署名者リスト - -マルチ署名を使用するには、あなたの代理として署名できるアドレスのリストを作成する必要があります。 - -[SignerListSetトランザクション][]は、あなたのアドレスからのトランザクションを承認できるアドレスを定義します。SignerListには最大8個のアドレスを指定できます。SignerListのquorum値とweight値を使用して、必要な署名の数と組み合わせを制御できます。 - -## マルチ署名済みトランザクションの送信 - -マルチ署名済みトランザクションを正常に送信するには、以下のすべての条件を満たす必要があります。 - -* トランザクションを送信するアドレス（`Account`に指定されるアドレス）は、[レジャーに`SignerList`](signerlist.html)を所有する必要があります。 -* トランザクションに`SigningPubKey`フィールドを空の文字列として含める必要があります。 -* トランザクションに、署名の配列が指定されている[`Signers`フィールド](transaction-common-fields.html#signersフィールド)を含める必要があります。 -* `Signers`配列に含まれている署名は、SignerListで定義されている署名と一致している必要があります。 -* 指定された署名で、これらの署名者に関連付けられている`weight`の合計が、SignerListの`quorum`以上である必要があります。 -* [トランザクションコスト](transaction-cost.html)（`Fee`フィールドで指定）は、通常のトランザクションコストの（N+1）倍以上である必要があります。このNは、指定される署名の数です。 -* トランザクションのすべてのフィールドは、署名収集前に定義する必要があります。フィールドの[自動入力](transaction-common-fields.html#自動入力可能なフィールド)は実行できません。 -* `Signers` 配列がバイナリ形式で指定される場合、この配列は署名者アドレスの数値に基づいて、低い値から順にソートされている必要があります。（JSONとして提出される場合は、[submit_multisignedメソッド][] がこの処理を自動的に実行します。） - -詳細は、[マルチ署名の設定](set-up-multi-signing.html)を参照してください。 - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} diff --git a/content/concepts/payment-system-basics/accounts/multi-signing.md b/content/concepts/payment-system-basics/accounts/multi-signing.md deleted file mode 100644 index ab48398028..0000000000 --- a/content/concepts/payment-system-basics/accounts/multi-signing.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -html: multi-signing.html -parent: accounts.html -blurb: Use multi-signing for greater security sending transactions. -labels: - - Smart Contracts - - Security ---- -# Multi-Signing - -Multi-signing in the XRP Ledger is a method of [authorizing transactions](transaction-basics.html#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](cryptographic-keys.html#master-key-pair), and a [regular key pair](cryptographic-keys.html#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 216-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](transaction-basics.html#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.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](transaction-common-fields.html#signers-field) containing an array of signatures. -* The signatures present in the `Signers` array must match signers defined in the SignerList. -* For the provided signatures, the total weight associated with those signers must be equal or greater than the quorum for the SignerList. -* The [transaction cost](transaction-cost.html) (specified in the `Fee` field) must be at least (N+1) times the normal transaction cost, where N is the number of signatures provided. -* All fields of the transaction must be defined before collecting signatures. You cannot [auto-fill](transaction-common-fields.html#auto-fillable-fields) any fields. -* If presented in binary form, the `Signers` array must be sorted based on the numeric value of the signer addresses, with the lowest value first. (If submitted as JSON, the [submit_multisigned 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][] - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} diff --git a/content/concepts/payment-system-basics/accounts/reserves.ja.md b/content/concepts/payment-system-basics/accounts/reserves.ja.md deleted file mode 100644 index 127a651184..0000000000 --- a/content/concepts/payment-system-basics/accounts/reserves.ja.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -html: reserves.html -parent: accounts.html -blurb: XRP Ledgerアカウントでは、レジャーデータ内のスパムを減らすためにXRPの準備金が必要です。 -labels: - - 手数料 - - アカウント -top_nav_grouping: 人気ページ ---- -# 準備金 - -XRP Ledgerでは、スパムや悪意のある使用によって、共有グローバル台帳（レジャー）が過度に大きくならないように、 _準備金_ の仕組みをXRPに適用しています。現在一般に市販されているのマシンで、処理中の現行レジャーを常にRAMに保存でき、全履歴がディスクに収まるように、技術の向上に合わせて台帳が大きくなるのを制限することが目的です。 - -取引（トランザクション）を送信するには、各アドレスが共有グローバル台帳内に最小量のXRPを保有している必要があります。このXRPを他のアドレスに送信することはできません。新しいアドレスに資金供給するには、必要準備金を満たすのに十分なXRPを送信する必要があります。 - -現在の最低必要準備金は**10 XRP**です。（これは、レジャーにそれ以外のオブジェクトを所有していないアドレスにかかるコストです。） - - -## 基本準備金と所有者準備金 - -必要な準備金は2つの部分に分けられます。 - -* **基本準備金**は、レジャーの各アドレスに必要なXRPの最小額です。現在、この準備金は、10 XRP（`10000000` drop）です。 -* **所有者準備金**は、アドレスがレジャーに所有しているオブジェクトごとに必要な準備金の増加額です。現在、これは1アイテムにつき2 XRP（`2000000` drop）です。 - - -### 所有者準備金 - -レジャー内の多くのオブジェクトは特定のアドレスによって所有され、そのアドレスに対する必要準備金と見なされます。レジャーから削除されたオブジェクトは、所有者の必要準備金にカウントされなくなります。 - -- [オファー](offer.html)はそれらを発行したアドレスによって所有されています。すべてが処理済みとなるか、または資金供給のないことが判明したオファーは、取引処理によって自動的に削除されます。または、所有者は、[OfferCancelトランザクション][]を送信するか、`OfferSequence`パラメーターを含む[OfferCreateトランザクション][]を送信することで、オファーを取り消すことができます。 -- [トラストライン](ripplestate.html)は2つのアドレス間で共有されます。所有者準備金は、いずれかまたは両方のアドレスに適用されます。どちらに適用されるかは、アドレスが制御するフィールドがデフォルト状態であるかどうかによって決まります。詳細については、[Contributing to the Owner Reserve](ripplestate.html#所有者の準備金への資金供給)を参照してください。 -- [MultiSignReserve Amendment][]がない場合、1つの[SignerList](signerlist.html)は、メンバーの数に応じて、所有者準備金用に3～10個のオブジェクトとしてカウントされます。[MultiSignReserve Amendment][]が有効になっている場合、1つのSignerListは、メンバーの数に関係なく、所有者準備金用に1つのオブジェクトとしてカウントされます。関連項目: [SignerListと準備金](signerlist.html#signerlistと準備金) -- [保留中の支払い（Escrow）](escrow-object.html)は、支払元のアドレスが所有します。 -- [Payment Channel](use-payment-channels.html)は、作成したアドレスが所有します。 -- [所有者ディレクトリー](directorynode.html)には、アドレスの所有者の準備金の対象となるすべてのレジャーオブジェクトが一覧表示されます。所有者ディレクトリー自体は準備金としてカウントされません。 -- [Checks](checks.html)は、作成したアドレス（送信先ではなく送信元）が所有します。 - - -#### 所有者準備金のエッジケース - -XRP Ledgerでは、 [OfferCreateトランザクション][]は、資産を保持する意図の明示的なステートメントであるとみなします。オファーが実行されることで、（限界値0で、その限界値を超える残高の）トラストラインが（そのようなトラストラインが存在しない場合）`taker_pays`の通貨で自動的に作成されます。ただし、オファーの所有者が新しく作られたトラストラインの所有者準備金を満たすための十分なXRPを保持していない場合、そのオファーは資金不足とみなされます。関連項目: [オファーのライフサイクル](offers.html#オファーのライフサイクル) - - -## 必要準備金を下回る - -トランザクション処理中、[トランザクションコスト](transaction-cost.html)によって、送信元アドレスのXRP残高の一部が消却されます。その結果、そのアドレスのXRPが必要準備金を下回る可能性があります。 - -アドレスが保持しているXRPが、現在の必要準備金を下回ると、XRPを他のアドレスに転送するトランザクションを送信したり、自身の準備金を増やしたりできなくなります。このような場合でも、そのアドレスはレジャー内に存在し、トランザクションコストを支払うのに十分なXRPを持っている限り、その他のトランザクションを送信することができます。必要準備金を満たすために十分なXRPを受け取った場合、またはそのアドレスのXRP保有額よりも[準備金の必要額が減少した](#必要準備金の変更)場合、そのアドレスはすべてのタイプのトランザクションを再度送信できるようになります。 - -**ヒント:** アドレスが必要準備金を下回った場合は、新しい[OfferCreateトランザクション][]を送信して、追加のXRP、または既存のトラストライン上の他の通貨を入手することができます。このような取引では、新しい[トラストライン](ripplestate.html)や[レジャー内のオファーノード](offer.html)を作成することはできないため、すでにオーダーブック内にあるオファーを実行するトランザクションのみを実行することができます。 - - -## 必要準備金の変更 - -XRP Ledgerには、XRPの価値の長期的な変動に応じて必要準備金を調整する仕組みがあります。変更はすべて、コンセンサスプロセスによる承認が必要です。詳細については、[手数料の投票](fee-voting.html)を参照してください。 - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-system-basics/accounts/reserves.md b/content/concepts/payment-system-basics/accounts/reserves.md deleted file mode 100644 index f393cf9607..0000000000 --- a/content/concepts/payment-system-basics/accounts/reserves.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -html: reserves.html -parent: accounts.html -blurb: XRP Ledger accounts require a reserve of XRP to reduce spam in ledger data. -labels: - - Fees - - Accounts -top_nav_grouping: Popular Pages ---- -# 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 reserve requirement changes from time to time due to the [Fee Voting](fee-voting.html) process, where validators can agree to new reserve settings. On [Mainnet](parallel-networks.html), 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](accounts.html) must set aside this much XRP. Some of this XRP can be recovered by [deleting the account](accounts.html#deletion-of-accounts). - -To determine the current minimum reserve requirement, use the [`server_info` command](server_info.html) and take `validated_ledger.reserve_base_xrp`. - -## Base Reserve and Owner Reserve - -The reserve requirement has two parts: - -* The **Base Reserve** is a minimum amount of XRP that is required for each address in the ledger. -* The **Owner Reserve** is an increase to the reserve requirement for each object that the address owns in the ledger. - - -### Owner Reserves - -Many objects in the ledger are owned by a particular address, and count toward the reserve requirement of that address. Each object increases the reserve requirement by the Owner Reserve. On Mainnet, this is currently 2 XRP (`2000000` [drops](xrp.html#xrp-properties)) per item. - -When objects are removed from the ledger, they no longer count against their owner's reserve requirement. - -To retrieve the number of objects an account owns in the ledger, use the [account_info method][] and take `account_data.OwnerCount`. `OwnerCount` is one of the fields of the [`AccountRoot` object](accountroot.html). To look up reserve settings, use the [server_info method][]: the `validated_ledger.reserve_inc_xrp` is the owner reserve and the `validated_ledger.reserve_base_xrp` is the base reserve, both in decimal XRP. To get the values in integer drops of XRP instead, use the [server_state method][]. - -To calculate an address's Owner Reserve requirement, multiply `OwnerCount` by `reserve_inc_xrp`, then add `reserve_base_xrp`. [Here is a demonstration](build-a-desktop-wallet-in-python.html#codeblock-17) of this calculation in Python. - -- [Offers](offer.html) are owned by the address that placed them. Transaction processing automatically removes Offers that are fully consumed or found to be unfunded. Alternatively, the owner can cancel an Offer by sending an [OfferCancel transaction][], or by sending an [OfferCreate transaction][] that contains an `OfferSequence` parameter. -- [Trust lines](ripplestate.html) are shared between two addresses. The owner reserve can apply to one or both of the addresses, depending on whether the fields that address controls are in their default state. See [Contributing to the Owner Reserve](ripplestate.html#contributing-to-the-owner-reserve) for details. -- A 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)](escrow-object.html) are owned by the address that placed them. -- [Payment Channels](use-payment-channels.html) are owned by the address that created them. -- [Owner directories](directorynode.html) list all the ledger objects that contribute to an address's owner reserve. However, the owner directory itself does not count towards the reserve. -- [Checks](checks.html) 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](offers.html#lifecycle-of-an-offer). - - -## Going Below the Reserve Requirement - -During transaction processing, the [transaction cost](transaction-cost.html) 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](ripplestate.html), or [Offer nodes in the ledger](offer.html), 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](fee-voting.html) for more information. - -## See Also - -- [account_objects method][] -- [AccountRoot Object][] -- [Fee Voting](fee-voting.html) -- [SetFee pseudo-transaction][] -- [Tutorial: Calculate and display the reserve requirement (Python)](build-a-desktop-wallet-in-python.html#3-display-an-account) - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-system-basics/accounts/tickets.ja.md b/content/concepts/payment-system-basics/accounts/tickets.ja.md deleted file mode 100644 index fa8a7a747b..0000000000 --- a/content/concepts/payment-system-basics/accounts/tickets.ja.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -html: tickets.html -parent: accounts.html -blurb: トランザクションを非連続的な順序で送信する -labels: - - アカウント - - トランザクション送信 ---- -# Ticket - -_([TicketBatch amendment][]が必要です。)_ - -XRP Ledgerのチケットは、取引をすぐに送信せずに、その取引のために[シーケンス番号][Sequence Number]を確保する方法です。チケットを使うことで、通常の順序以外で取引を送信することができます。この使用例としては、必要な署名を集めるのに時間がかかるような[マルチサイン取引](multi-signing.html)などが挙げられます。 - -## 背景 - -[トランザクション](transaction-basics.html)にはシーケンス番号が付いているので、任意のトランザクションを2回以上実行することはできません。シーケンス番号はまた、任意のトランザクションが一意であることを保証します。全く同じ金額を同じ人に複数回送信する場合、シーケンス番号は毎回異なることが保証される1つの詳細です。最後に、シーケンス番号は、ネットワーク全体に送信される際に一部のトランザクションが順不同で届いたとしても、トランザクションを一貫した順序で並べるためのエレガントな方法を提供します。 - -しかし、シーケンス番号では限界がある場合もあります。たとえば、次のような場合です。 - -- 2人以上のユーザーがアカウントへのアクセスを共有し、それぞれが独立してトランザクションを送信することができる状態。これらのユーザーが事前に調整することなく同時期に取引を送信しようとすると、それぞれが同じシーケンス番号を異なる取引に使用しようとする可能性があり、成功するのは1人だけです。 -- トランザクションを事前に準備して署名し、安全な場所に保存しておいて、特定のイベントが発生したときにいつでも実行できるようにしておきたい場合があります。しかし、その間も通常通りにアカウントを使用したい場合、準備しておくトランザクションに使用するシーケンス番号がわかりません。 -- トランザクションを有効にするために[複数人が署名しなければならない](multi-signing.html)場合、一度に複数のトランザクションを計画するのは難しいでしょう。トランザクションに別々のシーケンス番号をつけると、全員が前のトランザクションに署名するまで、後の番号のトランザクションを送信することができません。しかし、保留中のトランザクションに同じシーケンス番号を使用すると、1つのトランザクションのみ成功します。 - -チケットでは、これらの問題を解決するために、通常の順番とは別に、後からでも（ただし、それぞれ1回まで）使用可能なシーケンス番号を用意しています。 - - -## チケットは予約済みのシーケンス番号 - -チケットとは、あるシーケンス番号が後に使用されるために確保されたという記録です。アカウントは、まず[TicketCreate トランザクション][]を送信して、1つまたは複数のシーケンス番号をチケットとして確保します。これにより、[台帳の状態データ](ledgers.html)に、予約された各シーケンス番号について[Ticket オブジェクト][]の形で記録が残されます。 - -チケットには、チケット作成時に設定されたシーケンス番号が使用されます。例えば、あなたのアカウントの現在のシーケンス番号が101で、3枚のチケットを作成した場合、それらのチケットにはチケットシーケンス番号102、103、104が付けられます。これにより、あなたのアカウントのシーケンス番号は105になります。 - -{{ include_svg("img/ticket-creation.svg", "Diagram: Creating three Tickets") }} - -後から、シーケンス番号の代わりに特定のチケットを使用してトランザクションを送信することができます。これにより、元帳の状態データから対応するチケットが削除され、アカウントの通常のシーケンス番号は変更されません。また、チケットを使用せずに、通常のシーケンス番号を使用してトランザクションを送信することもできます。利用可能なチケットは、いつでもどのような順番でも使用できますが、各チケットは1回しか使用できません。 - -{{ include_svg("img/ticket-usage.svg", "Diagram: Using Ticket 103.") }} - -上記の例では、シーケンス番号105または作成した3つのチケットのいずれかを使用してトランザクションを送信できます。チケット103を使ってトランザクションを送信すると、それによってチケット103は元帳から削除されます。その後の次のトランザクションでは、シーケンス番号105、チケット102、またはチケット104を使用できます。 - -**注意:** チケットは1枚ごとに[所有者準備金](reserves.html#所有者準備金)としてカウントされますので、チケット1枚につき2XRPを確保する必要があります。 (このXRPは、チケットを使用した後に再び使用可能になります）一度に多くのチケットを作成すると、このコストはすぐに膨れ上がります。 - -シーケンス番号と同様に、トランザクションの送信は、そのトランザクションが[コンセンサス](consensus.html)によって確認された場合にのみ、チケットを使用します。しかし、意図した通りにならなかった取引でも、[`tec`クラスの結果コード](tec-codes.html)を用いてコンセンサスで確認することができます。 - -あるアカウントで利用可能なチケットを調べるには、[account_objects メソッド][]を使用します。 - -## 制約事項 - -どのアカウントでも、どのような種類の取引でもチケットを作成し、使用することができます。ただし、いくつかの制限があります。 - -- 各チケットは一度しか使用できません。同じチケットシーケンスを使用する複数の異なるトランザクション候補があることは可能ですが、コンセンサスで検証できるのはそのうちの1つだけです。 -- 各アカウントでは、一度に250枚以上のチケットをレジャーに登録することはできません。また、一度に250枚以上のチケットを作成することもできません。 -- チケットを使って別のチケットを作ることは_できます_。その場合、使用したチケットは、一度に所持できるチケットの合計数にはカウントされません。 -- 各チケットは[所有者準備金](reserves.html#所有者準備金)にカウントされるため、まだ使用していないチケット1枚につき2XRPを確保する必要があります。このXRPは、チケットを使用した後、再び使用することができます。 -- 個々の元帳の中では、チケットを使用した取引は、同じ送信者からの他の取引の後に実行されます。1つのアカウントが同じ元帳のバージョンでTicketを使用する複数のトランザクションを持つ場合、それらのTicketは最も低いTicket Sequenceから最も高いTicket Sequenceの順に実行されます。 (詳細については、コンセンサスの[正規順序](consensus.html#xrp-ledgerプロトコル-コンセンサスと検証)に関するドキュメントを参照してください)。 -- 個々の元帳の中では、チケットを使用した取引は、同じ送信者からの他の取引の後に実行されます。1つのアカウントが同じ元帳のバージョンでチケットを使用する複数のトランザクションを持つ場合、それらのチケットは最も低いチケット シーケンス番号から最も高いチケット シーケンス番号の順に実行されます。 (詳細については、コンセンサスの[正規順序](consensus.html#xrp-ledgerプロトコル-コンセンサスと検証)に関するドキュメントを参照してください)。 - -## 関連項目 - - -- **Concepts:** - - [マルチ署名](multi-signing.html) -- **Tutorials:** - - [チケットを使用する](use-tickets.html) -- **References:** - - [TicketCreate トランザクション][] - - [トランザクションの共通フィールド](transaction-common-fields.html) - - [Ticket オブジェクト](ticket.html) - - [account_objects メソッド][] - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-system-basics/accounts/tickets.md b/content/concepts/payment-system-basics/accounts/tickets.md deleted file mode 100644 index 27d1a3bc14..0000000000 --- a/content/concepts/payment-system-basics/accounts/tickets.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -html: tickets.html -parent: accounts.html -blurb: Send transactions in non-sequential order. -labels: - - Accounts - - Transaction Sending ---- -# Tickets - -_(Added by the [TicketBatch amendment][].)_ - -A Ticket in the XRP Ledger is a way of setting aside a [sequence number][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.html) 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](transaction-basics.html) 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. -- When [multiple people must sign a transaction](multi-signing.html) 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](ledgers.html), 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](reserves.html), 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](consensus.html). However, transactions that fail to do what they were intended to do can still be confirmed by consensus with [`tec`-class result codes](tec-codes.html). - -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](reserves.html), 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.html) [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][] - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-system-basics/fees.ja.md b/content/concepts/payment-system-basics/fees.ja.md deleted file mode 100644 index 888a2caef7..0000000000 --- a/content/concepts/payment-system-basics/fees.ja.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -html: fees.html -parent: payment-system-basics.html -blurb: レジャーを悪用から守る中立的な手数料（誰にも支払われません）や、ユーザーが互いから徴収できる手数料など、XRP Ledgerで許可されている手数料のタイプについて説明します。 -labels: - - 手数料 ---- -# 手数料（曖昧さの回避） - -XRP Ledgerは分散型レジャーであり、暗号技術により保護され、サーバーで構成される分散型ピアツーピアネットワークで運用されます。つまり、Rippleを含め誰もネットワークアクセス料を要求できません。 - -ただしXRP Ledgerのルールには、レジャーを悪用から保護するための中立的な手数料を含む各種手数料が設定されています。この中立的な手数料の受取先はありません。また、XRP Ledgerの内外でユーザーはさまざまな方法で相互に手数料を徴収できます。 - - -## レジャー内部 - -### 中立的な手数料 - -_**トランザクションコスト**_（トランザクション手数料とも呼ばれます）は、トランザクションの送信にあたって消却される極わずかな額のXRPです。このコストはネットワークへの負荷に比例して増減するため、ピアツーピアネットワークをスパムから保護します。詳細は、[トランザクションコスト](transaction-cost.html)を参照してください。 - -_**必要準備金**_ は、アカウントが保有する必要があるXRPの最小額です。これは、アカウントがレジャーで所有するオブジェクトの数に比例して増加します。これにより、ユーザーが不注意または悪意によってレジャーのサイズを増やすことを防ぎます。詳細は、[準備金](reserves.html)を参照してください。 - -### オプションの手数料 - -_**送金手数料**_ は、イシュアーが発行する通貨を、そのイシュアーがXRP Ledger内の他のアドレスに送金する場合に請求できる手数料であり、そのパーセンテージは任意に設定されます。詳細は、[送金手数料](transfer-fees.html)を参照してください。 - -_**トラストラインクオリティ**_ は、アカウントがトラストラインの残高を額面価格よりも高い価格または低い価格で評価できるようにする設定です。この設定により、手数料が発生するような状況になることがあります。トラストラインクオリティは、トラストラインに関連付けられていないXRPには適用されません。 - - -## レジャー外部 - -XRP Ledgerには前述の手数料しか組み込まれていませんが、この他にもレジャーに関連した手数料を請求する方法を考案することが可能です。たとえば、一般的に金融機関は、XRP Ledgerへの資金の送金やXRP Ledgerからの資金の受領に関して、手数料を顧客に請求します。 - -その他にもさまざまな手数料を設定できます。企業はクライアントアプリケーションへのアクセス、XRP Ledger以外のアカウント、取引所サービス（特にXRP Ledgerの分散型取引所内ではなくプライベートマーケットでXRPを購入する場合）、およびその他のさまざまなサービスの管理の手数料を請求できます。金融機関と取引を行う前に、必ず手数料一覧を確認してください。 diff --git a/content/concepts/payment-system-basics/fees.md b/content/concepts/payment-system-basics/fees.md deleted file mode 100644 index e4ab5810e6..0000000000 --- a/content/concepts/payment-system-basics/fees.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -html: fees.html -parent: payment-system-basics.html -blurb: Learn about the types of fees allowed by the XRP Ledger, including neutral fees (payable to no one) that protect the ledger against abuse, as well as fees that users can collect from each other. -labels: - - Fees ---- -# 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](transaction-cost.html) 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](reserves.html) 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](transfer-fees.html) 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. diff --git a/content/concepts/payment-system-basics/ledgers.ja.md b/content/concepts/payment-system-basics/ledgers.ja.md deleted file mode 100644 index b78bc1d60f..0000000000 --- a/content/concepts/payment-system-basics/ledgers.ja.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -html: ledgers.html -parent: payment-system-basics.html -blurb: XRP Ledgerは、rippledによって内部データベースに保持されている一連の個別レジャー（レジャーバージョン）で構成されています。これらのレジャーの構造と内容について説明します。 -labels: - - ブロックチェーン - - データ保持 ---- -# レジャー - -XRP Ledgerは完全にオープンな共有グローバルレジャーです。個々の参加者はこのレジャーを管理する個々の機関を信頼しなくても、レジャーの整合性を信頼できます。`rippled`サーバーソフトウェアは、非常に特殊なルールによってのみ更新可能なレジャーデータベースを管理することにより、これを実現しています。各`rippled`インスタンスはレジャーの完全なコピーを保持し、`rippled`サーバーからなるピアツーピアネットワークはトランザクション候補を各サーバーに配信します。コンセンサスプロセスによって、レジャーの新しいバージョンに適用されるトランザクションが決定します。関連項目: [コンセンサスプロセス](consensus.html)。 - -![図: 各レジャーは、その前のレジャーバージョンにトランザクションを適用して生成されます。](img/ledger-changes.ja.png) - -この共有グローバルレジャーは、実際には`rippled`の内部データベースに保持されている一連の個別レジャー（レジャーバージョン）です。各レジャーバージョンには、レジャーの生成順を示す[レジャーインデックス][]が付いています。各閉鎖済みレジャーバージョンにも、レジャーの内容を示す識別用ハッシュ値があります。`rippled`インスタンスには常に、1つの処理中の「現行」オープンレジャー、コンセンサスにより承認されていないいくつかの閉鎖済みレジャー、およびコンセンサスによる検証済みの任意の数の履歴レジャーがあります。検証済みレジャーだけが、その内容が正確で変更できません。 - -1つのレジャーバージョンはさまざまな要素で構成されています: - -![図: レジャーにはトランザクション、状態ツリー、閉鎖時刻、検証情報を含むヘッダーが含まれています。](img/anatomy-of-a-ledger-simplified.ja.png) - -* **ヘッダー** - [レジャーインデックス][]、レジャーのその他のコンテンツのハッシュ、その他のメタデータ。 -* **トランザクションツリー** - このレジャーの作成時に、直前のレジャーに適用された[トランザクション](transaction-formats.html)。トランザクションは、レジャーの変更を可能にする _唯一の_ 手段です。 -* **状態ツリー** - このバージョンのレジャーの設定、残高、オブジェクトを含むすべての[レジャーオブジェクト](ledger-object-types.html)。 - - -## ツリーの形式 - -レジャーの状態ツリーは、その名前のとおりツリー型データ構造です。状態ツリーの各オブジェクトは256ビットのオブジェクトIDで識別されます。JSONではレジャーオブジェクトのIDは`index`フィールドです。このフィールドには64文字の16進数文字列が含まれています（例: `"193C591BF62482468422313F9D3274B5927CA80B4DD3707E42015DD609E39C94"`）。状態ツリーの各オブジェクトには、オブジェクトの検索に使用できるIDが設定されています。各トランザクションには、トランザクションツリーでトランザクションを検索するときに使用できる識別用ハッシュが含まれています。レジャーオブジェクトの`index`（ID）と[レジャーの`ledger_index`（シーケンス番号）][レジャーインデックス]を混同しないでください。 - -**ヒント:** レジャーの状態ツリーのオブジェクトは「レジャーノード」と呼ばれることもあります。たとえばトランザクションメタデータは`AffectedNodes`のリストを返します。これをピアツーピアネットワークの「ノード」（サーバー）と混同しないでください。 - -トランザクションの場合、識別用ハッシュは署名済みトランザクションの指示に基づいていますが、検索時のトランザクションオブジェクトにはトランザクションの結果とメタデータが含まれています。これは、ハッシュの生成時には反映されません。 - - -## 関連項目 - -レジャーヘッダー、レジャーオブジェクトID、レジャーオブジェクトタイプについての詳細は、[レジャーデータフォーマット](ledger-data-formats.html)を参照してください。 - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-system-basics/ledgers.md b/content/concepts/payment-system-basics/ledgers.md deleted file mode 100644 index 4c38d8f80c..0000000000 --- a/content/concepts/payment-system-basics/ledgers.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -html: ledgers.html -parent: payment-system-basics.html -blurb: The XRP Ledger is composed of a series of individual ledgers, or ledger versions, which rippled keeps in its internal database. Learn about the structure and contents of these ledgers. -labels: - - Blockchain - - Data Retention ---- -# Ledgers - -The XRP Ledger is a shared, global ledger 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, and the peer-to-peer network of `rippled` servers distributes candidate transactions among themselves. The consensus process determines which transactions get applied to each new version of the ledger. See also: [The Consensus Process](consensus.html). - -{{ include_svg("img/ledger-changes.svg", "Diagram: Each ledger is the result of applying transactions to the previous ledger version.") }} - -The shared global ledger is actually a series of individual ledgers, or ledger versions, which `rippled` keeps in its internal database. Every ledger version has a [Ledger Index][] which identifies the order in which ledgers occur. Each closed ledger version also has an identifying hash value, which uniquely identifies the contents of that ledger. At any given time, a `rippled` instance has an in-progress "current" open ledger, plus some number of closed ledgers that have not yet been approved by consensus, and any number of historical ledgers that have been validated by consensus. Only the validated ledgers are certain to be correct and immutable. - -A single ledger version consists of several parts: - -{{ include_svg("img/anatomy-of-a-ledger-simplified.svg", "Diagram: A ledger has transactions, a state tree, and a header with the close time and validation info") }} - -* A **header** - The [Ledger Index][], hashes of its other contents, and other metadata. -* A **transaction tree** - The [transactions](transaction-formats.html) that were applied to the previous ledger to make this one. Transactions are the _only_ way to change the ledger. -* A **state tree** - All the [ledger objects](ledger-object-types.html) that contain the settings, balances, and objects in the ledger as of this version. - - -## Tree Format - -As its name might suggest, a ledger's state tree is a tree data structure. 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][Ledger Index]. - -**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, but the contents of the transaction object when you look it up also contain the results and metadata of the transaction, which are not taken into account when generating the hash. - -## 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 | - -Unintuitively, 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. This is a consequence of [how consensus solves the double-spend problem](consensus-principles-and-rules.html#simplifying-the-problem). - -For an open ledger, servers apply transactions in the order those transactions appear, but different servers may see transactions in different orders. Since there is no central timekeeper to decide which transaction was actually first, servers may disagree on the exact order of transactions that were sent around the same time. Thus, 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 and efficient, but hard to game, to increase the difficulty of front-running Offers in the [decentralized exchange](decentralized-exchange.html). - -Thus, an open ledger is only ever used as a temporary workspace, which is a major reason why transactions' [tentative results may vary from their final results](finality-of-results.html). - -## Ledger Close Times - -The time that a ledger version closed is recorded at the `close_time` field of the [ledger header](ledger-header.html). 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. - -Since new ledger versions usually close about every 3 to 5 seconds, these rules result in a loose pattern where ledgers' 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 randomly 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](escrow.html) could successfully finish at a real-world time that is up to about 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](consensus.html#validation) that others did the same. - -Non-validating servers do all the same steps, except they don't 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. - -## See Also - -- 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) - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-system-basics/transaction-basics/finality-of-results.ja.md b/content/concepts/payment-system-basics/transaction-basics/finality-of-results.ja.md deleted file mode 100644 index 735fc00983..0000000000 --- a/content/concepts/payment-system-basics/transaction-basics/finality-of-results.ja.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -html: finality-of-results.html -parent: transaction-basics.html -blurb: トランザクション結果が最終的かつ不変になるタイミングについて説明します。 -labels: - - トランザクション送信 - - ブロックチェーン ---- -# 結果のファイナリティー - -トランザクションがコンセンサスレジャーに適用される順序は、[レジャー](ledgers.html)がクローズされ、そのトランザクションセットが[コンセンサスプロセス](intro-to-consensus.html)によって承認されるまで確定されません。最初に成功したトランザクションはその後で失敗する可能性があり、最初に失敗したトランザクションはその後で成功する可能性があります。さらに、あるラウンドでコンセンサスプロセスによって拒否されたトランザクションは、後のラウンドでコンセンサスに達する可能性があります。 - -検証済みレジャーには、失敗したトランザクション（`tec`結果コード）だけでなく、成功したトランザクション（`tes`結果コード）も含まれる可能性があります。それ以外の結果のトランザクションはレジャーに含まれません。 - -結果コードがそれ以外の場合は、結果が最終的なものかどうかを判断するのは困難です。次の表は、トランザクションの結果がいつ確定するかをまとめたものです。この内容は、トランザクション送信からの結果コードに基づいています。 - -| 結果コード | ファイナリティー | -|:----------------|:-----------------------------------------------------------| -| `tesSUCCESS` | 検証済みレジャーに含まれる場合は確定 | -| すべての`tec`コード | 検証済みレジャーに含まれる場合は確定 | -| すべての`tem`コード | 確定（トランザクションが有効になるようにプロトコルが変更される場合を除く） | -| `tefPAST_SEQ` | 検証済みレジャーに同じシーケンス番号の別のトランザクションが含まれている場合は確定 | -| `tefMAX_LEDGER` | 検証済みレジャーにトランザクションの`LastLedgerSequence`フィールドよりも大きい[レジャーインデックス][レジャーインデックス]があり、検証済みレジャーにそのトランザクションが含まれていない場合は確定 | - -他のトランザクション結果は確定でない可能性があります。その場合、トランザクションはその後に成功または失敗する可能性があります（特に、条件の変更によってトランザクションの適用を妨げる原因がなくなった場合）。例えば、まだ存在していないアカウントにXRP以外の通貨を送信しようとしても失敗しますが、別のトランザクションで送信先アカウントを作成するのに十分なXRPを送信すれば成功します。サーバーは、一時的に失敗した署名付きのトランザクションを保存してから、事前に確認せずに後でそれを正常に適用する場合があります。 - -## 未確定の結果はどのように変更できますか? - -最初にトランザクションを送信すると、`rippled`サーバーはそのトランザクションを現在のオープンレジャーに暫定的に適用し、その結果から暫定的な[トランザクションの結果](transaction-results.html)を返します。ただし、トランザクションの最終結果は、暫定的な結果とは大きく異なる場合があります。考えられる理由を以下に示します。 - -- トランザクションは、後のレジャーバージョンまで延期されるか、検証済みレジャーに取り込まれない場合があります。ほとんどの場合、XRP Ledgerでは、すべての有効なトランザクションをできるだけ早く処理するという原則に従います。ただし、次のような例外があります。 - - - 提案されたトランザクションが[コンセンサスラウンド](consensus.html)の開始時点で過半数のバリデータに中継されていない場合は、残りのバリデータがトランザクションを取得して有効であることを確認する時間を確保できるように、次のレジャーバージョンまで延期される場合があります。 - - - アドレスが同じシーケンス番号を使用して2つの異なるトランザクションを送信する場合、それらのトランザクションのうち最大1つが検証されます。そのようなトランザクションが異なるパスのネットワーク経由で中継される場合、サーバーによっては、他の競合するトランザクションが先に過半数のサーバーに到達したために、暫定的に成功したトランザクションが失敗する可能性があります。 - - - ネットワークをスパムから保護するには、すべてのトランザクションでXRPの[トランザクションコスト](transaction-cost.html)を消却し、XRP Ledgerピアツーピアネットワーク全体に中継する必要があります。ピアツーピアネットワークの負荷が大きいためにトランザクションコストが増加する場合、暫定的に成功したトランザクションは、コンセンサスを達成するのに十分なサーバーに中継されないか、後で[キューに入れられる](transaction-queue.html)可能性があります。 - - - 一時的なインターネットの停止または遅延により、`LastLedgerSequence`フィールドで設定されたトランザクションの指定有効期限内であっても、提案されたトランザクションが正常に中継されない場合があります。（トランザクションに有効期限が設定されていない場合、トランザクションは有効状態を維持し、後で成功する可能性がありますが、独自の方法では望ましくない場合があります。詳細は、[信頼できるトランザクションの送信](reliable-transaction-submission.html)を参照してください。) - - - 上記の要因が2つ以上同時に発生する場合もあります。 - -- 通常、[トランザクションが決済済みレジャーに適用される順序](ledgers.html)は、それらのトランザクションが現在のオープンレジャーに一時的に適用された順序とは異なります。そのため、関連するトランザクションに応じて、一時的に成功したトランザクションが失敗したり、一時的に失敗したトランザクションが成功したりする場合があります。以下に例を示します。 - - - 2つのトランザクションでそれぞれ、同じ[オファー](offers.html)を[分散型取引所](decentralized-exchange.html)で完全に使用する場合、どちらか一方が先に成功すると、もう一方は失敗します。それらのトランザクションが適用される順序は変わる可能性があるため、成功したトランザクションが失敗したり、失敗したトランザクションが成功したりする可能性があります。オファーは部分的に実行できるため、成功する可能性もありますが、程度は異なります。 - - - [分散型取引所](decentralized-exchange.html)で[オファー](offers.html)を使用することで[複数通貨間の支払い](cross-currency-payments.html)は成功したが、別のトランザクションが同じオーダーブックでオファーを使用または作成した場合、複数通貨間の支払いは仮に実行されたときとは異なる為替レートで成功する場合があります。[Partial Payment](partial-payments.html)では、別の金額を送金することもできます。 - - - 送金元に十分な資金がないために一時的に失敗した[Paymentトランザクション][]は、必要な資金を送金する別の取引が正規の順序で先に行われることにより、後で成功する可能性があります。逆も同様です。一時的に成功したトランザクションは、必要な資金を送金するトランザクションが標準的な順序に入れられたものの先に来なかったために失敗する可能性があります。 - - **ヒント:** 上記の理由により、XRP Ledgerに対してテストを実行しており、同じデータに影響する複数のアカウントがある場合、必ずトランザクション間のレジャーが閉じられるまでお待ちください。[スタンドアロンモード](rippled-server-modes.html#rippledサーバーをスタンドアロンモードで実行する理由)のサーバーに対してテストを実行する場合は、[レジャーを手動で閉じる](advance-the-ledger-in-stand-alone-mode.html)必要があります。 - - -## 関連項目 - -- [トランザクションの結果の確認](look-up-transaction-results.html) -- [トランザクション結果のリファレンス](transaction-results.html) - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-system-basics/transaction-basics/finality-of-results.md b/content/concepts/payment-system-basics/transaction-basics/finality-of-results.md deleted file mode 100644 index d7138cb344..0000000000 --- a/content/concepts/payment-system-basics/transaction-basics/finality-of-results.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -html: finality-of-results.html -parent: transaction-basics.html -blurb: Learn when the outcome of a transaction is final and immutable. -labels: - - Transaction Sending - - Blockchain ---- -# Finality of Results - -The order in which transactions apply to the consensus [ledger](ledgers.html) is not final until a ledger is closed and the exact transaction set is approved by the [consensus process](intro-to-consensus.html). 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][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](transaction-results.html) from doing so. However, the transaction's final result may be very different than its tentative results, for several reasons: - -- The transaction may be delayed until a later ledger version, or may 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](consensus.html) begins, it may 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 may 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.html) 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 may not get relayed to enough servers to achieve a consensus, or may be [queued](transaction-queue.html) for later. - - - Temporary internet outages or delays may 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](ledgers.html#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](offers.html) in the [decentralized exchange](decentralized-exchange.html), whichever one comes first succeeds, and the other fails. Since the order in which those transactions apply may 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. - - - If a [cross-currency payment](cross-currency-payments.html) succeeds by consuming an [Offer](offers.html) in the [decentralized exchange](decentralized-exchange.html), but a different transaction consumes or creates offers in the same order book, the cross-currency payment may succeed with a different exchange rate than it had when it executed tentatively. If it was a [partial payment](partial-payments.html), it could also deliver a different amount. - - - A [Payment transaction][] that tentatively failed because the sender did not have enough funds may 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 may 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](advance-the-ledger-in-stand-alone-mode.html) in such cases. - - -## See Also - -- [Look up Transaction Results](look-up-transaction-results.html) -- [Transaction Results Reference](transaction-results.html) - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-system-basics/transaction-basics/source-and-destination-tags.md b/content/concepts/payment-system-basics/transaction-basics/source-and-destination-tags.md deleted file mode 100644 index f480bceca6..0000000000 --- a/content/concepts/payment-system-basics/transaction-basics/source-and-destination-tags.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -html: source-and-destination-tags.html -parent: transaction-basics.html -blurb: Use source and destination tags to indicate specific purposes for payments from and to multi-purpose addresses. -labels: - - Payments - - Accounts - - Security ---- -# Source and Destination Tags - -_Source tags_ and _destination tags_ are a feature of XRP Ledger [payments](payment-types.html) 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](list-xrp-as-an-exchange.html) or [gateway](become-an-xrp-ledger-gateway.html) 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. - -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.html) 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](reserves.html) 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](require-destination-tags.html). 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. - - -## See Also - -- [Require Destination Tags](require-destination-tags.html) -- [XRP Ledger Businesses](xrp-ledger-businesses.html) -- [Payment Types](payment-types.html) - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-system-basics/transaction-basics/transaction-basics.ja.md b/content/concepts/payment-system-basics/transaction-basics/transaction-basics.ja.md deleted file mode 100644 index 8383ae251a..0000000000 --- a/content/concepts/payment-system-basics/transaction-basics/transaction-basics.ja.md +++ /dev/null @@ -1,226 +0,0 @@ ---- -html: transaction-basics.html -parent: payment-system-basics.html -blurb: トランザクションは、XRP Ledgerの変更を可能にする唯一の手段です。トランザクションの形態とその使用方法について説明します。 -labels: - - トランザクション送信 - - 支払い ---- -# トランザクションの基本 - -_トランザクション（取引）_ は、XRP Ledgerを変更する唯一の方法です。[コンセンサスプロセス](consensus.html)に従って署名され、送信され、検証済みのレジャーバージョンに承認された場合にのみ、トランザクションは最終的なものになります。レジャーのルールによっては、_[疑似トランザクション](pseudo-transaction-types.html)_ も生成されます。このトランザクションは署名も送信もされませんが、コンセンサスによって承認されなければならないことは同様です。失敗したトランザクションであっても、スパム対策の[トランザクションコスト][]を支払のためXRPの残高が変わるため、レジャーに記録されます。 - -トランザクションで行えることは、送金だけではありません。XRP Ledgerのトランザクションは、さまざまな[支払いタイプ](payment-types.html)に対応しているだけでなく、[暗号鍵](cryptographic-keys.html)のローテーション、その他の設定の管理、およびXRP Ledgerの[分散型取引所](decentralized-exchange.html)での取引にも使用されます。[トランザクションタイプの詳細なリスト](transaction-types.html)については、[`rippled` APIリファレンス](http-websocket-apis.html)を参照してください。 - - -### トランザクションの識別 - -署名付きトランザクションには、それを識別する固有の`"hash"`があります。トランザクションを送信すると、サーバーの応答でハッシュが返されます。[account_txコマンド](account_tx.html)を使用して、アカウントのトランザクション履歴でトランザクションを検索することもできます。 - -だれでも最終的なステータスを確認として[ハッシュによってトランザクションを調べる](look-up-transaction-results.html)ことができるため、トランザクションハッシュは「支払いの証明」として使用することができます。 - -{% include '_snippets/setfee_uniqueness_note.ja.md' %} - - - -## 請求コストの正当化 - -失敗したトランザクションに対しても[トランザクションコスト](transaction-cost.html)が発生するのは不公平に思えるかもしれませんが、正当な理由から`tec`クラスのエラーが存在します。 - -* 失敗したトランザクションの後に送信するトランザクションでは、シーケンス値の番号を変更する必要はありません。失敗したトランザクションをレジャーに組み込むと、トランザクションのシーケンス番号が順に使われ予想される順序が保持されます。 -* ネットワーク全体にトランザクションを拡散されられると、ネットワークの負荷が増大します。トランザクションコストを強制することにより、攻撃者が失敗したトランザクションでネットワークを乱用することが難しくなります。 -* トランザクションコストは実際には非常に少額であるため、大量のトランザクションを送信している場合を除き、ユーザーに害を及ぼすことはありません。 - - -## トランザクションの承認 - -分散型XRP Ledgerでは、デジタル署名によって、トランザクションが一定のアクションを起こすが承認されていることが証明されます。署名されたトランザクションのみがネットワークに送信され、検証済みレジャーに含まれます。署名付きトランザクションは不変です。その内容は変更できず、他のトランザクションでこの署名を使用することはできません。 - -トランザクションは、次のいずれかの署名によって承認できます。 - -* 送信元アドレスと数学的に関連付けられている、マスター秘密鍵による単一の署名。[AccountSetトランザクション][]を使用して、マスターキーペアを無効または有効にできます。 -* アドレスに関連付けられているレギュラー秘密鍵と一致する単一の署名。[SetRegularKeyトランザクション][]を使用して、レギュラーキーペアを追加、削除、または置き換えることができます。 -* アドレスが所有する署名者のリストと一致する[マルチ署名](multi-signing.html)。[SignerListSetトランザクション][]を使用して、署名者のリストを追加、削除、または置換することができます。 - -署名の種類に関係なく、あらゆるタイプのトランザクションを承認できます。ただし、次の例外があります。 - -* マスター秘密鍵だけが[マスター公開鍵](accountset.html)を無効にできます。 -* マスター秘密鍵だけが[凍結機能を永続的に放棄](freezes.html#no-freeze)できます。 -* アドレスからトランザクションに署名する最後の方法を削除することはできません。 - -マスターキーとレギュラーキーペアについて詳しくは、[暗号鍵](cryptographic-keys.html)を参照してください。 - - - - -## トランザクションへの署名とトランザクションの送信 - -XRP Ledgerにトランザクションを送信するには、いくつかの手順を実行する必要があります。 - -1. [未署名のトランザクションをJSON形式](#未署名のトランザクションの例)で作成します。 -2. 1つ以上の署名を使用して[トランザクションを承認](#トランザクションの承認)します。 -3. `rippled`サーバーにトランザクションを送信します。トランザクションが適切に作成されている場合、サーバーはそのトランザクションを現行バージョンのレジャーに暫定的に適用し、そのトランザクションをピアツーピアネットワークの他のメンバーに中継します。 -4. [コンセンサスプロセス](consensus.html)によって、次の検証済みレジャーに含まれる暫定的なトランザクションが決定されます。 -5. `rippled`サーバーはそれらのトランザクションを正規順序で前のレジャーに適用し、それらの結果を共有します。 -6. 十分に[信頼できるバリデータ](rippled-server-modes.html#バリデータを運用する理由) がまったく同じレジャーを作成した場合、そのレジャーは _検証済み_ であると宣言され、そのレジャーの[トランザクションの結果](transaction-results.html)は不変となります。 - -XRP決済の送信に関する対話型チュートリアルについては、[Send XRP](send-xrp.html)を参照してください。 - - -### 未署名のトランザクションの例 - -JSON形式の未署名の[Paymentトランザクション][]の例を次に示します。 - -```json -{ - "TransactionType" : "Payment", - "Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", - "Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX", - "Amount" : { - "currency" : "USD", - "value" : "1", - "issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn" - }, - "Fee": "12", - "Flags": 2147483648, - "Sequence": 2, -} -``` - -XRP Ledgerは、トランザクションオブジェクトが送信元アドレス（`Account`内）フィールドによって承認されている場合にのみ、トランザクションを中継して実行します。これを安全に行う方法については、[安全な署名の設定](set-up-secure-signing.html)を参照してください。 - -## 署名付きトランザクションブロブの例 - -トランザクションに署名すると、ネットワークに送信できるバイナリーブロブが生成されます。この場合、`rippled`の[submitコマンド](submit.html)を使用します。署名付きブロブと同じトランザクションの例を示します。このトランザクションは、WebSocket APIを使用して送信されています。 - -```json -{ - "id": 2, - "command": "submit", - "tx_blob" : "120000240000000461D4838D7EA4C6800000000000000000000000000055534400000000004B4E9C06F24296074F7BC48F92A97916C6DC5EA968400000000000000F732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB74483046022100982064CDD3F052D22788DB30B52EEA8956A32A51375E72274E417328EBA31E480221008F522C9DB4B0F31E695AA013843958A10DE8F6BA7D6759BEE645F71A7EB240BE81144B4E9C06F24296074F7BC48F92A97916C6DC5EA983143E9D4A2B8AA0780F682D136F7A56D6724EF53754" -} -``` - -## メタデータを含む実行済みトランザクションの例 - -トランザクションが送信されたら、APIを使用して（例えば、[txコマンド](tx.html)を使用して）トランザクションのステータスを確認できます。これにより、トランザクションの指示、その結果、およびそれを実行する過程で行われたすべての変更の[メタデータ](transaction-metadata.html) が表示されます。 - -**注意:** トランザクションが結果コード`tesSUCCESS`で**検証済み**のレジャーに表示されない限り、トランザクションの成功は確定ではありません。関連項目: [結果のファイナリティー](finality-of-results.html) - -`tx`コマンドの応答の例: - -```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 - } -} -``` - - -## 関連項目 - -- **コンセプト:** - - [支払いタイプ](payment-types.html) - - [コンセンサスネットワーク](consensus-network.html) -- **チュートリアル:** - - [安全な署名の設定](set-up-secure-signing.html) - - [XRPの送金](send-xrp.html) - - [トランザクションの結果の確認](look-up-transaction-results.html) - - [WebSocketを使用した着信ペイメントの監視](monitor-incoming-payments-with-websocket.html) - - [トランザクションの取り消しまたはスキップ](cancel-or-skip-a-transaction.html) - - [信頼できるトランザクションの送信](reliable-transaction-submission.html) -- **リファレンス:** - - [トランザクションの共通フィールド](transaction-common-fields.html) - - [トランザクションのタイプ](transaction-types.html) - - [トランザクションのメタデータ](transaction-metadata.html) - - [account_txメソッド][] - - [txメソッド][] - - [submitメソッド][] - - [submit_multisignedメソッド][] - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-system-basics/transaction-basics/transaction-basics.md b/content/concepts/payment-system-basics/transaction-basics/transaction-basics.md deleted file mode 100644 index c1037879ff..0000000000 --- a/content/concepts/payment-system-basics/transaction-basics/transaction-basics.md +++ /dev/null @@ -1,228 +0,0 @@ ---- -html: transaction-basics.html -parent: payment-system-basics.html -blurb: Transactions are the only way to change the XRP Ledger. Understand what forms they take and how to use them. -labels: - - Payments - - Transaction Sending ---- -# Transaction Basics - -A _Transaction_ is the only way to modify the XRP Ledger. Transactions are only final if signed, submitted, and accepted into a validated ledger version following the [consensus process](consensus.html). Some ledger rules also generate _[pseudo-transactions](pseudo-transaction-types.html)_, which aren't signed or submitted, but still must be accepted by consensus. Transactions that fail are also included in ledgers because they modify balances of XRP to pay for the anti-spam [transaction cost][]. - -Transactions can do more than send money. In addition to supporting various [Payment Types](payment-types.html), transactions in the XRP Ledger are also used to rotate [cryptographic keys](cryptographic-keys.html), manage other settings, and trade in the XRP Ledger's [decentralized exchange](decentralized-exchange.html). The [`rippled` API reference](http-websocket-apis.html) has a complete [list of transaction types](transaction-types.html). - - -### 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](account_tx.html). - -The transaction hash can be used as a "proof of payment" since anyone can [look up the transaction by its hash](look-up-transaction-results.html) to verify its final status. - -{% include '_snippets/setfee_uniqueness_note.md' %} - - - -## Claimed Cost Justification - -Although it may seem unfair to charge a [transaction cost](transaction-cost.html) 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. - -A transaction can be authorized by any of the following types of signatures: - -* 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.html) 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](accountset.html). -* Only the master private key can [permanently give up the ability to freeze](freezes.html#no-freeze). -* You can never remove the last method of signing transactions from an address. - -For more information about master and regular key pairs, see [Cryptographic Keys](cryptographic-keys.html). - - - - -## 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](xrpl-servers.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](rippled-server-modes.html#validators) created the exact same ledger, that ledger is declared _validated_ and the [results of the transactions](transaction-results.html) in that ledger are immutable. - -See [Send XRP](send-xrp.html) for an interactive tutorial in sending XRP payments. - - -### 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, -} -``` - -The XRP Ledger only relays and executes a transaction if the transaction object has been authorized by the sending address (in the `Account`) field. For instructions on how to do this securely, see [Set Up Secure Signing](set-up-secure-signing.html). - -## Example Signed Transaction Blob - -Signing a transaction results in a chunk of binary data, called a "blob", that can be submitted to the network. Here is an example of the same transaction, as a signed blob, being [submitted with the WebSocket API](submit.html): - -```json -{ - "id": 2, - "command": "submit", - "tx_blob" : "120000240000000461D4838D7EA4C6800000000000000000000000000055534400000000004B4E9C06F24296074F7BC48F92A97916C6DC5EA968400000000000000F732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB74483046022100982064CDD3F052D22788DB30B52EEA8956A32A51375E72274E417328EBA31E480221008F522C9DB4B0F31E695AA013843958A10DE8F6BA7D6759BEE645F71A7EB240BE81144B4E9C06F24296074F7BC48F92A97916C6DC5EA983143E9D4A2B8AA0780F682D136F7A56D6724EF53754" -} -``` - -## Example Executed Transaction with Metadata - -After a transaction has been executed, the XRP Ledger adds [metadata](transaction-metadata.html) to show the transaction's final outcome and all the changes that the transaction made to the shared state of the XRP Ledger. - -You can check a transaction's status using the API, for example using the [tx command](tx.html). - -**Caution:** The results of a transaction, including all its metadata, are not final unless the transaction appears in a **validated** ledger. See also: [Finality of Results](finality-of-results.html). - -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 - } -} -``` - - -## 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][] - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-system-basics/transaction-basics/understanding-signatures-draft.md b/content/concepts/payment-system-basics/transaction-basics/understanding-signatures-draft.md deleted file mode 100644 index d8ee700472..0000000000 --- a/content/concepts/payment-system-basics/transaction-basics/understanding-signatures-draft.md +++ /dev/null @@ -1,74 +0,0 @@ -# Understanding Signatures - -***TODO: DRAFT*** - -***TODO: Question: Added this concept section based on fantastic source material from Rome -- thought we should publish it. Useful? May be good to associate it with a flow diagram - like the one for address encoding: https://ripple.com/build/accounts/#address-encoding. Address both single and multi-sign flows.*** - -In the XRP Ledger, a digital signature proves that a transaction is authorized to do a specific set of actions. A digital signature is created based on a [key pair](cryptographic-keys.html) associated with the transaction's sending account. - -Here's an overview of some of the more common signature-related fields used in the XRP Ledger. - -***TODO: address from Ryan: Where would you see these fields? Either address in text -- or ensure that this is answered via the flow diagram discussed below.*** - -***TODO: JHA fix the IA here. Also need to more clearly express the single-signer flow vs multi-signer flow. Provide a flow diagram. Also need to move some conceptual content out of "Authorizing Transactions" and "Signing and Submitting Transactions" and put it in this doc.*** - -## `SigningPubKey` (top-level) - -The public key of the sender in hex format. Empty in the case of a multi-signed transaction. - -To verify whether a single-signed transaction is valid, a `rippled` server checks that all of the following are true: - -1. This key hashes to an address that's authorized by the transaction's sender. - - The default is that only the address of an account is authorized to send all transactions for that account. That address is [derived from](accounts.html#address-encoding) the public key from the master key pair that was generated during address creation. Regular keys add a different address (derived from a different key pair) that's authorized to send most transactions. And of course, you can also disable the [master key](cryptographic-keys.html) or add a [multi-signing list](reference-transaction-format.html#multi-signing). ***TODO: address from Ryan: "And of course" - Nit: this seems a little informal. Maybe just drop it and go into the next sentence? JHA take a closer look at what this sentence is trying to say.*** - -2. This key matches the signature on the transaction. - -3. The signature matches the transaction instructions. - -The validation process for multi-signed transactions is slightly different. For more information, see [`Signers[*].SigningPubKey`](#signerssigningpubkey). - - -## `TxnSignature` (top-level) - -The signature of the transaction instructions, in hex format. - -Used with the `SigningPubKey` to verify that the sender did in fact approve the corresponding transaction instructions. - -***TODO: Ensure that this doc reflects this: In transactions, we have two TxnSignature fields—one at the top level for single-signed transactions, and one in each member of the Signers array for multi-signed transactions. (Any given transaction has either the top level TxnSignature or the members in the Signers array but not both.)*** - -## `Signers` (in a multi-signed transaction) - -An array of signature data for a [multi-signed transaction](reference-transaction-format.html#multi-signing). - -Used to verify that a quorum of signers approved a transaction. - - -### `Signers[*].AccountID` - -The address of one signer, in base58. -***TODO: JHA: Slightly nitpicky note (relevant to all the fields, but it especially attracted my notice here): the base58 is how it's generally represented in JSON. In the canonical binary format, I believe this is the AccountID as a 160-bit number, so it's not base58-encoded and doesn't have the checksum in the binary format. Similarly, hexadecimal is just a way of representing a 160-bit number in formats like JSON. In the native binary format, the various fields are just numbers/data in various low-level computer formats. That's only relevant for people who are trying to implement offline signing, though. Everyone else will probably see the JSON representation, where they'll want to know what the conventional way to represent the fields is.*** - -Identifies which signer from the (predefined) [multi-signing list](reference-transaction-format.html#multi-signing) this portion of the multi-signature represents. - - -### `Signers[*].TxnSignature` - -One signature, as hexadecimal. - -Verifying a [multi-signed transaction](reference-transaction-format.html#multi-signing) involves making sure each such signature is valid for its `SigningPubKey` and the transaction instructions. - - -### `Signers[*].SigningPubKey` - -The public key of one signer. Verifying a [multi-signed transaction](reference-transaction-format.html#multi-signing) involves making sure each such key is authorized to sign for the `AccountID` of the signer. - -Multi-signature `AccountIDs` are a little special. If one is an address that doesn't exist in the ledger, then the `SigningPubKey` must hash to the `AccountID` value using the standard rules for [deriving an AccountID](accounts.html#address-encoding) from a public key. If the address does exist in the ledger, then either: - -1. The `SigningPubKey` must hash to the `AccountID` and the address must not have the master key disabled. - - or - -2. The `SigningPubKey` must hash to a regular key that the address has set in the ledger. - -For more information about signing transactions, see [Signing and Submitting Transactions](reference-transaction-format.html#signing-and-submitting-transactions). diff --git a/content/concepts/payment-types/checks.ja.md b/content/concepts/payment-types/checks.ja.md deleted file mode 100644 index 85f1e1f4be..0000000000 --- a/content/concepts/payment-types/checks.ja.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -html: checks.html -parent: payment-types.html -blurb: Checksを使用すると、指定の受取人による取消または換金が可能な後払いの支払いを生成することができます。 -labels: - - Checks - - 支払い - - トークン ---- -# Checks - -_（[Checks Amendment][]が必要です）_ - -XRP LedgerのChecks機能を使用すると、指定の受取人による取消または換金が可能な後払いの支払いを生成することができます。個人用の紙の小切手と同様に、XRP Ledger Checksでは最初に資金の送金元が金額と受取人を指定するCheckを作成します。受取人はCheckを換金して、送金元のアカウントから受取人のアカウントに資金を移動します。受取人がCheckを換金するまでは、実際の資金移動は発生しません。Checkの作成時には資金は保留されていないことから、受取人が換金する時点で送金元に十分な資金がない場合、従来の小切手同様に換金が失敗します。Checkを換金できなかった場合、送信者はCheckが有効期限切れになるまで再試行できます。 - -XRP Ledger Checksには有効期限があり、この期限を過ぎると換金できなくなります。受取人が有効期限までにCheckを換金できなかった場合、Checkオブジェクトは誰かに取り消されるまでXRP Ledgerに残ります。有効期限切れになったCheckは誰でも取り消すことができます。有効期限前、あるいはChecksが換金されるまでは、送金元と受取人のみがCheckを取り消すことができます。Checkオブジェクトは、送金元がそのCheckを換金できた時点または誰かが取り消した時点でLedgerから削除されます。 - -Checksは[Escrow](escrow.html)と[Payment Channel](use-payment-channels.html)に似ていますが、Checksとこれらの機能の間には重要な相違がいくつかあります。 - -* Checksでは発行済み通貨を送金できます。Payment ChannelとEscrowで送金できるのはXRPのみです。 - -* Checksは資金を凍結しません。Payment ChannelとEscrowでは、送金元が発行したクレームでXRPが清算されるか（Payment Channel）、または有効期限切れまたはCrypto-conditionsによってXRPがリリースされる（Escrow）までは、そのXRPを使用できません。 - -* EscrowではXRPを自分自身に送金できます。ChecksとPayment Channelを使用してXRP（Checksの場合は発行済み通貨）を自身に送金することはできません。 - - -**注記:** [Checks Amendment][] により、[OfferCreate][]トランザクションの有効期限が変更されます。詳細は[オファーの有効期限](offers.html#オファーの有効期限)を参照してください。 - - -## Checksを利用する理由 - -従来の紙の小切手では、実際の通貨を即座にやり取りすることなく残高を送金できます。XRP Ledger Checksを使用すると、銀行業界でよく利用され受け入れられている方法で資金を非同期にやり取りすることができます。 - -XRP Ledger Checksは、XRP Ledgerに固有の問題も解決できます。たとえば、ユーザーが不審な支払いを拒否したり、支払いの一部のみを受領することを可能にします。これは、コンプライアンス上の理由から支払いの受け入れに慎重に対応する必要がある機関にとっては有用です。 - -Checksはその他のさまざまな用途に利用できる可能性があります。RippleはコミュニティにてChecksの新しく創造的な用途が探られていくことを推奨しています。 - - -### ユースケース: 支払いの承認 - -**課題:** [BSA、KYC、AML、CFT](become-an-xrp-ledger-gateway.html#compliance-guidelines)などの規制に準拠するにあたり、金融機関は受領する資金の送金元に関する文書を提出する必要があります。違法な資金移動を防止するため、これらの規制は金融機関に対して、処理済のすべての支払いについて、その送金元と送金先を開示するよう義務付けています。XRP Ledgerの性質上、誰でもXRPを（および該当する場合には発行済み通貨を）XRP Ledger上の金融機関のアカウントに送金することができます。金融機関のコンプライアンス部門では、このような不審な支払いへの対応にかかるコスト（罰金の可能性を含む）の増大と処理の遅れが生じます。 - -**解決策:** 金融機関は各自のXRP Ledgerのアカウントで、[`AccountSet`トランザクションの`asfDepositAuth`フラグを設定](accountset.html)することにより、[Deposit Authorization](depositauth.html)を有効にできます。これにより、アカウントはPaymentトランザクションを受領できなくなります。Deposit Authorizationが有効なアカウントは、Escrow、Payment Channel、またはChecksでのみ資金を受領できます。Deposit Authorizationが有効な場合、Checksが最もシンプルで使いやすく、柔軟な資金移動手段となります。 - - -## 使用法 - -Checksの一般的なライフサイクルを以下で説明します。 - - - -[![Checkのフローチャート（換金に成功した場合）](img/checks-happy-path.ja.png)](img/checks-happy-path.ja.png) - -**ステップ1:** Checkを作成するため、送金元が[CheckCreate][]トランザクションを送信し、受取人（`Destination`）、有効期限（`Expiration`）、および送金元アカウントからの引き落とし限度額（`SendMax`）を指定します。 - - -**ステップ2:** CheckCreateトランザクションの処理が完了すると、XRP Ledgerに[Checkオブジェクト](check.html)が作成されます。このオブジェクトには、オブジェクトを作成したトランザクションにより定義されたCheckのプロパティーが含まれています。有効期限前にこのオブジェクトを変更できるのは、送金元（[CheckCancel][]トランザクションで取り消す）と受取人（取り消すかまたは換金する）だけです。有効期限の経過後は、誰でもCheckを取り消すことができます。 - -**ステップ3:** Checkを換金するため、受取人が[CheckCash][]トランザクションを送信します。受取人には次の2つのCheck換金オプションがあります。 - -* `Amount` — 受取人はこのオプションを使用して換金する正確な額を指定できます。これは、送金元が想定される[送金手数料](transfer-fees.html)をCheckの額に上乗せし、受取人は請求書やその他の契約に記載されている指定された額のみ受け取れるようにする場合に役立ちます。 - -* `DeliverMin` — 受取人はこのオプションを使用してCheckから受領する最小額を指定できます。受取人がこのオプションを使用する場合、`rippled`は可能な限り多くの送金を試み、少なくともこの額以上を送金します。受取人に入金できる額がこの額よりも少ない場合には、このトランザクションは失敗します。 - -送金元にCheckの裏付けとなる資金が十分あり、有効期限が経過してなければ、資金は送金元のアカウントから引き落とされ、受取人のアカウントに入金され、Checkオブジェクトは消却されます。 - - - -#### 有効期限切れの例 - -Checksが有効期限切れになった場合のライフサイクルを以下で説明します。 - - - -[![Checkのフローチャート（有効期限切れ）](img/checks-expiration.ja.png)](img/checks-expiration.ja.png) - - -Checksはすべて同じ方法で開始されるため、**ステップ1と2**は換金の例と同じです。 - -**ステップ3a:** 受取人が換金する前にCheckが有効期限切れになると、そのCheckは換金できなくなりますが、レジャーに残ります。 - -**ステップ4a:** 有効期限切れになったCheckは、[CheckCancel][]トランザクションを送信することで誰でも取り消すことができます。このトランザクションによりレジャーからCheckが削除されます。 - - - -## Checksの利用可能性 - -Checksを使用するには`rippled` v0.90.0以降が必要です。2018年10月11日の時点では、Checks Amendmentは本番環境のXRP Ledgerで有効になっていません。すべての既知のAmendmentの最新状況については、[既知のAmendment](known-amendments.html)を参照してください。Amendmentを有効化し、Amendmentに投票する方法については、[Amendmentプロセス](amendments.html#amendmentプロセス)を参照してください。 - -Test NetまたはプライベートXRP LedgerネットワークでのAmendmentの状況を確認するには、[featureメソッド][]を使用してください。 - - -## 参考情報 - -XRP LedgerのChecksの詳細は、以下を参照してください。 - -- [トランザクションのリファレンス](transaction-types.html) - - [CheckCreate][] - - [CheckCash][] - - [CheckCancel][] -- [Checksのチュートリアル](use-checks.html) - - [Checkの送信](send-a-check.html) - - [送金元アドレスに基づくChecksの検索](look-up-checks-by-sender.html) - - [受取人アドレスに基づくChecksの検索](look-up-checks-by-recipient.html) - - [Checkの指定された金額での換金](cash-a-check-for-an-exact-amount.html) - - [Checkの変動金額での換金](cash-a-check-for-a-flexible-amount.html) - - [Checkの取消し](cancel-a-check.html) -- [Checks Amendment][] - -関連機能の詳細については、以下を参照してください。 - -* [Deposit Authorization](depositauth.html) -* [Escrow](escrow.html) -* [Payment Channelチュートリアル](use-payment-channels.html) - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-types/checks.md b/content/concepts/payment-types/checks.md deleted file mode 100644 index 5e13e926c5..0000000000 --- a/content/concepts/payment-types/checks.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -html: checks.html -parent: payment-types.html -blurb: Checks let users create deferred payments that can be canceled or cashed by the intended recipients. -labels: - - Checks - - Payments - - Tokens ---- -# 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.html) and [Payment Channels](use-payment-channels.html), but there are some important differences between those features and Checks: - -* You can send [tokens](tokens.html) 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](become-an-xrp-ledger-gateway.html#compliance-guidelines), 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. - -**Solution:** Institutions can enable [Deposit Authorization](depositauth.html) on their XRP Ledger accounts by [setting the `asfDepositAuth` flag in an `AccountSet` transaction](accountset.html). 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. - - - -[![Check flow diagram (successful cashing)](img/checks-happy-path.png)](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](check.html) 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](transfer-fees.html) 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. - - - -[![Check flow diagram (expiration)](img/checks-expiration.png)](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. - - - - -## 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.html#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) - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-types/cross-currency-payments.ja.md b/content/concepts/payment-types/cross-currency-payments.ja.md deleted file mode 100644 index 1a14a03003..0000000000 --- a/content/concepts/payment-types/cross-currency-payments.ja.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -html: cross-currency-payments.html -parent: payment-types.html -blurb: 複数通貨間の支払いでは、パスとオーダーブックを通じて変換するのとは異なる通貨を自動的にに送金します。 -labels: - - 複数通貨間 - - 支払い ---- -# 複数通貨間の支払い - -XRP Ledgerでは、1つ以上の発行済み通貨、XRP、またはその両方を交換して、複数通貨間で支払いを送金できます。[XRPによる直接支払](use-simple-xrp-payments.html)と同様に、このような支払いでは[Paymentトランザクションタイプ][Payment]が使用されます。XRP Ledgerでの複数通貨間の支払いは完全に非可分です。つまり、支払いを全額実行するか、またはまったく実行しないかのいずれかになります。 - -デフォルトでは、複数通貨間の支払いでは宛先に一定額が送金され、支払元が変動コストを負担します。複数通貨間の支払いが、[Partial Payments](partial-payments.html)で行われ、一定の送金限度内の変動額が宛先に送金される場合もあります。 - - -## 前提条件 - -- 定義上、複数通貨間支払いには2種類以上の通貨が関係します。つまり、関係する通貨のうち、少なくとも1種類以上がXRP以外の発行済み通貨である必要があります。 - - 通常は、[XRP Ledgerゲートウェイ](become-an-xrp-ledger-gateway.html)が発行した通貨を1種類以上使用することになります。このような通貨はXRP Ledger外部の資金を担保とし、ゲートウェイを通じて引き出すことができます。 - - 取引を行う当事者が、XRP Ledger内でのみ発行され、外部の担保がないデジタルトークンを送受信し、何らかの価値を持つ資産として取り扱うことを望む限り、このデジタルトークンを使用することもできます。 -- 送金元と受取人の間に1つ以上の[パス](paths.html)が確立しており、すべてのパスの総流動性が、支払いを促進するのに十分である必要があります。複数通貨間の支払いの場合、これは一般に通貨取引[オファー](offers.html)を消費することを意味します。 - - -## オートブリッジング - -2種類の発行済み通貨を自動的に交換する複数通貨間の支払いでは、XRPの使用により支払いコストを抑えられる場合には自動的にXRPが使用されます。この場合、オーダーブックを接続して流動性プールが拡大されます。たとえば、USDからMXNに送金する支払いの場合、USDからXRP、XRPからMXNへの交換にかかるコストが、USDからMXNへの直接交換にかかるコストよりも低い場合には、前者の交換が自動的に実行されます。 - -詳細は、[オートブリッジング](autobridging.html)を参照してください。 - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-types/cross-currency-payments.md b/content/concepts/payment-types/cross-currency-payments.md deleted file mode 100644 index d79df06581..0000000000 --- a/content/concepts/payment-types/cross-currency-payments.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -html: cross-currency-payments.html -parent: payment-types.html -blurb: Cross-currency payments atomically deliver a different currency than they send by converting through paths and order books. -labels: - - Cross-Currency - - Payments ---- -# Cross-Currency Payments - -In the XRP Ledger, you can send cross-currency payments that exchange tokens, XRP, or both. Like [direct XRP payments](use-simple-xrp-payments.html), these payments use the [Payment transaction type][Payment]. 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.html), 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.html). -- There must be at least one [Path](paths.html) 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](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) - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-types/direct-xrp-payments.ja.md b/content/concepts/payment-types/direct-xrp-payments.ja.md deleted file mode 100644 index b8ed15c8db..0000000000 --- a/content/concepts/payment-types/direct-xrp-payments.ja.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -html: direct-xrp-payments.html -parent: payment-types.html -blurb: XRPによる直接支払いは、XRP Ledgerで資産を送金する最も簡単な方法です。 ---- -# XRPによる直接支払 - -金融システムの基本は、 _価値の移動_ です。一言で言えば、決済です。XRP Ledgerでの最も簡単な支払いタイプは、XRP間の直接支払で、XRP Ledgerのあるアカウントから別のアカウントにXRPを直接移動します。 - -## XRP間の直接支払について - -一般的に、XRPは、XRP Ledgerのどのアドレスからでも、他のアドレスに直接送金できます。受信側のアドレスは _宛先アドレス_ 、送信側のアドレスは _支払元アドレス_ と呼ばれます。XRPを直接送金するには、送信者は[Paymentトランザクション][]を使用します。これは、次のように簡潔に表すことができます。 - -```json -{ - "TransactionType": "Payment", - "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", - "Destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX", - "Amount": "13000000" -} -``` - -上記のトランザクション指示によって、以下のように実行されます。rf1Bi ...からra5nK... にPaymentを送信することで、ちょうど13 XRPが送金されます。トランザクションが正常に処理されると、その内容が正確に実行されます。新しいレジャーバージョンが[検証済み](consensus.html)になるまでに、通常約4秒かかるため、現在処理中のレジャーの後にレジャーバージョンのキューに入れられても、正常なトランザクションを作成、送信、実行後、8秒以内に最終結果を出すことができます。 - -**注意:** [Paymentトランザクションタイプ][Payment]は、[通貨間の支払い](cross-currency-payments.html)や[Partial Payment](partial-payments.html)を含む、より特殊な支払いにも使用できます。Partial Paymentの場合、トランザクションで非常に少ない金額しか送金しなかった場合でも、多額のXRPが`Amount`に表示される可能性があります。誤った金額を顧客に入金しないようにする方法については、[Partial Paymentの悪用](partial-payments.html#partial-paymentの悪用)を参照してください。 - -XRP間の直接支払ではPartial Paymentは使用できませんが、Partial Paymentでは複数の送金元通貨から変換後にXRPを送金できます。 - - -## アカウントの資金提供 - -XRP Ledgerにそのアドレスの記録が事前に存在していなくても、支払いで[口座準備金](reserves.html)の最少額を満たすのに十分なXRPが送金されれば、数学的に有効なアドレスで支払いを受け取ることができます。支払いで十分なXRPを送金できない場合は失敗します。 - -詳細は、[アカウント](accounts.html#アカウントの作成)を参照してください。 - - -## アドレスの再利用 - -XRP Ledgerでは、支払いを受け取ることができるアドレスは永続的ですが、XRPの重要な[必要準備金](reserves.html)は消費できません。つまり、他の一部のブロックチェーンシステムとは異なり、トランザクションごとに異なる使い捨てアドレスを使用することはお勧めできません。XRP Ledgerでは、ベストプラクティスとして、複数のトランザクションに同じアドレスを再利用することをお勧めします。アドレスを定期的に使用する場合（特にインターネット接続サービスによって管理されている場合）は、[レギュラーキー](cryptographic-keys.html)を設定し、キーの漏えいのリスクを低減するためにキーを定期的に事前変更する必要があります。 - -送金元は、目的の受取人が最後に支払いを送信したときと同じアドレスを使用していると仮定しないことが重要です。必然的に、セキュリティの侵害が発生し、ユーザーまたは企業はアドレスを変更しなければならない場合があります。送金する前に、現在の受取アドレスを受取人に尋ねてください。これにより、漏えいした古いアドレスを制御している不正ユーザーに誤ってお金を送信することはありません。 - - -## XRPによる直接支払の処理方法 - -大まかに言えば、XRP Ledgerのトランザクション処理エンジンでは、XRPによる直接支払を次のように適用します。 - -1. [Paymentトランザクション][]のパラメータを検証します。トランザクションがXRPを送信、送金するように構成されている場合、トランザクション処理エンジンはそのトランザクションをXRP間の直接支払として認識します。検証チェックは次のように行います。 - - - すべてのフィールドが正しいフォーマットであることを確認します。たとえば、XRPによる直接支払の場合、`Amount`フィールドは[XRPのdrop数][]でなければなりません。 - - 送信元アドレスがXRP Ledgerの資金供給された[アカウント](accounts.html)であることを確認します。 - - 指定された署名がすべて、送信元アドレスに対して有効であることを確認します。 - - 宛先アドレスと送金元アドレスが異なることを確認します。（[宛先タグ](source-and-destination-tags.html)が異なる同一アドレスに送金するだけでは不十分です。） - - Paymentを送信するのに十分なXRP残高が送金元にあることを確認します。 - - いずれかのチェックに失敗すると、支払いは失敗します。 - -2. 受取アドレスが、資金供給されたアカウントかどうかを確認します。 - - - 受取アドレスに資金が供給されている場合は、[DepositAuth](depositauth.html)や[RequireDest](source-and-destination-tags.html#requiring-tags)など、支払いの受け取りに関する制限が受取アドレスにあるかどうかを確認します。そのような制限を支払いが満たしていない場合、支払いは失敗します。 - - 受取アドレスに資金が供給されていない場合は、[必要準備金](reserves.html)の最低額を満たすのに十分なXRPが支払いで送金されるかどうかを確認します。十分でない場合、支払いは失敗します。 - -3. `Amount`フィールドで指定されたXRPの金額と、[トランザクションコスト](transaction-cost.html)用に消却されるXRPの金額の合計を送金元アカウントから引き落とし、受取アカウントに同じ金額を送金します。 - - 必要に応じて、受取アドレス用に新規アカウント([AccountRootオブジェクト](accountroot.html)) を作成します。新規アカウントの開始残高は、支払いの`Amount`と同額になります。 - - エンジンは、[トランザクションのメタデータ](transaction-metadata.html)に`delivered_amount`フィールドを追加して、送金金額を示します。正しい金額のXRPを受け取ったことを確認できるように、必ず`delivered_amount`を使用する必要があります。`Amount`フィールドでは**ありません**。（通貨間の支払「Partial Payment」では、`Amount`フィールドに記載されているよりも少額のXRPが送金される場合があります。）詳細は、[Partial Payments](partial-payments.html)を参照してください。 - - -## 他の支払いタイプとの比較 - -- **XRPによる直接支払**は、単一のトランザクションでXRPを送受信する唯一の方法です。この方法は、速度、シンプルさ、低コストの面でバランスが取れています。 -- [通貨間の支払い](cross-currency-payments.html)でも[Payment][]トランザクションタイプを使用しますが、XRPとXRP以外の[発行済み通貨](issued-currencies.html)を組み合わせて送金できます。ただし、XRP間の支払いは除きます。また、[Partial Payment](partial-payments.html)でも使用できます。通貨間の支払いは、XRPで指定されていない支払いや、[分散型取引所](decentralized-exchange.html)で裁定取引の機会を得るのに適しています。 -- [Checks](checks.html)すぐに送金せずに送金元に債務を設定してもらいます。受取人は有効期間内であればいつでも換金できますが、その金額は保証されません。Checksでは、XRPまたは発行済み通貨のいずれかを送金できます。Checksは、受取人に支払いを請求する自律性を与えるのに適しています。 -- [Escrow](escrow.html)では、特定の条件が満たされたときに、意図した受取人が要求できるXRPを確保します。XRPの金額は完全に保証されており、Escrowの有効期限が切れない限り、送金元が使用することはできません。Escrowは、巨額のスマートコントラクトに適しています。 -- [Payment Channel](payment-channels.html)では、XRPが確保されます。受取人は、署名による認証を使用して、チャネルから一括でXRPを要求できます。XRP Ledgerの全トランザクションを送信せずに、認証を個々に確認できます。Payment Channelは、極めて大量の小口決済または「ストリーミング」支払いに適しています。 - - -## 関連項目 - -- **コンセプト:** - - [決済システムの基本](payment-system-basics.html) -- **チュートリアル:** - - [XRPの送金（対話型チュートリアル）](send-xrp.html) - - [WebSocketを使用した着信ペイメントの監視](monitor-incoming-payments-with-websocket.html) -- **リファレンス:** - - [Paymentトランザクション][] - - [トランザクションの結果](transaction-results.html) - - [account_infoメソッド][] - XRP残高を確認します。 - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-types/direct-xrp-payments.md b/content/concepts/payment-types/direct-xrp-payments.md deleted file mode 100644 index 711c89e6cc..0000000000 --- a/content/concepts/payment-types/direct-xrp-payments.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -html: direct-xrp-payments.html -parent: payment-types.html -blurb: Direct XRP payments are the simplest way to send value in the XRP Ledger. -labels: - - XRP - - Payments ---- -# 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](consensus.html), 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][Payment] can also be used for some more specialized kinds of payments, including [cross-currency payments](cross-currency-payments.html) and [partial payments](partial-payments.html). 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.html#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](reserves.html). If the payment would not deliver enough XRP, it fails. - -For more information, see [Accounts](accounts.html#creating-accounts). - - -## Address Reuse - -In the XRP Ledger, addresses where you can receive payments are permanent, and have a non-trivial [reserve requirement](reserves.html) 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](cryptographic-keys.html) 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.html) 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.html).) - - 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](depositauth.html) or [`RequireDest`](source-and-destination-tags.html#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](reserves.html). 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.html) and credits the receiving account for the same amount. - - If necessary, it creates a new account ([AccountRoot object](accountroot.html)) 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.html) 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.html). - - -## 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.html) also use the [Payment][] transaction type, but can send any combination of XRP and non-XRP [tokens](tokens.html) except XRP-to-XRP. They can also be [partial payments](partial-payments.html). Cross-currency payments are good for payments not denominated in XRP or for taking arbitrage opportunities in the [decentralized exchange](decentralized-exchange.html). -- [Checks](checks.html) 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.html). Checks are good for giving the recipient the autonomy to claim the payment. -- [Escrow](escrow.html) 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.html) 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 - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-types/escrow.ja.md b/content/concepts/payment-types/escrow.ja.md deleted file mode 100644 index d3bfd02d1b..0000000000 --- a/content/concepts/payment-types/escrow.ja.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -html: escrow.html -parent: payment-types.html -blurb: XRPはEscrowに預託され、後日特定の条件が満たされた時点で送金されます。Escrowは時間制限、暗号条件、あるいはその両方によって異なる場合があります。 -labels: - - Escrow - - スマートコントラクト ---- -# Escrow - -Escrowは、XRP建ての条件付き送金決済を可能にするXRP Ledgerの機能です。 _Escrow_ と呼ばれるこの条件付き決済では、XRPはエスクローに預託され、後日特定の条件が満たされた時点で送金されます。Escrowを完了する条件には、時間ベースのロック解除や[Crypto-conditions][]などがあります。期限までに終了しなかった場合に期限切れとなるようにEscrowを設定することもできます。 - -エスクローに預託されているXRPはロックアップされます。Escrowが正常に終了またはキャンセルされるまでは、誰もXRPを使用または消却できません。有効期限前は、指定された受取人のみがXRPを受領できます。有効期限経過後は、XRPは送金元にのみ返金されます。 - -## 使用法 - - - -[![Escrowのフローチャート（正常終了）](img/escrow-success-flow.ja.png)](img/escrow-success-flow.ja.png) - -**ステップ1:** Escrowを送信するにあたり、送金元は[EscrowCreateトランザクション][]を使用していくらかのXRPをロックアップします。このトランザクションでは、終了時刻または有効期限、あるいはその両方が定義されます。また、このトランザクションでは、Escrow終了時に満たされるべきCrypto-conditionも定義できます。さらに、このトランザクションでは、XRPの指定受取人を定義する必要があります。受取人と送金元は同じでも _かまいません_ 。 - -**ステップ2:** このトランザクションの処理完了後に、エスクローに預託されたXRPを保持する[Escrowオブジェクト](escrow-object.html)がXRP Ledgerに作成されます。このオブジェクトには、オブジェクトを作成したトランザクションにより定義されたEscrowのプロパティーが含まれています。このEscrowに終了時刻が設定されている場合、この時刻まではXRPには誰もアクセスできません。 - -**ステップ3:** 受取人またはその他のXRP Ledgerアドレスが[EscrowFinishトランザクション][]を送信し、XRPが送金されます。正しい条件が満たされると、レジャーのEscrowオブジェクトは消却され、XRPが指定受取人に入金されます。EscrowにCrypto-conditionが指定されている場合、このトランザクションにはその条件に対するフルフィルメントが含まれている必要があります。Escrowの有効期限がすでに切れている場合、EscrowFinishトランザクションはコード[`tecNO_PERMISSION`](tec-codes.html)で失敗します。 - -### 有効期限切れの例 - -[![Escrowのフローチャート（期限切れEscrow）](img/escrow-cancel-flow.ja.png)](img/escrow-cancel-flow.ja.png) - -Escrowはすべて同じ方法で開始されるため、**ステップ1と2**は正常終了の例と同じです。 - -**ステップ3a:** Escrowに有効期限が設定されており、有効期限までにEscrowが正常に終了しなかった場合、Escrowは期限切れとみなされます。XRP Ledgerに引き続き残りますが、これ以降は正常に終了できなくなります。（期限切れオブジェクトは、トランザクションにより変更されるまでレジャーに残ります。時間ベースのトリガーではレジャーの内容は変更できません。） - -**ステップ4a:** 送金元またはその他のXRP Ledgerアドレスが、[EscrowCancelトランザクション][]を送信し、期限切れのEscrowをキャンセルします。これによりレジャーの[Escrowオブジェクト](escrow-object.html)が消却され、XRPは送金元に返金されます。 - -## 制約事項 - -Escrowは、XRP Ledgerを[Interledger Protocol][]やその他のスマートコントラクトで使用できるようにする機能として設計されています。現行バージョンでは、複雑にならないように範囲が適度に制限されています。 - -- EscrowはXRPでのみ実行でき、発行済み通貨では実行できません。 -- Escrowでは、少なくとも2つのトランザクション（Escrowを作成するトランザクションとEscrowを終了またはキャンセルするトランザクション）を送信する必要があります。したがって、参加者は2つのトランザクションの[トランザクションコスト](transaction-cost.html)を消却する必要があるため、ごく少額の決済にEscrowを使用することは合理的ではありません。 - - Crypto-conditionを使用する場合、[EscrowFinishトランザクションのコスト](#escrowfinishトランザクションのコスト)が通常よりも高くなります。 -- Escrowはすべて、「Finish-after」時刻または[Crypto-condition][]のいずれか、またはこの両方を使用して作成する必要があります。EscrowにFinish-after時刻が設定されていない場合は、有効期限が設定されている必要があります。 - - **注記:** [fix1571 Amendment][] でEscrowの作成要件が変更されました。このAmendmentよりも前に作成されたEscrowでは、条件やFinish-after時刻を指定せずに有効期限を指定できました。このようなEscrowは誰でも即時に終了できます（資金を指定受取人に送金します）。 - -- Escrowを作成するトランザクションの実行時には、時刻の値が過去の時間であってはなりません。 -- 時限リリースおよび有効期限は、XRP Ledgerクローズに制約されます。つまり実際には、レジャーの正確なクローズ時刻に基づいて、これらの時刻が約5秒単位で丸められる場合があります。 -- サポートされている唯一の[Crypto-condition][]タイプはPREIMAGE-SHA-256です。 - -Escrowは、少量の大口決済に適した大きな保証を提供しています。[Payment Channel](use-payment-channels.html)は、迅速な小口決済に適しています。もちろん、条件無しの[決済](payment.html)も多くのユースケースで好まれます。 - -## 状態遷移図 - -次の図は、Escrow実施時の各状態を示します。 - -[![Escrowの状態がHeld → Ready/Conditionally Ready → Expiredと遷移する様子を示す状態遷移図](img/escrow-states.ja.png)](img/escrow-states.ja.png) - -この図は、Escrowの「Finish-after」時刻（`FinishAfter`フィールド）、Crypto-condition（`Condition`フィールド）、および有効期限（`CancelAfter`フィールド）の3通りの組み合わせの3つの例を示します。 - -- **時間ベースのEscrow（左）:** Finish-after時刻のみが設定されているEscrowは、**Held**状態で作成されます。指定の時刻が経過すると**Ready**になり、誰でもこのEscrowを終了できるようになります。Escrowに有効期限が設定されており、その時刻になるまでに誰もEscrowを終了しないと、そのEscrowは**Expired**になります。Expired状態では、Escrowを終了できなくなり、誰でもEscrowをキャンセルできるようになります。Escrowに`CancelAfter`フィールドが設定されていない場合、Escrowが期限切れになることがないため、キャンセルできません。 - -- **コンビネーションEscrow（中央）:** EscrowでCrypto-condition（`Condition`フィールド） _および_ 「Finish-after」時刻（`FinishAfter` フィールド）の両方が指定されている場合、Finish-after時刻が経過するまでEscrowは**Held**状態です。その後**Conditionally Ready**になり、Crypto-conditionに対し正しいフルフィルメントを提供すればEscrowを終了できます。Escrowに有効期限（`CancelAfter`フィールド）が設定されており、その時刻になるまでに誰もEscrowを終了しないと、そのEscrowは**Expired**になります。Expired状態では、Escrowを終了できなくなり、誰でもEscrowをキャンセルできるようになります。Escrowに`CancelAfter`フィールドが設定されていない場合、Escrowが期限切れになることがないため、キャンセルできません。 - -- **条件付きEscrow（右）:** EscrowでCrypto-condition（`Condition`フィールド）が指定されており、Finish-after時刻が指定されていない場合、Escrowは作成時点で即時に**Conditionally Ready**になります。この時点では、Crypto-conditionに対する正しいフルフィルメントを提供した人だけがEscrowを終了できます。有効期限（`CancelAfter`フィールド）までに終了されなかったEscrowは**Expired**になります。（Finish-after時刻が設定されていないEscrowには、有効期限が設定されている _必要があります_ 。）Expired状態では、Escrowを終了できなくなり、誰でもEscrowをキャンセルできるようになります。 - - - -## Escrowの利用可能性 - -条件付き決済は、2017-03-31以降XRP Ledgerコンセンサスプロトコルに対する[「Escrow」Amendment](known-amendments.html#escrow)により利用可能になりました。同機能の以前のバージョンは、2016年に「Suspended Payments」（SusPay）という名称で[XRP Ledger Testnet](xrp-testnet-faucet.html)で利用可能になりました。 - -[スタンドアロンモード](rippled-server-modes.html#rippledサーバーをスタンドアロンモードで実行する理由)でのテストの際には、Amendmentのステータスに関係なく、Escrow機能をローカルで強制的に有効にできます。次のスタンザを`rippled.cfg`に追加してください。 - - [features] - Escrow - -Escrow Amendmentのステータスは、[featureメソッド][]を使用して確認できます。 - -## EscrowFinishトランザクションのコスト - -[Crypto-condition][]を使用する場合、Crypto-conditionフルフィルメントの検証に高い処理負荷がかかるため、EscrowFinishトランザクションでは[高額なトランザクションコスト](transaction-cost.html#特別なトランザクションコスト)を支払う必要があります。 - -Escrowが時間のみによってロックされており、Crypto-conditionがない場合、EscrowFinishのコストは、リファレンストランザクションの標準[トランザクションコスト](transaction-cost.html)のみです。 - -必要となる追加のトランザクションコストは、フルフィルメントのサイズに比例します。現時点では、フルフィルメントのあるEscrowFinishでは最小トランザクションコストとして、**330 drop（[XRPのdrop数](basic-data-types.html#通貨額の指定)）と、フルフィルメントのサイズで16バイトあたり10 drop**が必要です。[マルチ署名済み](multi-signing.html)トランザクションの場合、マルチ署名のコストがフルフィルメントのコストに加算されます。 - -**注記:** 上記の式は、トランザクションのリファレンスコストがXRPの10 dropであることを前提としています。 - -[手数料投票](fee-voting.html)により`reference_fee`の値が変更される場合、この式は新しいリファレンスコストに基づいてスケーリングされます。フルフィルメントのあるEscrowFinishトランザクションの公式は次のとおりです。 - -``` -reference_fee * (signer_count + 33 + (fulfillment_bytes / 16)) -``` - - -## Escrowを使用する理由 - -従来の[Escrow](https://en.wikipedia.org/wiki/Escrow)では、特にオンラインでリスクが高いと見なされる可能性のあるさまざまな金融取引を可能にしてきました。取引期間中または評価期間中に信頼できる第三者に資金を預託することで、相手側が当事者としての責任を必ず果たすことが両者に対し保証されます。 - -Escrow機能では、第三者をXRP Ledger に組み込まれている自動システムに置き換えることで、この概念をさらに発展させました。これにより、資金のロックアップとリリースが公平に行われ、自動化できるようになりました。 - -完全に自動化されたEscrowは、XRP Ledger 自体の整合性で裏付けられており、Rippleにとって重大な問題を解決します。Escrowで実現可能なユースケースは他にも多数あると思われます。Rippleは、Escrowのユニークな活用法を新たに編み出すように業界に働きかけています。 - -### ユースケース: 時間ベースのロックアップ - -**背景:** Rippleは大量のXRPを保有しており、XRP Ledgerと関連テクノロジーの健全な発展を促進し、資金を調達する目的でXRPを系統立てて売却しています。その一方、大量のXRPを保有しているために、Rippleでは次のような課題が生じています: - -- XRP Ledgerを使用する個人や企業は、Rippleが市場でXRPを通常よりも高値で売却して市場へ大量供給した場合に、XRPへの投資の希薄化や価値の低下を招く可能性があると懸念しています。 - - 市場への大量売却は長期的にはRippleに損失をもたらしますが、Rippleがそのような大量売却を行う可能性は、XRP価格への押し下げ圧力を促し、Rippleの資産価値を下げることになります。 -- Rippleは、内部関係者を含め、デジタル盗難やその他の悪意のある行為からアカウントを保護するため、アカウント所有権を慎重に管理しなければなりません。 - -**解決策:** Rippleは550億XRPを時間ベースのエスクローに預託することで、XRPの供給量を予測可能なものとし、その供給量がゆっくりですが安定したペースで増加していくようにしています。XRPを保有するその他の当事者は、Rippleの優先課題や戦略が変わったとしても、同社が市場へ大量供給できないとわかっています。 - -資金をEscrowに委託しても、Rippleの保有分が不正使用者から直接保護されるわけではありませんが、不正使用者が一時的にRippleのXRPアカウントを乗っ取っても、すぐに盗んだり流用したりできるXRPの量は大幅に減少します。これによりXRPの壊滅的な損失リスクは減少し、Rippleが自社のXRP資産の不正な流用を検出、防止、追跡する時間が増加します。 - -### ユースケース: インターレジャー決済 - -**背景:** 急速に成長しているフィンテック業界の主な課題の1つに、複数のデジタル通貨システムまたはレジャー間でのアクティビティーの調整があります。この課題に対して多くの解決策（XRP Ledgerの初期ビューを含む）が提案されていますが、これは「すべてを管理する1つのレジャー」の作成に絞り込むことができます。Rippleでは、1つのシステムでは世界中のすべての人々のニーズに応えることはできないと考えています。実際に、望ましい機能のいくつかは互いに矛盾しています。Rippleではその代わりに、レジャーを相互に接続するネットワーク、つまり _インターレジャー_ に、フィンテックの未来があると考えています。[Interledger Protocol][]は、できるだけ多くのシステムを安全かつスムーズに接続するための標準を定義します。 - -インターレジャー決済の根幹をなす基本原則は、 _条件付き送金_ です。マルチホップペイメントにはリスクの問題があります。中間のホップが増えるほど、決済が失敗する箇所が増えます。インターレジャーでは、この問題が金融版「[2相コミット](https://en.wikipedia.org/wiki/Two-phase_commit_protocol)」で解決されます。この2相コミットでの2つのステップとは、（1）条件付き送金の準備と（2）送金実行のための条件のフルフィルメントです。インターレジャープロジェクトでは、条件の定義と確認を自動化する方法を標準化するために[Crypto-condition][]仕様が定義され、このような条件の「共通の土台」としてSHA-256ハッシュが定められました。 - -**解決策:** Escrow機能により、XRP LedgerはInterledger Protocolを使用したマルチホップペイメントのブリッジングに理想的なレジャーとなりました。これは、Escrow機能がPREIMAGE-SHA-256 Crypto-conditionに基づいてXRPの送金をネイティブにサポートしており、一致するフルフィルメントの提示から数秒以内にこれらの送金が実行されるためです。 - - -## 参考情報 - -XRP LedgerのEscrowの詳細は、以下を参照してください: - -- [Escrowチュートリアル](use-escrows.html) - - [時間に基づくEscrowの送信](send-a-time-held-escrow.html) - - [条件に基づくEscrowの送信](send-a-conditionally-held-escrow.html) - - [送金元または受取人別のEscrow検索](look-up-escrows.html) -- [トランザクションのリファレンス](transaction-formats.html) - - [EscrowCreateトランザクション][] - - [EscrowFinishトランザクション][] - - [EscrowCancelトランザクション][] -- [レジャーリファレンス](ledger-data-formats.html) - - [Escrowオブジェクト](escrow-object.html) - -インターレジャーと、条件付き送金が実現する複数レジャー間での安全な決済についての詳細は、[Interledger Architecture](https://interledger.org/rfcs/0001-interledger-architecture/)を参照してください。 - -Rippleによる550億XRPのロックアップについては、[Ripple's Insights Blog](https://ripple.com/insights/ripple-to-place-55-billion-xrp-in-escrow-to-ensure-certainty-into-total-xrp-supply/)を参照してください。 - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-types/escrow.md b/content/concepts/payment-types/escrow.md deleted file mode 100644 index e4c833f6e2..0000000000 --- a/content/concepts/payment-types/escrow.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -html: escrow.html -parent: payment-types.html -blurb: Escrows set aside XRP and deliver it later when certain conditions are met. Escrows can depend on time limits, cryptographic conditions, or both. -labels: - - Escrow - - Smart Contracts ---- -# 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 - - - -[![Escrow Flow Diagram (Successful finish)](img/escrow-success-flow.png)](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 _may_ be the same as the sender. - -**Step 2:** After this transaction has been processed, the XRP Ledger has an [Escrow object](escrow-object.html) 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`](tec-codes.html). - -### Expiration Case - -[![Escrow Flow Diagram (Expired escrow)](img/escrow-cancel-flow.png)](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](escrow-object.html) in the ledger and returns the XRP to the sender. - - - - -## 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.html) 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](use-payment-channels.html) are better suited for fast, low-value payments. Of course, unconditional [Payments](payment.html) are also preferable for many use cases. - -## State Diagram - -The following diagram shows the states an Escrow can progress through: - -[![State diagram showing escrows going from Held → Ready/Conditionally Ready → Expired](img/escrow-states.png)](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](known-amendments.html#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](xrp-test-net-faucet.html) 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.html#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](basic-data-types.html#specifying-currency-amounts) plus 10 drops per 16 bytes in the size of the fulfillment**. If the transaction is [multi-signed](multi-signing.html), the cost of multi-signing is added to the cost of the fulfillment. - -**Note:** The above formula is based on the assumption that the reference cost of a transaction is 10 drops of XRP. - -If [Fee Voting](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/). - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-types/partial-payments.ja.md b/content/concepts/payment-types/partial-payments.ja.md deleted file mode 100644 index 28f82df6a7..0000000000 --- a/content/concepts/payment-types/partial-payments.ja.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -html: partial-payments.html -parent: payment-types.html -blurb: Partial Paymentsは送金額から手数料を差し引き、変動額を送金します。Partial Paymentsは、追加コストなしで不審な支払いを返金したい場合に便利です。 -labels: - - 支払い - - セキュリティ ---- -# Partial Payment - -デフォルトのケースでは、XRP Ledgerの[Paymentトランザクション][]の`Amount`フィールドに、為替レートと[送金手数料](transfer-fees.html)を差し引いた実際の送金額が指定されます。「Partial Payment」フラグ（[**tfPartialPayment**](payment.html#paymentのフラグ)）を使うと、送金額を増額する代わりに受取金額を減額して、支払を正常に実行できます。Partial Paymentは、追加コストなしで[支払を返金](become-an-xrp-ledger-gateway.html#bouncing-payments)したい場合に便利です。 - -[トランザクションコスト](transaction-cost.html)に使用されるXRPの額は、トランザクションタイプに関わらず常に送金元のアカウントから差し引かれます。 - -Partial Paymentは、XRP Ledgerとのネイティブ統合を悪用して取引所およびゲートウェイから資金を盗むのに使用される恐れがあります。本書の[Partial Paymentの悪用](#partial-paymentの悪用)セクションで、この悪用の仕組みと防止対策を説明します。 - -## セマンティクス - -### Partial Paymentを使用しない場合 - -Partial Paymentフラグを使用しないで送金する場合、トランザクションの`Amount`フィールドに実際の送金額を指定し、`SendMax`フィールドに送金上限額と通貨を指定します。`Amount`の額を全額送金すると`SendMax`パラメーターの値を超えてしまう場合や、その他何らかの理由で総額を送金できない場合は、トランザクションは失敗します。トランザクション指示で`SendMax`フィールドが省略されると、`Amount`と同額とみなされます。この場合、手数料の合計が0である場合のみ支払が成功します。 - -つまり、次の式になります。 - - Amount+（手数料）=（送金額）≤ SendMax - -この式の「手数料」は、[送金手数料](transfer-fees.html)と通貨の為替レートを指します。送金額（`Amount`）の通貨は、送金側と受取側で異なる通貨建てにすることができ、XRP Ledgerの分散型取引所でオファーを消費することにより交換されます。 - -**注記:** トランザクションの`Fee`フィールドが参照するXRP[トランザクションコスト](transaction-cost.html)は、トランザクションをネットワークに中継するために消却されます。トランザクションコストは、常に指定通りの額が送金元から引き落とされ、あらゆるタイプの支払の手数料計算とは完全に切り離されています。 - -### Partial Paymentを使用する場合 - -Partial Paymentフラグが有効になっている支払を送金する場合、このトランザクションの`Amount`フィールドには送金限度額を指定します。Partial Paymentでは、制限（手数料、流動性不足、受取アカウントのトラストラインの枠不足など）の有無にかかわらず、指定額の _一部_ を送金できます。 - -オプションの`DeliverMin`フィールドには、送金下限額を指定します。`SendMax`フィールドは、Partial Payment以外で送金する場合と同様に機能します。Partial Paymentトランザクションは、送金額が`DeliverMin`フィールドの金額以上、`SendMax`の金額未満であれば成功します。`DeliverMin`フィールドに指定のない場合、任意の正の金額の送金であれば、Partial Paymentは成功します。 - -つまり、次の式になります。 - - 金額 ≥（送金額）= SendMax -（手数料）≥ DeliverMin > 0 - -### Partial Paymentの制限事項 - -Partial Paymentには次の制限事項があります。 - -- Partial Paymentでは、アドレスにXRPにて資金を供給できません。この場合、[結果コード][]`telNO_DST_PARTIAL`が返されます。 -- Partial Paymentでは、XRP間の直接決済はできません。この場合、[結果コード][]`temBAD_SEND_XRP_PARTIAL`が返されます。 - - ただし、イシュアンスからXRPへの支払またはXRPからイシュアンスへの支払は、Partial Paymentが可能です。 - -[結果コード]: transaction-results.html - -### `delivered_amount`フィールド - -Partial Paymentでの実際の送金額を把握できるように、正常に完了したPaymentトランザクションのメタデータには`delivered_amount`フィールドが含まれています。このフィールドには送金額が`Amount`フィールドと[同じフォーマット](basic-data-types.html#通貨額の指定)で示されています。 - -Partial Payment以外の場合、トランザクションのメタデータの`delivered_amount`フィールドは、トランザクションの`Amount`フィールドと同じです。支払が発行済み通貨で行われた場合、丸め方により`delivered_amount`が`Amount`フィールドとやや異なることがあります。 - -次の**両方**の条件に該当するトランザクションでは、送金額を**使用できません**。 - -- Partial Paymentである -- 2014-01-20以前の検証済みレジャーに含まれている - -この両方の条件に該当する場合、`delivered_amount`には実際の金額ではなく文字列値`unavailable`が示されます。この状況で実際の送金額を確認する唯一の方法は、トランザクションのメタデータでAffectedNodesを参照することです。発行済み通貨を送金するトランザクションで、`Amount`の`issuer`が`Destination`アドレスと同じアカウントである場合、送金額は異なる取引相手へのトラストラインを表す複数の`AffectedNodes`メンバー間で分割できます。 - -`delivered_amount`フィールドは以下のフィールドに含まれています。 - -| API | メソッド | フィールド | -|-----|--------|-------| -| [JSON-RPC / WebSocket][] | [account_txメソッド][] | `result.transactions` 配列メンバーの `meta.delivered_amount` | -| [JSON-RPC / WebSocket][] | [txメソッド][] | `result.meta.delivered_amount` | -| [JSON-RPC / WebSocket][] | [transaction_entryメソッド][] | `result.metadata.delivered_amount` | -| [JSON-RPC / WebSocket][] | [ledgerメソッド][]（トランザクションが展開されている状態） | `result.ledger.transactions` 配列メンバーの`metaData.delivered_amount` [新規: rippled 1.2.1][] | -| [WebSocket][] | [トランザクションサブスクリプション](subscribe.html#トランザクションストリーム) | サブスクリプションメッセージの`meta.delivered_amount` [新規: rippled 1.2.1][] | -| ripple-lib v1.x | `getTransaction` メソッド | `outcome.deliveredAmount` | -| ripple-lib v1.x | `getTransactions` メソッド | 配列メンバーの `outcome.deliveredAmount` | - -[WebSocket]: http-websocket-apis.html -[JSON-RPC / WebSocket]: http-websocket-apis.html - -## Partial Paymentの悪用 - -金融機関によるXRP Ledgerとの統合が、Paymentの`Amount`フィールドは常に総送金額であると想定して行われる場合、不正使用者がその想定を悪用して、金融機関から資金を盗むことが可能になります。Partial Paymentがゲートウェイ、取引所、または業者のソフトウェアで正しく処理されない限り、これらの機関に対してこのような悪用が行われる可能性があります。 - -**着信Paymentトランザクションを正しく処理するには、**`Amount`フィールドではなく **[`delivered_amount`メタデータフィールド](#delivered_amountフィールド)を使用します。** これにより、金融機関が _実際の_ 受取金額を間違えることがなくなります。 - - -### 悪用シナリオの流れ - -脆弱な金融機関を攻撃するため、不正使用者は次のような操作を試みます。 - -1. 不正使用者がPaymentトランザクションを金融機関に送信します。このトランザクションの`Amount`フィールドの額は高額で、**tfPartialPayment**フラグが有効になっています。 -2. Partial Paymentは成功しますが（結果コード`tesSUCCESS`）、実際には指定通貨でわずかな金額だけが送金されます。 -3. 脆弱な金融機関はトランザクションの`Amount`フィールドを確認しますが、`Flags`フィールドや`delivered_amount`メタデータフィールドは確認しません。 -4. 脆弱な金融機関は、XRP Ledgerへ入金された`delivered_amount`が非常に少額のであるにもかかわらず、外部システム（金融機関独自のレジャーなど）で`Amount`の総額を不正使用者に入金します。 -5. 不正使用者は、脆弱な機関がこの差異に気付く前に、可能な限りの多くの残高を別のシステムに出金します。 - - ブロックチェーントランザクションは通常不可逆であるため、不正使用者は一般的にBitcoinなどの他の仮想通貨に残高を換金することを好みます。法定通貨システムに出金した場合、金融機関がトランザクションを撤回または取り消せるのは、最初にトランザクションが実行されてから数日後になります。 - - 取引所の場合、不正使用者はXRPから残高を出金し、直接XRP Ledgerに戻すこともできます。 - -業者の場合、操作の順序がやや異なりますが、概念は同じです: - -1. 不正使用者が大量の商品やサービスの購入を依頼します。 -2. 脆弱な業者が不正使用者に対し、購入された商品やサービスの手数料を請求します。 -3. 不正使用者がPaymentトランザクションを業者に送信します。このトランザクションの`Amount`フィールドの額は高額で、**tfPartialPayment**フラグが有効になっています。 -4. Partial Paymentが成功しますが（結果コード`tesSUCCESS`）、指定通貨でわずかな金額だけが送金されます。 -5. 脆弱な業者はトランザクションの`Amount`フィールドを確認しますが、`Flags`フィールドや`delivered_amount`メタデータフィールドは確認しません。 -6. 脆弱な業者は、XRP Ledgerへの入金された`delivered_amount` が非常に少額であるにもかかわらず、請求を支払済みとして扱い、商品またはサービスを不正使用者に納入します。 -7. 不正使用者は、業者が差異に気付く前に、商品やサービスを使用、再販売または持ち逃げします。 - -### その他の緩和対策 - -このような悪用を防ぐには、着信トランザクションの処理で[`delivered_amount`フィールド](#delivered_amountフィールド)を使用すれば十分です。ただし、積極的な取り組みを追加することによっても、このような悪用が発生する可能性を回避または緩和できます。例: - -- 出金処理のビジネスロジックにサニティチェックを追加します。XRP Ledgerで保有している残高の合計が、予期されている資産と債務に一致しない場合は、出金を処理をしません。 -- 「顧客確認」のガイドラインに従い、顧客の身元情報を厳密に検証します。不正使用者を事前に認識して阻止したり、システムを悪用した不正使用者に対して法的措置を講じたりすることができます。 - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-types/partial-payments.md b/content/concepts/payment-types/partial-payments.md deleted file mode 100644 index 9139e4a859..0000000000 --- a/content/concepts/payment-types/partial-payments.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -html: partial-payments.html -parent: payment-types.html -blurb: Partial payments subtract fees from the amount sent, delivering a flexible amount. Partial payments are useful for returning unwanted payments without incurring additional costs. -labels: - - Payments - - Security ---- -# 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](transfer-fees.html). The "Partial Payment" flag ([`tfPartialPayment`](payment.html#payment-flags)) allows a payment to succeed by reducing the amount received instead of increasing the amount sent. Partial payments are useful for [returning payments](become-an-xrp-ledger-gateway.html#bouncing-payments) without incurring additional costs to oneself. - -The amount of XRP used for the [transaction cost](transaction-cost.html) 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](transfer-fees.html) 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.html), 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](basic-data-types.html#specifying-currency-amounts) as the `Amount` field. - -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.html), the `delivered_amount` may 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.html#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 - -## 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][] - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-types/payment-channels.ja.md b/content/concepts/payment-types/payment-channels.ja.md deleted file mode 100644 index f937625f29..0000000000 --- a/content/concepts/payment-types/payment-channels.ja.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -html: payment-channels.html -parent: payment-types.html -blurb: Payment Channelは、少額の単位に分割可能な高速な非同期のXRPペイメントを送信し、後日決済されるようにします。 -labels: - - Payment Channel - - スマートコントラクト ---- -# Payment Channel - -Payment Channelは、少額の単位に分割可能な「非同期」のXRPペイメントを送信し、後日決済する高度な機能です。 - -Payment Channel向けのXRPは、指定された期間にわたって留保されます。送金元がチャネルに対する _クレーム_ を作成します。受取人は、XRP Ledgerトランザクションを送信したり、新しいレジャーバージョンが[コンセンサス](consensus.html)に基づいて承認されるまで待つことなしに、このクレームを検証します。（これは、合意に基づいてトランザクションが承認される通常のパターンとは別に発生する、 _非同期_ のプロセスです。）受取人はいつでもクレームを _清算_ して、このクレームにより承認された額のXRPを受領することができます。このようなクレームを清算するときには、通常の合意プロセスの一部として標準XRP Ledgerトランザクションを使用します。この1回のトランザクションに、少額のクレームにより保証される任意の数のトランザクションを含めることができます。 - -クレームは個別に検証され、後で一括で清算できるため、Payment Channelでは、クレームのデジタル署名を作成および検証する参加者の能力によってのみ制限されるペースで、トランザクションを行えます。この制限は主に、参加者のハードウェアのスピードと、署名アルゴリズムの複雑さによるものです。最大限の速度を引き出すにはEd25519署名を使用します。これはXRP Ledgerのデフォルトのsecp256k1 ECSDA 署名よりも高速です。研究の結果、2011年のコモディティーハードウェアで[1秒あたりEd25519署名を100,000個以上作成し、1秒あたり70,000個以上を検証できることが実証されました](https://ed25519.cr.yp.to/ed25519-20110926.pdf)。 - - -## Payment Channelを使用する理由 - -Payment Channelを使用するプロセスには常に、支払人と受取人という2名の当事者が関わります。支払人とは、受取人の顧客で、XRP Ledgerを使用している個人または機関です。受取人とは、商品またはサービスの代金としてXRPを受領する個人または事業者です。 - -Payment Channelでは本来、そこで売買可能なものにいては、一切指定されません。ただし、次の商品やサービスはPayment Channelに適しています。 - -- デジタルアイテムなど、ほぼ即時に送信できるもの -- 安価な商品（価格に占めるトランザクション処理コストの割合が大きい） -- 通常大量購入する商品（正確な希望数量が事前に判明していない） - - -## Payment Channelのライフサイクル - -次の図は、Payment Channelのライフサイクルの概要を示します。 - -[![Payment Channelフローチャート](img/paychan-flow.ja.png)](img/paychan-flow.ja.png) - - -## 関連項目 - -- [Payment Channelの使用](use-payment-channels.html): Payment Channelを使用するプロセスを段階的に説明するチュートリアル。 - -- [Escrow](escrow.html): 速度が遅い、条件付きの大量XRP決済のための類似機能。 - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-types/payment-channels.md b/content/concepts/payment-types/payment-channels.md deleted file mode 100644 index 41fd2ca8d7..0000000000 --- a/content/concepts/payment-types/payment-channels.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -html: payment-channels.html -parent: payment-types.html -blurb: Payment Channels enable fast, asynchronous XRP payments that can be divided into very small increments and settled later. -labels: - - Payment Channels - - Smart Contracts ---- -# 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](consensus.html). (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][] - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/tokens/authorized-trust-lines.ja.md b/content/concepts/tokens/authorized-trust-lines.ja.md deleted file mode 100644 index 65ba7b9400..0000000000 --- a/content/concepts/tokens/authorized-trust-lines.ja.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -html: authorized-trust-lines.html -parent: tokens.html -blurb: 通貨発行者が自己の発行済み通貨を保有できる人を制限できる、Authorized Trust Lineについて説明します。 -labels: - - トークン - - セキュリティ ---- -# Authorized Trust Lines - -XRP LedgerのAuthorized Trust Lines機能により、通貨イシュアーは自身の（XRP以外の）発行済み通貨を保有できるユーザーを制限できます。これにより、不明なXRP Ledgerアドレスは発行済み通貨を保有できなくなります。Authorized Trust Lines機能は発行済み通貨にのみ適用され、XRPには影響しません。 - -Authorized Trust Lines機能を使用するには、発行アドレスでRequireAuthフラグを有効にします。その後、発行アドレスは他のアドレスからのトラストラインを承認する[TrustSetトランザクション][]を送信できます。RequireAuthが有効であるときに発行アドレスから発行された資金を他のアドレスが保有できるのは、発行アドレスへのトラストラインが承認されている場合だけです。 - -トラストラインを承認するトランザクションには発行アドレスによる署名が必要ですが、これにより発行アドレスが危険にさらされる可能性が高くなります。RequireAuthが有効であるXRP Ledgerへの資金の送金プロセスは次のようになります。 - -1. 発行ゲートウェイがその発行アドレスを顧客に公開します。 -2. 顧客のXRP Ledgerアドレスからゲートウェイの発行アドレスへのトラストラインを作成するために顧客は[TrustSetトランザクション][]を送信します。これは、ゲートウェイが発行した特定通貨を特定の限度額まで保有することを顧客が望んでいることを意味します。 -3. ゲートウェイの発行アドレスは、顧客のトラストラインを承認するTrustSetトランザクションを送信します。 - -**ヒント:** 発行ゲートウェイは、顧客がトラストラインの作成を完了する前に、そのトラストラインを事前に承認できます（ステップ3）。これにより限度額がゼロのトラストラインが作成されます。顧客のTrustSetトランザクション（ステップ2）により、事前承認されたトラストラインに限度額が設定されます。_（[TrustSetAuth Amendment][]が必要です。）_ - -## RequireAuth設定 - -`RequireAuth`設定をすることで、発行アドレスが当該通貨に関してその取引相手とのトラストラインを具体的に承認している場合を除き、すべての取引相手はアドレスから発行された残高を保有できなくなります。 - -用心として、発行ゲートウェイが[運用アドレスとスタンバイアドレス](issuing-and-operational-addresses.html)に対して`RequireAuth`を常に有効にし、これらのアドレスへのトラストラインを一切承認しないことが推奨されます。これにより、運用アドレスとスタンバイアドレスがXRP Ledgerで誤って通貨を発行することを防止できます。これは純粋な予防措置であり、発行アドレスにより作成された発行済み通貨の残高を、これらのアドレスが意図したとおりに送金することを阻止するものではありません。 - -Authorized Trust Lines機能を使用するには、イシュアーがその発行アドレスの`RequireAuth`も有効にする必要もあります。その後、発行アドレスは顧客からの[各トラストラインを承認する`TrustSet`トランザクションを送信する](#トラストラインの承認)必要があります。 - -**注意:** アカウントが`RequireAuth`を有効にできるのは、アカウントがトラストラインを所有しておらず、またXRP Ledgerにオファーがない場合に限られます。したがってXRP Ledgerで取引を開始する前に、この設定を使用するかどうかを決定しておく必要があります。 - -### RequireAuthの有効化 - -ローカルでホストされている`rippled`の[submitメソッド][]を使用して、RequireAuthフラグを有効にする[AccountSetトランザクション][]を送信する例を以下に示します。（このメソッドは、アドレスが発行アドレス、運用アドレス、スタンバイアドレスのいずれであっても同様に機能します。） - -要求: - -```json -POST http://localhost:5005/ -{ - "method": "submit", - "params": [ - { - "secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9", - "tx_json": { - "Account": "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v", - "Fee": "15000", - "Flags": 0, - "SetFlag": 2, - "TransactionType": "AccountSet" - } - } - ] -} -``` - -{% include '_snippets/secret-key-warning.md' %} - - -## アカウントのRequireAuthの有効化の確認 - -アカウントのRequireAuth設定の有効化の状態を確認するには、[account_infoメソッド][]を使用してアカウントを調べます。`Flags`フィールド（`result.account_data`オブジェクト）の値を、[AccountRootレジャーオブジェクトのビット単位フラグ](accountroot.html)と比較します。 - -`Flags`値と`lsfRequireAuth`フラグ値（0x00040000）のビット単位のANDの結果がゼロ以外の場合、アカウントではRequireAuthが有効になっています。結果がゼロの場合、アカウントではRequireAuthが無効になっています。 - -## トラストラインの承認 - -Authorized Trust Lines機能を使用している場合、他のアカウントからのトラストラインを最初に承認しなければ、これらの他のアカウントはあなたが発行する残高を保有できません。複数の通貨を発行する場合には、各通貨のトラストラインを個別に承認する必要があります。 - -トラストラインを承認するには、`LimitAmount`の`issuer`として信頼するユーザーを指定して、発行アドレスから[TrustSetトランザクション][]を送信します。`value`（信頼する額）を**0**のままにし、トランザクションの[tfSetfAuth](trustset.html#trustsetのフラグ)フラグを有効にします。 - -ローカルでホストされている`rippled`の[submitメソッド][]を使用して、顧客アドレス（rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn）が発行アドレス（rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW）からのUSDのイシュアンスを保有することを承認するTrustSetトランザクションを送信する例を以下に示します。 - -要求: - -```json -POST http://localhost:8088/ -{ - "method": "submit", - "params": [ - { - "secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9", - "tx_json": { - "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW", - "Fee": "15000", - "TransactionType": "TrustSet", - "LimitAmount": { - "currency": "USD", - "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", - "value": 0 - }, - "Flags": 65536 - } - } - ] -} -``` - -{% include '_snippets/secret-key-warning.md' %} - - -## トラストラインの承認状況の確認 - -トラストラインの承認状況を確認するには、[account_linesメソッド][]を使用してトラストラインを調べます。要求の`account`フィールドに顧客のアドレスを指定し、`peer`フィールドにイシュアーのアドレスを指定します。 - -応答の`result.lines`配列で、必要とする通貨のトラストラインを表している`currency`フィールドを持つオブジェクトを見つけます。そのオブジェクトの`peer_authorized`フィールドに値`true`が設定されている場合は、イシュアー（要求の`peer`フィールドとして使用したアドレス）によりそのトラストラインが承認されています。 - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/tokens/authorized-trust-lines.md b/content/concepts/tokens/authorized-trust-lines.md index e4956ca72b..f6f5ed0bf6 100644 --- a/content/concepts/tokens/authorized-trust-lines.md +++ b/content/concepts/tokens/authorized-trust-lines.md @@ -1,18 +1,10 @@ ---- -html: authorized-trust-lines.html -parent: tokens.html -blurb: Authorized trust lines is a setting to limit who can hold a token. -labels: - - Tokens - - Security ---- # 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](freezes.html) that trust line if you need to.) +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. @@ -24,14 +16,14 @@ With a stablecoin on the XRP Ledger and use Authorized Trust Lines, the process 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. +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][].)_ +**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](issuing-and-operational-addresses.html), 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. +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 @@ -39,7 +31,7 @@ Even if you don't intend to use Authorized Trust Lines, you can enable the `Requ ### 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.) +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: @@ -61,13 +53,13 @@ POST http://localhost:5005/ ] } ``` - + ## 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](accountroot.html). +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. @@ -75,9 +67,9 @@ If the result of the `Flags` value bitwise-AND the `lsfRequireAuth` flag value ( 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`](trustset.html#trustset-flags) flag for the transaction. +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`: +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: @@ -104,17 +96,17 @@ POST http://localhost:8088/ ] } ``` - + ## 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. +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. - + -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} +--> \ No newline at end of file diff --git a/content/concepts/tokens/common-misconceptions-about-freezes.md b/content/concepts/tokens/common-misconceptions-about-freezes.md deleted file mode 100644 index 2d18c1b351..0000000000 --- a/content/concepts/tokens/common-misconceptions-about-freezes.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -parent: freezes.html -blurb: Clarify common misunderstandings about the XRP Ledger's freeze feature. -labels: - - Tokens ---- -# 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](freezes.html), 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](currency-formats.html#comparison). 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"](freezes.html#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](decentralized-exchange.html), you custody your own assets so no one can stop you from dealing in XRP. diff --git a/content/concepts/tokens/demurrage.ja.md b/content/concepts/tokens/demurrage.ja.md deleted file mode 100644 index a688c7e5dc..0000000000 --- a/content/concepts/tokens/demurrage.ja.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -html: demurrage.html -parent: tokens.html -blurb: (廃止) 一部の古いXRP Ledgerツールは、組み込み金利やマイナス金利を持つ通貨コードをサポートしていました。. -status: removed ---- -# デマレージ - -**注意:** デマレージは非推奨の機能であり、継続的なサポートはありません。このページでは、旧バージョンのXRP Ledgerソフトウェアの過去の動作について説明します。 - -[デマレージ](https://ja.wikipedia.org/wiki/%E3%83%87%E3%83%9E%E3%83%AC%E3%83%BC%E3%82%B8) とは、保有資産にかかるマイナスの金利で、その資産を保有するためのコストを表すものです。 XRP Ledgerで発行された通貨のデマレージを表現するために、デマレージレートを示すカスタム[通貨コード](currency-formats.html#通貨コード) を使って追跡することができます。 これによって、様々なデマレージの量に対応した別々のバージョンの通貨が効果的に作成されます。クライアントアプリケーションは、通貨コードと一緒に年率でデマレージ通貨コードを表現することによって、これをサポートすることができます。例えば、以下のようになります。"XAU (-0.5%pa)". - -## 通貨量の表記について - -XRP Ledgerのすべての金額を継続的に更新するのではなく、有利子通貨や減耗通貨の金額を2種類の金額に分割する方法です。XRP Ledgerに記録される「レジャー値」と、人に見せる「表示値」の2種類に分けます。「レジャー値」は、ある一定時点、すなわち2000年1月1日午前0時の「リップルエポック」での通貨の価値を表しています。「表示値」は、リップルエポックからその時点までの連続した利息やデマレージを計算した後の時点（通常は現在時刻）での金額を表しています。 - -**ヒント:** デマレージはインフレに似ていると考えることができます。インフレの影響を受けたすべての資産の価値は時間とともに減少しますが、レジャーには常に2000年の値で金額が記録されます。これは実際のインフレを反映しているわけではなく、デマレージはむしろ一定の割合での仮想的なインフレのようなものです。 - -したがって、クライアントソフトウェアは2つの変換を適用する必要があります。 - -- ある時点の表示値を取り込み、レジャー値に変換して記録すること。 -- レジャー値を、ある時点の表示値に変換すること。 - -### デマレージの計算 - -通貨に関するデマレージの完全な計算式は以下の通りです。 - -``` -D = A × ( e ^ (t ÷ τ) ) -``` - -- **D** はデマレージ後の金額 -- **A** はグローバルレジャーに記録されたデマレージ前金額です。 -- **e** はオイラー数 -- **t** はリップルエポック（UTC2000年1月1日0時）からの経過秒数 -- **τ** は、e倍加時間の時間（秒）です。この値は［希望する金利から計算］（#e倍加時間の計算）されます。 - -表示金額とレジャー金額の変換は、以下の手順で行います。 - -1. `( e ^ (t ÷ τ) )`の値を計算する。この数値を「デマレージ係数」と呼ぶ。デマレージ係数は常に現在時刻など特定の時刻からの相対値である。 -2. 変換する量に適用します。 - - レジャー値を表示値に変換する場合は、デマレージ係数を乗じる。 - - 表示値をレジャー値に変換する場合は、デマレージ係数で割ってください。 -3. 必要であれば、結果値が望ましい精度で表現できるように調整する。XRP Ledgerの[発行通貨形式](currency-formats.html#発行済み通貨の精度)により、レジャー値の精度は小数点以下15桁までとされています。. - - -## 利子付き通貨コードフォーマット - -[標準通貨コード形式](currency-formats.html#標準通貨コード)ではなく、正の金利や負の金利（Demurrage）を持つ通貨は、以下の形式の160ビット通貨コードを使用します。 - -![通貨コード形式を削除する](img/demurrage-currency-code-format.png) - -1. 最初の8ビットは `0x01` でなければなりません。 -2. 次の24ビットはASCIIの3文字を表します。 - これはISO 4217のコードと予想されます。標準フォーマットのASCII文字と同じ文字をサポートしています。 -3. 次の24ビットはすべて「0」でなければなりません。 -4. 次の64ビットは通貨の金利で、IEEE754ダブルフォーマットで「[e-folding time](http://en.wikipedia.org/wiki/E-folding)」と表現される。 -5. 次の24ビットは予約されており，すべて`0`でなければなりません - -### e倍加時間の計算 - -レジャー金額と表示金額の変換や、有利子/不利子通貨の通貨コードの計算には、「e倍加時間」としての金利が必要です。e倍加時間とは、ある数量が_e_（オイラー数）の倍数だけ増加するのにかかる時間のことである。慣例として、e倍加時間は数式では**τ**という文字で表記される。 - -ある年率パーセントの利息に対するe倍加時間の時間を計算すること。 - -1. 100%に金利を足すと、年利を適用した後の初期金額に対する割合が算出されます。デマレージには、マイナスの金利を使用します。例えば、0.5%のデマレージは-0.5%の金利となり、**99.5%**の残存率となります。 -2. パーセンテージを小数で表します。例えば、99.5%は**0.995**となります。 -3. その数値の自然対数をとります。例えば、**ln(0.995) = -0.005012541823544286** となります。(この数値は、当初の金利がプラスであればプラス、マイナスであればマイナスになります)。 -4. 1年間の秒数（31536000）を、前のステップの自然対数の結果で割ってください。例えば、**31536000 ÷ -0.005012541823544286 = -6291418827.045599** となります。この結果が、e倍加時間（秒）です。 - -**注記:** XRP Ledgerの利息・デマレージルールでは、慣習上、1年あたりの固定秒数（31536000）が使用されており、閏日や閏秒の調整は行われていません。 - -## クライアントサポート - -利息通貨とデマレージ通貨をサポートするために、クライアントアプリケーションはいくつかの機能を実装する必要があります。 - -- レジャーやトランザクションデータから取得した通貨を減耗して表示する場合、クライアント側でレジャー値から表示値への変換が必要です。(デマレージでは、表示値はレジャー値より小さくなる)。 - -- デマレージ通貨の入力を受け付ける場合、クライアントは金額を表示形式からレジャー形式に変換する必要があります。(デマレッジの場合、ユーザー入力値よりレジャー値の方が大きい)。クライアントは、支払い、オファー、その他のトランザクションを作成する際に、レジャーの値を使用しなければなりません。 - -- クライアントは、金利やデマレージが発生する通貨と発生しない通貨、および金利やデマレージの利率が異なる通貨を区別する必要があります。クライアントは、[利子付き通貨コードフォーマット](#利子付き通貨コードフォーマット)を解析して、「XAU (-0.5% pa)」などの表示にできるようにしなければなりません。 - -### ripple-lib サポート - -デマレージは ripple-lib のバージョン **0.7.37** から **0.12.9** まででサポートされていました。デマレージは、最近のほとんどのライブラリでは***サポートされていません***。 - -以下のコードサンプルは、互換性のあるバージョンのripple-libを使用して、レジャー値と表示値の変換を行う方法を示しています。また、[Ripple Demurrage Calculator](https://ripple.github.io/ripple-demurrage-tool/)も参照してください。 - -表示値からレジャー値に変換するには、`Amount.from_human()`を使用する。 - -```js -// デマレージ通貨の表示金額を表す Amount オブジェクトを作成し、 -// 現在の日付を表すreference_dateを渡します。 -// (この場合、2017-11-04T00:07:50Zに、年0.5%の脱税で台帳値10 XAU。)。 -var demAmount = ripple.Amount.from_human('10 0158415500000000C1F76FF6ECB0BAC600000000', - {reference_date:563069270}); - -// 発行者を設定します -demAmount.set_issuer("rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh"); - -// get the JSON format for the ledger amount -console.log(demAmount.to_json()); - -// { "value": "10.93625123082769", -// "currency": "0158415500000000C1F76FF6ECB0BAC600000000", -// "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh" } -``` - -レジャー値から表示値へ変換する場合、 - -```js -// レジャー値を持つ Amount オブジェクトを作成します。 -ledgerAmount = ripple.Amount.from_json({ - "currency": "015841551A748AD2C1F76FF6ECB0CCCD00000000", - "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh", - "value": "10.93625123082769"}) - -// 表示金額を得るために現在時刻までの利息を適用する -var displayAmount = demAmount.applyInterest(new Date()); - -console.log(displayAmount.to_json()); - -// { "value": "9.999998874657716", -// "currency": "0158415500000000C1F76FF6ECB0BAC600000000", -// "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh" } -``` diff --git a/content/concepts/tokens/demurrage.md b/content/concepts/tokens/demurrage.md deleted file mode 100644 index 3f81f50d87..0000000000 --- a/content/concepts/tokens/demurrage.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -html: demurrage.html -parent: tokens.html -blurb: (Obsolete) Some older XRP Ledger tools used to support currency codes with built-in interest and negative interest rates. -status: removed ---- -# Demurrage - -**Warning:** Demurrage is a deprecated feature with no ongoing support. This page describes historical behavior of older versions of XRP Ledger software. - -[Demurrage](http://en.wikipedia.org/wiki/Demurrage_%28currency%29) is a negative interest rate on assets held that represents the cost of holding those assets. To represent the demurrage on a token in the XRP Ledger, you can track it using a custom [currency code](currency-formats.html#currency-codes) that indicates the demurrage rate. This effectively creates separate versions of the token for each varying amount of demurrage. Client applications can support this by representing the demurraging currency code with an annual percentage rate alongside the currency code. For example: "XAU (-0.5%pa)". - -## Representing Demurraging Token Amounts - -Rather than continuously update all amounts in the XRP Ledger, this approach divides amounts of interest-bearing or demurraging tokens into two types of amount: "ledger values" recorded in the XRP Ledger, and "display values" shown to people. The "ledger values" represent the value of the currency at a fixed point, namely the "Ripple Epoch" of midnight January 1, 2000. The "display values" represent the amount at a later point in time (usually the current time) after calculating continuous interest or demurrage from the Ripple Epoch until that time. - -**Tip:** You can think of demurrage as similar to inflation, where the value of all assets affected by it decreases over time, but the ledger always holds amounts in year-2000 values. This does not reflect actual real-world inflation; demurrage is more like hypothetical inflation at a constant rate. - -Thus, client software must apply two conversions: - -- Taking display values at a given time and converting them to ledger values to be recorded. -- Taking ledger values and converting them to a display value at a given point in time. - -### Calculating Demurrage - -The full formula for calculating demurrage is as follows: - -``` -D = A × ( e ^ (t ÷ τ) ) -``` - -- **D** is the amount after demurrage -- **A** is the pre-demurrage amount as recorded in the global ledger -- **e** is Euler's number -- **t** is the number of seconds since the Ripple Epoch (0:00 on January 1, 2000 UTC) -- **τ** is the e-folding time in seconds. This value is [calculated from the desired interest rate](#calculating-e-folding-time). - -To convert between display amounts and ledger amounts, you can use the following steps: - -1. Calculate the value of `( e ^ (t ÷ τ) )`. We call this number the "demurrage coefficient". The demurrage coefficient is always relative to a specific time, such as the current time. -2. Apply it to the amount to convert: - - To convert ledger values to display values, multiply by the demurrage coefficient. - - To convert display values to ledger values, divide by the demurrage coefficient. -3. If necessary, adjust the resulting value so that it can be represented to the desired accuracy. Ledger values are limited to 15 decimal digits of precision, according to the XRP Ledger's [token format](currency-formats.html#token-precision). - - -## Interest-Bearing Currency Code Format - -Rather than using the [standard currency code format](currency-formats.html#currency-codes), tokens that have positive interest or negative interest (demurrage) use a 160-bit currency code in the following format: - -![Demurraging Currency Code Format](img/demurrage-currency-code-format.png) - -1. The first 8 bits must be `0x01`. -2. The next 24 bits represent 3 characters of ASCII. - This is expected to be an ISO 4217 code. It supports the same characters as the standard format's ASCII characters. -3. The next 24 bits MUST be all `0`s. -4. The next 64 bits are the interest rate of the currency, represented as "[e-folding time](http://en.wikipedia.org/wiki/E-folding)" in an IEEE 754 double format. -5. The next 24 bits are reserved and should be all `0`s. - -### Calculating e-folding Time - -To convert between ledger amounts and display amounts, or to calculate a currency code for an interest-bearing/demurraging currency, you need the interest rate as an "e-folding time". The e-folding time is the amount of time it takes a quantity to increase by a factor of _e_ (Euler's number). By convention, e-folding time is written as the letter **τ** in formulas. - -To calculate an e-folding time for a given rate of annual percent interest: - -1. Add the interest rate to 100% to get the percentage of the initial amount present after applying annual interest. For demurrage, use a negative interest rate. For example, 0.5% demurrage would be an interest rate of -0.5%, resulting in **99.5%** remaining. -2. Represent the percentage as a decimal. For example, 99.5% becomes **0.995**. -3. Take the natural log of that number. For example, **ln(0.995) = -0.005012541823544286**. (This number is positive if the initial interest rate was positive, and negative if the interest rate was negative.) -4. Take the number of seconds in one year (31536000) and divide by the natural log result from the previous step. For example, **31536000 ÷ -0.005012541823544286 = -6291418827.045599**. This result is the e-folding time in seconds. - -**Note:** By convention, the XRP Ledger's interest/demurrage rules use a fixed number of seconds per year (31536000), which is not adjusted for leap days or leap seconds. - -## Client Support - -To support interest-bearing and demurraging tokens, client applications must implement several features: - -- When displaying the amount of a demurraging token retrieved from ledger or transaction data, the client must convert from the ledger value to the display value. (With demurrage, the display values are smaller than the ledger values.) - -- When accepting input for a demurraging token, the client must convert amounts from a display format to the ledger format. (With demurrage, the ledger values are larger than the user input value.) The client must use the ledger value when creating payments, offers, and other types of transaction. - -- Clients must distinguish between tokens that do and do not have interest or demurrage, and among tokens that have different rates of interest or demurrage. Clients should be able to parse the [Interest-Bearing Currency Code Format](#interest-bearing-currency-code-format) into a display such as "XAU (-0.5% pa)". - -### ripple-lib Support - -Demurrage was supported in ripple-lib versions **0.7.37** through **0.12.9**. Demurrage is ***not supported*** in most modern libraries. - -The following code samples demonstrate how to use compatible versions of ripple-lib to convert between ledger values and display values. Also see the [Ripple Demurrage Calculator](https://ripple.github.io/ripple-demurrage-tool/). - -To convert from a display value to a ledger value, use `Amount.from_human()`: - -```js -// create an Amount object for the display amount of the demurring currency -// and pass in a reference_date that represents the current date -// (in this case, ledger value 10 XAU with 0.5% annual demurrage, -// at 2017-11-04T00:07:50Z.) -var demAmount = ripple.Amount.from_human('10 0158415500000000C1F76FF6ECB0BAC600000000', - {reference_date:563069270}); - -// set the issuer -demAmount.set_issuer("rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh"); - -// get the JSON format for the ledger amount -console.log(demAmount.to_json()); - -// { "value": "10.93625123082769", -// "currency": "0158415500000000C1F76FF6ECB0BAC600000000", -// "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh" } -``` - -To convert from a ledger value to a display value: - -```js -// create an Amount object with the ledger value, -ledgerAmount = ripple.Amount.from_json({ - "currency": "015841551A748AD2C1F76FF6ECB0CCCD00000000", - "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh", - "value": "10.93625123082769"}) - -// apply interest up to the current time to get the display amount -var displayAmount = demAmount.applyInterest(new Date()); - -console.log(displayAmount.to_json()); - -// { "value": "9.999998874657716", -// "currency": "0158415500000000C1F76FF6ECB0BAC600000000", -// "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh" } -``` diff --git a/content/concepts/tokens/freezes.ja.md b/content/concepts/tokens/freezes.ja.md deleted file mode 100644 index 435dd01ae3..0000000000 --- a/content/concepts/tokens/freezes.ja.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -html: freezes.html -parent: tokens.html -blurb: 凍結では、コンプライアンス目的で発行済み通貨の取引を停止できます。 -labels: - - トークン ---- -# 発行済み通貨の凍結 - -XRPは発行済み通貨ではありません。XRPはXRP Ledgerのネイティブ資産であり、XRP Ledgerでのトランザクションの実行に必要となります。XRPは取引相手を必要としません。つまり、XRPを保有しているということは負債ではなく実際の通貨であるXRPを保有していることになります。このため、_**いかなる組織または個人もXRPを凍結できません**_。 - -XRP Ledgerでは、XRP以外の通貨はすべて発行済み通貨として表すことができます。このような発行済み通貨（「イシュアンス」または「IOU」とも呼ばれます）は、「トラストライン」と呼ばれるアドレス間の会計上の関係で管理されます。発行済み通貨は通常、負債とも資産とも見なされるため、トラストラインの残高は、見る視点によってマイナスにもプラスにもなります。どのアドレスも（XRP以外の）通貨を自由に発行できますが、他のアドレスが希望する保有量によってのみ制限されます。 - -特定のケースでは、法的要件への準拠や、疑わしい活動の調査のために、取引所またはゲートウェイが、XRP以外の発行済み通貨の残高を急きょ凍結することがあります。 - -**ヒント:** 誰もXRPを凍結することはできません。 - -凍結については、3種類の設定があります。 - -* [**Individual Freeze**](#individual-freeze) - 1件の取引相手を凍結します。 -* [**Global Freeze**](#global-freeze) - 取引相手全員を凍結します。 -* [**No Freeze**](#no-freeze) - 個々の取引相手の凍結機能と、Global Freezeを終了できる機能を永久に放棄します。 - -凍結機能は発行済み通貨にのみ適用されます。XRP Ledgerには特権的な立場の当事者は存在しないため、凍結機能では、取引相手が、XRPまたはその他の取引相手が発行した資金で取引を実行することを阻止できません。Rippleを含め誰もXRPを凍結することはできません。 - -凍結対象の残高がプラス、マイナスにかかわらず、すべての凍結設定を行うことができます。通貨イシュアーまたは通貨保持者のいずれかがトラストラインを凍結できますが、通貨保持者がイシュアーを凍結しても、その影響はわずかです。 - - -## Individual Freeze - -**Individual Freeze**機能は、[トラストライン](trust-lines-and-issuing.html)に関する設定です。発行アドレスがIndividual Freeze設定を有効にすると、そのトラストラインの通貨に対して以下のルールが適用されます。 - -* 凍結されたトラストラインの両当事者間の直接決済は、凍結後も可能です。 -* そのトラストラインの取引相手は、イシュアーへ直接支払う場合を除き、凍結されたトラストラインの残高を減らすことはできません。取引相手は、凍結されたイシュアンスを直接イシュアーに送信することだけが可能です。 -* 取引相手は、凍結されたトラストライン上で引き続きその他の当事者からの支払を受け取ることができます。 -* 取引相手が凍結されたトラストライン上の発行済み通貨の売りオファーを出した場合、[資金不足とみなされます](offers.html#オファーのライフサイクル)。 - -確認事項: トラストラインではXRPは保持されません。XRPは凍結できません。 - -金融機関は、疑わしい活動を行う取引相手や、金融機関の利用規約に違反する取引相手にリンクしているトラストラインを凍結できます。金融機関は、同機関が運用する、XRP Ledgerに接続されているその他のシステムにおいても、その取引相手を凍結する必要があります。（凍結しないと、アドレスから金融機関経由で支払を送金することで、望ましくない活動を行うことが依然として可能となります。） - -各個別アドレスは金融機関とのトラストラインを凍結できます。これは金融機関とその他のユーザーの間の取引には影響しません。ただし、他のアドレス（[運用アドレス](issuing-and-operational-addresses.html)を含む）からその個別アドレスに対しては、その金融機関のイシュアンスを送信できなくなります。このようなIndividual Freezeは、オファーには影響しません。 - -Individual Freezeは1つの通貨にのみ適用されます。特定の取引相手の複数通貨を凍結するには、アドレスが各通貨のトラストラインで、個別にIndividual Freezeを有効にする必要があります。 - -[No Freeze](#no-freeze)設定を有効にしている場合、アドレスはIndividual Freeze設定を有効にできません。 - - -## Global Freeze - -**Global Freeze**機能は、アドレスに設定できます。発行アドレスがGlobal Freeze機能を有効にすると、その発行アドレスのすべての発行済み通貨に対して以下のルールが適用されます: - -* 凍結された発行アドレスのすべての取引相手は、イシュアーに直接支払う場合を除き、凍結されたアドレスへのトラストラインの残高を減らすことができません。（これはすべての[運用アドレス](issuing-and-operational-addresses.html)にも影響します。） -* 凍結された発行アドレスの取引相手は、発行アドレスとの直接的な支払の送受信を引き続き行うことができます。 -* 凍結アドレスによる発行済み通貨の売りオファーはすべて、[資金不足とみなされます](offers.html#オファーのライフサイクル)。 - -確認事項: アドレスはXRPを発行できません。Global FreezeはXRPには適用されません。 - -運用アドレスのシークレットキーが漏えいした場合には、運用アドレスの制御を取り戻した後であっても金融機関の[発行アドレス](issuing-and-operational-addresses.html)に対してGlobal Freezeを有効にすることが有益です。これにより資金流出を止め、攻撃者がそれ以上の資金を盗むことを防止し、少なくともそれまでの経過の追跡が容易になります。XRP LedgerでGlobal Freezeを行う他に、金融機関は外部システムへのコネクターでの疑わしい活動を停止する必要があります。 - -また、金融機関が新しい[発行アドレス](issuing-and-operational-addresses.html)への移行や、営業の停止を予定している場合にも、Global Freezeを有効にすることが有用です。これにより、特定の時点で資金がロックされるため、ユーザーは他の通貨で取引することができなくなります。 - -Global Freezeは、当該アドレスによって発行および保有されている _すべての_ 通貨に適用されます。1つの通貨のみに対してGlobal Freezeを有効にすることはできません。一部の通貨のみを凍結できるようにしたい場合は、通貨ごとに異なるアドレスを使用してください。 - -アドレスのGlobal Freeze設定はいつでも有効にできます。ただし、アドレスの[No Freeze](#no-freeze)設定を有効にすると、Global Freezeを _無効にする_ ことはできません。 - - -## No Freeze - -**No Freeze**機能をアドレスに設定すると、取引相手が発行した通貨を凍結する機能を永久に放棄します。この機能を使用すれば、企業は自社が発行した資金を「物理的なお金のように」扱うことができます。これにより、企業は顧客どうしがその資金を取引することに介入できなくなります。 - -確認事項: XRPはすでに凍結できません。No Freeze機能は、XRP Ledgerで発行された他の通貨にのみ適用されます。 - -No Freeze設定には次の2つの効果があります。 - -* 発行アドレスは、すべての取引相手とのトラストラインに対してIndividual Freezeを有効にできなくなります。 -* 発行アドレスは、Global Freezeを有効にしてグローバル凍結を施行できますが、Global Freezeを _無効にする_ ことはできません。 - -XRP Ledgerは金融機関に対し、その発行資金が表す債務を履行することを強制できません。このため、Global Freezeを有効にする機能を放棄しても顧客を保護できません。ただし、Global Freezeを _無効にする_ 機能を放棄することで、Global Freeze機能が一部の顧客に対して不当に適用されないようにすることができます。 - -No Freeze設定は、アドレスに対して発行される通貨と、アドレスから発行される通貨のすべてに適用されます。一部の通貨のみを凍結できるようにしたい場合は、通貨ごとに異なるアドレスを使用してください。 - -No Freeze設定は、アドレスのマスターキーのシークレットキーにより署名されたトランザクションでのみ有効にできます。[レギュラーキー](setregularkey.html)または[マルチ署名済みトランザクション](multi-signing.html)を使用してNo Freezeを有効にすることはできません。 - - - - - -# 関連項目 - -* [GB-2014-02新機能残高凍結](https://ripple.com/files/GB-2014-02.pdf) -* [凍結コードの例](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content/_code-samples/freeze) - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/tokens/freezes.md b/content/concepts/tokens/freezes.md deleted file mode 100644 index 11a77aa57f..0000000000 --- a/content/concepts/tokens/freezes.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -html: freezes.html -parent: tokens.html -blurb: Issuers can freeze their issued tokens for compliance purposes. -labels: - - Tokens ---- -# 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.html). - -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](trust-lines-and-issuing.html). 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](offers.html#lifecycle-of-an-offer). - -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 addresses, including [operational addresses](issuing-and-operational-addresses.html), from sending that financial institution's tokens to the individual address. 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](issuing-and-operational-addresses.html).) -* 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](offers.html#lifecycle-of-an-offer). - -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](issuing-and-operational-addresses.html) if the issuer's [secret key](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 address](issuing-and-operational-addresses.html), 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](setregularkey.html) or a [multi-signed transaction](multi-signing.html) 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) - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/tokens/issuing-and-operational-addresses.ja.md b/content/concepts/tokens/issuing-and-operational-addresses.ja.md deleted file mode 100644 index ee04830a37..0000000000 --- a/content/concepts/tokens/issuing-and-operational-addresses.ja.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -html: issuing-and-operational-addresses.html -parent: tokens.html -blurb: XRP Ledgerで自動的にトランザクションを送信するビジネスは、リスクを最小限に抑えるために目的ごとに別のアドレスを設定することをおすすめします。 -labels: - - トークン - - セキュリティ ---- -# 発行アドレスと運用アドレス - -{% include '_snippets/issuing-and-operational-addresses-intro.ja.md' %} - - -## 資金のライフサイクル - -XRP LedgerのXRP以外の残高はすべて、2つのXRP Ledgerアドレス間の会計上の関係に関連付けられている _発行済み通貨_ です。Rippleが推奨する役割の分割を金融機関が行うと、その金融機関に関連する資金の流れは循環する傾向にあります。 - -[![図: 発行アドレスからスタンバイアドレス、運用アドレス、顧客アドレスおよびパートナーアドレスに移動し、最後に発行アドレスに戻る資金フロー](img/funds_flow_diagram.png)](img/funds_flow_diagram.png) - -発行アドレスはペイメントの送金時に、XRP Ledgerの会計上の関係に残高を作成します。ユーザーはXRP Ledger内のさまざまな会計上の関係と残高を交換できます。このため、XRP以外の残高を表す用語として _イシュアンス_ を使用します。イシュアンスの額は、発行アドレスの側から見ると債務を表すため、マイナスです。同じイシュアンスの額を発行アドレスの相手側から見ると、プラスになります。発行アドレスがペイメントを受領すると、送信されたイシュアンスが消去され、発行アドレスの債務が減少します。 - -イシュアンスは発行アドレスからスタンバイアドレスに送信されるか、または運用アドレスに直接送信されます。これらのイシュアンスはスタンバイアドレスから運用アドレスに送信されます。運用アドレスから他の取引相手（流動性プロバイダー、パートナー、その他の顧客など）にペイメントが送信されます。すべてのイシュアンスは発行アドレスとの会計上の関係に関連付けられているため、イシュアンスのペイメントと取引は、発行アドレスを「通じてRippling」されます。ペイメントが行われると、送金元と発行アドレスの会計上の関係において送金元の残高から支払額が引き落とされ、受取人と発行アドレスの会計上の関係において受取人の残高に支払額が入金されます。XRP Ledgerでは、オーダーブックや[資金のRipplingに対応する流動性プロバイダー](rippling.html)を通じて複数のイシュアーを結び付ける、より複雑な[パス](paths.html)もサポートされています。 - -## 発行アドレス - -発行アドレスは、金庫に似ています。パートナーアドレス、顧客アドレス、運用アドレスは、発行アドレスとの間で会計上の関係（トラストライン）を作成しますが、発行アドレスから送信されるトランザクションは可能な限り少ない数に抑えられます。人間のオペレーターが定期的に、発行アドレスからトランザクションを作成、署名し、スタンバイアドレスまたは運用アドレスの残高を補充します。このようなトランザクションの署名に使用されるシークレットキーには、インターネットに接続されたどのコンピューターからもアクセスできないことが極めて重要です。 - -金庫とは異なり、発行アドレスは顧客またはパートナーからのペイメントを直接受領できます。XRP Ledgerのトランザクションはすべて公開されているため、自動システムは発行アドレスからのペイメントを監視する際にシークレットキーを必要としません。 - -### 発行アドレスの漏えい - -不正使用者は金融機関の発行アドレスのシークレットキーを入手すると、際限なく新しいイシュアンスを作成し、分散型取引所でそのイシュアンスを取引できるようになります。これにより、金融機関が正式に取得したイシュアンスを識別して適切に清算することが難しくなります。金融機関の発行アドレスが乗っ取られた場合には、金融機関が新たに発行アドレスを作成する必要があり、また古い発行アドレスと会計上の関係を有するすべてのユーザーは新しいアドレスで、アカウントとの関係を新たに作成する必要があります。 - -### 複数の発行アドレス - -金融機関はXRP Ledgerで1つの発行アドレスから複数の通貨を発行できます。ただし、いくつかの設定（[送金手数料](transfer-fees.html)のパーセンテージや[Global Freeze](freezes.html)の状況など）は、1つのアドレスから発行されるすべての通貨に同様に適用されます。金融機関が通貨ごとに設定を変えて柔軟に管理したい場合、金融機関は通貨ごとに異なる発行アドレスを使用する必要があります。 - -## 運用アドレス - -運用アドレスはレジに似ています。イシュアンスを顧客とパートナーに送信して、金融機関に代わってペイメントを行います。トランザクションに自動的に署名するには、運用アドレスのシークレットキーをインターネットに接続されたサーバーに保管する必要があります。（シークレットキーは暗号化して保管できますが、サーバーがトランザクションに署名する際にシークレットキーを暗号化解除する必要があります。）顧客とパートナーは、運用アドレスとの会計上の関係を作成すべきではありません。 - -各運用アドレスではイシュアンスの残高が限られています。運用アドレスの残高が少なくなると、金融機関は残高を補充するため、発行アドレスまたはスタンバイアドレスから送金します。 - -### 運用アドレスの漏えい - -不正使用者が運用アドレスのシークレットキーを入手した場合に金融機関が失う可能性のある通貨額は、最大でも運用アドレスが保有している額までです。金融機関は、顧客やパートナーからのアクションなしに、新しい運用アドレスに切り替えることができます。 - -## スタンバイアドレス - -金融機関がリスクと利便性のバランスを保つためのもう1つの手段として、発行アドレスと運用アドレスの中間ステップとして「スタンバイアドレス」を利用することができます。金融機関はスタンバイアドレスという追加のXRP Ledgerアドレスに資金を供給できます。このアドレスのキーはオンライン上に保管されず、別の信頼できるユーザーに預けられています。 - -運用アドレスの資金が少なくなると、信頼できるユーザーがスタンバイアドレスを使用して運用アドレスの残高を補充できます。スタンバイアドレスの資金が少なくなると、金融機関は発行アドレスを使用して1回のトランザクションでスタンバイアドレスにより多くの額の通貨を送金できます。スタンバイアドレスは、送金された通貨を必要に応じてスタンバイアドレス間で分散できます。これにより発行アドレスのセキュリティが強化され、発行アドレスが実行する合計トランザクション数が減少し、1つの自動化システムの管理下に過剰な資金が残ることがなくなります。 - -運用アドレスと同様に、スタンバイアドレスは顧客やパートナーではなく発行アドレスとの間に会計上の関係を確立する必要があります。運用アドレスに適用される注意事項はすべてスタンバイアドレスにも適用されます。 - -### スタンバイアドレスの漏えい - -スタンバイアドレスの漏えいが発生した場合、運用アドレスが漏えいした場合と同様の影響が及びます。不正使用者がスタンバイアドレスに保有される残高を盗むことが可能となり、金融機関は顧客やパートナーからのアクションなしに新しいスタンバイアドレスに切り替えることができます。 - -## 関連項目 - -- **コンセプト:** - - [アカウント](accounts.html) - - [暗号鍵](cryptographic-keys.html) -- **チュートリアル:** - - [XRP Ledgerゲートウェイの開設](become-an-xrp-ledger-gateway.html) - - [レギュラーキーペアの割り当て](assign-a-regular-key-pair.html) - - [レギュラーキーペアの変更または削除](change-or-remove-a-regular-key-pair.html) -- **リファレンス:** - - [account_infoメソッド][] - - [SetRegularKeyトランザクション][] - - [AccountRootオブジェクト](accountroot.html) - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/tokens/issuing-and-operational-addresses.md b/content/concepts/tokens/issuing-and-operational-addresses.md deleted file mode 100644 index ca3afd3d0d..0000000000 --- a/content/concepts/tokens/issuing-and-operational-addresses.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -html: issuing-and-operational-addresses.html -parent: tokens.html -blurb: Businesses sending transactions on the XRP Ledger automatically should set up separate addresses for different purposes to minimize risk. -labels: - - Tokens - - Security ---- -# Issuing and Operational Addresses - -{% include '_snippets/issuing-and-operational-addresses-intro.md' %} - - -## 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 address to standby addresses, to operational addresses, to customer and partner addresses, and finally back to the issuing address.")}} - -The issuing address creates tokens by sending payments to standby addresses. These tokens have negative value from the perspective of the issuing address, since they (often) represent obligations. The same tokens have positive value from other perspectives, including from the perspective of a standby address. - -The standby addresses, which are operated by actual humans, send those tokens to operational addresses. This step allows the issuing address to be used as little as possible after this point, while having at least some tokens available on standby. - -Operational addresses, 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. - - -## Issuing Address - -The issuing address is like a vault. Partners, customers, and operational addresses create trust lines to the issuing address, but this address sends as few transactions as possible. Periodically, a human operator creates and signs a transaction from the issuing address to refill the balances of a standby or operational address. Ideally, the secret key used to sign these transactions should never be accessible from any internet-connected computer. - -Unlike a vault, the issuing address 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 address without needing a secret key. - -### Issuing Address Compromise - -If a malicious actor learns the secret key behind a institution's issuing address, 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 address, the institution must create a new issuing address, and all users who have trust lines to the old issuing address must create new trust lines with the new address. - -### Multiple Issuing Addresses - -A financial institution can issue more than one type of token in the XRP Ledger from a single issuing address. However, there are some settings that apply equally to all (fungible) tokens issued from an address, including the percentage for [transfer fees](transfer-fees.html) and the [global freeze](freezes.html) status. If the financial institution wants the flexibility to manage settings differently for each type of token, the institution must multiple issuing addresses. - - -## Operational Addresses - -An operational address 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 address 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 address. - -Each operational address has a limited balance of tokens and XRP. When the balance of an operational address gets low, the financial institution refills it by sending a payment from the issuing address or a standby address. - -### Operational Address Compromise - -If a malicious actor learns the secret key behind an operational address, the financial institution can only lose as much as that operational address holds. The institution can switch to a new operational address with no action from customers and partners. - - -## Standby Addresses - -Another optional step that an institution can take to balance risk and convenience is to use "standby addresses" as an intermediate step between the issuing address and operational addresses. The institution can fund additional XRP Ledger addresses as standby addresses, whose keys are not available to always-online servers, but are entrusted to different trusted users. - -When an operational address is running low on funds (either tokens or XRP), a trusted user can use a standby address to refill the operational address's balance. When a standby addresses run low on funds, the institution can use the issuing address to send more funds to a standby address in a single transaction, and the standby addresses can distribute those funds among themselves if necessary. This improves security of the issuing address, allowing it to make fewer total transactions, without leaving too much money in the control of a single automated system. - -As with operational addresses, a standby address must have an accounting relationship with the issuing address, and not with customers or partners. All precautions that apply to operational addresses also apply to standby addresses. - -### Standby Address Compromise - -If a standby address is compromised, the consequences are like an operational address being compromised. A malicious actor can steal any balances possessed by the standby address, and the financial institution can change to a new standby address with no action from customers and partners. - - -## 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) - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/tokens/nftoken-batch-minting.md b/content/concepts/tokens/nftoken-batch-minting.md index 79d601f1ad..5fd51190db 100644 --- a/content/concepts/tokens/nftoken-batch-minting.md +++ b/content/concepts/tokens/nftoken-batch-minting.md @@ -1,14 +1,3 @@ ---- -html: nftoken-batch-minting.html -parent: non-fungible-tokens.html -blurb: Minting NFToken objects in batches. -filters: - - include_code -labels: - - Non-fungible Tokens, NFTs -status: not_enabled ---- - # Batch minting There are two common approaches to minting NFToken objects in batches: mint on demand and scripted minting. @@ -30,7 +19,7 @@ Any market activity prior to the initial sale of the NFToken object is not recor 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](batch-minting.html) tutorial. +For a practical example, see the [Batch Mint NFTokens](../../../tutorials/quickstart/batch-minting.md) tutorial. ### Benefits diff --git a/content/concepts/tokens/non-fungible-token-transfers.ja.md b/content/concepts/tokens/non-fungible-token-transfers.ja.md deleted file mode 100644 index 4fd7634e13..0000000000 --- a/content/concepts/tokens/non-fungible-token-transfers.ja.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -html: non-fungible-token-transfers.html -parent: non-fungible-tokens.html -blurb: NFTokenをダイレクトモードまたはブローカーモードで取引する。 -filters: - - include_code -labels: - - Non-fungible Tokens, NFTs -status: not_enabled ---- - -# XRP Ledger上でNFTokenを売買する -{% include '_snippets/nfts-disclaimer.ja.md' %} - -XRP Ledger上のアカウント間で`NFToken`オブジェクトを転送することができます。`NFToken` の売買をオファーしたり、他のアカウントから自分が保有する NFToken への売買オファーを受け入れることができます。`NFToken` を 無料(価格が0)で売却することで、`NFToken` を配布することもできます。すべてのオファーは [NFTokenCreateOfferトランザクション][] を使って作成されます。 - - -## 売却オファー - - -### 売却オファーの作成 - -`NFToken` オブジェクトの所有者であれば、`tfSellToken` フラグを指定して [NFTokenCreateOffer トランザクション][] を使用して売却オファーを作成することができます。`NFTokenID` と、対価として受け取る金額 `Amount` を指定します。オプションで、そのオファーが無効になる `Expiration` と、その `NFToken` を購入することができる唯一のアカウントである `Destination` を指定することができます。 - - -### 売却オファーを受け入れる - -販売されている `NFToken` を購入するには、`NFTokenAcceptOffer` トランザクションを使用します。`NFTokenOffer` オブジェクトの所有者アカウントと `NFTokenOfferID` を指定し、受け入れることを決定します。 - - -## 購入オファー - - -### 購入オファーの作成 - -どのアカウントでも `NFToken` の購入オファーを作成することができます。`tfSellToken` のフラグを指定せずに、[NFTokenCreateOffer][] を使用することで、購入オファーを作成することが可能です。`Owner`アカウント、`NFTokenID`、オファーの `Amount` を指定します。 - - -### 購入オファーを受け入れる - -`NFTokenAcceptOffer` トランザクションを使用して `NFToken` を転送します。`NFTokenOfferID` と所有者アカウントを指定して、トランザクションを完了させてください。 - - -## 取引モード - -`NFToken`を取引する場合、購入者と販売者の間で直接取引を行う、 _ダイレクト_ 取引と、第三者の口座が売りと買いのオファーをマッチングして取引を仲介する、 _ブローカー_ 取引を選択することができます。 - -ダイレクトモードでの取引では、販売者が転送をコントロールすることができます。販売者は誰でも購入できるように `NFToken` を出品するか、特定の取引先アカウントに `NFToken` を販売することができます。販売者はNFTokenの販売価格全額を受け取ります。 - -ブローカーモードでは、販売者は第三者のアカウントに`NFToken`の販売を仲介させます。ブローカーアカウントは、合意したレートで仲介手数料を徴収し、転送を行います。購入はリアルタイムで完了し、ブローカーと販売者には購入資金から支払われ、ブローカーによる前払いは必要ありません。 - - -### ブローカーモードを使用する場合 - -`NFToken`の作成者が適切な購入者を探す時間と忍耐力がある場合、作成者は販売から得たすべての収益を得ることができます。これは、少数の`NFToken`オブジェクトを様々な価格で販売するクリエイターにとって、非常に有効な方法です。 - -一方、クリエイターは、創作に時間を割くことができるのに、販売に時間を割くのは抵抗があるのではないでしょうか。そのような場合、個別に対応するのではなく、第三者であるブローカーのアカウントに販売業務を委託することが可能です。 - -ブローカーを利用すると、いくつかの利点があります。例えば - -* ブローカーは仲介者として、`NFToken`の販売価格を最大化するために活動することができます。ブローカーが販売価格の何割かを受け取る場合、価格が高ければ高いほど、ブローカーの収入も増えます。 -* ブローカーは、ニッチな市場や 価格帯などの基準に基づいて`NFToken`オブジェクトの管理を行う管理者として活動することができます。これによって、クリエイターの作品を発見できないような購入者のグループを呼び込むことができるでしょう。 -* ブローカーは、Opensea.ioのようなマーケットプレイスとして機能し、アプリケーション層でオークション機能を提供することもできます。 - - -### ブローカー販売のワークフロー - -最も単純なワークフローでは、クリエイターが新しい`NFToken`を発行します。クリエイターは売却オファーを作成する際、最低売却価格を入力し、売却先にブローカーを設定します。購入希望者はブローカーを経由して`NFToken`に入札を行います。ブローカーは落札者を選び、取引を完了させ、ブローカー手数料を受け取ります。ベストプラクティスとして、ブローカーは`NFToken`に対して残っている購入オファーをすべてキャンセルします。 - - -![Brokered Mode with Reserve](img/nft-brokered-mode-with-reserve.png) - - -もう1つのワークフローは、クリエイターが販売をよりコントロールできるようにするものです。このワークフローでは、クリエイターが新しい`NFToken`を発行します。入札者はオファーを作成し、ブローカーを宛先として設定します。ブローカーは落札者を選び、仲介手数料を差し引き、`NFTokenCreateOffer`を使用してクリエイターに署名の依頼をします。クリエーターは要求されたオファーに署名し、ブローカーを宛先として設定します。ブローカーは `NFTokenAcceptOffer` を使って売却を完了し、仲介手数料を保持します。ブローカーは `NFTokenCancelOffer` を使用して `NFToken` に対する残りの入札をキャンセルします。 - - -![Brokered Mode without Reserve](img/nft-brokered-mode-without-reserve.png) - - -所有者が他のアカウントで作成した `NFToken` をリセールする場合にも、同じワークフローを使用することができます。 - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/tokens/non-fungible-token-transfers.md b/content/concepts/tokens/non-fungible-token-transfers.md index 2da86ee4b2..77e75977d7 100644 --- a/content/concepts/tokens/non-fungible-token-transfers.md +++ b/content/concepts/tokens/non-fungible-token-transfers.md @@ -1,18 +1,7 @@ ---- -html: non-fungible-token-transfers.html -parent: non-fungible-tokens.html -blurb: Trading NFTokens in direct or brokered mode. -filters: - - include_code -labels: - - Non-fungible Tokens, NFTs -status: not_enabled ---- - # 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][]. +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 @@ -20,7 +9,7 @@ You can transfer `NFToken` objects between accounts on the XRP Ledger. You can o ### 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`. +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 @@ -33,7 +22,7 @@ To purchase a `NFToken` that is offered for sale, you use a `NFTokenAcceptOffer` ### 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. +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 @@ -68,19 +57,13 @@ Using a broker offers several advantages. For example: 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`. -![Brokered Mode with Reserve](img/nft-brokered-mode-with-reserve.png) +![Brokered Mode with Reserve](../../../img/nft-brokered-mode-with-reserve.png) 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`. -![Brokered Mode without Reserve](img/nft-brokered-mode-without-reserve.png) +![Brokered Mode without Reserve](../../../img/nft-brokered-mode-without-reserve.png) -The same workflows can be used when an owner resells a `NFToken` created by another account. - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} +The same workflows can be used when an owner resells a `NFToken` created by another account. \ No newline at end of file diff --git a/content/concepts/tokens/non-fungible-tokens.ja.md b/content/concepts/tokens/non-fungible-tokens.ja.md deleted file mode 100644 index e7db9f29f2..0000000000 --- a/content/concepts/tokens/non-fungible-tokens.ja.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -html: non-fungible-tokens.html -parent: tokens.html -blurb: XRPL NFTの紹介。 -filters: - - include_code -labels: - - Non-fungible Tokens, NFTs -status: not_enabled ---- - -# NFTのコンセプトの概要 -{% include '_snippets/nfts-disclaimer.ja.md' %} - -XRP Ledgerは、_IOUs_ としても知られる[発行済み通貨(tokens.html)のサポートを提供しています。このような資産は、主に、代替可能(Fungible)です。 - -> 代替可能性 -> -> 1. 個々の単位が本質的に交換可能であり、各部分が別の部分と区別できない商品または商品の特性である - -代替可能トークンは、XRP Ledgerの分散型取引所において、ユーザー間でXRPや他の発行済み通貨と手軽に交換することができます。そのため、決済に適しています。 - - -例えば、切手などがそうです。1919年当時、あなたが航空便で手紙を送る必要がある場合、24セントの切手を購入し、封筒に張ったでしょう。もしその切手をなくしてしまったら、別の24セント切手を使うか、10セント切手2枚と2セント切手2枚を使うことができます。非常に使い勝手がいいのです。 - -![Jenny Stamps](img/nft-concepts1.png "Jenny Stamps") - -しかし、1919年という時代のことですから、切手の飛行機が偶然にも逆さまに印刷されている24セントの航空郵便切手が出回るかもしれません。これが世界的に有名な「インバート・ジェニー」切手です。1枚の切手シートで100枚しか流通しなかったため、非常に希少で人気の高い切手です。現在、鑑定では一枚150万円以上の価値があるとされています。 - -![Jenny Stamps](img/nft-concepts2.png "Jenny Stamps") - -これらの切手は、他の24セント切手と交換することはできません。非代替(Non-fungible)になってしまったのです。 - -[NonFungibleTokensV1の修正][] :現在有効ではありません: は、XRP Ledgerに非代替性トークン（NFT）のサポートをネイティブで追加するものです。 非代替性トークンは、芸術品やゲーム内アイテムなど、ユニークな物理的、非物理的、あるいは純粋なデジタル商品の所有権をコード化する役割を果たします。 - - -## XRP Ledger上のNFT - -XRP Ledger上では、non-fungible tokenは[NFToken][]オブジェクトとして表されます。NFTokenはユニークで分割できない単位で、決済には使用できません。ユーザーはこのようなトークンを発行（作成）、保有、購入、売却、焼却（破棄）することができます。 - -XRP Ledgerでは、容量を節約するために、一つのアカウントで最大32個の `NFToken` オブジェクトを一つの[NFTokenPageオブジェクト][]に格納します。その結果、所有者の `NFToken` オブジェクトに対する [準備金] (reserves.html) は、追加のトークンを格納するためにレジャーが新しいページを作成する場合にのみ増加します。 - -また、アカウントは、自分に代わってNFTokenオブジェクトを発行・販売するブローカー（代理発行者）を指定することができます。 - -`NFToken` オブジェクトは、トークンが発行された時点で確定し、後で変更することが出来ない設定項目を持ちます。これらは以下の通りです。 - -- トークンを一意に定義する各種識別データ。 -- 発行者が、現在の保有者に関係なく、トークンを焼却できるかどうか。 -- トークンの保持者がトークンを他者に転送できるかどうか。( `NFToken` は常に発行者に直接送信したり、発行者から送信することが可能です)。 - - 転送が許可されている場合、発行者は販売価格に対する一定の割合で手数料を徴収することができます。 -- NFTokenを[発行済み通貨](tokens.html)で売却できるか、XRPのみでしか売却できないか。 - - -## `NFToken`のライフサイクル - -誰もが [NFTokenMint トランザクション][] を使って新しい `NFToken` を作成することができます。`NFToken` は発行者アカウントの [NFTokenPage オブジェクト][] に格納されます。所有者または利害関係者は [NFTokenCreateOffer トランザクション][]を送信して `NFToken` の売買を提案できます。レジャーは提案された転送を [NFTokenOffer オブジェクト][]として追跡し、一方が承諾またはキャンセルすると `NFTokenOffer` を削除します。`NFToken` が転送可能であれば、アカウント間で複数回取引することができます。 - -[NFTokenBurn トランザクション][] を使用して、自分が所有する `NFToken` を破棄することができます。発行者が `tfBurnable` フラグを有効にしてトークンを発行した場合、発行者は現在の所有者に関係なくトークンを破棄することが可能です。( 例えば、あるイベントのチケットを表すトークンである場合、そのチケットをある時点で消費するといった場合に便利です)。 - -![The NFT Lifecycle](img/nft-lifecycle.png "NFT Lifecycle Image") - -`NFToken` オブジェクトの転送に関する詳細は、[XRP Ledger上でNFTokenを売買する](non-fungible-token-transfers.html) を参照してください。 - - -## 関連項目 - -- [NFToken][] データ型 -- レジャーオブジェクト - - [NFTokenOffer オブジェクト][] - - [NFTokenPage オブジェクト][] -- トランザクション - - [NFTokenMint トランザクション][] - - [NFTokenCreateOffer トランザクション][] - - [NFTokenCancelOffer トランザクション][] - - [NFTokenAcceptOffer トランザクション][] - - [NFTokenBurn トランザクション][] -- API メソッド - - [account_nfts メソッド][] - - [nft_sell_offers メソッド][] - - [nft_buy_offers メソッド][] - - [nft_info メソッド][] (Clioサーバのみ) - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/tokens/non-fungible-tokens.md b/content/concepts/tokens/non-fungible-tokens.md deleted file mode 100644 index 1ce7da8ec4..0000000000 --- a/content/concepts/tokens/non-fungible-tokens.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -html: non-fungible-tokens.html -parent: tokens.html -blurb: Introduction to XRPL NFTs. -filters: - - include_code -labels: - - Non-fungible Tokens, NFTs -status: not_enabled ---- - -# NFT Conceptual Overview -{% include '_snippets/nfts-disclaimer.md' %} - -The XRP Ledger offers support for [tokens](tokens.html), also known as _IOUs_. Such assets 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. - -![Jenny Stamps](img/nft-concepts1.png "Jenny Stamps") - -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. - -![Jenny Stamps](img/nft-concepts2.png "Jenny Stamps") - -Those stamps cannot be replaced by just another other 24-cent stamp. They have become _non-fungible_. - -The [NonFungibleTokensV1 amendment][] :not_enabled: adds support for non-fungible tokens (NFTs, or “nifties” in the vernacular) natively on the XRP Ledger. 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. - - -## NFTs on the XRP Ledger - -On the XRP Ledger, a non-fungible token is represented as a [NFToken][] object. A `NFToken` is a unique, indivisible unit that is not used for payments. Users can mint (create), hold, buy, sell, and burn (destroy) such tokens. - -The ledger stores up to 32 `NFToken` objects owned by the same account in a single [NFTokenPage object][] to save space. As a result, the owner's [reserve requirement](reserves.html) for `NFToken` objects only increases when the ledger needs to make a new page to store additional tokens. - -Accounts can also designate a broker, or "Authorized Minter", who can mint and sell `NFToken` objects on their behalf. - -`NFToken` objects have several settings that are defined when the token is minted and cannot be changed later. These include: - -- Various identifying data that uniquely defines the token. -- Whether the issuer can burn the token regardless of who currently holds it. -- Whether the holder of the token can transfer it to others. (The `NFToken` can always be sent to or from the issuer directly.) - - If transfers are allowed, the issuer can charge a transfer fee as a percentage of the sale price. -- Whether the holder can sell the `NFToken` for [fungible token](tokens.html) amounts, or only for XRP. - - -## `NFToken` Lifecycle - -Anyone can create a new `NFToken` using the [NFTokenMint transaction][] type. The `NFToken` lives on the [NFTokenPage object][] of the issuing account. Either the owner or an interested party can send a [NFTokenCreateOffer transaction][] to propose buying or selling the `NFToken`; the ledger tracks the proposed transfer as a [NFTokenOffer object][], and deletes the `NFTokenOffer` when either side accepts or cancels the offer. If the `NFToken` is transferable, it can be traded multiple times between accounts. - -You can destroy a `NFToken` you own using the [NFTokenBurn transaction][]. If the issuer minted the token with `tfBurnable` flag enabled, the issuer can also burn the token regardless of the current owner. (This could be useful, for example, for a token that represents a ticket to an event which is used up at some point.) - -![The NFT Lifecycle](img/nft-lifecycle.png "NFT Lifecycle Image") - -For more info about transferring `NFToken` objects, see [Trading NFTokens on the XRP Ledger](non-fungible-token-transfers.html). - - -## 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 method][] - - [nft_sell_offers method][] - - [nft_buy_offers method][] - - [nft_info method][] (Clio server only) - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/tokens/paths.ja.md b/content/concepts/tokens/paths.ja.md deleted file mode 100644 index ff6bcf31c1..0000000000 --- a/content/concepts/tokens/paths.ja.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -html: paths.html -parent: tokens.html -blurb: 発行済み通貨の支払いは、接続されているユーザーのパスとオーダーブックを通す必要があります。 -labels: - - 支払い - - 複数通貨間 ---- -# パス - -XRP Ledgerでは、[発行済み通貨](tokens.html)の支払いが送金元から受取人に届くまでにたどる中間ステップの道筋をパスによって定義します。パスは、XRP Ledgerの[分散型取引所](decentralized-exchange.html)のオーダーを介して送金元と受取人を結び付けることで、[複数通貨間の支払い](cross-currency-payments.html)を可能にします。また、負債を相殺するような複雑な決済もパスにより可能になります。 - -XRP Ledgerでは1つのPaymentトランザクションは複数のパスを使用でき、複数のソースの流動性を組み合わせて必要な額を送金することができます。そのため、トランザクションには使用可能なパスをまとめた _パスセット_ が含まれます。パスセットの中のパスでは開始時と終了時には同一通貨が使用される必要があります。 - -XRPは任意のアドレスに直接送金できるため、[XRP間のトランザクション](direct-xrp-payments.html)ではパスは使用されません。 - -## パスのステップ - -パスは、支払いの送金元と受取人を結ぶステップで構成されています。すべてのステップは次のいずれかを行います。 - -* 同一通貨の別のアドレスを通じたRippling -* オーダーブックでの通貨の取引 - -別のアドレスを通じたRipplingは、負債を移動するプロセスです。一般的なケースでは、ある当事者に対するイシュアーの債務が削減され、別の当事者に対する債務が増加します。Ripplingは、トラストラインで結ばれているすべてのアドレスの間で発生させることができます。Ripplingのその他の例については、[NoRippleフラグについて](rippling.html)を参照してください。 - -通貨取引ステップの場合、パスステップにより変換先の通貨が指定されますが、オーダーブックにはオファーの状態は記録されません。レジャーが検証されるまではトランザクションの正規の順序は最終的ではないため、トランザクションの検証が完了するまでは、トランザクションがどのオファーをとるかは不明です。（各トランザクションは最終レジャーでの実行時に利用可能なオファーの中から最適なオファーをとるため、経験に基づいて推測することができます。） - -いずれのタイプのステップでも、中間アドレスでは取得する価値と失う価値はほぼ同等です。トラストラインから同じ通貨の別のトラストラインへ残高がripplingするか、または以前に出されたオーダーに基づいて通貨が交換されます。場合によっては、[送金手数料](transfer-fees.html)、トラストラインクオリティ、または数値の丸め方が原因で、取得する価値と失われる価値が厳密に同等ではないことがあります。 - -[![3つのパスの例を示す図](img/paths-examples.ja.png)](img/paths-examples.ja.png) - - - -# 技術詳細 - -## Pathfinding - -`rippled` APIではPathfindingに使用できるメソッドが2つあります。[ripple_path_findメソッド][]は、1回限りのパスセットの検索を実行します。[path_findメソッド][]（WebSocketのみ）は、レジャーが閉鎖するか、またはサーバーがより適切なパスを検出するたびに、フォローアップ応答によって検索を拡大します。 - -署名時に`rippled`によりパスが自動的に入力されるようにするには、[signメソッド][]または[`submit`コマンド（署名と送信モード）](submit.html#署名と送信モード)への要求に`build_path`フィールドを指定します。ただし、トラブルを回避するために、署名前にPathfindingを個別に実行し、結果を確認することが推奨されます。 - -**注意:** `rippled`は可能な限り低コストのパスを検出するように設計されていますが、常にこのようなパスを検出できるわけではありません。信頼できない`rippled`インスタンスが改ざんされ、利益目的でこの動作が変更される可能性もあります。パスに沿った支払いの実行にかかる実際のコストは、送信時とトランザクション実行時で異なることがあります。 - -パスの検出は、新しいレジャーが検証されるたびに数秒ごとに変化する非常に難しい課題であるため、`rippled`は完全に最適なパスを検出するようには設計されていません。ただし、いくつかの有効なパスを検出し、特定額の送金コストを推定することができます。 - - -## 暗黙のステップ - -規約として、パスのステップのいくつかは[Paymentトランザクションのフィールド](payment.html)により黙示的に示されます。これらのフィールドは、`Account`（送金元）、`Destination`（受取人）、`Amount`（通貨と納入額）、`SendMax`（通貨と送金額（指定されている場合））です。暗黙のステップは次のとおりです。 - -* パスの1番目のステップは、トランザクションの`Account`フィールドに定義されるとおり、トランザクションの送信者であると常に黙示されます。 -* トランザクションに、そのトランザクションの送信者ではない`issuer`が指定されている`SendMax`フィールドが含まれている場合、そのイシュアーはパスの2番目のパスとして黙示されます。 - * `SendMax`の`issuer`が送信側アドレス _である_ 場合、パスはその送信側アドレスから始まり、そのアドレスの特定の通貨のトラストラインのいずれかを使用できます。詳細は、[SendMaxおよびAmountの特殊な値](payment.html#sendmaxおよびamountで使用する特殊なissuerの値)を参照してください。 -* トランザクションの`Amount`フィールドに、トランザクションの`Destination`とは異なる`issuer`が指定されている場合、そのイシュアーはパスの最後から2番目のステップであると黙示されます。 -* 最後に、トランザクションの`Destination`フィールドに定義されるとおり、パスの最終ステップはトランザクションの受信者であることが常に黙示されます。 - - -## デフォルトパス - -明示的に指定されたパスの他に、トランザクションは _デフォルトパス_ に沿って実行できます。デフォルトパスは、トランザクションの[暗黙のステップ](#暗黙のステップ)を接続する最も簡単な方法です。 - -デフォルトパスは次のいずれかになります。 - -* トランザクションで（イシュアーに関係なく）1種類の通貨のみが使用される場合、デフォルトパスでは支払いが、関連するアドレスを通じてRipplingされると想定されます。このパスは、これらのアドレスがトラストラインで接続されている場合にのみ機能します。 - * `SendMax`が省略されているか、または`SendMax`の`issuer`が送金元の場合、デフォルトパスが機能するためには送金元`Account`から宛先`Amount`の`issuer`へのトラストラインが必要です。 - * `SendMax`と`Amount`に異なる`issuer`値が指定されており、そのいずれも送金元または受取人ではない場合、これらの2つのイシュアー間のトラストラインでRipplingが必要となるため、デフォルトパスは有用ではない可能性があります。一般にイシュアーが互いに直接信頼し合うことはお勧めしません。 -* 複数通貨間のトランザクションの場合、デフォルトパスは支払元通貨（`SendMax`フィールドで指定）と宛先通貨（`Amount`フィールドで指定）の間でオーダーブックを使用します。 - -有効なすべてのデフォルトパスを次の図に示します。 -[![デフォルトパスの図](img/paths-default_paths.ja.png)](img/paths-default_paths.ja.png) - -デフォルトパスを無効にするには[`tfNoDirectRipple`フラグ](payment.html#paymentのフラグ)を使用します。このケースでは、トランザクションに明示的に指定されたパスを使用してトランザクションを実行することだけが可能です。トレーダーはこのオプションを使用して裁定取引を実行できます。 - - -## パスの仕様 - -パスセットは配列です。パスセットの各要素は、個々の _パス_ を表す別の配列です。パスの各要素は、ステップを指定するオブジェクトです。ステップのフィールドを次に示します。 - -| フィールド | 値 | 説明 | -|:-----------|:-----------------------|:---------------------------------------| -| `account` | 文字列 - アドレス | _（省略可）_ 指定されている場合、このパスステップは指定されたアドレスを通じたRipplingを表します。このステップに`currency`フィールドまたは`issuer`フィールドが指定されている場合は、このフィールドを指定しないでください。 | -| `currency` | 文字列 - 通貨コード | _（省略可）_ 指定されている場合、このパスステップはオーダーブックを通じた通貨の変換を表します。指定される通貨は新しい通貨を表します。このステップに`account`フィールドが指定されている場合は、このフィールドを指定しないでください。 | -| `issuer` | 文字列 - アドレス | _（省略可）_ 指定されている場合、このパスステップは通貨の変換を表し、このアドレスは新しい通貨のイシュアーを定義します。XRP以外の`currency`のステップでこのフィールドが省略されている場合、パスの直前のステップがイシュアーを定義します。`currency`が省略され、このフィールドが指定されている場合、イシュアーが異なる同名の通貨間でオーダーブックを使用するパスステップを示します。`currency`がXRPの場合は省略する必要があります。このステップに`account`フィールドが指定されている場合は、このフィールドを指定しないでください。 | -| `type` | 整数 | **廃止予定**_（省略可）_ 他にどのフィールドが指定されているかを示します。 | -| `type_hex` | 文字列 | **廃止予定**: _（省略可）_`type`フィールドの16進数表現です。 | - -要約すると、以下のフィールドの組み合わせが有効であり、またオプションで`type`、`type_hex`のいずれかまたは両方を指定できます。 - -- `account`のみ -- `currency`のみ -- `currency`と`issuer`（`currency`がXRP以外の場合） -- `issuer`のみ - -パスステップで`account`、`currency`、`issuer`の各フィールドを上記以外の方法で指定することは無効です。 - -パスセットのバイナリシリアル化に使用される`type`フィールドは、実際には1つの整数上でビット演算により作成されます。ビットの定義は次のとおりです。 - -| 値（16進数） | 値（10進数） | 説明 | -|-------------|-----------------|-------------| -| 0x01 | 1 | アドレスの変更（Rippling）:`account`フィールドが指定されています。 | -| 0x10 | 16 | 通貨の変更:`currency`フィールドが指定されています。 | -| 0x20 | 32 | イシュアーの変更:`issuer`フィールドが指定されています。 | - -## 関連項目 - -- **コンセプト:** - - [複数通貨間の支払い](cross-currency-payments.html) - - [分散型取引所](decentralized-exchange.html) - - [Partial Payments](partial-payments.html) -- **リファレンス:** - - [Paymentトランザクション][] - - [path_findメソッド][]（WebSocketのみ） - - [ripple_path_findメソッド][] - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/tokens/paths.md b/content/concepts/tokens/paths.md index ffc18fb28c..3c9f3d8898 100644 --- a/content/concepts/tokens/paths.md +++ b/content/concepts/tokens/paths.md @@ -1,18 +1,10 @@ ---- -html: paths.html -parent: tokens.html -blurb: Payments of tokens must traverse paths of connected users and order books. -labels: - - Payments - - Cross-Currency ---- # Paths -In the XRP Ledger, paths define a way for [tokens](tokens.html) to flow through intermediary steps as part of a payment. Paths enable [cross-currency payments](cross-currency-payments.html) by connecting sender and receiver through orders in the XRP Ledger's [decentralized exchange](decentralized-exchange.html). Paths also enable complex settlement of offsetting debts. +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](direct-xrp-payments.html) does not use any paths. +Since XRP can be sent directly to any address, an XRP-to-XRP transaction does not use any paths. ## Path Steps @@ -21,11 +13,11 @@ A path is made of steps that connect the sender to the receiver of the payment. * Rippling through another address with the same currency * Trading tokens or XRP using an order book -[Rippling](rippling.html) 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. +[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](decentralized-exchange.html) 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.) +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.) -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.html), trust line quality settings, or rounding. +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") }} @@ -35,9 +27,9 @@ In both types of steps, each intermediate address gains and loses approximately ## 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. +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)](submit.html#sign-and-submit-mode). However, we recommend pathfinding separately and confirming the results before signing, to avoid surprises. +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. @@ -46,11 +38,11 @@ Finding paths is a very challenging problem that changes slightly every few seco ## Implied Steps -By convention, several steps of a path are implied by the [fields of the Payment transaction](payment.html): 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: +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`](payment.html#special-issuer-values-for-sendmax-and-amount) for details. + * 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. @@ -70,7 +62,7 @@ The following diagram enumerates all possible default paths: {{ include_svg("img/default-paths.svg", "Diagram of default paths") }} -You can use the [`tfNoDirectRipple` flag](payment.html#payment-flags) 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. +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 @@ -102,7 +94,7 @@ The `type` field, used for the binary serialization of a path set, is actually c | `0x10` | 16 | A change of currency: the `currency` field is present. | | `0x20` | 32 | A change of issuer: the `issuer` field is present. | - + -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} +--> diff --git a/content/concepts/tokens/rippling.ja.md b/content/concepts/tokens/rippling.ja.md deleted file mode 100644 index c581ae358d..0000000000 --- a/content/concepts/tokens/rippling.ja.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -html: rippling.html -parent: tokens.html -blurb: Ripplingは、複数当事者間での発行済み通貨残高の自動ネット決済です。 -labels: - - トークン - - 複数通貨間 ---- -# Rippling - -XRP Ledgerでは、「Rippling」とは同一通貨の[トラストライン](trust-lines-and-issuing.html)を有する複数の接続当事者間での非可分なネット決済のプロセスを指しています。Ripplingは発行済み通貨の基幹的なプロセスです。Ripplingを利用すれば、同一イシュアーを信頼するユーザーは、そのイシュアーを受動的な仲介機関として発行済み残高を相互に送金できるようになります。Ripplingは、受動的かつ双方向の[通貨取引オーダー](offers.html)のようなもので、制限がなく、通貨コードが同一でイシュアーが異なる2つの通貨間の為替レートは1:1です。 - -Ripplingは、支払[パス](paths.html)でのみ発生します。[XRP間の直接決済](direct-xrp-payments.html)にはRipplingは使用されません。 - -発行アカウント以外のアカウントでは、Ripplingが望ましくない場合があります。Ripplingを使えば、他のユーザーが同一通貨のイシュアー間で債権債務を移動できるようになるためです。このため、アカウントの[DefaultRippleフラグ](#defaultrippleフラグ)を有効にして、アカウントがデフォルトでRipplingを有効にしない限り、デフォルトでは[NoRippleフラグ](#norippleフラグ)により着信トラストラインでのRipplingが無効になっています。 - -**注意:** 別のアドレスへのトラストラインを作成する場合、そのトラストラインのあなたの側でRipplingをブロックするには、tfSetNoRippleフラグを明示的に有効にする必要があります。 - -## Ripplingの例 - -「Rippling」は、支払いを行うために複数のトラストラインが調整されたときに発生します。たとえば、AliceがCharlieにお金を借りており、さらにAliceはBobからもお金を借りている場合、XRP Ledgerではトラストラインは次のようになります: - -![Charlie --（$10）-- Alice -- （$20） -- Bob](img/noripple-01.png) - -BobがCharlieに$3を支払いたい場合、BobはAliceに対して「Alice、君に貸しているお金の中から$3をCharlieに支払ってくれ。」と言えます。AliceはBobに借りているお金の一部をCharlieに送金します。最終的にはトラストラインは次のようになります。 - -![Charlie --（$13）-- Alice --（$17）-- Bob](img/noripple-02.png) - -2つのアドレスが、アドレス間のトラストライン上の残高を調整することで相互に支払うこのプロセスを「Rippling」と呼びます。これはXRP Ledgerの有用で重要な機能です。Ripplingは、同一の[通貨コード][]を使用するトラストラインによってアドレスがリンクされている場合に起こります。イシュアーが同一でなくてもかまいません。実際、大規模なチェーンでは常にイシュアーが変更されます。 - -## NoRippleフラグ - -発行アカウント以外のアカウント、特に手数料やポリシーが異なる複数のイシュアーの残高を保有している流動性プロバイダーは、一般的に残高がRipplingされることを望みません。 - -「NoRipple」フラグは、トラストライン上の設定です。2つのトラストラインの両方で、同じアドレスによってNoRippleが有効に設定されている場合、第三者からの支払を、これらのトラストラインでこのアドレスを通じて「Rippling」することはできません。これにより、同一通貨の複数イシュアー間で流動性プロバイダーの残高が予期せず移動されるのを防ぎます。 - -アカウントは1つのトラストラインでNoRippleを無効にできます。これにより、そのトラストラインを含む任意のペアを通じてのRipplingが可能になります。アカウントにてデフォルトでRipplingを有効にするには、[DefaultRippleフラグ](#defaultrippleフラグ)を有効にします。 - -たとえば、Emilyが2つの異なる金融機関から発行されたお金を保有しているとします。 - -![Charlie --（$10）-- 金融機関A --（$1）-- Emily --（$100）-- 金融機関B --（$2）-- Daniel](img/noripple-03.png) - -CharlieはDanielに支払うため、Emilyのアドレスを通じてRipplingします。たとえば、CharlieがDanielに$10を支払うとします: - -![Charlie --（$0）-- 金融機関A --（$11）-- Emily --（$90）-- 金融機関B --（$12）-- Daniel](img/noripple-04.png) - -この場合、CharlieやDanielと面識のないEmilyは驚く可能性があります。さらに、金融機関Aが金融機関Bよりも高い出金手数料をEmilyに請求した場合、Emilyがコストを負担することになる可能性があります。NoRippleフラグはこの状況を回避するためのフラグです。Emilyが両方のトラストラインでNoRippleフラグを設定していれば、この2つのトラストラインを使用しているEmilyのアドレスを通じて、支払がRipplingされることはありません。 - -例: - -![Charlie --（$10）-- 金融機関A --（$1、NoRipple）-- Emily --（$100、NoRipple）-- 金融機関B --（$2）-- Daniel](img/noripple-05.png) - -このように、CharlieがEmilyのアドレスを通じてRipplingし、Danielに支払うという上記のシナリオは、不可能になります。 - -### 詳細 - -NoRippleフラグにより特定のパスが無効になり、無効になったパスは支払に使用できなくなります。パスが無効であると見なされるのは、パスが、あるアドレスに対してNoRippleが有効となっているトラストラインを通じて、そのアドレスノードに入り**かつ**そのノードから出た場合に限られます。 - -![処理を行うためには同一アドレスによって両方のトラストラインにNoRippleが設定されている必要があることを示す図](img/noripple-06.png) - - -## DefaultRippleフラグ - -DefaultRippleフラグは、デフォルトで着信トラストラインでのRipplingを有効にするアカウント設定です。ゲートウェイやその他の通貨イシュアーは、顧客が通貨を相互に送金できるようにするには、このフラグを有効にする必要があります。 - -アカウントのDefaultRipple設定は、他者があなたに対してオープンしたトラストラインにのみ影響し、あなたが作成するトラストラインには影響しません。アカウントのDefaultRipple設定を変更する場合、変更前に作成したトラストラインでは既存のNoRipple設定が維持されます。アドレスの新しいデフォルトに合わせてトラストラインのNoRipple設定を変更するには、[TrustSetトランザクション][]を使用します。 - -詳細は、[「XRP Ledgerゲートウェイの開設」のDefaultRipple](become-an-xrp-ledger-gateway.html#default-ripple)を参照してください。 - - -## NoRippleを使用する - - -### NoRippleを有効/無効にする - -トラストライン上のNoRippleフラグは、トラストライン上のアドレスの残高がプラスまたはゼロの場合に限り、有効にできます。これにより、この機能を悪用してトラストラインの残高に示される債務を不履行にすることができなくなります。（ただし、アドレスを放棄すれば債務を不履行にできます。） - -[`rippled` API](http-websocket-apis.html)でNoRippleフラグを有効にするには、`tfSetNoRipple`フラグを設定した[TrustSetトランザクション][]を送信します。NoRippleを無効にする（Ripplingを有効にする）には、`tfClearNoRipple`フラグを使用します。 - - -### NoRippleステータスの確認 - -相互に信頼し合っている2つのアカウントの場合、NoRippleフラグはアカウントごとに管理されます。 - -[`rippled` API](http-websocket-apis.html)でアドレスに関連付けられているトラストラインを確認するには、[account_linesメソッド][]を使用します。各トラストラインの`no_ripple`フィールドには、現在のアドレスがそのトラストラインに対してNoRippleフラグを有効にしているか否かが表示され、`no_ripple_peer`フィールドには、取引相手がNoRippleフラグを有効にしているか否かが表示されます。 - - -## 関連項目 - -- **コンセプト:** - - [パス](paths.html) -- **チュートリアル:** - - [XRP Ledgerゲートウェイの開設](become-an-xrp-ledger-gateway.html) -- **リファレンス:** - - [account_linesメソッド][] - - [account_infoメソッド][] - - [AccountSetトランザクション][] - - [TrustSetトランザクション][] - - [AccountRootのフラグ](accountroot.html#accountrootのフラグ) - - [RippleState（トラストライン）のフラグ](ripplestate.html#ripplestateのフラグ) - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/tokens/rippling.md b/content/concepts/tokens/rippling.md index 718b632dd0..14ca7dccf0 100644 --- a/content/concepts/tokens/rippling.md +++ b/content/concepts/tokens/rippling.md @@ -1,16 +1,10 @@ ---- -html: rippling.html -parent: tokens.html -blurb: Rippling is automatic multi-party net settlement of token balances. -labels: - - Tokens - - Cross-Currency ---- # Rippling -In the XRP Ledger, "rippling" describes a process of atomic net settlement between multiple connected parties who have [trust lines](trust-lines-and-issuing.html) 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](offers.html) with no limit and a 1:1 exchange rate for two tokens with the same currency code but different issuers. +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. -Rippling only occurs along the [paths](paths.html) of a payment. [Direct XRP-to-XRP payments](direct-xrp-payments.html) do not involve rippling. + + +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). @@ -65,7 +59,7 @@ The **Default Ripple** flag is an account setting that enables rippling on all _ 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). +For more information, see Default Ripple in 'Becoming an XRP Ledger Gateway'. ## Using No Ripple @@ -75,14 +69,20 @@ For more information, see [Default Ripple in 'Becoming an XRP Ledger Gateway'](b 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. +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](http-websocket-apis.html) or your preferred [client library](client-libraries.html), 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. +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. + + -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/tokens/tokens.ja.md b/content/concepts/tokens/tokens.ja.md deleted file mode 100644 index 034611fca8..0000000000 --- a/content/concepts/tokens/tokens.ja.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -parent: concepts.html -html: tokens.html -blurb: 発行済み通貨の概要と、XRP Ledgerにおけるその特性について説明します。 -labels: - - トークン ---- -# 発行済み通貨の概要 - -XRP Ledgerでは、XRP以外の通貨はすべて**発行済み通貨**とされます。このようなデジタル資産（「イシュアンス」または「IOU」とも呼ばれます）は、「トラストライン」と呼ばれるアドレス間の会計上の関係で管理されます。発行済み通貨は通常、負債とも資産とも見なされるため、トラストラインの残高は、見る視点によってマイナスにもプラスにもなります。どのアドレスも（XRP以外の）通貨を自由に発行できますが、他のアドレスが希望する保有量によってのみ制限されます。 - -発行済み通貨は、同一通貨コードを使用する複数のイシュアーと保有者を通じて「Rippling」されます。これが役立つ場合もありますが、予期しない結果や望ましくない結果が生じることもあります。トラストライン上で[NoRippleフラグ](rippling.html)を使用すれば、トラストラインを通じたRipplingを防ぐことができます。 - -XRP Ledgerの分散型取引所では、発行済み通貨対XRPの取引や、発行済み通貨間の取引を行えます。 - -一般的なモデルでは、発行済み通貨は、XRP Ledger外部で保有されている通貨またはその他の資産に結び付けられています。通貨のイシュアー（_ゲートウェイ_）は、XRP Ledger外部の通貨を、XRP Ledgerの発行済み通貨の同等の残高と交換するための入出金処理を行います。ゲートウェイの運用方法についての詳細は、[XRP Ledgerのゲートウェイになる](become-an-xrp-ledger-gateway.html)を参照してください。 - -XRP Ledgerの発行済み通貨は他の用途にも使えます。たとえば、固定量の通貨をセカンダリアドレスに発行し、イシュアーへキーを譲渡すれば、「イニシャルコインオファリング」（ICO）を作成できます。 - -**警告:** ICOは米国では[証券と見なされ、規制対象となる](https://www.sec.gov/oiea/investor-alerts-and-bulletins/ib_coinofferings)可能性があります。 - -金融サービスビジネスを始める前に、関連規制を調査されることを強くお勧めします。 - -## 発行済み通貨の使用方法 - -トラストラインは、ゲートウェイの債務を負う意思を明示的に表明するものです。（つまり、「あなたはXRP Ledgerの外部で私からこれだけのお金を借りることができます。」ということです。） - -発行済み通貨の使用方法として想定されるモデルは、信頼できる金融機関である _ゲートウェイ_ で使用することです。ゲートウェイでは、外界の資産を管理し、[複数通貨間の支払い](cross-currency-payments.html)や[分散型取引所](decentralized-exchange.html)での取引のためにXRP Ledgerで使用できるようにします。この流れは以下のようになります。 - -1. 顧客がゲートウェイに通貨を送金します。通貨は、法定通貨やBitcoinなど、XRP Ledgerのネイティブ資産でないものが考えられます。 -2. ゲートウェイは、その通貨を保管して記録します。 -3. ゲートウェイは、その顧客に属するアドレスに対して、XRP Ledgerでの残高を同じ通貨建てで発行します。 -4. 顧客は、[複数通貨間の支払い](cross-currency-payments.html)の送金や[分散型取引所](decentralized-exchange.html)での取引などによって、発行済み通貨をXRP Ledgerで自由に使用できます。 -5. 顧客（必ずしも最初に預金した顧客ではない）は、発行済み通貨をゲートウェイのXRP Ledgerのアドレスに送金します。 -6. ゲートウェイは、XRP Ledgerの資金の残高を送信した顧客のIDを確認し、対応する金額を _XRP Ledgerの外部で_ その顧客に付与します。 - -XRP Ledgerへの「入金」や「出金」のプロセスに関する詳細は、ゲートウェイ、法的管轄、関連する資産のタイプなどの要因に基づいて異なります。 - -## 発行済み通貨の特性 - -XRP Ledger内の発行済み通貨はすべてトラストラインに存在し、レジャーのデータでは[RippleStateオブジェクト](ripplestate.html)として表示されます。発行済み通貨を作成するには、発行アドレスは、対象となる通貨に対し非ゼロ制限のあるイシュアーへのトラストラインを持つアドレスに対し、[Paymentトランザクション][]を送信します。（発行済み通貨は、このようなトラストラインを通じてRipplingする方法でも作成できます。）発行済み通貨を消去するには、通貨をイシュアーに戻します。 - -通貨のイシュアーは、2名の当事者が発行済み通貨で取引をする際に差し引かれる[送金手数料](transfer-fees.html)のパーセンテージを定義できます。 - -アドレスは発行済み通貨を[凍結](freezes.html)することもでき、企業が当該地域の金融規制に準拠する際に有用です。この機能が不要で、通貨を凍結しない場合は、アドレスが有する個別のトラストラインを凍結する機能と、Global Freezeを取り消す機能を放棄できます。XRPは凍結できません。 - -発行済み通貨は、あらゆる種類の通貨または資産（額面価格が極めて低い、または高いものを含む）に相当するとされています。通貨コードの種類と発行済み通貨の表記の数値制限に関する技術的な詳細は、[通貨フォーマットのリファレンス](currency-formats.html)を参照してください。 - -## 関連項目 - -- **コンセプト:** - - [XRP](xrp.html) - - [複数通貨間の支払い](cross-currency-payments.html) - - [分散型取引所](decentralized-exchange.html) -- **チュートリアル:** - - [XRP Ledgerゲートウェイの開設](become-an-xrp-ledger-gateway.html) - - [トランザクションの結果の確認](look-up-transaction-results.html) - - [専門化した支払いタイプの使用](use-specialized-payment-types.html) -- **リファレンス:** - - [Paymentトランザクション][] - - [TrustSetトランザクション][] - - [RippleStateオブジェクト](ripplestate.html) - - [account_linesメソッド][] - - [account_currenciesメソッド][] - - [gateway_balancesメソッド][] - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/tokens/tokens.md b/content/concepts/tokens/tokens.md index 4ea1cf4ce7..18657dc362 100644 --- a/content/concepts/tokens/tokens.md +++ b/content/concepts/tokens/tokens.md @@ -1,61 +1,42 @@ --- +html: tokens.html parent: concepts.html -blurb: Anyone can make tokens representing digital value on the XRP Ledger. +blurb: The XRP Ledger is a blockchain that records transactions of XRP and other tokens between accounts. labels: - Tokens --- # 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. Any account can issue tokens to other recipients who are willing to hold them, but you cannot unilaterally give tokens away to users who don't want them. 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. +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. -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-tokens.html) :not_enabled: for details of the XRP Ledger's native support. +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. -Tokens can used for [cross-currency payments](cross-currency-payments.html) and can be traded in the [decentralized exchange](decentralized-exchange.html). +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. -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.html) on trust lines to prevent those trust lines from rippling. +Tokens can used for [cross-currency payments](../transactions/payments/cross-currency-payments.md) and can be traded in the decentralized exchange. + -## 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 the [Becoming an XRP Ledger Gateway](become-an-xrp-ledger-gateway.html). - - -## 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](rippling.html). - -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 pay 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](paths.html). - - -## 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. - -Be sure to research the relevant regulations before engaging in any financial service business. - +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](currency-formats.html#comparison). 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](decentralized-exchange.html) or by decreasing the limit after you already have a positive balance.) +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.) + + + 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 × 1080) and very small values (down to 1.0 × 10-81). -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](cross-currency-payments.html) or trades can also create more tokens according to an issuer's settings. +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.html) that is automatically deducted when users transfer their tokens. Issuers can also define a [tick size](ticksize.html) for exchanges rates involving their tokens. Both issuers and regular accounts can [freeze](freezes.html) trust lines, which limits how the tokens in those trust lines can be used. (None of these things applies to XRP.) +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.) + + + -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} +--> \ No newline at end of file diff --git a/content/concepts/tokens/transfer-fees.ja.md b/content/concepts/tokens/transfer-fees.ja.md deleted file mode 100644 index 8b7addc6ef..0000000000 --- a/content/concepts/tokens/transfer-fees.ja.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -html: transfer-fees.html -parent: tokens.html -blurb: 通貨発行者は、自己の発行済み通貨の送金に手数料を課すことができます。 -labels: - - 手数料 - - トークン ---- -# 送金手数料 - -[XRP Ledgerで通貨を発行する金融機関](become-an-xrp-ledger-gateway.html)は、XRP Ledgerの`TransferRate`設定を使用して、 その金融機関が発行する通貨を送金するユーザーに対し _送金手数料_ を請求できます。この送金の送金元からは送金手数料に基づくパーセンテージが引き落とされ、送金先には予定額が入金されます。差額が送金手数料です。送金手数料は発行アドレスの資産となり、XRP Ledgerではこれ以上追跡されません。発行アカウントとの _直接_ の送金と入金には送金手数料は適用されませんが、[運用アドレス][]から別のユーザーへの送金には送金手数料が適用されます。 - -[運用アドレス]: issuing-and-operational-addresses.html -[発行アドレス]: issuing-and-operational-addresses.html - -XRPにはイシュアーがいないため、送金手数料が発生することはありません。 - -たとえばACME BankがACMEイシュアンスの送金手数料を1%に設定するとします。支払いの受取人が2 EUR.ACMEを受領するには、送金元が2.02 EUR.ACMEを送金する必要があります。このトランザクションの後、XRP LedgerのACMEの債務残高は0.02€減少します。つまり、ACMEはそのXRP Ledgerイシュアンスの担保となるアカウントで当該の額を保有する必要がありません。 - -次の図は、XRP LedgerによるAliceからCharlieへの2 EUR.ACMEの支払い（送金手数料1%）を示します。 - -![Aliceが2,02€を送金し、Charlieが2,00€を受領し、XRP LedgerでのACMEの負債が0,02€減少します](img/e2g-with_transferrate.png) - -## ペイメントパスでの送金手数料 - - - -送金手数料は、各送金においてイシュアンスが発行アカウントを通じて当事者間を移動するたびに適用されます。さらに複雑なトランザクションでは、手数料が複数回適用されます。送金手数料は、送金の終わりの時点から逆方向に適用されるので、最終的には支払いの送金者がすべての手数料をカバーするのに十分な額を送金する必要があります。例: - -![手数料が適用された複数通貨間の支払いの図](img/transfer_fees_example.png) - -このシナリオでは、ACMEが発行したEURをSalazar（送金元）が保有しており、WayGateが発行した100 USDをRosa（受取人）に送金したいと思っています。FXMakerはオーダーブックで最も良いレート（1 USD.WayGate = 0.9 EUR.ACME）のオファーを提供する通貨取引業者です。もし手数料がなければ、Salazarは90 EURを送金すればRosaに100 USDを送金することができます。しかしながら、ACMEで1%の送金手数料が発生し、WayGateで0.2%の送金手数料が発生します。つまり、次のようになります。 - -* Rosaが100 USD.WayGateを受領するには、FXMakerから100.20 USD.WayGateを送金する必要があります。 -* 100.20 USD.WayGateを送金する場合のFXMakerの現在の買値は90.18 EUR.ACMEです。 -* FXMakerが90.18 EUR.ACMEを受領するには、Salazarが91.0818 EUR.ACMEを送金する必要があります。 - -# 技術詳細 - -送金手数料は[発行アドレス][]の設定により表されます。送金手数料には、0%未満の値と100%を超える値は指定できず、0.0000001%の位までで切り捨てられます。TransferRate設定は同一アカウントにより発行されるすべての通貨に適用されます。通貨によって異なる送金手数料のパーセンテージを適用するには、通貨ごとに異なる[発行アドレス][]を使用します。 - -**注記:** `rippled` v0.80.0で導入され2017-11-14に有効となった[fix1201 Amendment](amendments.html)により、最大送金手数料は実効限度である約329%（32ビット整数の最大サイズに基づく）から100%に引き下げられました。送金手数料の設定が100%（`TransferRate`が`2000000000`）を上回るアカウントがレジャーにまだ含まれている可能性があります。すでに設定されている手数料はすべて、規定のレートで引き続き運用されます。 - -## rippled - -`rippled`のJSON-RPC APIおよびWebSocket APIでは、送金手数料は`TransferRate`フィールドに10進数で指定され、この数字は受取人が同一通貨を10億単位受領できるよう送金する必要のある額を表します。`TransferRate`が`1005000000`の場合、送金手数料0.5%に相当します。デフォルトでは`TransferRate`は手数料なしに設定されています。`TransferRate`には、`1000000000`（手数料「0%」）未満の値と`2000000000`（手数料「100%」）を上回る値は指定できません。値`0`は手数料なしの特殊なケースであり、`1000000000`に相当します。 - -金融機関は、[発行アドレス][]から[AccountSetトランザクション][]を送信して、イシュアンスの`TransferRate`を変更することができます。 - -アカウントの`TransferRate`を確認するには、[account_infoメソッド][]を使用します。`TransferRate`が省略されている場合は、手数料はありません。 - - -## 関連項目 - -- **コンセプト:** - - [手数料（曖昧さの回避）](fees.html) - - [トランザクションコスト](transaction-cost.html) - - [パス](paths.html) -- **チュートリアル:** - - [XRP Ledgerゲートウェイの開設](become-an-xrp-ledger-gateway.html) -- **リファレンス:** - - [account_linesメソッド][] - - [account_infoメソッド][] - - [AccountSetトランザクション][] - - [AccountRootのフラグ](accountroot.html#accountrootのフラグ) - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/tokens/transfer-fees.md b/content/concepts/tokens/transfer-fees.md index 39d83f7150..ba4f86a578 100644 --- a/content/concepts/tokens/transfer-fees.md +++ b/content/concepts/tokens/transfer-fees.md @@ -1,11 +1,3 @@ ---- -html: transfer-fees.html -parent: tokens.html -blurb: Token issuers can charge a fee for transferring their tokens. -labels: - - Fees - - Tokens ---- # 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. @@ -82,9 +74,3 @@ Some [client libraries](client-libraries.html) have convenience functions for ge - [account_info method][] - [AccountSet transaction][] - [AccountRoot Flags](accountroot.html#accountroot-flags) - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/tokens/trust-lines-and-issuing.ja.md b/content/concepts/tokens/trust-lines-and-issuing.ja.md deleted file mode 100644 index 6126e05e94..0000000000 --- a/content/concepts/tokens/trust-lines-and-issuing.ja.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -html: trust-lines-and-issuing.html -parent: tokens.html -blurb: トラストラインの特性と根本原理について説明します。 -labels: - - トークン ---- -# トラストラインと発行 - -XRP Ledgerの[発行済み通貨](issued-currencies.html)は、XRP Ledger外部で _ゲートウェイ_ が保有する価値をしばしば表します。ユーザーがXRP Ledgerの残高をイシュアーに返却して清算するときには、XRP Ledger内でこれらの資金を発行するアドレスが、XRP Ledger外部で残高を払い戻すことが期待されます。 - -コンピュータープログラムは外界で約束を守ることを誰にも強制できないため、トラストラインは、イシュアーがあなたの代わりに保有する価値の量として、あなたが信頼できる量を設定する手段となります。信用のある大手金融機関は、お金のないルームメートに比べれば返済能力は高いため、トラストラインごとに異なる限度を設定して、XRP Ledgerでイシュアーがあなたから「借用」できる上限額を指定できます。イシュアーが債務不履行になった場合や、倒産した場合には、XRP Ledgerでの保有残高をその他の等価の資産と交換できなくなるため、設定した上限額まで失う可能性があります。（XRP Ledgerで引き続き発行済み通貨を保持または取引できますが、発行済み通貨に価値があると見なされる理由がなくなる可能性があります。） - -次の2つの場合、残高が限度額を _超過_ しても、トラストラインにその残高を保有できます。[取引](decentralized-exchange.html)によりその通貨をさらに積み増しする場合と、トラストラインの限度を引き下げる場合。 - -トラストラインはレジャーのスペースを使用するため、[トラストラインにより、アカウントの準備金として保有する必要のあるXRPが増加します](reserves.html)。これは、信頼を受けているアカウントではなく、信頼を拡大しているアカウントに適用されます。 - -各トラストラインは、特定の[通貨コード][]に固有です。2つのアカウント間に作成できる各種通貨コードのトラストラインの数に制限はありませんが、どの通貨コードについても、作成できるトラストラインは1方向に1つだけです。 - -## トラストラインの設定 - -トラストラインは、レジャーの状態データでは[RippleStateオブジェクト](ripplestate.html)として表されます。1つのRippleStateオブジェクトは、一方向または両方向のトラストラインの可能性を表します。このオブジェクトにはトラストラインのそれぞれのサイドに対する制限やその他の設定が含まれていますが、両サイドは1つの正味残高を共有しています。 - -トラストラインの設定がデフォルトの状態である場合、トラストラインがないのと同等です。 - -[NoRippleフラグ](rippling.html)（デフォルトの設定はDefaultRippleフラグの設定に応じて異なる）を除き、トラストラインフラグのすべてのフラグは、デフォルトでオフになっています。 - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/tokens/trust-lines-and-issuing.md b/content/concepts/tokens/trust-lines-and-issuing.md deleted file mode 100644 index 54a5b3a8e8..0000000000 --- a/content/concepts/tokens/trust-lines-and-issuing.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -html: trust-lines-and-issuing.html -parent: tokens.html -blurb: Learn about the properties and rationale of trust lines. -labels: - - Tokens ---- -# Trust Lines and Issuing - -Trust lines are structures in the XRP Ledger for holding [tokens](tokens.html). 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.html#community-credit) among other benefits. - -Each "trust line" is a _bidirectional_ relationship consisting of: - -- The identifiers for the **two [accounts](accounts.html)** 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](http-websocket-apis.html), 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-above-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 Above 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](checks.html). (_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](rippling.html) 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](freezes.html#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](reserves.html). 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](cross-currency-payments.html), 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. - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/understanding-xrpl/accounts/account-creating.md b/content/concepts/understanding-xrpl/accounts/account-creating.md deleted file mode 100644 index 83d93dc5fe..0000000000 --- a/content/concepts/understanding-xrpl/accounts/account-creating.md +++ /dev/null @@ -1,43 +0,0 @@ -# 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. - diff --git a/content/concepts/understanding-xrpl/accounts/account-deleting.md b/content/concepts/understanding-xrpl/accounts/account-deleting.md deleted file mode 100644 index a314fbb1ec..0000000000 --- a/content/concepts/understanding-xrpl/accounts/account-deleting.md +++ /dev/null @@ -1,23 +0,0 @@ -# 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. - diff --git a/content/concepts/understanding-xrpl/accounts/account-structure.md b/content/concepts/understanding-xrpl/accounts/account-structure.md deleted file mode 100644 index 1375a60186..0000000000 --- a/content/concepts/understanding-xrpl/accounts/account-structure.md +++ /dev/null @@ -1,24 +0,0 @@ -# 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. diff --git a/content/concepts/understanding-xrpl/accounts/account-types.md b/content/concepts/understanding-xrpl/accounts/account-types.md deleted file mode 100644 index c0827a07c9..0000000000 --- a/content/concepts/understanding-xrpl/accounts/account-types.md +++ /dev/null @@ -1,80 +0,0 @@ -# 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: - - - -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. - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/accounts/accounts.md b/content/concepts/understanding-xrpl/accounts/accounts.md deleted file mode 100644 index 7dc3ab86e6..0000000000 --- a/content/concepts/understanding-xrpl/accounts/accounts.md +++ /dev/null @@ -1,21 +0,0 @@ -# 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. - diff --git a/content/concepts/understanding-xrpl/accounts/addresses.md b/content/concepts/understanding-xrpl/accounts/addresses.md deleted file mode 100644 index 41d1b786cc..0000000000 --- a/content/concepts/understanding-xrpl/accounts/addresses.md +++ /dev/null @@ -1,46 +0,0 @@ -## 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 232 - -> **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 | diff --git a/content/concepts/understanding-xrpl/accounts/balances.md b/content/concepts/understanding-xrpl/accounts/balances.md deleted file mode 100644 index 19e6c9db4e..0000000000 --- a/content/concepts/understanding-xrpl/accounts/balances.md +++ /dev/null @@ -1,3 +0,0 @@ -# Balances - -Placeholder for details of the account balances. \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/accounts/cryptographic-keys.md b/content/concepts/understanding-xrpl/accounts/cryptographic-keys.md deleted file mode 100644 index 492abe4159..0000000000 --- a/content/concepts/understanding-xrpl/accounts/cryptographic-keys.md +++ /dev/null @@ -1,257 +0,0 @@ -# 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. - - - -### 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.) - -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. - - - -**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. - - - -## 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. - -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. - - -## 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. - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/accounts/deposit-authorization.md b/content/concepts/understanding-xrpl/accounts/deposit-authorization.md deleted file mode 100644 index cdbe58a478..0000000000 --- a/content/concepts/understanding-xrpl/accounts/deposit-authorization.md +++ /dev/null @@ -1,111 +0,0 @@ -# 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. - -## 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). - - - -## 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. - - - -### 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: - -- 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. - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/accounts/history.md b/content/concepts/understanding-xrpl/accounts/history.md deleted file mode 100644 index e3506c88ea..0000000000 --- a/content/concepts/understanding-xrpl/accounts/history.md +++ /dev/null @@ -1,3 +0,0 @@ -# History - -Placeholder for details of account history. \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/accounts/reserves.md b/content/concepts/understanding-xrpl/accounts/reserves.md deleted file mode 100644 index 79f05d43cd..0000000000 --- a/content/concepts/understanding-xrpl/accounts/reserves.md +++ /dev/null @@ -1,67 +0,0 @@ -# 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. - - - -- A SignerList counts as 1 object for purposes of the owner reserve (since the `MultiSignReserve amendment` activated in April 2019). - - -- 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. - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/accounts/sequence.md b/content/concepts/understanding-xrpl/accounts/sequence.md deleted file mode 100644 index 1be56d77fd..0000000000 --- a/content/concepts/understanding-xrpl/accounts/sequence.md +++ /dev/null @@ -1,3 +0,0 @@ -# Sequence - -Placeholder for details of sequence with regard to account transactions. \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/fees.md b/content/concepts/understanding-xrpl/fees.md deleted file mode 100644 index 6d1e447419..0000000000 --- a/content/concepts/understanding-xrpl/fees.md +++ /dev/null @@ -1,27 +0,0 @@ -# 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. \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/networks/federated-sidechains.md b/content/concepts/understanding-xrpl/networks/federated-sidechains.md deleted file mode 100644 index eb344e1909..0000000000 --- a/content/concepts/understanding-xrpl/networks/federated-sidechains.md +++ /dev/null @@ -1,76 +0,0 @@ -# Federated Sidechains - -_Federated Sidechains are available as an Engineering Preview and can be used to develop and test using `rippled` 1.8.0._ - -A sidechain is an independent ledger with its own consensus algorithm and transaction types and rules. It acts as its own blockchain. Federation enables value in the form of XRP and other tokens to move efficiently between a sidechain and an XRP Ledger _mainchain_ (usually Mainnet, but could be [Testnet or Devnet](parallel-networks.html) for testing). Federated sidechains operate without compromising the speed, efficiency, and throughput of the public Mainnet. - -Federated sidechains enable developers to launch new features and innovative applications using the foundation of XRP Ledger technology. Sidechains can customize the XRP Ledger protocol to the needs of a specific use case or project and run it as its own blockchain. Here are a few examples: - -* Build a smart contract layer, powered by an engine compatible with the Ethereum Virtual Machine (EVM), web assembly, or a Move VM. For example, a [smart sidechain with Hooks](https://hooks-testnet.xrpl-labs.com/) enabled. -* Build your own algorithmic stable coin with customised ledger types and transaction rules. -* Build permissioned or nearly permissionless, centralized or largely decentralized ledgers whose assets can be traded on the Mainnet [decentralized exchange](decentralized-exchange.html). - -## How Federated Sidechains Work - - -A sidechain is an independent ledger with its own consensus algorithm and transaction types and rules. Each sidechain is run by its own set of servers (including validators) and does not rely on the validators on the Mainnet for transactions on the sidechain. - -Each sidechain has two door accounts, one on the sidechain and one on the mainchain, that are controlled by the federators on the sidechain. The federators listen for transactions to and from both of these door accounts. - -The sidechain has _federators_ who jointly control the door accounts on both networks using [multi-signing](multi-signing.html) so that 80% of federators must approve a transaction. In many cases, the federators should also be the trusted validators of the sidechain. - -When a door account receives a transaction on either the sidechain or the mainchain, the federators create a mirror transaction on the other chain. (For example, if you send XRP _to_ the mainchain door account, the federators create a transaction on the sidechain to send XRP _from_ the sidechain door account to the intended recipient.) The federators sign the transaction and broadcast it to each other. Simultaneously, federators also listen for signed transactions from other federators and collect them. - -When 80% of the federators have signed the transaction, they submit it to the sidechain or mainchain as appropriate. This way, assets that the mainchain door account holds can be allocated to others on the sidechain, and assets that sidechain door account receives can be sent to others on the mainchain. - -Transactions within the sidechain are not visible to the servers on the mainchain. - - -## Terminology - -Below is an alphabetical list of terms and their definitions. - -_Door account_: An account controlled by the federators. There are two door accounts: one on the mainchain and one on the sidechain. Cross chain transactions are started by users sending assets to a door account. Mainchain to sidechain transactions cause the balance to increase on the mainchain door account and the balance to decrease on the sidechain door account. It is called a "door" because it is the mechanism to move assets from one chain to another—much like going between rooms in a house requires stepping through a door. - -_Federator_: A server on the sidechain that listens for triggering transactions on both the mainchain and the sidechain. Each federator has a signing key associated with it that is used to sign transactions. A transaction must be signed by a quorum of federators before it can be submitted. Federators are responsible for creating and signing valid response transactions, collecting signatures from other federators, and submitting transactions to the mainchain and sidechain. - -_Mainchain_: The blockchain where assets originate and where assets are held while being used on the sidechain. For most sidechains, the mainchain is the XRP Ledger Mainnet, Testnet, or Devnet. - -_Response transaction_: A transaction submitted by the federators in reaction to a triggering transaction. In most cases, the response transaction occurs on the opposite chain as the triggering transaction. However, there are some exceptions for handling failed transactions. - -_Sidechain_: An XRP Ledger sidechain is another blockchain based on XRP Ledger technology. A _federated_ sidechain provides a way to transfer assets from a mainchain to the sidechain and back. A sidechain can use an exact copy of the XRP Ledger's protocol or it can make changes, including to the [consensus algorithm](consensus.html), [transaction types](transaction-types.html), and other rules. Sidechains have separate history, rules, and validators than the mainchain. Proxy assets are issued in the sidechain, with the equivalent assets held by a door account on the mainchain. Proxy assets on the sidechain can be sent back to the mainchain and unlocked from the control of the federators. - -_Triggering transaction_: A transaction that causes the federators to start the process of signing and submitting a new response transaction. For example, sending XRP to the mainchain's door account is a triggering transaction that causes the federators to submit a new transaction on the sidechain. - -## How to Set Up a Federated Sidechain - -Federated Sidechains are currently available as an Engineering Preview so you can experiment and explore the potential of sidechains. You can connect sidechains to the XRP Ledger Testnet, Devnet, or Mainnet as long as [the servers](xrpl-servers.html) in the mainchain network are running version 1.8.0 or higher. - -**Caution:** You can connect sidechains to the XRP Ledger Mainnet to develop and test with small amounts; it is not recommended for production use cases until federated sidechains are available in a release. - -Setting up a sidechain involves the following high-level steps: - -1. Clone the `rippled` source code and check out the `sidechain` branch: https://github.com/ripple/rippled/tree/sidechain. -2. Customize the source code for your sidechain. For example, you may want to write custom [transaction types](transaction-types.html). Note that this is an important and non-trivial task. -3. Each sidechain federator has its own configuration file that must be updated to include the following information: - - `[sidechain]` stanza - add details such as signing key, mainchain account, and the mainchain address (IP and port) to listen to. - - `[sidechain_assets]` stanza - define assets that can be used for cross-chain transactions (XRP or [issued tokens](issued-currencies.html)), exchange rate for the assets, and optional refund penalty to discourage transactions that may default. - - [sidechain_federators] stanza - list of federators public keys to be used for signing. This list is common for all federators on the sidechain. -4. Set up door accounts to enable cross chain transactions. This involves the following steps (on _both_ chains): - - Create and fund the door accounts. - - [Set up the SignerList](set-up-multi-signing.html) for the door account. - - Create three [tickets](tickets.html) for error handling. - - And finally, [disable the master key pair](disable-master-key-pair.html) to the door account to ensure that the federators jointly control the door account. - - Note that it is important to perform this final step only after successful completion of the previous steps. - - -The _Sidechain Launch Kit_ is a commandline tool that simplifies setting up federated sidechains and can be used to quickly spin up a sidechain on your local machine. The launch kit also installs an interactive Sidechain Shell that enables you to interact with the sidechain. - -[Sidechain Launch Kit >](https://github.com/xpring-eng/sidechain-launch-kit) - - -## See Also - -- **Concepts:** - - [Federated Sidechains Video](https://www.youtube.com/embed/NhH4LM8NxgY) diff --git a/content/concepts/understanding-xrpl/networks/parallel-networks.md b/content/concepts/understanding-xrpl/networks/parallel-networks.md deleted file mode 100644 index 016f064d46..0000000000 --- a/content/concepts/understanding-xrpl/networks/parallel-networks.md +++ /dev/null @@ -1,42 +0,0 @@ -# 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, Ripple hosts two alternative networks, or altnets: the Testnet and the Devnet. Here's a breakdown of all three networks: - -| Network | Upgrade Cadence | Description | -|:--------|:----------------|:-------------------------------------------------| -| Mainnet | Stable releases | _The_ [XRP Ledger](xrp-ledger-overview.html), a decentralized cryptographic ledger powered by a network of peer-to-peer servers and the home of [XRP](xrp.html). | -| Testnet | Stable releases | An "alternate universe" network that acts as a testing ground for software built on the XRP Ledger, without impacting production XRP Ledger users and without risking real money. The [amendment status](known-amendments.html) of the Testnet is intended to closely mirror the Mainnet, although slight variations in timing may occur due to the unpredictable nature of decentralized systems. | -| Devnet | Beta releases | A preview of coming attractions, where unstable changes to the core XRP Ledger software may be tested out. Developers can use this altnet to interact with and learn about planned new XRP Ledger features and amendments that are not yet enabled on the Mainnet. | -| 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 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 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 on a regular basis. - - -## See Also - -- **Tools:** - - [XRP Testnet Faucet](xrp-test-net-faucet.html) -- **Concepts:** - - [Introduction to Consensus](intro-to-consensus.html) - - [Amendments](amendments.html) -- **Tutorials:** - - [Connect Your `rippled` to the XRP Testnet](connect-your-rippled-to-the-xrp-test-net.html) - - [Use rippled in Stand-Alone Mode](use-stand-alone-mode.html) -- **References:** - - [server_info method][] - - [consensus_info method][] - - [validator_list_sites method][] - - [validators method][] - - [Daemon Mode Options](commandline-usage.html#daemon-mode-options) \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/networks/xrpl-networks.md b/content/concepts/understanding-xrpl/networks/xrpl-networks.md deleted file mode 100644 index 53fbdae8e7..0000000000 --- a/content/concepts/understanding-xrpl/networks/xrpl-networks.md +++ /dev/null @@ -1,3 +0,0 @@ -# The XRP Ledger Networks - -Placeholder for XRPL networks documentation. \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/server/clio-server.md b/content/concepts/understanding-xrpl/server/clio-server.md deleted file mode 100644 index bc733ad0d8..0000000000 --- a/content/concepts/understanding-xrpl/server/clio-server.md +++ /dev/null @@ -1,3 +0,0 @@ -# Clio Server - -Placeholder for Clio server documentation. \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/server/invariant-checking.md b/content/concepts/understanding-xrpl/server/invariant-checking.md deleted file mode 100644 index d5b4d18967..0000000000 --- a/content/concepts/understanding-xrpl/server/invariant-checking.md +++ /dev/null @@ -1,145 +0,0 @@ -# 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) - - - diff --git a/content/concepts/understanding-xrpl/server/rippled-server.md b/content/concepts/understanding-xrpl/server/rippled-server.md deleted file mode 100644 index 6c425052dd..0000000000 --- a/content/concepts/understanding-xrpl/server/rippled-server.md +++ /dev/null @@ -1,3 +0,0 @@ -# rippled Server - -Placeholder for rippled server documentation. \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/server/server-modes.md b/content/concepts/understanding-xrpl/server/server-modes.md deleted file mode 100644 index 445f358614..0000000000 --- a/content/concepts/understanding-xrpl/server/server-modes.md +++ /dev/null @@ -1,3 +0,0 @@ -# Server Modes - -Placeholder for Server Mode documentation. \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/server/transaction-queue.md b/content/concepts/understanding-xrpl/server/transaction-queue.md deleted file mode 100644 index 4230c95f7e..0000000000 --- a/content/concepts/understanding-xrpl/server/transaction-queue.md +++ /dev/null @@ -1,67 +0,0 @@ -# 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. - -## Transaction Queue and Consensus - -The transaction queue plays an important role in selecting the transactions that are included or excluded from a given ledger version in the consensus process. The following steps describe how the transaction queue relates to the [consensus process](consensus.html). - -{{ include_svg("img/consensus-with-queue.svg", "Transaction queue and consensus diagram") }} - -1. **Consensus Round 1** - Each validator proposes a set of transactions to be included in the next ledger version. Each also keeps a queue of candidate transactions not currently proposed. - -2. **Consensus Round 2** - If a validator removes a transaction from its proposal in later rounds, it adds that transaction to its queue. - -3. **Consensus Round N** - The consensus process continues until enough servers agree on a transaction set. - -4. **Validation** - Servers confirm that they built the same resulting ledger and declare it validated. - -5. **Building the Next Proposal** - Each validator prepares its proposal for the next ledger version, starting with queued transactions. - -6. **Adding to the Queue** - If the next proposed ledger is already full, incoming transactions are queued for a later ledger version. (Transactions that pay the [open ledger cost](transaction-cost.html#open-ledger-cost) can still get into the next proposed ledger even if it's "full", but the open ledger cost grows exponentially with each transaction added this way.) - - After this step, the process repeats from the beginning. - -**Note:** Technically, several of the steps described in the above process occur in parallel, because each server is always listening for new transactions, and starts preparing its next ledger proposal while the consensus process for the previous ledger version is ongoing. - -## Queuing Restrictions - -The `rippled` server uses a variety of heuristics to estimate which transactions are "likely to be included in a ledger." The current implementation uses the following rules to decide which transactions to queue: - -- Transactions must be properly-formed and [authorized](transaction-basics.html#authorizing-transactions) with valid signatures. -- Transactions with an `AccountTxnID` field cannot be queued. -- A single sending address can have at most 10 transactions queued at the same time. -- To queue a transaction, the sender must have enough XRP for all of the following: [Updated in: rippled 1.2.0][] - - Destroying the XRP [transaction cost](transaction-cost.html) as specified in the `Fee` fields of all the sender's queued transactions. The total amount among queued transactions cannot be more than the base account reserve (currently 10 XRP). (Transactions paying significantly more than the minimum transaction cost of 0.00001 XRP typically skip the queue and go straight into the open ledger.) - - Sending the maximum sum of XRP that all the sender's queued transactions could send. - - Keeping enough XRP to meet the account's [reserve requirements](reserves.html). -- If a transaction affects how the sending address authorizes transactions, no other transactions from the same address can be queued behind it. [New in: rippled 0.32.0][] -- If a transaction includes a `LastLedgerSequence` field, the value of that field must be at least **the current ledger index + 2**. - -### Fee Averaging - -[New in: rippled 0.33.0][] - -If a sending address has one or more transactions queued, that sender can "push" the existing queued transactions into the open ledger by submitting a new transaction with a high enough transaction cost to pay for all of them. Specifically, the new transaction must pay a high enough transaction cost to cover the [open ledger cost](transaction-cost.html#open-ledger-cost) of itself and each other transaction from the same sender before it in the queue. (Keep in mind that the open ledger cost increases exponentially each time a transaction pays it.) The transactions must still follow the other [queuing restrictions](#queuing-restrictions) and the sending address must have enough XRP to pay the transaction costs of all the queued transactions. - -This feature helps you work around a particular situation. If you submitted one or more transactions with a low cost that were queued, you cannot send new transactions from the same address unless you do one of the following: - -* Wait for the queued transactions to be included in a validated ledger, _or_ -* Wait for the queued transactions to be permanently invalidated if the transactions have the [`LastLedgerSequence` field](reliable-transaction-submission.html#lastledgersequence) set, _or_ -* [Cancel the queued transactions](cancel-or-skip-a-transaction.html) by submitting a new transaction with the same sequence number and a higher transaction cost. - -If none of the above occur, transactions can stay in the queue for a theoretically unlimited amount of time, while other senders can "cut in line" by submitting transactions with higher transaction costs. Since signed transactions are immutable, you cannot increase the transaction cost of the queued transactions to increase their priority. If you do not want to invalidate the previously submitted transactions, fee averaging provides a workaround. If you increase the transaction cost of your new transaction to compensate, you can ensure the queued transactions are included in an open ledger right away. - -## Order Within the Queue - -Within the transaction queue, transactions are ranked so that transactions paying a higher transaction cost come first. This ranking is not by the transactions' _absolute_ XRP cost, but by costs _relative to the [minimum cost for that type of transaction](transaction-cost.html#special-transaction-costs)_. Transactions that pay the same transaction cost are ranked in the order the server received them. Other factors may also affect the order of transactions in the queue; for example, transactions from the same sender are sorted by their `Sequence` numbers so that they are submitted in order. - -The precise order of transactions in the queue decides which transactions get added to the next in-progress ledger version in cases where there are more transactions in the queue than the expected size of the next ledger version. The order of the transactions **does not affect the order the transactions are executed within a validated ledger**. In each validated ledger version, the transaction set for that version executes in [canonical order](consensus.html#calculate-and-share-validations). - -**Note:** When `rippled` queues a transaction, the provisional [transaction response code](transaction-results.html) is `terQUEUED`. This means that the transaction is likely to succeed in a future ledger version. As with all provisional response codes, the outcome of the transaction is not final until the transaction is either included in a validated ledger, or [rendered permanently invalid](finality-of-results.html). - - -## See Also - -- [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. diff --git a/content/concepts/understanding-xrpl/server/xrpl-servers.md b/content/concepts/understanding-xrpl/server/xrpl-servers.md deleted file mode 100644 index 977c519677..0000000000 --- a/content/concepts/understanding-xrpl/server/xrpl-servers.md +++ /dev/null @@ -1,3 +0,0 @@ -# The XRP Ledger Servers - -Placeholder for XRPL servers documentation. \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/tokens/authorized-trust-lines.md b/content/concepts/understanding-xrpl/tokens/authorized-trust-lines.md deleted file mode 100644 index f6f5ed0bf6..0000000000 --- a/content/concepts/understanding-xrpl/tokens/authorized-trust-lines.md +++ /dev/null @@ -1,124 +0,0 @@ -# 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 - - -### 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" - } - } - ] -} -``` - - -## 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 - } - } - ] -} -``` - - -## 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. - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/tokens/common-misunderstandings-about-freezes.md b/content/concepts/understanding-xrpl/tokens/common-misunderstandings-about-freezes.md deleted file mode 100644 index 0b858c5f2f..0000000000 --- a/content/concepts/understanding-xrpl/tokens/common-misunderstandings-about-freezes.md +++ /dev/null @@ -1,26 +0,0 @@ -# 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. \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/tokens/freezing-tokens.md b/content/concepts/understanding-xrpl/tokens/freezing-tokens.md deleted file mode 100644 index 0961be831b..0000000000 --- a/content/concepts/understanding-xrpl/tokens/freezing-tokens.md +++ /dev/null @@ -1,93 +0,0 @@ -# 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. - - - diff --git a/content/concepts/understanding-xrpl/tokens/fungible.md b/content/concepts/understanding-xrpl/tokens/fungible.md deleted file mode 100644 index 0583b59daa..0000000000 --- a/content/concepts/understanding-xrpl/tokens/fungible.md +++ /dev/null @@ -1,3 +0,0 @@ -# Fungible Tokens - -Fungible tokens topic placeholder. \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/tokens/nftoken-batch-minting.md b/content/concepts/understanding-xrpl/tokens/nftoken-batch-minting.md deleted file mode 100644 index 5fd51190db..0000000000 --- a/content/concepts/understanding-xrpl/tokens/nftoken-batch-minting.md +++ /dev/null @@ -1,31 +0,0 @@ -# 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. \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/tokens/non-fungible-token-transfers.md b/content/concepts/understanding-xrpl/tokens/non-fungible-token-transfers.md deleted file mode 100644 index 77e75977d7..0000000000 --- a/content/concepts/understanding-xrpl/tokens/non-fungible-token-transfers.md +++ /dev/null @@ -1,69 +0,0 @@ -# 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`. - - -![Brokered Mode with Reserve](../../../img/nft-brokered-mode-with-reserve.png) - - -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`. - - -![Brokered Mode without Reserve](../../../img/nft-brokered-mode-without-reserve.png) - - -The same workflows can be used when an owner resells a `NFToken` created by another account. \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/tokens/non-fungible.md b/content/concepts/understanding-xrpl/tokens/non-fungible.md deleted file mode 100644 index c81d4b82ab..0000000000 --- a/content/concepts/understanding-xrpl/tokens/non-fungible.md +++ /dev/null @@ -1,68 +0,0 @@ -# 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. - -![Jenny Stamps](../../../img/nft-concepts1.png "Jenny Stamps") - -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. - -![Jenny Stamps](../../../img/nft-concepts2.png "Jenny Stamps") - -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. - -![The NFT Lifecycle](../../../img/nft-lifecycle.png "NFT Lifecycle Image") - - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/tokens/paths.md b/content/concepts/understanding-xrpl/tokens/paths.md deleted file mode 100644 index 3c9f3d8898..0000000000 --- a/content/concepts/understanding-xrpl/tokens/paths.md +++ /dev/null @@ -1,108 +0,0 @@ -# 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.) - -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. | - - diff --git a/content/concepts/understanding-xrpl/tokens/rippling.md b/content/concepts/understanding-xrpl/tokens/rippling.md deleted file mode 100644 index 14ca7dccf0..0000000000 --- a/content/concepts/understanding-xrpl/tokens/rippling.md +++ /dev/null @@ -1,100 +0,0 @@ -# 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. - - - -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'. - - -## Using No Ripple - - -### 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. - - - - -## 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. - -Be sure to research the relevant regulations before engaging in any financial service business. diff --git a/content/concepts/understanding-xrpl/tokens/tokens.md b/content/concepts/understanding-xrpl/tokens/tokens.md deleted file mode 100644 index 2c902a4729..0000000000 --- a/content/concepts/understanding-xrpl/tokens/tokens.md +++ /dev/null @@ -1,54 +0,0 @@ -# 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. - - - -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.) - - - - -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 × 1080) and very small values (down to 1.0 × 10-81). - -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.) - - - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/tokens/transfer-fees.md b/content/concepts/understanding-xrpl/tokens/transfer-fees.md deleted file mode 100644 index ba4f86a578..0000000000 --- a/content/concepts/understanding-xrpl/tokens/transfer-fees.md +++ /dev/null @@ -1,76 +0,0 @@ -# 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 - - - -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. - - - -# 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) diff --git a/content/concepts/understanding-xrpl/transactions/about-canceling-a-transaction.md b/content/concepts/understanding-xrpl/transactions/about-canceling-a-transaction.md deleted file mode 100644 index 56bdd8c97c..0000000000 --- a/content/concepts/understanding-xrpl/transactions/about-canceling-a-transaction.md +++ /dev/null @@ -1,17 +0,0 @@ -# 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. - - - -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. diff --git a/content/concepts/understanding-xrpl/transactions/finality-of-results.md b/content/concepts/understanding-xrpl/transactions/finality-of-results.md deleted file mode 100644 index ba64890b72..0000000000 --- a/content/concepts/understanding-xrpl/transactions/finality-of-results.md +++ /dev/null @@ -1,58 +0,0 @@ -# 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. - - - - - 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. - - - - - - If a [cross-currency payment](./payments/cross-currency-payments.md) succeeds by consuming an 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. - - - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/transactions/multi-signing.md b/content/concepts/understanding-xrpl/transactions/multi-signing.md deleted file mode 100644 index 97f60cdb93..0000000000 --- a/content/concepts/understanding-xrpl/transactions/multi-signing.md +++ /dev/null @@ -1,79 +0,0 @@ -# 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 216-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.* The transaction must include the `SigningPubKey` field as an empty string. -* The transaction must include a `Signers` field containing an array of signatures.* The signatures present in the `Signers` array must match signers defined in the SignerList. -* For the provided signatures, the total weight associated with those signers must be equal or greater than the quorum for the SignerList. -* The [transaction cost](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. -* 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.) - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/transactions/payments/checks.md b/content/concepts/understanding-xrpl/transactions/payments/checks.md deleted file mode 100644 index b8d712afb3..0000000000 --- a/content/concepts/understanding-xrpl/transactions/payments/checks.md +++ /dev/null @@ -1,108 +0,0 @@ -# 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. - - - - -## 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. - - - -**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. - - - -[![Check flow diagram (successful cashing)](../../../../img/checks-happy-path.png)](../../../../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. - - - -[![Check flow diagram (expiration)](../../../../img/checks-expiration.png)](../../../../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. - - - - -## 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. - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/transactions/payments/cross-currency-payments.md b/content/concepts/understanding-xrpl/transactions/payments/cross-currency-payments.md deleted file mode 100644 index c5a796ed04..0000000000 --- a/content/concepts/understanding-xrpl/transactions/payments/cross-currency-payments.md +++ /dev/null @@ -1,34 +0,0 @@ -# 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. - - - - -## 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. - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/transactions/payments/direct-xrp-payments.md b/content/concepts/understanding-xrpl/transactions/payments/direct-xrp-payments.md deleted file mode 100644 index 6f8a44f731..0000000000 --- a/content/concepts/understanding-xrpl/transactions/payments/direct-xrp-payments.md +++ /dev/null @@ -1,85 +0,0 @@ -# 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. - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/transactions/payments/escrow.md b/content/concepts/understanding-xrpl/transactions/payments/escrow.md deleted file mode 100644 index f8570b5e33..0000000000 --- a/content/concepts/understanding-xrpl/transactions/payments/escrow.md +++ /dev/null @@ -1,145 +0,0 @@ -# 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 - - - -[![Escrow Flow Diagram (Successful finish)](../../../../img/escrow-success-flow.png)](../../../../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 - -[![Escrow Flow Diagram (Expired escrow)](../../../../img/escrow-cancel-flow.png)](../../../../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. - - - - -## 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: - -[![State diagram showing escrows going from Held → Ready/Conditionally Ready → Expired](../../../../img/escrow-states.png)](../../../../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. - - - -**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. - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/transactions/payments/partial-payments.md b/content/concepts/understanding-xrpl/transactions/payments/partial-payments.md deleted file mode 100644 index b0ceed061d..0000000000 --- a/content/concepts/understanding-xrpl/transactions/payments/partial-payments.md +++ /dev/null @@ -1,131 +0,0 @@ -# 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. - - - - -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. - - - -### 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. - - - -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 - - - - -## 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. - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/transactions/payments/payment-channels.md b/content/concepts/understanding-xrpl/transactions/payments/payment-channels.md deleted file mode 100644 index 5456909cb1..0000000000 --- a/content/concepts/understanding-xrpl/transactions/payments/payment-channels.md +++ /dev/null @@ -1,43 +0,0 @@ -# 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") }} - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/transactions/payments/payment-types.md b/content/concepts/understanding-xrpl/transactions/payments/payment-types.md deleted file mode 100644 index eff48258a6..0000000000 --- a/content/concepts/understanding-xrpl/transactions/payments/payment-types.md +++ /dev/null @@ -1,26 +0,0 @@ -# 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. \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/transactions/source-and-destination-tags.md b/content/concepts/understanding-xrpl/transactions/source-and-destination-tags.md deleted file mode 100644 index d38a045498..0000000000 --- a/content/concepts/understanding-xrpl/transactions/source-and-destination-tags.md +++ /dev/null @@ -1,47 +0,0 @@ -# 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. - - - -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. - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/transactions/tickets.md b/content/concepts/understanding-xrpl/transactions/tickets.md deleted file mode 100644 index 17d5c1d972..0000000000 --- a/content/concepts/understanding-xrpl/transactions/tickets.md +++ /dev/null @@ -1,65 +0,0 @@ -# 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. -- 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. - - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/transactions/transaction-cost.md b/content/concepts/understanding-xrpl/transactions/transaction-cost.md deleted file mode 100644 index 08e9ed1383..0000000000 --- a/content/concepts/understanding-xrpl/transactions/transaction-cost.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -html: transaction-cost.html -parent: transactions.html -blurb: Every transaction costs a small amount of XRP for purely practical reasons. -labels: - - 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](../../../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. - - -## Current Transaction Cost - -The current minimum transaction cost required by the network for a standard transaction is **0.00001 XRP** (10 drops). It sometimes increases due to higher than usual load. - -You can also [query `rippled` for the current transaction cost](#querying-the-transaction-cost). - -### Special Transaction Costs - -Some transactions have different transaction costs: - -| Transaction | Cost Before Load Scaling | -|-----------------------|--------------------------| -| [Reference Transaction](#reference-transaction-cost) (Most transactions) | 10 drops | -| [Key Reset Transaction](#key-reset-transaction) | 0 | -| [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 | - - - -## Beneficiaries of the Transaction Cost - -The transaction cost is not paid to any party: the XRP is irrevocably destroyed. - -## Load Cost and Open Ledger Cost - -When the `FeeEscalation` amendment is enabled, there are two thresholds for the transaction cost: - -* If the transaction cost does not meet a `rippled` server's [load-based transaction cost threshold](#local-load-cost), the server ignores the transaction completely. (This logic is essentially unchanged with or without the amendment.) -* If the transaction cost does not meet a `rippled` server's [open ledger cost threshold](#open-ledger-cost), the server queues the transaction for a later ledger. - -This divides transactions into roughly three categories: - -* Transactions that specify a transaction cost so low that they get rejected by the load-based transaction cost. -* Transactions that specify a transaction cost high enough to be included in the current open ledger. -* Transactions in between, which get [queued for a later ledger version](#queued-transactions). - - -## Local Load Cost - -Each `rippled` server maintains a cost threshold based on its current load. If you submit a transaction with a `Fee` value that is lower than current load-based transaction cost of the `rippled` server, that server neither applies nor relays the transaction. (**Note:** If you submit a transaction through an admin connection, 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. - - - - -## Open Ledger Cost - -The `rippled` server has a second mechanism for enforcing the transaction cost, called the _open ledger cost_. A transaction can only be included in the open ledger if it meets the open ledger cost requirement in XRP. Transactions that do not meet the open ledger cost may be [queued for a following ledger](#queued-transactions) instead. - -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.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). - -### Queued Transactions - -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](../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.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 - -_Fee levels_ represent the proportional difference between the minimum cost and the actual cost of a transaction. The [Open Ledger Cost](#open-ledger-cost) is measured in fee levels instead of absolute cost. See the following table for a comparison: - -| Transaction | Minimum cost in drops | Minimum cost in Fee levels | Double cost in drops | Double cost in fee levels | -|-------------|-----------------------|----------------------------|----------------------|---------------------------| -| Reference transaction (most transactions) | 10 | 256 | 20 | 512 | -| [Multi-signed transaction](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 | - - - -## 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). - -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: - -**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. 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`** - - - -## Specifying the Transaction Cost - -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). - -Before signing a transaction, we recommend [looking up the current load-based transaction cost](#querying-the-transaction-cost). If the transaction cost is high due to load scaling, you may want to wait for it to decrease. If you do not plan on submitting the transaction immediately, we recommend specifying a slightly higher transaction cost to account for future load-based fluctuations in the transaction cost. - - -### Automatically Specifying the Transaction Cost - -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.md) by reusing the same `Sequence` number. - - - -- 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. - - 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/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.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.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` 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 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. - -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](../xrpl/fee-voting.md) for more information. - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/transactions/transaction-history.md b/content/concepts/understanding-xrpl/transactions/transaction-history.md deleted file mode 100644 index e2722b42c2..0000000000 --- a/content/concepts/understanding-xrpl/transactions/transaction-history.md +++ /dev/null @@ -1,17 +0,0 @@ -# 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. diff --git a/content/concepts/understanding-xrpl/transactions/transaction-malleability.md b/content/concepts/understanding-xrpl/transactions/transaction-malleability.md deleted file mode 100644 index e25bbaa64f..0000000000 --- a/content/concepts/understanding-xrpl/transactions/transaction-malleability.md +++ /dev/null @@ -1,141 +0,0 @@ -# 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. - -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. - -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.) - - - -## Background - -In the XRP Ledger, a transaction cannot execute unless: - -- 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. - -Since the signature is among the data used to compute a transaction's identifying hash, any changes to a malleable transaction result in a different hash. - -### Alternate secp256k1 Signatures - -To be "canonical", signatures created with the ECDSA algorithm and secp256k1 curve (the default) must meet the following requirements: - -- The signature must be properly [DER-encoded data](https://en.wikipedia.org/wiki/X.690#DER_encoding). -- The signature must not have any padding bytes outside the DER-encoded data. -- The signature's component integers must not be negative, and they must not be larger than the secp256k1 group order. - -Generally speaking, any standard ECDSA implementation handles these requirements automatically. However, with secp256k1, those requirements are insufficient to prevent malleability. Thus, the XRP Ledger has a concept of "fully canonical" signatures which do not have the same problem. - -An ECDSA signature consists of two integers, called R and S. The secp256k1 _group order_, called N, is a constant value for all secp256k1 signatures. Specifically, N is the value `0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141`. For any given signature `(R,S)`, the signature `(R, N-S)` (that is, using N minus S in place of S) is also valid. - -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. - -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 - -An important, explicit feature of multi-signing is that multiple different possible configurations can make a transaction valid. For example, an account can be configured so that signatures from any three of five signers could authorize a transaction. However, this inherently means that there can be several different variations of a valid transaction, each with a different identifying hash. - -All of the following cases can lead to transaction malleability: - -- If a transaction still has enough signatures to meet its quorum after removing one or more. Any third party could remove a signature and re-submit the transaction without it. -- If one can add a valid signature to a transaction that already has a quorum. Only an authorized signer of the sending account could create such a signature. -- If one can replace one signature from a transaction with another valid signature while maintaining a quorum. Only an authorized signer of the sending account could create such a signature. - -Even if your authorized signers are not intentionally malicious, confusion or poor coordination could cause several signers to submit different valid versions of the same transaction. - -#### Mitigations for Multi-Signature Malleability - -**Good operational security can protect against these problems.** Generally, you can avoid transaction malleability problems when multi-signing if you follow good operational security practices, including the following: - -- 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.) -- 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. - -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 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 might be vulnerable if you or your signers provide more signatures than necessary. - -### Exploit Scenario Steps - -The process to exploit a vulnerable system follows a series of steps like the following: - -1. The vulnerable system constructs a multi-signed transaction and collects more than the necessary number of signatures. - - If an authorized signer is malicious or irresponsible, the transaction could also be vulnerable if that signer's signature is not included but could be added. - -2. The system notes the identifying hash of the vulnerable transaction, submits it to the XRP Ledger network, then begins monitoring for that hash to be included in a validated ledger version. - -3. A malicious actor sees the transaction propagating through the network before it becomes confirmed. - -4. The malicious actor removes an extra signature from the vulnerable transaction. - - Unlike creating a signature for different transaction instructions, this does not require a large amount of computational work. It can be done in much less time than it takes to generate a signature in the first place. - - Alternatively, an authorized signer whose signature is not already part of the transaction could add their signature to the vulnerable transaction's list of signatures. Depending on the sender's multi-signing settings, this can be instead of or in addition to removing other signatures from the transaction. - - The modified list of signatures results in a different identifying hash. (You do not have to calculate the hash before you submit to the network, but knowing the hash makes it easier to check the transaction's status later.) - -5. The malicious actor submits the modified transaction to the network. - - This creates a "race" between the transaction as originally submitted and the modified version submitted by the malicious actor. The two transactions are mutually exclusive. Both are valid, but they have the same exact transaction data, including the `Sequence` number, so at most one of them can ever be included in a validated ledger. - - Servers in the peer-to-peer network have no way of knowing which one "came first" or was intended by its original sender. Delays or other coincidences in network connectivity could result in validators seeing only one or the other by the time they finalize their consensus proposals, so either one could "win the race". - - A malicious actor could increase the chances of getting non-canonical transactions confirmed if they controlled some number of well-connected servers in the peer-to-peer network, even if those servers are not trusted as validators. - - If the malicious actor controls the only server to which the vulnerable system submitted the transaction, the malicious actor can easily control which version is distributed to the rest of the network. - -6. The malicious actor's version of the transaction achieves consensus and becomes included in a validated ledger. - - At this point, the transaction has executed and cannot be reversed. Its effects (such as sending XRP) are final. The original version of the transaction is no longer valid because its `Sequence` number has been used. - - The effects of the transaction in the XRP Ledger are exactly the same as if the original version had executed. - -7. The vulnerable system does not see the transaction hash it is expecting, and erroneously concludes that the transaction did not execute. - - 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. - - - -8. The vulnerable system takes action assuming that the transaction has failed. - - For example, it may refund (or not debit) a customer's balance in its own system, to account for the funds that it thinks have not been sent in the XRP Ledger. - - 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. - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/transactions/transaction-metadata-concept.md b/content/concepts/understanding-xrpl/transactions/transaction-metadata-concept.md deleted file mode 100644 index 36d3aaa888..0000000000 --- a/content/concepts/understanding-xrpl/transactions/transaction-metadata-concept.md +++ /dev/null @@ -1,1574 +0,0 @@ ---- -html: transaction-metadata-concept.html -parent: transactions.html -blurb: Transaction metadata is a section of data that is added to a transaction after it is processed. -labels: - - Ledgers ---- -# Transaction Metadata - -Transaction metadata is a section of data that gets added to a transaction after it is processed. Any transaction that gets included in a ledger has metadata, regardless of whether it is successful. The transaction metadata describes the outcome of the transaction in detail. - -The changes described in transaction metadata are only final if the transaction is in a validated ledger version. - -Some fields that might appear in transaction metadata include: - -| Field | Value | Description | -|:----------------------------------------|:--------------------|:-------------| -| `AffectedNodes` | Array | List of ledger objects that were created, deleted, or modified by this transaction, and specific changes to each. | -| `DeliveredAmount` | Currency Amount | _(May be omitted)_ For a [partial payment](payments/partial-payments.md), this field records the amount of currency actually delivered to the destination. To avoid errors when reading transactions, instead use the `delivered_amount` field, which is provided for all Payment transactions, partial or not. | -| `TransactionIndex` | Unsigned Integer | The transaction's position within the ledger that included it. This is zero-indexed. (For example, the value `2` means it was the 3rd transaction in that ledger.) | -| `TransactionResult` | String | A [result code](transaction-results.html) indicating whether the transaction succeeded or how it failed. | -| [`delivered_amount`](transaction-metadata.html#delivered_amount) | Currency Amount | _(Omitted for non-Payment transactions)_ The Currency Amount actually received by the `Destination` account. Use this field to determine how much was delivered, regardless of whether the transaction is a [partial payment](payments/partial-payments.md). See [this description](transaction-metadata.md#delivered_amount) for details. | - -## Example Metadata - -The following JSON object shows the metadata for [a complex cross-currency payment](https://xrpcharts.ripple.com/#/transactions/8C55AFC2A2AA42B5CE624AEECDB3ACFDD1E5379D4E5BF74A8460C5E97EF8706B): - -```json -{ - "AffectedNodes": [ - { - "ModifiedNode": { - "FinalFields": { - "Account": "r9ZoLsJHzMMJLpvsViWQ4Jgx17N8cz1997", - "Balance": "77349986", - "Flags": 0, - "OwnerCount": 2, - "Sequence": 9 - }, - "LedgerEntryType": "AccountRoot", - "LedgerIndex": "1E7E658C2D3DF91EFAE5A12573284AD6F526B8F64DD12F013C6F889EF45BEA97", - "PreviousFields": { - "OwnerCount": 3 - }, - "PreviousTxnID": "55C11248ACEFC2EFD59755BF88867783AC18EA078517108F942069C2FBE4CF5C", - "PreviousTxnLgrSeq": 35707468 - } - }, - { - "ModifiedNode": { - "FinalFields": { - "Balance": { - "currency": "USD", - "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji", - "value": "2298.927882138068" - }, - "Flags": 1114112, - "HighLimit": { - "currency": "USD", - "issuer": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun", - "value": "0" - }, - "HighNode": "000000000000006B", - "LowLimit": { - "currency": "USD", - "issuer": "rpvvAvaZ7TXHkNLM8UJwCTU6yBU2jDTJ1P", - "value": "1000000000" - }, - "LowNode": "0000000000000007" - }, - "LedgerEntryType": "RippleState", - "LedgerIndex": "220DDA7164F3F41F3C5223FA3125D4CD368EBB4FB954B5FBFFB6D1EA6DACDD5E", - "PreviousFields": { - "Balance": { - "currency": "USD", - "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji", - "value": "2297.927882138068" - } - }, - "PreviousTxnID": "1DB2F9C67C3F42F7B8AB02BA2264254A78A201EC8A9974A1CACEFD51545B1263", - "PreviousTxnLgrSeq": 43081739 - } - }, - { - "ModifiedNode": { - "FinalFields": { - "Balance": { - "currency": "USD", - "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji", - "value": "33403.80553244443" - }, - "Flags": 1114112, - "HighLimit": { - "currency": "USD", - "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq", - "value": "0" - }, - "HighNode": "0000000000001A40", - "LowLimit": { - "currency": "USD", - "issuer": "rd5Sx93pCMgfxwBuofjen2csoFYmY8VrT", - "value": "1000000000" - }, - "LowNode": "0000000000000000" - }, - "LedgerEntryType": "RippleState", - "LedgerIndex": "38569918AF54B520463CFDDD00EB5ADD8768039BD94E61A5E25C387EA4FDC9A3", - "PreviousFields": { - "Balance": { - "currency": "USD", - "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji", - "value": "33402.80752845242" - } - }, - "PreviousTxnID": "38A0E82ADC2DA6C6D59929B73E9812CD1E1384E452FD23D0717EA0037E2FC9E3", - "PreviousTxnLgrSeq": 43251694 - } - }, - { - "ModifiedNode": { - "FinalFields": { - "Account": "rBndiPPKs9k5rjBb7HsEiqXKrz8AfUnqWq", - "BookDirectory": "4627DFFCFF8B5A265EDBD8AE8C14A52325DBFEDAF4F5C32E5B09B13AC59DBA5E", - "BookNode": "0000000000000000", - "Flags": 0, - "OwnerNode": "0000000000000000", - "Sequence": 407556, - "TakerGets": { - "currency": "USD", - "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B", - "value": "75.1379833998197" - }, - "TakerPays": "204986996" - }, - "LedgerEntryType": "Offer", - "LedgerIndex": "557BDD35E40EAFFE0AC98108A0F4AC4BB812A168CFD5B4E35475F42A60ABD9C8", - "PreviousFields": { - "TakerGets": { - "currency": "USD", - "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B", - "value": "76.1399833998197" - }, - "TakerPays": "207720593" - }, - "PreviousTxnID": "961C575073788979815F103D065CEE449D2EA6EFE8FC8C33C26EC08586925D90", - "PreviousTxnLgrSeq": 43251680 - } - }, - { - "ModifiedNode": { - "FinalFields": { - "Account": "r9KG7Du7aFmABzMvDnwuvPaEoMu4Eurwok", - "Balance": "8080207629", - "Flags": 0, - "OwnerCount": 6, - "Sequence": 1578765 - }, - "LedgerEntryType": "AccountRoot", - "LedgerIndex": "5A667CB5FBAB4143EDEFBD6EDDD4B6D19C905209C8EE16486D5D7CD6CB083E78", - "PreviousFields": { - "Balance": "8080152531", - "Sequence": 1578764 - }, - "PreviousTxnID": "E3CDFD288620871455634DC1E56439136AACA1DDBCE987BE12F97486AB477375", - "PreviousTxnLgrSeq": 43251694 - } - }, - { - "DeletedNode": { - "FinalFields": { - "Account": "r9ZoLsJHzMMJLpvsViWQ4Jgx17N8cz1997", - "BookDirectory": "A6D5D1C1CC92D56FDDFD4434FB10BD31F63EB991DA3C756653071AFD498D0000", - "BookNode": "0000000000000000", - "Flags": 0, - "OwnerNode": "0000000000000000", - "PreviousTxnID": "DB028A461E98B0398CAD65F2871B381A6D0B9A21662CA5B033438D83C518C0F2", - "PreviousTxnLgrSeq": 35686129, - "Sequence": 7, - "TakerGets": { - "currency": "EUR", - "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq", - "value": "2.5" - }, - "TakerPays": { - "currency": "ETH", - "issuer": "rcA8X3TVMST1n3CJeAdGk1RdRCHii7N2h", - "value": "0.05" - } - }, - "LedgerEntryType": "Offer", - "LedgerIndex": "6AA7E5121FEB456F0A899E3D6F25D62ABB408BB67B91C9270E13714401ED72B5" - } - }, - { - "ModifiedNode": { - "FinalFields": { - "Account": "rd5Sx93pCMgfxwBuofjen2csoFYmY8VrT", - "Balance": "8251028196", - "Flags": 0, - "OwnerCount": 4, - "Sequence": 274 - }, - "LedgerEntryType": "AccountRoot", - "LedgerIndex": "6F830A1B38F827CD4BEC946A40F1E2DF726FC22AFC3918FD621567AF17F49F3A", - "PreviousFields": { - "Balance": "8253816902" - }, - "PreviousTxnID": "38A0E82ADC2DA6C6D59929B73E9812CD1E1384E452FD23D0717EA0037E2FC9E3", - "PreviousTxnLgrSeq": 43251694 - } - }, - { - "ModifiedNode": { - "FinalFields": { - "Account": "rd5Sx93pCMgfxwBuofjen2csoFYmY8VrT", - "BookDirectory": "79C54A4EBD69AB2EADCE313042F36092BE432423CC6A4F784E0CB6D74F25A336", - "BookNode": "0000000000000000", - "Flags": 0, - "OwnerNode": "0000000000000000", - "Sequence": 273, - "TakerGets": "8246341599", - "TakerPays": { - "currency": "USD", - "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq", - "value": "2951.147613535471" - } - }, - "LedgerEntryType": "Offer", - "LedgerIndex": "7FD1EAAE17B7D68AE640FFC56CECC3999B4F938EFFF6EA6887B6CC8BD9DBDC63", - "PreviousFields": { - "TakerGets": "8249130305", - "TakerPays": { - "currency": "USD", - "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq", - "value": "2952.145617527486" - } - }, - "PreviousTxnID": "38A0E82ADC2DA6C6D59929B73E9812CD1E1384E452FD23D0717EA0037E2FC9E3", - "PreviousTxnLgrSeq": 43251694 - } - }, - { - "ModifiedNode": { - "FinalFields": { - "Balance": { - "currency": "USD", - "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji", - "value": "-11.68225001668339" - }, - "Flags": 131072, - "HighLimit": { - "currency": "USD", - "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59", - "value": "5000" - }, - "HighNode": "0000000000000000", - "LowLimit": { - "currency": "USD", - "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B", - "value": "0" - }, - "LowNode": "000000000000004A" - }, - "LedgerEntryType": "RippleState", - "LedgerIndex": "826CF5BFD28F3934B518D0BDF3231259CBD3FD0946E3C3CA0C97D2C75D2D1A09", - "PreviousFields": { - "Balance": { - "currency": "USD", - "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji", - "value": "-10.68225001668339" - } - }, - "PreviousTxnID": "28B271F7C27C1A267F32FFCD8B1795C5D3B1DC761AD705E3A480139AA8B61B09", - "PreviousTxnLgrSeq": 43237130 - } - }, - { - "ModifiedNode": { - "FinalFields": { - "Account": "rBndiPPKs9k5rjBb7HsEiqXKrz8AfUnqWq", - "Balance": "8276201534", - "Flags": 0, - "OwnerCount": 5, - "Sequence": 407558 - }, - "LedgerEntryType": "AccountRoot", - "LedgerIndex": "880C6FB7B9C0083211F950E4449AD45895C0EC1114B5112CE1320AC7275E3237", - "PreviousFields": { - "Balance": "8273467937" - }, - "PreviousTxnID": "CB4B54942F11510A47D2731C3260429093F24016B366CBF15D8EC4B705372F02", - "PreviousTxnLgrSeq": 43251683 - } - }, - { - "ModifiedNode": { - "FinalFields": { - "Balance": { - "currency": "USD", - "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji", - "value": "-6557.745685633666" - }, - "Flags": 2228224, - "HighLimit": { - "currency": "USD", - "issuer": "rBndiPPKs9k5rjBb7HsEiqXKrz8AfUnqWq", - "value": "1000000000" - }, - "HighNode": "0000000000000000", - "LowLimit": { - "currency": "USD", - "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B", - "value": "0" - }, - "LowNode": "0000000000000512" - }, - "LedgerEntryType": "RippleState", - "LedgerIndex": "8A9FEE5192E334195314B5C162BC78F7452ADB14E06839D48943BAE05EE1967F", - "PreviousFields": { - "Balance": { - "currency": "USD", - "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji", - "value": "-6558.747685633666" - } - }, - "PreviousTxnID": "961C575073788979815F103D065CEE449D2EA6EFE8FC8C33C26EC08586925D90", - "PreviousTxnLgrSeq": 43251680 - } - }, - { - "ModifiedNode": { - "FinalFields": { - "Balance": { - "currency": "GCB", - "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji", - "value": "9990651675.348776" - }, - "Flags": 3211264, - "HighLimit": { - "currency": "GCB", - "issuer": "rHaans8PtgwbacHvXAL3u6TG28gTAtCwr8", - "value": "0" - }, - "HighNode": "0000000000000000", - "LowLimit": { - "currency": "GCB", - "issuer": "r9KG7Du7aFmABzMvDnwuvPaEoMu4Eurwok", - "value": "10000000000" - }, - "LowNode": "0000000000000000" - }, - "LedgerEntryType": "RippleState", - "LedgerIndex": "A2B41EE7818A5756B6A2276BDBB3CE0ED3A3B350787FD6B76E5EA1354A8F20D2", - "PreviousFields": { - "Balance": { - "currency": "GCB", - "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji", - "value": "9990651678.137482" - } - }, - "PreviousTxnID": "961C575073788979815F103D065CEE449D2EA6EFE8FC8C33C26EC08586925D90", - "PreviousTxnLgrSeq": 43251680 - } - }, - { - "DeletedNode": { - "FinalFields": { - "ExchangeRate": "53071AFD498D0000", - "Flags": 0, - "RootIndex": "A6D5D1C1CC92D56FDDFD4434FB10BD31F63EB991DA3C756653071AFD498D0000", - "TakerGetsCurrency": "0000000000000000000000004555520000000000", - "TakerGetsIssuer": "2ADB0B3959D60A6E6991F729E1918B7163925230", - "TakerPaysCurrency": "0000000000000000000000004554480000000000", - "TakerPaysIssuer": "06CC4A6D023E68AA3499C6DE3E9F2DC52B8BA254" - }, - "LedgerEntryType": "DirectoryNode", - "LedgerIndex": "A6D5D1C1CC92D56FDDFD4434FB10BD31F63EB991DA3C756653071AFD498D0000" - } - }, - { - "ModifiedNode": { - "FinalFields": { - "Flags": 0, - "Owner": "r9ZoLsJHzMMJLpvsViWQ4Jgx17N8cz1997", - "RootIndex": "A83C1B192A27582EDB320EBD7A3FE58D7042CE04B67A2B3D87FDD63D871E12D7" - }, - "LedgerEntryType": "DirectoryNode", - "LedgerIndex": "A83C1B192A27582EDB320EBD7A3FE58D7042CE04B67A2B3D87FDD63D871E12D7" - } - }, - { - "ModifiedNode": { - "FinalFields": { - "Balance": { - "currency": "USD", - "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji", - "value": "0" - }, - "Flags": 65536, - "HighLimit": { - "currency": "USD", - "issuer": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun", - "value": "0" - }, - "HighNode": "0000000000000002", - "LowLimit": { - "currency": "USD", - "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59", - "value": "1" - }, - "LowNode": "0000000000000000" - }, - "LedgerEntryType": "RippleState", - "LedgerIndex": "C493ABA2619D0FC6355BA862BC8312DF8266FBE76AFBA9636E857F7EAC874A99", - "PreviousFields": { - "Balance": { - "currency": "USD", - "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji", - "value": "1" - } - }, - "PreviousTxnID": "28B271F7C27C1A267F32FFCD8B1795C5D3B1DC761AD705E3A480139AA8B61B09", - "PreviousTxnLgrSeq": 43237130 - } - }, - { - "ModifiedNode": { - "FinalFields": { - "Account": "r9KG7Du7aFmABzMvDnwuvPaEoMu4Eurwok", - "BookDirectory": "E6E8A9842EA2ED1FD5D0599343692CE1EBF977AEA751B7DC5B038D7EA4C68000", - "BookNode": "0000000000000000", - "Flags": 65536, - "OwnerNode": "0000000000000000", - "Sequence": 39018, - "TakerGets": { - "currency": "GCB", - "issuer": "rHaans8PtgwbacHvXAL3u6TG28gTAtCwr8", - "value": "9990651675.348776" - }, - "TakerPays": "9990651675348776" - }, - "LedgerEntryType": "Offer", - "LedgerIndex": "C939B9B2C5803DD6D89B792E72470F79CBE9F9E999691789E0B68C3808BDDD8E", - "PreviousFields": { - "TakerGets": { - "currency": "GCB", - "issuer": "rHaans8PtgwbacHvXAL3u6TG28gTAtCwr8", - "value": "9990651678.137482" - }, - "TakerPays": "9990651678137482" - }, - "PreviousTxnID": "961C575073788979815F103D065CEE449D2EA6EFE8FC8C33C26EC08586925D90", - "PreviousTxnLgrSeq": 43251680 - } - }, - { - "ModifiedNode": { - "FinalFields": { - "Balance": { - "currency": "USD", - "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji", - "value": "2963.413395452545" - }, - "Flags": 65536, - "HighLimit": { - "currency": "USD", - "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq", - "value": "0" - }, - "HighNode": "0000000000001A97", - "LowLimit": { - "currency": "USD", - "issuer": "rpvvAvaZ7TXHkNLM8UJwCTU6yBU2jDTJ1P", - "value": "0" - }, - "LowNode": "0000000000000007" - }, - "LedgerEntryType": "RippleState", - "LedgerIndex": "E4D1FBD5CB72A1D3EE38C21F3BCB13E454FCB469CD01C1366E0008A031E6A7FC", - "PreviousFields": { - "Balance": { - "currency": "USD", - "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji", - "value": "2964.413395452545" - } - }, - "PreviousTxnID": "1DB2F9C67C3F42F7B8AB02BA2264254A78A201EC8A9974A1CACEFD51545B1263", - "PreviousTxnLgrSeq": 43081739 - } - } - ], - "DeliveredAmount": { - "currency": "GCB", - "issuer": "rHaans8PtgwbacHvXAL3u6TG28gTAtCwr8", - "value": "2.788706" - }, - "TransactionIndex": 38, - "TransactionResult": "tesSUCCESS", - "delivered_amount": { - "currency": "GCB", - "issuer": "rHaans8PtgwbacHvXAL3u6TG28gTAtCwr8", - "value": "2.788706" - } -} -``` - -## AffectedNodes - -The `AffectedNodes` array contains a complete list of the [objects in the ledger][] that this transaction modified in some way. Each entry in this array is an object with one top-level field indicating what type it is: - -- `CreatedNode` indicates that the transaction created a new object in the ledger. -- `DeletedNode` indicates that the transaction removed an object from the ledger. -- `ModifiedNode` indicates that the transaction modified an existing object in the ledger. - -The value of each of these fields is a JSON object describing the changes made to the ledger object. - -### CreatedNode Fields - -A `CreatedNode` object contains the following fields: - -| Field | Value | Description | -|:------------------|:------------------|:-------------------------------------| -| `LedgerEntryType` | String | The type of [ledger object](../../../references/protocol-reference/ledger-data/ledger-object-types/ledger-object-types.md) that was created. | -| `LedgerIndex` | String - Hash | The [ID of this ledger object](../../../references/protocol-reference/ledger-data/ledger-object-ids.md) in the ledger's [state tree](../xrpl/ledgers.md). **Note:** This is _not__ the same as a [ledger index](../../../references/protocol-reference/data-types/basic-data-types.md#ledger-index), even though the field name is very similar. | -| `NewFields` | Object | The content fields of the newly-created ledger object. Which fields are present depends on what type of ledger object was created. | - -### DeletedNode Fields - -A `DeletedNode` object contains the following fields: - -| Field | Value | Description | -|:------------------|:------------------|:-------------------------------------| -| `LedgerEntryType` | String | The [type of ledger object][] that was deleted. | -| `LedgerIndex` | String - [Hash][] | The [ID of this ledger object](../../../references/protocol-reference/ledger-data/ledger-object-ids.md) in the ledger's [state tree](ledgers.html). **Note:** This is **not the same** as a [ledger index](../../../references/protocol-reference/data-types/basic-data-types.md#ledger-index), even though the field name is very similar. | -| `FinalFields` | Object | The content fields of the ledger object immediately before it was deleted. Which fields are present depends on what type of ledger object was created. | - -### ModifiedNode Fields - -A `ModifiedNode` object contains the following fields: - -| Field | Value | Description | -|:--------------------|:--------------------------|:---------------------------| -| `LedgerEntryType` | String | The [type of ledger object](../../../references/protocol-reference/ledger-data/ledger-object-types/ledger-object-types.md) that was deleted. | -| `LedgerIndex` | String - Hash | The [ID of this ledger object](../../../references/protocol-reference/ledger-data/ledger-object-ids.md) in the ledger's [state tree](../xrpl/ledgers.md). **Note:** This is **not the same** as a [ledger index](../../../references/protocol-reference/data-types/basic-data-types.md#ledger-index), even though the field name is very similar. | -| `FinalFields` | Object | The content fields of the ledger object after applying any changes from this transaction. Which fields are present depends on what type of ledger object was created. This omits the `PreviousTxnID` and `PreviousTxnLgrSeq` fields, even though most types of ledger objects have them. | -| `PreviousFields` | Object | The previous values for all fields of the object that were changed as a result of this transaction. If the transaction _only added_ fields to the object, this field is an empty object. | -| `PreviousTxnID` | String - Hash | _(May be omitted)_ The identifying hash of the previous transaction to modify this ledger object. Omitted for ledger object types that do not have a `PreviousTxnID` field. | -| `PreviousTxnLgrSeq` | Number - Ledger Index | _(May be omitted)_ The Ledger Index of the ledger version containing the previous transaction to modify this ledger object. Omitted for ledger object types that do not have a `PreviousTxnLgrSeq` field. | - -**Note:** If the modified ledger object has `PreviousTxnID` and `PreviousTxnLgrSeq` fields, the transaction always updates them with the transaction's own identifying hash and the index of the ledger version that included the transaction, but these fields' new value is not listed in the `FinalFields` of the `ModifiedNode` object, and their previous values are listed at the top level of the `ModifiedNode` object rather than in the nested `PreviousFields` object. - - -## delivered_amount - -The `Amount` of a `Payment` transaction indicates the amount to deliver to the `Destination`, so if the transaction was successful, then the destination received that much -- _except if the transaction was a [partial payment](payments/partial-payments.md)_. (In that case, any positive amount up to `Amount` might have arrived.) Rather than choosing whether or not to trust the `Amount` field, you should use the `delivered_amount` field of the metadata to see how much actually reached its destination. - -The `rippled` server provides a `delivered_amount` field in JSON transaction metadata for all successful Payment transactions. This field is formatted like a normal currency amount. However, the delivered amount is not available for transactions that meet both of the following criteria: - -* Is a partial payment -* 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 figure out the actual delivered amount by reading the `AffectedNodes` in the transaction's metadata. - -**Note:** The `delivered_amount` field is generated on-demand for the request, and is not included in the binary format for transaction metadata, nor is it used when calculating the hash of the transaction metadata. In contrast, the `DeliveredAmount` field _is_ included in the binary format for partial payment transactions after 2014-01-20. - -See also: [Partial Payments](payments/partial-payments.md) - - - - - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/transactions/transaction-results/tec-codes.md b/content/concepts/understanding-xrpl/transactions/transaction-results/tec-codes.md deleted file mode 100644 index 39a4f57f96..0000000000 --- a/content/concepts/understanding-xrpl/transactions/transaction-results/tec-codes.md +++ /dev/null @@ -1,1057 +0,0 @@ -# tec Codes - -These codes indicate that the transaction failed, but it was applied to a ledger to apply the [transaction cost](../transaction-cost.md). They have numerical values in the range 100 to 199. Ripple recommends using the text code, not the numeric value. - -For the most part, transactions with `tec` codes take no action other than to destroy the XRP paid as a [transaction cost](../transaction-cost.md), but there are some exceptions. As one such exception, a transaction that results in `tecOVERSIZE` still cleans up some unfunded offers. Always look at the [transaction metadata](../transaction-metadata.md) to see precisely what a transaction did. - - - -**Caution:** A transaction that provisionally failed with a `tec` code may still succeed or fail with a different code after being reapplied. The result is final when it appears in a validated ledger version. For more information, see [Finality of Results](../finality-of-results.md) - - -| Code | Value | Explanation | -|:---------------------------|:------|:----------------------------------------| -| `tecCLAIM` | 100 | Unspecified failure, with transaction cost destroyed. | -| `tecCRYPTOCONDITION_ERROR` | 146 | This `EscrowCreate` or `EscrowFinish` transaction contained a malformed or mismatched crypto-condition. | -| `tecDIR_FULL` | 121 | The transaction tried to add an object (such as a trust line, Check, Escrow, or Payment Channel) to an account's owner directory, but that account cannot own any more objects in the ledger. | -| `tecDUPLICATE` | 149 | The transaction tried to create an object (such as a `DepositPreauth` authorization) that already exists. | -| `tecDST_TAG_NEEDED` | 143 | The `Payment` transaction omitted a [destination tag](../source-and-destination-tags.md), but the destination account has the `lsfRequireDestTag` flag enabled. [New in: rippled 0.28.0][] | -| `tecEXPIRED` | 148 | The transaction tried to create an object (such as an Offer or a Check) whose provided Expiration time has already passed. | -| `tecFAILED_PROCESSING` | 105 | An unspecified error occurred when processing the transaction. | -| `tecFROZEN` | 137 | The `OfferCreate` transaction failed because one or both of the assets involved are subject to a [global freeze](../../tokens/freezing-tokens.md). | -| `tecHAS_OBLIGATIONS` | 151 | The `AccountDelete` transaction failed because the account to be deleted owns objects that cannot be deleted. See [Deletion of Accounts](../../accounts/account-deleting.md) for details. | -| `tecINSUF_RESERVE_LINE` | 122 | The transaction failed because the sending account does not have enough XRP to create a new trust line. (See: [Reserves](../../accounts/reserves.md)) This error occurs when the counterparty already has a trust line in a non-default state to the sending account for the same currency. (See `tecNO_LINE_INSUF_RESERVE` for the other case.) | -| `tecINSUF_RESERVE_OFFER` | 123 | The transaction failed because the sending account does not have enough XRP to create a new Offer. (See: [Reserves](../../accounts/reserves.md)) | -| `tecINSUFF_FEE` | 136 | The transaction failed because the sending account does not have enough XRP to pay the [transaction cost](../transaction-cost.md) that it specified. (In this case, the transaction processing destroys all of the sender's XRP even though that amount is lower than the specified transaction cost.) This result only occurs if the account's balance decreases _after_ this transaction has been distributed to enough of the network to be included in a consensus set. Otherwise, the transaction fails with [`terINSUF_FEE_B`](ter-codes.md) before being distributed. | -| `tecINSUFFICIENT_RESERVE` | 141 | The transaction would increase the [reserve requirement](../../accounts/reserves.md) higher than the sending account's balance. `SignerListSet`, `PaymentChannelCreate`, `PaymentChannelFund`, and `EscrowCreate` can return this error code. See [Signer Lists and Reserves](../../../../references/protocol-reference/ledger-data/ledger-object-types/signerlist.md#signer-lists-and-reserves) for more information. | -| `tecINTERNAL` | 144 | Unspecified internal error, with transaction cost applied. This error code should not normally be returned. If you can reproduce this error, please [report an issue](https://github.com/ripple/rippled/issues). | -| `tecINVARIANT_FAILED` | 147 | An invariant check failed when trying to execute this transaction. Added by the EnforceInvariants amendment. If you can reproduce this error, please [report an issue](https://github.com/ripple/rippled/issues). | -| `tecKILLED` | 150 | The OfferCreate transaction specified the `tfFillOrKill` flag and could not be filled, so it was killed. _(Added by the fix1578 amendment.)_ | -| `tecNEED_MASTER_KEY` | 142 | This transaction tried to cause changes that require the master key, such as [disabling the master key or giving up the ability to freeze balances](../../../../references/protocol-reference/transactions/transaction-types/accountset.md#accountset-flags). [New in: rippled 0.28.0][] | -| `tecNO_ALTERNATIVE_KEY` | 130 | The transaction tried to remove the only available method of [authorizing transactions](../transactions.md#authorizing-transactions). This could be a `SetRegularKey` transaction to remove the regular key, a `SignerListSet transaction` to delete a SignerList, or an `AccountSet` transaction to disable the master key. (Prior to `rippled` 0.30.0, this was called `tecMASTER_DISABLED`.) | -| `tecNO_AUTH` | 134 | The transaction failed because it needs to add a balance on a trust line to an account with the `lsfRequireAuth` flag enabled, and that trust line has not been authorized. If the trust line does not exist at all, `tecNO_LINE` occurs instead. | -| `tecNO_DST` | 124 | The account on the receiving end of the transaction does not exist. This includes Payment and TrustSet transaction types. (It could be created if it received enough XRP.) | -| `tecNO_DST_INSUF_XRP` | 125 | The account on the receiving end of the transaction does not exist, and the transaction is not sending enough XRP to create it. | -| `tecNO_ENTRY` | 140 | The transaction tried to modify a [ledger object](../../../../references/protocol-reference/ledger-data/ledger-object-types/ledger-object-types.md), such as a [Check](../payments/checks.md), [Payment Channel](../payments/payment-channels.md), or [Deposit Preauthorization](../../../../references/protocol-reference/ledger-data/ledger-object-types/depositpreauth.md), but the specified object does not exist. It might have already been deleted by a previous transaction or the transaction might have an incorrect value in an ID field such as `CheckID`, `Channel`, `Unauthorize`. | -| `tecNO_ISSUER` | 133 | The account specified in the `issuer` field of a currency amount does not exist. | -| `tecNO_LINE` | 135 | The `TakerPays` field of the `OfferCreate` transaction specifies an asset whose issuer has `lsfRequireAuth` enabled, and the account making the offer does not have a trust line for that asset. (Normally, making an offer implicitly creates a trust line if necessary, but in this case it does not bother because you cannot hold the asset without authorization.) If the trust line exists, but is not authorized, `tecNO_AUTH` occurs instead. | -| `tecNO_LINE_INSUF_RESERVE` | 126 | The transaction failed because the sending account does not have enough XRP to create a new trust line. (See: [Reserves](../../accounts/reserves.md)) This error occurs when the counterparty does not have a trust line to this account for the same currency. (See `tecINSUF_RESERVE_LINE` for the other case.) | -| `tecNO_LINE_REDUNDANT` | 127 | The transaction failed because it tried to set a trust line to its default state, but the trust line did not exist. | -| `tecNO_PERMISSION` | 139 | The sender does not have permission to do this operation. For example, the `EscrowFinish` transaction tried to release a held payment before its `FinishAfter` time, someone tried to use `PaymentChannelFund` on a channel the sender does not own, or a `Payment` tried to deliver funds to an account with the "DepositAuth" flag enabled. | -| `tecNO_REGULAR_KEY` | 131 | The `AccountSet` transaction tried to disable the master key, but the account does not have another way to [authorize transactions](../transactions.md#authorizing-transactions). If [multi-signing](../multi-signing.md) is enabled, this code is deprecated and `tecNO_ALTERNATIVE_KEY` is used instead. | -| `tecNO_TARGET` | 138 | The transaction referenced an Escrow or PayChannel ledger object that doesn't exist, either because it never existed or it has already been deleted. (For example, another `EscrowFinish` transaction has already executed the held payment.) Alternatively, the destination account has `asfDisallowXRP` set so it cannot be the destination of this `PaymentChannelCreate` or `EscrowCreate` transaction. | -| `tecOVERSIZE` | 145 | This transaction could not be processed, because the server created an excessively large amount of [metadata](../transaction-metadata.md) when it tried to apply the transaction. [New in: rippled 0.29.0-hf1][] | -| `tecOWNERS` | 132 | The transaction requires that account sending it has a nonzero "owners count", so the transaction cannot succeed. For example, an account cannot enable the [`lsfRequireAuth`](../../../references/protocol-reference/transactions/transaction-types/accountset.md#accountset-flags) flag if it has any trust lines or available offers. | -| `tecPATH_DRY` | 128 | The transaction failed because the provided [paths](paths.html) did not have enough liquidity to send anything at all. This could mean that the source and destination accounts are not linked by [trust lines](../trust-lines-and-issuing.md). | -| `tecPATH_PARTIAL` | 101 | The transaction failed because the provided [paths](../../tokens/paths.md) did not have enough liquidity to send the full amount. | -| `tecTOO_SOON` | 152 | The `AccountDelete` transaction failed because the account to be deleted had a `Sequence` number that is too high. The current ledger index must be at least 256 higher than the account's sequence number. | -| `tecUNFUNDED` | 129 | The transaction failed because the account does not hold enough XRP to pay the amount in the transaction _and_ satisfy the additional [reserve](../../accounts/reserves.md) necessary to execute this transaction. | -| `tecUNFUNDED_ADD` | 102 | **DEPRECATED.** | -| `tecUNFUNDED_PAYMENT` | 104 | The transaction failed because the sending account is trying to send more XRP than it holds, not counting the [reserve](../../accounts/reserves.md). | -| `tecUNFUNDED_OFFER` | 103 | The `OfferCreate` transaction failed because the account creating the offer does not have any of the `TakerGets` currency. | - - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/transactions/transaction-results/tef-codes.md b/content/concepts/understanding-xrpl/transactions/transaction-results/tef-codes.md deleted file mode 100644 index a0544b3be0..0000000000 --- a/content/concepts/understanding-xrpl/transactions/transaction-results/tef-codes.md +++ /dev/null @@ -1,1037 +0,0 @@ -# tef Codes - - -These codes indicate that the transaction failed and was not included in a ledger, but the transaction could have succeeded in some theoretical ledger. Typically this means that the transaction can no longer succeed in any future ledger. They have numerical values in the range -199 to -100. The exact code for any given error is subject to change, so don't rely on it. - -**Caution:** Transactions with `tef` codes are not applied to ledgers and cannot cause any changes to the XRP Ledger state. However, a transaction that provisionally failed may still succeed or fail with a different code after being reapplied. For more information, see [Finality of Results](../finality-of-results.md) and Reliable Transaction Submission. - - -| Code | Explanation | -|:-----------------------|:----------------------------------------------------| -| `tefALREADY` | The same exact transaction has already been applied. | -| `tefBAD_ADD_AUTH` | **DEPRECATED.** | -| `tefBAD_AUTH` | The key used to sign this account is not authorized to modify this account. (It could be authorized if the account had the same key set as the [Regular Key](../../accounts/cryptographic-keys.md).) | -| `tefBAD_AUTH_MASTER` | The single signature provided to authorize this transaction does not match the master key, but no regular key is associated with this address. | -| `tefBAD_LEDGER` | While processing the transaction, the ledger was discovered in an unexpected state. If you can reproduce this error, please [report an issue](https://github.com/ripple/rippled/issues) to get it fixed. | -| `tefBAD_QUORUM` | The transaction was [multi-signed](../multi-signing.md), but the total weights of all included signatures did not meet the quorum. | -| `tefBAD_SIGNATURE` | The transaction was [multi-signed](../multi-signing.md), but contained a signature for an address not part of a SignerList associated with the sending account. | -| `tefCREATED` | **DEPRECATED.** | -| `tefEXCEPTION` | While processing the transaction, the server entered an unexpected state. This may be caused by unexpected inputs, for example if the binary data for the transaction is grossly malformed. If you can reproduce this error, please [report an issue](https://github.com/ripple/rippled/issues) to get it fixed. | -| `tefFAILURE` | Unspecified failure in applying the transaction. | -| `tefINTERNAL` | When trying to apply the transaction, the server entered an unexpected state. If you can reproduce this error, please [report an issue](https://github.com/ripple/rippled/issues) to get it fixed. | -| `tefINVARIANT_FAILED` | An invariant check failed when trying to claim the [transaction cost](../transaction-cost.md). Added by the EnforceInvariants amendment. If you can reproduce this error, please [report an issue](https://github.com/ripple/rippled/issues). | -| `tefMASTER_DISABLED` | The transaction was signed with the account's master key, but the account has the `lsfDisableMaster` field set. | -| `tefMAX_LEDGER` | The transaction included a `LastLedgerSequence`parameter, but the current ledger's sequence number is already higher than the specified value. | -| `tefNO_AUTH_REQUIRED` | The `TrustSet` transaction tried to mark a trust line as authorized, but the `lsfRequireAuth` flag is not enabled for the corresponding account, so authorization is not necessary. | -| `tefNO_TICKET` | The transaction attempted to use a [Ticket](../tickets.md), but the specified `TicketSequence` number does not exist in the ledger, and cannot be created in the future because it is earlier than the sender's current sequence number. | -| `tefNOT_MULTI_SIGNING` | The transaction was [multi-signed](../multi-signing.md), but the sending account has no SignerList defined. | -| `tefPAST_SEQ` | The sequence number of the transaction is lower than the current sequence number of the account sending the transaction. | -| `tefTOO_BIG` | The transaction would affect too many objects in the ledger. For example, this was an `AccountDelete` transaction but the account to be deleted owns over 1000 objects in the ledger. | -| `tefWRONG_PRIOR` | The transaction contained an `AccountTxnID` field (or the deprecated `PreviousTxnID` field), but the transaction specified there does not match the account's previous transaction. | - - - - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/transactions/transaction-results/tel-codes.md b/content/concepts/understanding-xrpl/transactions/transaction-results/tel-codes.md deleted file mode 100644 index 521d85063e..0000000000 --- a/content/concepts/understanding-xrpl/transactions/transaction-results/tel-codes.md +++ /dev/null @@ -1,1028 +0,0 @@ -# tel Codes - -These codes indicate an error in the local server processing the transaction; it is possible that another server with a different configuration or load level could process the transaction successfully. They have numerical values in the range -399 to -300. The exact code for any given error is subject to change, so don't rely on it. - -**Caution:** Transactions with `tel` codes are not applied to ledgers and cannot cause any changes to the XRP Ledger state. However, these transactions may be automatically cached and retried later. Transactions that provisionally failed may still succeed or fail with a different code after being reapplied. For more information, see [Finality of Results](../finality-of-results.md). - - - -| Code | Explanation | -|:----------------------|:-----------------------------------------------------| -| `telBAD_DOMAIN` | The transaction specified a domain value (for example, the `Domain` field of an `AccountSet` transaction) that cannot be used, probably because it is too long to store in the ledger. | -| `telBAD_PATH_COUNT` | The transaction contains too many paths for the local server to process. | -| `telBAD_PUBLIC_KEY` | The transaction specified a public key value (for example, as the `MessageKey` field of an `AccountSet` transaction) that cannot be used, probably because it is not the right length. | -| `telCAN_NOT_QUEUE` | The transaction did not meet the [open ledger cost](transaction-cost.html), but this server did not queue this transaction because it did not meet the [queuing restrictions](../../server/transaction-queue.md#queuing-restrictions). For example, a transaction returns this code when the sender already has 10 other transactions in the queue. You can try again later or sign and submit a replacement transaction with a higher transaction cost in the `Fee` field. | -| `telCAN_NOT_QUEUE_BALANCE` | The transaction did not meet the [open ledger cost](../transaction-cost.md) and also was not added to the transaction queue because the sum of potential XRP costs of already-queued transactions is greater than the expected balance of the account. You can try again later, or try submitting to a different server. New in: rippled 0.70.2 | -| `telCAN_NOT_QUEUE_BLOCKS` | The transaction did not meet the [open ledger cost](../transaction-cost.md) and also was not added to the transaction queue. This transaction could not replace an existing transaction in the queue because it would block already-queued transactions from the same sender by changing authorization methods. (This includes all `SetRegularKey` and `SignerListSet` transactions, as well as `AccountSet` transactions that change the `RequireAuth`/`OptionalAuth`, `DisableMaster`, or `AccountTxnID` flags.) You can try again later, or try submitting to a different server. New in: rippled 0.70.2 | -| `telCAN_NOT_QUEUE_BLOCKED` | The transaction did not meet the [open ledger cost](../transaction-cost.md) and also was not added to the transaction queue because a transaction queued ahead of it from the same sender blocks it. (This includes all `SetRegularKey` and `SignerListSet` transactions, as well as `AccountSet` transactions that change the `RequireAuth`/`OptionalAuth`, `DisableMaster`, or `AccountTxnID` flags.) You can try again later, or try submitting to a different server. New in: rippled 0.70.2 | -| `telCAN_NOT_QUEUE_FEE` | The transaction did not meet the [open ledger cost](../transaction-cost.md) and also was not added to the transaction queue. This code occurs when a transaction with the same sender and sequence number already exists in the queue and the new one does not pay a large enough transaction cost to replace the existing transaction. To replace a transaction in the queue, the new transaction must have a `Fee` value that is at least 25% more, as measured in [fee levels](../transaction-cost.md#fee-levels). You can increase the `Fee` and try again, send this with a higher `Sequence` number so it doesn't replace an existing transaction, or try sending to another server. New in: rippled 0.70.2 | -| `telCAN_NOT_QUEUE_FULL` | The transaction did not meet the [open ledger cost](../transaction-cost.md) and the server did not queue this transaction because this server's transaction queue is full. You could increase the `Fee` and try again, try again later, or try submitting to a different server. The new transaction must have a higher transaction cost, as measured in [fee levels](../transaction-cost.md#fee-levels), than the transaction in the queue with the smallest transaction cost. New in: rippled 0.70.2 | -| `telFAILED_PROCESSING` | An unspecified error occurred when processing the transaction. | -| `telINSUF_FEE_P` | The `Fee` from the transaction is not high enough to meet the server's current [transaction cost](../transaction-cost.md) requirement, which is derived from its load level and network-level requirements. If the individual server is too busy to process your transaction right now, it may cache the transaction and automatically retry later. | -| `telLOCAL_ERROR` | Unspecified local error. | -| `telNO_DST`_`PARTIAL` | The transaction is an XRP payment that would fund a new account, but the [`tfPartialPayment` flag](../payments/partial-payments.md) was enabled. This is disallowed. | - - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/transactions/transaction-results/tem-codes.md b/content/concepts/understanding-xrpl/transactions/transaction-results/tem-codes.md deleted file mode 100644 index 6efa490166..0000000000 --- a/content/concepts/understanding-xrpl/transactions/transaction-results/tem-codes.md +++ /dev/null @@ -1,1048 +0,0 @@ -# tem Codes - -These codes indicate that the transaction was malformed, and cannot succeed according to the XRP Ledger protocol. They have numerical values in the range -299 to -200. The exact code for any given error is subject to change, so don't rely on it. - -**Tip:** Transactions with `tem` codes are not applied to ledgers, and cannot cause any changes to XRP Ledger state. A `tem` result is final unless the rules for a valid transaction change. (For example, using functionality from an [Amendment](../../../../amendments/amendments.md) before that amendment is enabled results in `temDISABLED`; such a transaction could succeed later if it becomes valid when the amendment is enabled.) - -| Code | Explanation | -|:-----------------------------|:----------------------------------------------| -| `temBAD_AMOUNT` | An amount specified by the transaction (for example the destination `Amount` or `SendMax` values of a `Payment`) was invalid, possibly because it was a negative number. | -| `temBAD_AUTH_MASTER` | The key used to sign this transaction does not match the master key for the account sending it, and the account does not have a [Regular Key](../../accounts/cryptographic-keys.md) set. | -| `temBAD_CURRENCY` | The transaction improperly specified a currency field. | -| `temBAD_EXPIRATION` | The transaction improperly specified an expiration value, for example as part of an `OfferCreate` transaction. Alternatively, the transaction did not specify a required expiration value, for example as part of an `EscrowCreate` transaction. | -| `temBAD_FEE` | The transaction improperly specified its `Fee` value, for example by listing a non-XRP currency or some negative amount of XRP. | -| `temBAD_ISSUER` | The transaction improperly specified the `issuer` field of some currency included in the request. | -| `temBAD_LIMIT` | The `TrustSet` transaction improperly specified the `LimitAmount` value of a trust line. | -| `temBAD_OFFER` | The `OfferCreate` transaction specifies an invalid offer, such as offering to trade XRP for itself, or offering a negative amount. | -| `temBAD_PATH` | The `Payment` transaction specifies one or more [Paths](../../tokens/paths.md) improperly, for example including an issuer for XRP, or specifying an account differently. | -| `temBAD_PATH_LOOP` | One of the [Paths](../../tokens/paths.md) in the `Payment` transaction was flagged as a loop, so it cannot be processed in a bounded amount of time. | -| `temBAD_SEND_XRP_LIMIT` | The `Payment` transaction used the [`tfLimitQuality` flag](../../../../references/protocol-reference/transactions/transaction-types/payment.md#limit-quality) in a direct XRP-to-XRP payment, even though XRP-to-XRP payments do not involve any conversions. | -| `temBAD_SEND_XRP_MAX` | The `Payment` transaction included a `SendMax` field in a direct XRP-to-XRP payment, even though sending XRP should never require `SendMax`. (XRP is only valid in `SendMax` if the destination `Amount` is not XRP.) | -| `temBAD_SEND_XRP_NO_DIRECT` | The `Payment` transaction used the [`tfNoDirectRipple` flag](../../../../references/protocol-reference/transactions/transaction-types/payment.md#payment-flags) for a direct XRP-to-XRP payment, even though XRP-to-XRP payments are always direct. | -| `temBAD_SEND_XRP_PARTIAL` | The `Payment` transaction used the [`tfPartialPayment` flag](../payments/partial-payments.html) for a direct XRP-to-XRP payment, even though XRP-to-XRP payments should always deliver the full amount. | -| `temBAD_SEND_XRP_PATHS` | The `Payment` transaction included `Paths` while sending XRP, even though XRP-to-XRP payments should always be direct. | -| `temBAD_SEQUENCE` | The transaction is references a sequence number that is higher than its own `Sequence` number, for example trying to cancel an offer that would have to be placed after the transaction that cancels it. | -| `temBAD_SIGNATURE` | The signature to authorize this transaction is either missing, or formed in a way that is not a properly-formed signature. (See [`tecNO_PERMISSION`](tec-codes.md) for the case where the signature is properly formed, but not authorized for this account.) | -| `temBAD_SRC_ACCOUNT` | The `Account` on whose behalf this transaction is being sent (the "source account") is not a properly-formed [account](../../accounts/accounts.md) address. | -| `temBAD_TRANSFER_RATE` | The [`TransferRate` field of an AccountSet transaction](../../../../references/protocol-reference/transactions/transaction-types/accountset.md#transferrate) is not properly formatted or out of the acceptable range. | -| `temCANNOT_PREAUTH_SELF` | The sender of the `DepositPreauth` transaction was also specified as the account to preauthorize. You cannot preauthorize yourself. | -| `temDST_IS_SRC` | The transaction improperly specified a destination address as the `Account` sending the transaction. This includes trust lines (where the destination address is the `issuer` field of `LimitAmount`) and payment channels (where the destination address is the `Destination` field). | -| `temDST_NEEDED` | The transaction improperly omitted a destination. This could be the `Destination` field of a `Payment` transaction, or the `issuer` sub-field of the `LimitAmount` field fo a `TrustSet` transaction. | -| `temINVALID` | The transaction is otherwise invalid. For example, the transaction ID may not be the right format, the signature may not be formed properly, or something else went wrong in understanding the transaction. | -| `temINVALID_COUNT` | The transaction includes a `TicketCount` field, but the number of Tickets specified is invalid. | -| `temINVALID_FLAG` | The transaction includes a [Flag](../transaction-common-fields.html#flags-field) that does not exist, or includes a contradictory combination of flags. | -| `temMALFORMED` | Unspecified problem with the format of the transaction. | -| `temREDUNDANT` | The transaction would do nothing; for example, it is sending a payment directly to the sending account, or creating an offer to buy and sell the same currency from the same issuer. | -| `temREDUNDANT_SEND_MAX` | Removed in: rippled 0.28.0 | -| `temRIPPLE_EMPTY` | The `Payment` transaction includes an empty `Paths` field, but paths are necessary to complete this payment. | -| `temBAD_WEIGHT` | The `SignerListSet` transaction includes a `SignerWeight` that is invalid, for example a zero or negative value. | -| `temBAD_SIGNER` | The `SignerListSet` transaction includes a signer who is invalid. For example, there may be duplicate entries, or the owner of the SignerList may also be a member. | -| `temBAD_QUORUM` | The `SignerListSet` transaction has an invalid `SignerQuorum` value. Either the value is not greater than zero, or it is more than the sum of all signers in the list. | -| `temUNCERTAIN` | Used internally only. This code should never be returned. | -| `temUNKNOWN` | Used internally only. This code should never be returned. | -| `temDISABLED` | The transaction requires logic that is disabled. Typically this means you are trying to use an [amendment](../../../../amendments/amendments.md) that is not enabled for the current ledger. | - - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/transactions/transaction-results/ter-codes.md b/content/concepts/understanding-xrpl/transactions/transaction-results/ter-codes.md deleted file mode 100644 index 0408c2c4ec..0000000000 --- a/content/concepts/understanding-xrpl/transactions/transaction-results/ter-codes.md +++ /dev/null @@ -1,1025 +0,0 @@ -# ter Codes - -These codes indicate that the transaction failed, but it could apply successfully in the future, usually if some other hypothetical transaction applies first. They have numerical values in the range -99 to -1. The exact code for any given error is subject to change, so don't rely on it. - -**Caution:** Transactions with `ter` codes are not applied the current ledger and cannot cause any changes to the XRP Ledger state. However, a transaction that provisionally failed may still succeed or fail with a different code after being automatically reapplied. For more information, see [Finality of Results](../finality-of-results.md). - -| Code | Explanation | -|:-----------------|:----------------------------------------------------------| -| `terFUNDS_SPENT` | **DEPRECATED.** | -| `terINSUF_FEE_B` | The account sending the transaction does not have enough XRP to pay the `Fee` specified in the transaction. | -| `terLAST` | Used internally only. This code should never be returned. | -| `terNO_ACCOUNT` | The address sending the transaction is not funded in the ledger (yet). | -| `terNO_AUTH` | The transaction would involve adding currency issued by an account with `lsfRequireAuth` enabled to a trust line that is not authorized. For example, you placed an offer to buy a currency you aren't authorized to hold. | -| `terNO_LINE` | Used internally only. This code should never be returned. | -| `terNO_RIPPLE` | Used internally only. This code should never be returned. | -| `terOWNERS` | The transaction requires that account sending it has a nonzero "owners count", so the transaction cannot succeed. For example, an account cannot enable the [`lsfRequireAuth`](../../../../references/protocol-reference/transactions/transaction-types/accountset.md#accountset-flags) flag if it has any trust lines or available offers. | -| `terPRE_SEQ` | The `Sequence` number of the current transaction is higher than the current sequence number of the account sending the transaction. | -| `terPRE_TICKET` | The transaction attempted to use a [Ticket](../tickets.md), but the specified `TicketSequence` number does not exist in the ledger. However, the Ticket could still be created by another transaction. | -| `terRETRY` | Unspecified retriable error. | -| `terQUEUED` | The transaction met the load-scaled [transaction cost](transaction-cost.html) but did not meet the open ledger requirement, so the transaction has been queued for a future ledger. | - - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/transactions/transaction-results/tes-success.md b/content/concepts/understanding-xrpl/transactions/transaction-results/tes-success.md deleted file mode 100644 index 5d6c8dc1c4..0000000000 --- a/content/concepts/understanding-xrpl/transactions/transaction-results/tes-success.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -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. | - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/transactions/transaction-results/transaction-results.md b/content/concepts/understanding-xrpl/transactions/transaction-results/transaction-results.md deleted file mode 100644 index e0133a7ee1..0000000000 --- a/content/concepts/understanding-xrpl/transactions/transaction-results/transaction-results.md +++ /dev/null @@ -1,1050 +0,0 @@ -# Transaction Results - -[[Source]](https://github.com/ripple/rippled/blob/master/src/ripple/protocol/TER.h "Source") - -The `rippled` server summarizes transaction results with result codes, which appear in fields such as `engine_result` and `meta.TransactionResult`. These codes are grouped into several categories of with different prefixes: - -| Category | Prefix | Description | -|:----------------------|:--------------------------|:-------------------------| -| Claimed cost only | [`tec`](tec-codes.md) | The transaction did not achieve its intended purpose, but the [transaction cost](../transaction-cost.md) was destroyed. This result is only final in a validated ledger. | -| Failure | [`tef`](tef-codes.md) | The transaction cannot be applied to the server's current (in-progress) ledger or any later one. It may have already been applied, or the condition of the ledger makes it impossible to apply in the future. | -| Local error | [`tel`](tel-codes.md) | The `rippled` server had an error due to local conditions, such as high load. You may get a different response if you resubmit to a different server or at a different time. | -| Malformed transaction | [`tem`](tem-codes.md) | The transaction was not valid, due to improper syntax, conflicting options, a bad signature, or something else. | -| Retry | [`ter`](ter-codes.md) | The transaction could not be applied, but it could apply successfully in a future ledger. | -| Success | [`tes`](tes-success.md) | (Not an error) The transaction succeeded. This result only final in a validated ledger. | - -The `rippled` server automatically retries failed transactions. It is important not to assume that a transaction has completely failed based on a tentative failure result. A transaction may later succeed unless its success or failure is [final](../finality-of-results.md). - -**Warning:** Transactions' provisional result codes may differ than their final result. Transactions that provisionally succeeded may eventually fail and transactions that provisionally failed may eventually succeed. Transactions that provisionally failed may also eventually fail with a different code. See [finality of results](../finality-of-results.md) for how to know when a transaction's result is final. - -The distinction between a local error (`tel`) and a malformed transaction (`tem`) is a matter of protocol-level rules. For example, the protocol sets no limit on the maximum number of paths that can be included in a transaction. However, a server may define a finite limit of paths it can process. If two different servers are configured differently, then one of them may return a `tel` error for a transaction with many paths, while the other server could successfully process the transaction. If enough servers are able to process the transaction that it survives consensus, then it can still be included in a validated ledger. - -By contrast, a `tem` error implies that no server anywhere can apply the transaction, regardless of settings. Either the transaction breaks the rules of the protocol, it is unacceptably ambiguous, or it is completely nonsensical. The only way a malformed transaction could become valid is through changes in the protocol; for example, if a new feature is adopted, then transactions using that feature could be considered malformed by servers that are running older software which predates that feature. - - -## Immediate Response - -The response from the `submit` method contains a provisional result from the `rippled` server indicating what happened during local processing of the transaction. - -The response from `submit` contains the following fields: - -| Field | Value | Description | -|:------------------------|:---------------|:----------------------------------| -| `engine_result` | String | A code indicating the outcome of the transaction, such as `tecPATH_DRY`. | -| `engine_result_code` | Signed Integer | A number that corresponds to the `engine_result`. The exact values are subject to change without notice. | -| `engine_result_message` | String | A human-readable message explaining what happened. This message is intended for developers to diagnose problems, and is subject to change without notice. | - -If nothing went wrong when submitting and applying the transaction locally, the response looks like this: - -```js - "engine_result": "tesSUCCESS", - "engine_result_code": 0, - "engine_result_message": "The transaction was applied. Only final in a validated ledger." -``` - -**Note:** A successful result at this stage does not indicate that the transaction has completely succeeded; only that it was successfully applied to the provisional version of the ledger kept by the local server. Failed results at this stage are also provisional and may change. See [Finality of Results](../finality-of-results.md) for details. - - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/transactions/transaction-structure.md b/content/concepts/understanding-xrpl/transactions/transaction-structure.md deleted file mode 100644 index 81940dab4b..0000000000 --- a/content/concepts/understanding-xrpl/transactions/transaction-structure.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -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.| -| `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. | -| [`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. - -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. - - diff --git a/content/concepts/understanding-xrpl/transactions/transactions.md b/content/concepts/understanding-xrpl/transactions/transactions.md deleted file mode 100644 index d2429313e2..0000000000 --- a/content/concepts/understanding-xrpl/transactions/transactions.md +++ /dev/null @@ -1,229 +0,0 @@ ---- -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. - - - -### 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. - - - -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. - - - - - - -## 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. - - - -For more information about master and regular key pairs, see [Cryptographic Keys](../accounts/cryptographic-keys.md). - - - - - diff --git a/content/concepts/understanding-xrpl/transactions/trust-lines-and-issuing.md b/content/concepts/understanding-xrpl/transactions/trust-lines-and-issuing.md deleted file mode 100644 index b9dea6283c..0000000000 --- a/content/concepts/understanding-xrpl/transactions/trust-lines-and-issuing.md +++ /dev/null @@ -1,80 +0,0 @@ -# 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, 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. 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. -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. 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 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. - -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. - - \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/understanding-xrpl.md b/content/concepts/understanding-xrpl/understanding-xrpl.md deleted file mode 100644 index 7f306e9570..0000000000 --- a/content/concepts/understanding-xrpl/understanding-xrpl.md +++ /dev/null @@ -1,19 +0,0 @@ -# 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. \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/xrpl/consensus-principles-and-rules.md b/content/concepts/understanding-xrpl/xrpl/consensus-principles-and-rules.md deleted file mode 100644 index 3f164d7fe4..0000000000 --- a/content/concepts/understanding-xrpl/xrpl/consensus-principles-and-rules.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -html: consensus-principles-and-rules.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 - - - -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. - -## 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. - -### 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: - -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. - -### Consensus Rounds - -A consensus round is an attempt to agree on a group of transactions so they can be processed. A consensus round starts with each participant who wishes to do so taking an initial position. This is the set of valid transactions they have seen. - -Participants then “avalanche” to consensus: If a particular transaction does not have majority support, participants agree to defer that transaction. If a particular transaction does have majority support, participants agree to include the transaction. Thus slight majorities rapidly become full support and slight minorities rapidly become universal rejection from the current round. - -To prevent consensus from stalling near 50% and to reduce the overlap required for reliable convergence, the required threshold to include a transaction increases over time. Initially, participants continue to agree to include a transaction if 50% or more of other participants agree. If participants disagree, they increase this threshold, first to 60% and then even higher, until all disputed transactions are removed from the current set. Any transactions removed this way are deferred to the next ledger version. - -When a participant sees a supermajority that agrees on the set of transactions to next be processed, it declares a consensus to have been reached. - -### Consensus Can Fail - -It is not practical to develop a consensus algorithm that never fails to achieve perfect consensus. To understand why, consider how the consensus process finishes. At some point, each participant must declare that a consensus has been reached and that some set of transactions is known to be the result of the process. This declaration commits that participant irrevocably to some particular set of transactions as the result of the consensus process. - -Some participant must do this first or no participant will ever do it, and they will never reach a consensus. Now, consider the participant that does this first. When this participant decides that consensus is finished, other participants have not yet made that decision. If they were incapable of changing the agreed set from their point of view, they would have already decided consensus was finished. So they must be still capable of changing their agreed set. - -In other words, for the consensus process to ever finish, some participant must declare that consensus has been reached on a set of transactions even though every other participant is theoretically still capable of changing the agreed upon set of transactions. - -Imagine a group of people in a room trying to agree which door they should use to exit. No matter how much the participants discuss, at some point, _someone_ has to be the first one to walk out of a door, even though the people behind that person could still change their minds and leave through the other door. - -The probability of this kind of failure can be made very low, but it cannot be reduced to zero. The engineering tradeoffs are such that driving this probability down below about one in a thousand makes consensus significantly slower, and less able to tolerate network and endpoint failures. - -### How the XRP Ledger Handles Consensus Failure - -After a consensus round completes, each participant applies the set of transactions that they believe were agreed to. This results in constructing what they believe the next state of the ledger should be. - -Participants that are also validators then publish a cryptographic fingerprint of this next ledger. We call this fingerprint a “validation vote”. If the consensus round succeeded, the vast majority of honest validators should be publishing the same fingerprint. - -Participants then collect these validation votes. From the validation votes, they can determine whether the previous consensus round resulted in a supermajority of participants agreeing on a set of transactions or not. - -Participants then find themselves in one of three cases, in order of probability: - -1. They built the same ledger a supermajority agreed to. In this case, they can consider that ledger fully validated and rely on its contents. -2. They built a different ledger than a supermajority agreed on. In this case, they must build and accept the supermajority ledger. This typically indicates that they declared a consensus early and many other participants changed after that. They must “jump” to the super-majority ledger to resume operation. -3. No supermajority is clear from the received validations. In this case, the previous consensus round was wasted and a new round must occur before any ledger can be validated. - -Of course, case 1 is the most common. Case 2 does no harm to the network whatsoever. A small percentage of the participants could even fall into case 2 every round, and the network would work with no issues. Even those participants can recognize that they did not build the same ledger as the supermajority, so they know not to report their results as final until they are in agreement with the supermajority. - -Case 3 results in the network losing a few seconds in which it could have made forward progress, but is extremely rare. In this case, the next consensus round is much less likely to fail because disagreements are resolved in the consensus process and only remaining disagreements can cause a failure. - -On rare occasions, the network as a whole fails to make forward progress for a few seconds. In exchange, average transaction confirmation times are low. - -## Philosophy - -One form of reliability is the ability of a system to provide results even under conditions where some components have failed, some participants are malicious, and so on. While this is important, there is another form of reliability that is much more important in cryptographic payment systems — the ability of a system to produce results that can be relied upon. That is, when a system reports a result to us as reliable, we should be able to rely on that result. - -Real-world systems, however, face operational conditions in which both kinds of reliability can be compromised. These include hardware failures, communication failures, and even dishonest participants. Part of the XRP Ledger's design philosophy is to detect conditions where the reliability of results are impaired and report them, rather than providing results that must not be relied on. - -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. - - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/understanding-xrpl/xrpl/consensus-protections.ja.md b/content/concepts/understanding-xrpl/xrpl/consensus-protections.ja.md deleted file mode 100644 index d8dbdf748f..0000000000 --- a/content/concepts/understanding-xrpl/xrpl/consensus-protections.ja.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -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. #TODO: translate -labels: - - ブロックチェーン ---- -# 攻撃および障害モードに対するコンセンサスの保護 - -XRP Ledgerコンセンサスプロトコルは、 _ビザンチンフォールトトレラント性_ のあるコンセンサスメカニズムです。つまり、あらゆる不適切な状況（参加者が信頼できないオープンネットワークを利用して通信している場合や、不正使用者が常にシステムを乗っ取ろうとしているかまたは中断しようとしている場合など）が発生しても動作するように設計されています。さらに、XRP Ledgerコンセンサスプロトコルの参加者が事前に判明していない場合や、時間の経過とともに変わる場合があります。 - -[ネットワークに求められる特性](intro-to-consensus.html#コンセンサスプロトコルの特性)を維持しつつ、トランザクションをタイミングよく承認する作業は複雑であり、また完璧なシステムを構築することは不可能です。XRP Ledgerコンセンサスプロトコルは、ほとんどの状況で機能し、機能できない状況では可能な限り安全に失敗するように設計されています。 - -このページでは、XRP Ledgerコンセンサスプロトコルのいくつかの課題のタイプとその対処について説明します。 - -## 個々のバリデータの不適切な動作 - -_バリデータ_ とは、新しいレジャーバージョンの決定プロセスにアクティブに参加するサーバーです。バリデータは、そのバリデータを信用するように設定されているサーバーにのみ影響を与えます（間接的な影響を含む）。一部バリデータの動作が不適切であってもコンセンサスを継続できます。このような不適切な動作には、以下のさまざまなケースがあります。 - -- 使用できないかまたは過負荷状態である。 -- ネットワークから部分的に切断されており、メッセージが遅延なしで届くのは一部の参加者に限られる。 -- 他のサーバーを欺くかまたはネットワークを停止する目的で意図的に動作している。 -- 外部要因（抑圧的な政府からの脅威など）からのプレッシャーによって不正に動作している。 -- バグまたは古いソフトウェアが原因で、わかりにくいメッセージまたは誤った形式のメッセージが偶発的に送信される。 - -一般に、信頼できるバリデータのうち、不適切に動作しているバリデータがごくわずか（約20%未満）である限り、特に問題なくコンセンサスを継続できます。（正確な割合とその計算については、最新の[コンセンサスに関する研究](consensus-research.html)を参照してください。） - -バリデータの約20%以上がアクセス不能であるか適切に動作していない場合、ネットワークはコンセンサスに達することができません。この間、新しいトランザクションを暫定的に処理できますが、新しいレジャーバージョンを検証できないため、これらのトランザクションの最終結果は未確定になります。このような状況では、XRP Ledgerが正常ではないことがただちに明らかになるため、待機するか、または信頼できるバリデータのセットを再設定するかを決定できる参加者からの人的介入が促されます。 - -無効なトランザクションを承認する唯一の方法は、80%以上の信頼できるバリデータがそのトランザクションを承認し、その結果に合意することです。（無効なトランザクションには、すでに使用された資金を送金するトランザクションや、ネットワークのルールに違反するトランザクションなどがあります。）つまり、信頼できるバリデータの過半数が _共謀する_ 必要があります。多数の信頼できるバリデータが世界各地域で異なる人々や企業により運用されている状況では、意図的にこれを達成することは非常に困難です。 - - -## ソフトウェアの脆弱性 - -あらゆるソフトウェアシステムと同様に、XRP Ledgerコンセンサスプロトコル、広く導入されているソフトウェアパッケージ、またはその依存関係の実装に伴うバグ（または意図的に悪意のあるコード）の問題には、真剣に取り組む必要があります。巧妙に作成された入力を取り込んだサーバーをクラッシュさせるだけのバグであっても、ネットワークの進捗を妨害する目的で悪用される可能性があります。Rippleではこのような脅威に対処するため、次のようなさまざまな対策を導入しています。 - -- [オープンソースコードベース](https://github.com/ripple/rippled/)。これにより、一般のユーザーが関連ソフトウェアをレビュー、コンパイルし、個別にテストできます。 -- 公式XRP Ledgerリポジトリのあらゆる変更のための綿密で堅固なコードレビュープロセス。 -- すべてのリリースと公式ソフトウェアパッケージへのRipple社員によるデジタル署名付与。 -- セキュリティの脆弱性と不安定さに関する定期的に委託された専門家レビュー。 -- 責任を持って脆弱性を公開したセキュリティ研究者に報奨金を授与する[Bug Bountyプログラム](https://ripple.com/bug-bounty/)。 - - -## シビル攻撃 - -_[シビル攻撃](https://en.wikipedia.org/wiki/Sybil_attack)_ とは、大量の偽IDを使ってネットワークのコントロールを試みる攻撃です。XRP Ledgerでは、シビル攻撃は多数のバリデータを操作して、他のバリデータにこれらのバリデータを信頼するように仕向ける形で攻撃をしかける可能性があります。このような攻撃は理論上は可能ですが、バリデータが信頼を得るには人間による介入が必要であるため、実際には非常に困難です。 - -攻撃者が操作する検証サーバーの数に関係なく、既存の参加者が攻撃者のバリデータを信頼しない限りは、これらの参加者が何を検証済みと判断するかについて、このようなサーバーが影響を及ぼすことはできません。その他のサーバーは、バリデータリストまたは明示的な設定によって信頼できると設定されたバリデータのみを信頼します。（デフォルトのバリデータリストの仕組みの概要については、[バリデータ重複要件](#バリデータ重複要件)を参照してください。） - -この信頼は自動的に形成されるものではありません。したがってシビル攻撃を成功させるには、ターゲットとなる人物や企業が、攻撃者のバリデータを信頼してXRP Ledgerサーバーを再設定するように仕向けるという難しい作業をこなさなければなりません。ある人物または企業がだまされてXRP Ledgerサーバーを再設定したとしても、自らの設定を変更していない他の人物や企業に対する影響は最小限となります。 - - -## 51%攻撃 - -「51%攻撃」とは、特定の当事者が全採掘能力または投票能力の50%を超える割合を支配しているブロックチェーンに対する攻撃です。（厳密には、50%を _わずかでも_ 超えていれば十分であるため、この攻撃の名前は多少間違っています。）XRP Ledgerは、コンセンサスメカニズムに採掘を採用していないため、51%攻撃に対し脆弱ではありません。これに最も類似するXRP Ledgerへの攻撃には[シビル攻撃](#シビル攻撃)がありますが、この攻撃を実際に実施することは困難です。 - - -## バリデータ重複要件 - -XRP Ledgerのすべての参加者が何を検証済みとみなすかについて合意するには、参加者はまず、他の参加者が選択したバリデータ群によく似た信頼できるバリデータ群を選択する必要があります。最悪のケースでは、重複が約90%未満のために一部の参加者間に不一致が生じる場合があります。このため、Rippleは推奨バリデータの署名付きリストを公開しています。このリストには、企業や業界、コミュニティが運用する信頼性が高く適切に管理されたサーバーが含まれます。 - -デフォルトでは、XRP LedgerサーバーはRippleが運用するバリデータリストサイトを使用するように設定されています。このサイトでは、Rippleが定期的に更新する推奨バリデータリスト（推奨 _ユニークノードリスト_ （UNL））が公開されています。このように設定されているサーバーは、最新バージョンのリストに含まれているすべてのバリデータを信頼します。これにより、同じリストを使用する他のサーバーと100%重複することが保証されます。デフォルトの設定には、サイトのコンテンツの真正性を検証する公開鍵が含まれています。サイトがダウンした場合、XRP Ledgerのピアツーピアネットワーク内のサーバー間でリストに対する署名済みの更新を直接中継できます。 - -技術的には、サーバーを実行している場合、各自のリストサイトを設定するかまたは信頼できるバリデータを個別に明示的に選択することができますが、これらを行うことは推奨されません。選択したバリデータ群と他のサーバーとの重複が十分ではない場合、サーバーはネットワークの他の部分と不一致になる可能性があり、サーバーが不一致の状態でアクションを実行すると資金を失う可能性があります。 - -コンセンサスプロトコルの設計を改善し、より多様性のあるバリデータリストを実現するための研究が進んでいます。詳細は、[コンセンサスの研究](consensus-research.html)ページを参照してください。 - - -## 関連項目 - -- コンセンサスの**入門レベルの概要**については、[コンセンサスについて](intro-to-consensus.html)を参照してください。 -- コンセンサスプロトコルの**詳細な説明**については、[コンセンサス](consensus.html)を参照してください。 -- コンセンサスプロトコルの**設計に関する決定と背景**については、[コンセンサスの原理とルール](consensus-principles-and-rules.html)を参照してください。 -- コンセンサスプロトコルの特性と制約に関する**学術研究**については、[コンセンサスの研究](consensus-research.html)を参照してください。 diff --git a/content/concepts/understanding-xrpl/xrpl/consensus-protections.md b/content/concepts/understanding-xrpl/xrpl/consensus-protections.md deleted file mode 100644 index 6b29e726a5..0000000000 --- a/content/concepts/understanding-xrpl/xrpl/consensus-protections.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -html: consensus-protections.html -parent: consensus.html -blurb: The XRP Ledger is designed to protect itself against both malicious actors and unexpected network errors. -labels: - - Ledgers ---- - -# Consensus Protections - -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. - -## Individual Validators Misbehaving - -_Validators_ are servers that actively contribute to the process of deciding each new ledger version. Validators only have an influence over servers configured to trust them (including indirectly). Consensus can continue even if some validators are misbehaving, including a large variety of failure cases, such as: - -- Being unavailable or overloaded. -- Being partially disconnected from the network, so their messages reach only a subset of participants without delay. -- Intentionally behaving with intent to defraud others or halt the network. -- 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.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. - -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. - - -## Software Vulnerabilities - -As with any software system, bugs (or intentionally malicious code) in the implementation of the XRP Ledger Consensus Protocol, commonly deployed software packages, or their dependencies, are a problem to be taken seriously. Even bugs that cause a server to crash when it sees carefully crafted inputs can be abused to disrupt the progress of the network. Ripple takes precautions to address this threat in its reference implementations of XRP Ledger software, including: - -- An [open-source code base](https://github.com/ripple/rippled/), so any member of the public can review, compile, and independently test the relevant software. -- A thorough and robust code review process for all changes to the official XRP Ledger repositories. -- Digital signatures from Ripple employees on all releases and official software packages. -- Regularly-commissioned professional reviews for security vulnerabilities and insecurities. -- A [bug bounty program](https://ripple.com/bug-bounty/) that rewards security researchers who responsibly disclose vulnerabilities. - - -## 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. - -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.) - -This trust does not happen automatically, so performing a successful Sybil attack would involve the difficult work of convincing targeted humans and businesses to reconfigure their XRP Ledger servers to trust the attacker's validators. Even in the case that one individual entity was fooled into doing so, this would have a minimal impact on others who do not change their configurations. - - -## 51% Attack - -A "51% attack" is an attack on a blockchain system where one party controls more than 50% of all mining or voting power. (Technically, the attack is slightly misnamed because _any_ amount over 50% is enough.) The XRP Ledger is not vulnerable to a 51% attack because it does not use mining in its consensus mechanism. The next closest analogue for the XRP Ledger is a [Sybil attack](#sybil-attacks), which would also be difficult. - - -## Validator Overlap Requirements - -For all participants in the XRP Ledger to agree on what they consider validated, they must start by choosing a set of trusted validators that are fairly similar to the sets chosen by everyone else. In the worst case, less than about 90% overlap could cause some participants to diverge from each other. For that reason, Ripple publishes a signed list of recommended validators, including trustworthy and well-maintained servers run by the company, industry, and community. - -By default, XRP Ledger servers are configured to use a validator list site run by Ripple. The site provides a list of recommended validators (also known as a recommended _Unique Node List_, or UNL), which Ripple updates periodically. Servers configured this way trust all validators in the latest version of the list, which ensures 100% overlap with others also using the same list. The default configuration includes a public key that verifies the authenticity of the site's contents. In case the site goes down, servers in the XRP Ledger's peer-to-peer network can directly relay the signed updates to the list among themselves. - -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.md) page. \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/xrpl/consensus-research.md b/content/concepts/understanding-xrpl/xrpl/consensus-research.md deleted file mode 100644 index 5e10942daf..0000000000 --- a/content/concepts/understanding-xrpl/xrpl/consensus-research.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -html: consensus-research.html -parent: consensus.html -blurb: Ripple researches both the theoretical and the practical limits of the XRP Ledger's consensus protocols. -labels: - - 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: - -| Date | Title | Authors | Summary | -|---|---|---|---| -| 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. | \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/xrpl/consensus-structure.ja.md b/content/concepts/understanding-xrpl/xrpl/consensus-structure.ja.md deleted file mode 100644 index cb83c4f4d4..0000000000 --- a/content/concepts/understanding-xrpl/xrpl/consensus-structure.ja.md +++ /dev/null @@ -1,216 +0,0 @@ ---- -html: consensus.html -parent: consensus-network.html -blurb: XRP Ledgerにおけるコンセンサスの役割について理解を深めましょう。 -labels: - - ブロックチェーン ---- -# コンセンサス - -_著者: Dave Cohen、David Schwartz、Arthur Britto_ - -この記事では、XRP Ledgerの概要や格納される情報、[トランザクション](transaction-formats.html)によってレジャー（台帳）が変化する様子について説明します。 - -XRP Ledger上でアプリケーションを構築する場合は、XRP Ledger APIの動作や、その動作によってもたされる影響を知っておくために、このプロセスを理解することが重要です。 - - -## まえがき - -ピアツーピアサーバーのXRP Ledgerネットワークは世界で共有されている台帳であり、ここから、アプリケーションはこの台帳の内容の状態に関して信頼できる情報を得ることができます。この状態に関する情報には以下の内容が含まれます。 - -- 各[アカウント](accounts.html)の設定 -- XRPおよび[発行済み通貨](issued-currencies.html)の残高 -- 分散型取引所でのオファー（注文） -- ネットワーク設定（例: [トランザクションコスト](transaction-cost.html)と[準備金](reserves.html)の金額） -- タイムスタンプ - -レジャーバージョンに含まれるデータの詳細な技術説明については、[レジャーフォーマットのリファレンス](ledger-data-formats.html)を参照してください。 - -[![図1: XRP Ledgerの要素](img/anatomy-of-a-ledger-complete.ja.png)](img/anatomy-of-a-ledger-complete.ja.png) - -_図1: XRP Ledgerの要素_ - -XRP Ledgerでは、数秒ごとに新しいレジャーバージョンが作成されます。あるレジャーバージョンの内容にネットワークが同意すると、そのレジャーバージョンは _検証済み_ となり、その内容が変更されることはありません。それ以前の検証済みのレジャーバージョンによって、レジャー履歴が形成されます。検証済みの最新のレジャーも、少し前の時点のネットワークの状態を表しており、履歴の一部となります。現時点で、ネットワークは次のレジャーバージョンに適用されてファイナライズされる可能性のあるトランザクションを評価しています。この評価が行われている間、ネットワークには、検証前のレジャーバージョン候補が存在します。 - -[![図2: XRP Ledgerの履歴](img/ledger-history.ja.png)](img/ledger-history.ja.png) - -_図2: XRP Ledgerの履歴_ - -レジャーバージョンには2つの識別子があります。1つ目の識別子は、そのレジャーバージョンの _レジャーインデックス_ です。レジャーバージョンの番号は1つずつ増加します。例えば、現行のレジャーバージョンのレジャーインデックスが100の場合、1つ前はレジャーインデックス99、1つ後はレジャーインデックスは101です。もう1つの識別子は _レジャーハッシュ_ で、レジャーの内容のデジタル指紋を表します。 - -サーバーがレジャーに適用するトランザクションを提案するときに、内容がわずかに異なる複数の候補レジャーバージョンが作成される場合があります。このような候補レジャーバージョンでは、レジャーインデックスは同じですがレジャーハッシュが異なります。多くの候補のうち、検証済みとなるのは1つだけです。それ以外の候補レジャーバージョンはすべて、破棄されます。そのため、履歴内の各レジャーインデックスに対して存在する検証済みのレジャーハッシュは1つのみです。 - -レジャーに対するユーザーレベルの変更は、トランザクションによってなされます。[トランザクション](transaction-formats.html)の例としては、決済、アカウントの設定またはトラストラインの変更、取引のオファー（注文）などがあります。各トランザクションは、レジャーに対する1つ以上の変更を承認するものであり、アカウント所有者によって暗号署名されます。アカウントの変更を承認したり、レジャーのそれ以外の内容を変更したりするには、トランザクションだけが唯一の方法です。 - -各レジャーバージョンには、一連のトランザクションと、そのようなトランザクションに関するメタデータも含まれています。それらのトランザクションは、新しいレジャーバージョンを作成するために前のバージョンのレジャーに適用されたものです。メタデータには、レジャーの状態データに対する、トランザクションの影響が正確に記録されています。 - -[![図3: レジャーバージョンに適用されるトランザクション](img/ledger-changes.ja.png)](img/ledger-changes.ja.png) - -_図3: レジャーバージョンに適用されるトランザクション_ - -レジャーインスタンスに含まれる一連のトランザクションはそのレジャーに記録され、XRP Ledger履歴の監査を可能としています。レジャーN+1のアカウント残高がレジャーNのアカウント残高と異なる場合、レジャーN+1にはその変更の原因となったトランザクションが含まれます。 - -検証済みのレジャー内に出現するトランザクションは、レジャーの変更に成功したか、または要求されたアクションを実行せずに処理された可能性があります。成功したトランザクションには、要求された変更がレジャーに適用されたことを示す**tesSUCCESS** [結果コード](transaction-results.html)が含まれます。レジャー内の失敗したトランザクションには、**tec**クラスの結果コードが含まれます。1 - -レジャーに含まれるトランザクションでは必ず、[トランザクションコスト](transaction-cost.html)として一部のXRPが消却されます。この場合、**tes**コードまたは**tec**コードが含まれていたかどうかは関係ありません。消却するXRPの正確な量は、署名されたトランザクションの手順で定義されます。 - -**tes**クラスや**tec**クラスの結果コード以外に、**ter**クラス、**tef**クラス、および**tem**クラスのコードがあります。後者の3つは、APIの呼び出しによって返された暫定的な失敗を示します。レジャーには、**tes**および**tec**のコードのみ表示されます。レジャーに含まれていないトランザクションによって、レジャーの状態（XRP残高を含む）が影響を受けることはありませんが、暫定的に失敗したトランザクションが後で成功する可能性があります。 - -[`rippled` API](http-websocket-apis.html)を使用する場合、レジャーに含めるように提案された候補トランザクションと、検証済みのレジャーに含まれる検証済みのトランザクションをアプリケーションで区別する必要があります。検証済みのレジャー内にあるトランザクションの結果のみが不変です。検証済みのレジャーには、候補トランザクションが含まれる場合と含まれない場合があります。 - -重要: 一部の[`rippled` API](http-websocket-apis.html)では、候補トランザクションに基づき暫定的な結果が返されます2。アプリケーションで、トランザクションの最終的な結果を判断する目的で暫定的な結果を使用するのは望ましくありません。最終的にトランザクションが成功したことを確実に知る唯一の方法は、そのトランザクションが検証済みのレジャー内にあり、かつ、結果コードがtesSUCCESSになるまで、トランザクションの状況を確認することです。トランザクションが検証済みレジャー内にあるが、結果コードがそれ以外の場合、トランザクションの失敗を意味します。トランザクションの[`LastLedgerSequence`](transaction-common-fields.html)で指定されたレジャーが検証済みにもかかわらず、そのトランザクションがそのレジャーまたはそれ以前の他のレジャー内にない場合、トランザクションは失敗しており、どのレジャーにも表示されません。検証済みのレジャー内に表示されるトランザクションの場合にのみ、結果は最終的なものとなります。それ以外の場合、このドキュメントで後述するように、`LastLedgerSequence`の制限により、表示されることはありません。 - -## XRP Ledgerプロトコル - コンセンサスと検証 - -ピアツーピアのXRP Ledgerネットワークは、トランザクションを承認して処理する多数の独立したXRP Ledgerサーバー（通常、[`rippled`](xrpl-servers.html)を実行）で構成されています。クライアントアプリケーションは、トランザクションに署名してXRP Ledgerサーバーに送信します。サーバーは、これらの候補トランザクションを処理するためにネットワーク内を中継します。クライアントアプリケーションには、モバイルおよびウェブウォレット、金融機関へのゲートウェイ、電子取引プラットフォームなどがあります。 - -[![図4: XRP Ledgerプロトコルの参加者](img/xrp-ledger-network.ja.png)](img/xrp-ledger-network.ja.png) - -_図4: XRP Ledgerプロトコルの参加者_ - -トランザクションを受信、中継、処理するサーバーは、追跡サーバーとバリデータのいずれかです。追跡サーバーの主な機能には、クライアントからのトランザクションの分散やレジャーに関する照会への応答が含まれます。検証サーバーは、追跡サーバーと同じ機能を実行し、さらにレジャー履歴を進めます3。 - -クライアントアプリケーションによって送信されたトランザクションを受け入れるときに、各追跡サーバーは最後に検証されたレジャーを開始点として使用します。受け入れられたトランザクションは候補トランザクションとなります。サーバーから候補トランザクションがそれぞれのピアに中継され、候補トランザクションがネットワーク全体に伝達されます。理想的には、各候補トランザクションはすべてのサーバーに伝達される必要があります。その結果、各サーバーは最後に検証されたレジャーに同じ一連のトランザクションを適用できる可能性が高くなります。しかし、トランザクションが伝達されるまでには時間がかかるため、サーバーは常に同じ候補トランザクションを処理するわけではありません。このことを考慮に入れて、XRP Ledgerでは、コンセンサスと呼ばれるプロセスを使用して、同一のトランザクションが処理され、ピアツーピアのXRP Ledgerネットワーク全体で検証済みのレジャーの一貫性が確保できるようにしています。 - -### コンセンサス - -ネットワーク内のサーバーは、候補トランザクションに関する情報を共有します。コンセンサスプロセスを通じて、バリデータは、候補トランザクションの特定のサブセットが次のレジャーで考慮されることに同意します。コンセンサスとは、サーバーが提案や一連の候補トランザクションを中継する反復プロセスです。サーバーは、選択されたバリデータの圧倒的多数4が同じ候補トランザクションのセットについて合意するまで、提案の通信と更新を行います。 - -コンセンサスの間、各サーバーは、そのサーバーの信頼できるバリデータ（ _ユニークノードリスト（UNL）_ ）と呼ばれる特定のサーバー群からの提案を評価します。5信頼できるバリデータとは、提案を評価するサーバーを欺こうと共謀しない、全体として「信頼できる」ネットワークのサブセットを表します。この「信頼」の定義では、選択された個々のバリデータが信頼されている必要はありません。バリデータの選択は、ネットワークに中継されたデータを改ざんする組織的な試みで共謀しないという想定に基づいて行われます6。 - -[![図5: バリデータによるトランザクションセットの提案と修正](img/consensus-rounds.ja.png)](img/consensus-rounds.ja.png) - -_図5: バリデータによるトランザクションセットの提案と修正 - コンセンサスの開始時点で、バリデータ毎に異なるトランザクションセットを持っている可能性があります。後のラウンドで、サーバーは現在の提案を信頼できるバリデータの提案と一致するように変更します。このプロセスでは、現在議論しているレジャーバージョンに適用するトランザクションと、それ以降のレジャーバージョンに適用するトランザクションを決定します。_ - -合意済みの提案に含まれていない候補トランザクションは、その後も候補トランザクションとして残ります。これらは次のレジャーバージョンで再度検討される可能性があります。通常、1つのレジャーバージョンから除外されたトランザクションは、次のレジャーバージョンに含まれます。 - -状況によっては、いつまでもコンセンサスに達することができないトランザクションもあります。そのような状況として、ネットワークが、必要な[トランザクションコスト](transaction-cost.html)を、トランザクションで指定されたものよりも高い値に変更している場合が考えられます。将来のある時点でこの手数料が引き下げられると、そのトランザクションが成功する可能性があります。トランザクションの成功または失敗が一定時間内に確定するように、トランザクションが特定のレジャーインデックスによって一定時間処理されない場合は期限切れになるように設定することができます。詳細は、[信頼できるトランザクションの送信](reliable-transaction-submission.html)を参照してください。 - -### 検証 - -検証は、全体のコンセンサスプロセスの第2段階です。このプロセスでは、すべてのサーバーで同じ結果が得られたことを確認し、あるレジャーバージョンが最終バージョンとして宣言されます。まれに、第一段階の[コンセンサスプロセスが失敗する場合](consensus-principles-and-rules.html#コンセンサス失敗の可能性)があります。検証によって後で確認が行われるため、サーバーは結果を確認し、それに応じて対処することができます。 - -検証は、大きく分けて次の2つの部分に分かれます。 - -- 合意済みのトランザクションセットから結果として生じるレジャーバージョンを計算する。 -- 結果を比較し、十分に信頼できるバリデータが同意した場合はレジャーバージョンの検証済みを宣言する。 - -#### 検証の計算と共有 - -コンセンサスプロセスが完了すると、各サーバーは合意済みの一連のトランザクションから新しいレジャーを個別に計算します。各サーバーは、同じ規則に従って結果を次のように計算します。 - -1. 一つ前の検証済みのレジャーから始めます。 - -2. すべてのサーバーが同じ方法で処理できるように、合意済みのトランザクションセットを _正規順序_ で並べ変えます。 - - [正規順序](https://github.com/ripple/rippled/blob/8429dd67e60ba360da591bfa905b58a35638fda1/src/ripple/app/misc/CanonicalTXSet.cpp#L25-L36)は、トランザクションを受け取った順序ではありません（サーバーが同じトランザクションを異なる順序で受け取る可能性があるため）。参加者がトランザクションの順序付けで競合しないように、故意に操作するのが困難な正規順序を使います。 - -3. 指示に従って、各トランザクションを順番に処理します。それに応じてレジャーの状態データを更新します。 - - トランザクションを正常に実行できない場合は、[`tec`クラス結果コード](tec-codes.html)を持つトランザクションを含めます。1 - - 特定の「再試行可能な」トランザクションの失敗に対しては、同じレジャーバージョンの他のトランザクションが実行された後に再試行されるように、そのトランザクションを正規順序の最後に移動します。 - -4. 適切なメタデータでレジャーヘッダーを更新します。 - - これには、レジャーインデックス、前に検証済みのレジャーの識別ハッシュ（このレジャーの「親」）、このレジャーバージョンの予定終了時刻、このレジャーの内容の暗号化ハッシュなどのデータが含まれます。 - -5. 新しいレジャーバージョンの識別用ハッシュを計算します。 - -[![図7: XRP Ledgerサーバーでレジャー検証を計算する](img/consensus-calculate-validation.ja.png)](img/consensus-calculate-validation.ja.png) - -_図7: XRP Ledgerサーバーでレジャー検証を計算する - 各サーバーは、同意済みのトランザクションを前の検証済みレジャーに適用します。バリデータは結果をネットワーク全体に送信します。_ - -#### 結果を比較する - -バリデータはそれぞれ、計算したレジャーバージョンのハッシュを含む署名付きメッセージの形式で結果を中継します。 _検証_ と呼ばれるこれらのメッセージによって、各サーバーで計算したレジャーとそのピアのレジャーを比較することができます。 - -[![図8: 圧倒的多数のピアが同じ結果を計算するとレジャーが検証される](img/consensus-declare-validation.ja.png)](img/consensus-declare-validation.ja.png) - -_図8: 圧倒的多数のピアが同じ結果を計算するとレジャーが検証される - 各サーバーは、計算されたレジャーを、選択されたバリデータから受け取ったハッシュと比較します。一致しない場合、サーバーは正しいレジャーを再計算または取得する必要があります。_ - -ネットワーク内のサーバーは、圧倒的多数のピアが同じ検証ハッシュに署名してそれをブロードキャストしたときに、そのレジャーインスタンスを検証済みと認識します 7。それ以降のトランザクションは、レジャーインデックスN+1の更新および検証済みのこのレジャーに適用されます。 - -サーバーが少数で、ピアと異なるレジャーを計算した場合、計算したレジャーは無視されます8。正しいレジャーを再計算するか、必要に応じて正しいレジャーを取得します。 - -ネットワークで、検証に関する圧倒的多数の同意が得られない場合、コンセンサスプロセスで一貫した提案を作成するにはトランザクション量が多すぎるか、ネットワーク遅延が大きすぎることを意味します。この場合、サーバーはコンセンサスプロセスを繰り返します。コンセンサスが始まってから時間が経過するにつれて、各コンセンサスラウンドで不一致は減少するため、過半数のサーバーが同じ候補トランザクションのセットを受け取った可能性が高くなります。XRP Ledgerは、これらの状況に応じて[トランザクションコスト](transaction-cost.html)と、コンセンサスを待つ時間を動的に調整します。 - -検証について圧倒的多数の合意が得られると、サーバーは検証済みの新しいレジャー、レジャーインデックスN+1との作業に入ることができます。最後のラウンドに含まれなかった候補トランザクションと、その間に送信された新しいトランザクションに対して、コンセンサスと検証プロセスが繰り返されます9。 - - -## 要点 - -XRP Ledgerに送信されたトランザクションはすぐには処理されません。一定期間、各トランザクションは候補状態になります。 - -単一トランザクションのライフサイクルは次のとおりです。 - -- アカウント所有者によってトランザクションが作成され、署名されます。 -- トランザクションがネットワークに送信されます。 - - 書式が正しくないトランザクションはその場で拒否される可能性があります。 - - 書式が正しいトランザクションは暫定的に成功し、その後で失敗する可能性があります。 - - 書式が正しトランザクションは暫定的に失敗し、その後で成功する可能性があります。 -- コンセンサスの間、トランザクションはレジャーに含まれます。 - - コンセンサスラウンドが成功すると、レジャーが有効になります。 - - コンセンサスラウンドが失敗すると、成功するまでコンセンサスプロセスが繰り返されます。 -- 検証済みレジャーには、トランザクションとレジャーの状態への反映が含まれます。 - -アプリケーションでは、候補トランザクションの暫定的な結果ではなく、検証済みのレジャーの情報のみを信頼してください。一部の[`rippled` API](http-websocket-apis.html)では、トランザクションの暫定的な結果が最初に返されます。トランザクションの結果が不変になるのは、そのトランザクションが検証済みレジャーに含まれている場合か、トランザクションに`LastLedgerSequence`が含まれ、そのレジャーインデックス以下の検証済みレジャーに出現しない場合に限られます。 - -トランザクションを送信するアプリケーションのベストプラクティスは次のとおりです。 - -- `LastLedgerSequence`パラメーターを使用して、トランザクションが確定的かつ迅速な方法で検証されるか、失敗するようにします。 -- 検証されたレジャーでトランザクションの結果を確認します。 - - トランザクションを含むレジャーが検証されるか、`LastLedgerSequence`が経過するまで、結果は暫定的です。 - - 結果コードが**tesSUCCESS**で`"validated": true`のトランザクションは、恒久的に成功しています。 - - 結果コードがそれ以外の場合で`"validated": true`のトランザクションは、恒久的に失敗しています。 - - トランザクションの`LastLedgerSequence`によって識別された検証済みレジャーを含め、これまでの検証済みのレジャーに出現しないトランザクションは、恒久的に失敗しています。 - - このようなケースを検出するために、レジャーの継続的な履歴を有するサーバーを使用には注意してください10。 - - `LastLedgerSequence`で識別されるレジャーが検証されるまで、トランザクションの状態を繰り返し確認する必要がある場合があります。 - -## 関連項目 - -- **コンセプト:** - - [コンセンサスについて](intro-to-consensus.html) - - [コンセンサスの研究](consensus-research.html) - - [Rippleコンセンサスの動画](https://www.youtube.com/watch?v=pj1QVb1vlC0) -- **チュートリアル:** - - [信頼できるトランザクションの送信](reliable-transaction-submission.html) - - [バリデータとしての`rippled`の実行](run-rippled-as-a-validator.html) -- **リファレンス:** - - [レジャーフォーマットのリファレンス](ledger-data-formats.html) - - [トランザクションフォーマットのリファレンス](transaction-formats.html) - - [Consensus_infoメソッド][] - - [Validator_list_sitesメソッド][] - - [Validatorsメソッド][] - - - - - -## 脚注 - -1 – [**tec**結果コード](tec-codes.html)を持つトランザクションでは、リクエストされたアクションは実行されませんが、レジャーには影響します。ネットワークの悪用を防ぎ、トランザクションの分散コストを賄うために、XRPの[トランザクションコスト](transaction-cost.html)が消却されます。同じ送信者によって同時刻に送信された他のトランザクションをブロックしないようにするには、送信者のアカウントの[シーケンス番号](basic-data-types.html#アカウントシーケンス)を都度増やしてゆきます。`tec`クラスの結果を持つトランザクションは、期限切れのオブジェクトや資金のない取引注文を削除するなどのメンテナンスも行います。 - -2 – 例えば、Aliceが100ドルを持っていて、全額をBobに送信するシナリオを考えてみましょう。アプリケーションは最初にPaymentトランザクションを送信し、Aliceの残高を確認したらすぐにAPIから0ドルが返されます。この値は、候補トランザクションの暫定結果に基づいています。支払いが失敗し、Aliceの残高が100ドルのままになる（または他のトランザクションによって別の金額になる）場合があります。AliceからBobへの支払いが成功したことを確実に知る唯一の方法は、そのトランザクションが検証済みのレジャー内にあり、かつ結果コードが**tesSUCCESS**になるまで、トランザクションの状況を確認することです。トランザクションが検証済みレジャーにあるが、結果コードが異なる場合、支払いは失敗したことを意味します。 - -3 – 厳密に言えば、バリデータは追跡サーバーのサブセットです。同じ機能を提供することに加えて、「検証」メッセージを送信します。追跡サーバーは、レジャー履歴全体を保持しているか、部分的なレジャー履歴を保持しているかによって、さらに分類することができます。 - -4 – トランザクションを認識したピアの割合（%）がしきい値を下回った場合、コンセンサスのラウンドは失敗します。各ラウンドは反復プロセスです。第1ラウンドの開始時には、少なくともピアの50%が同意する必要があります。コンセンサスラウンドの最終的なしきい値は80%の合意です。これらの具体的な値は変更される可能性があります。 - -5 – 各サーバーは独自の信頼できるバリデータを定義しますが、ネットワークの一貫性は、様々なサーバーで重複の度合いが高いバリデータのリストが選択されるかどうかにかかっています。このため、Rippleでは推奨するバリデータのリストを公開しています。 - -6 – 共謀しないとされるバリデータからだけでなくすべてのバリデータからの提案が評価される場合は、悪意のある攻撃者によって、無効なトランザクションが導入されたり、提案から有効なトランザクションが除外されたりする可能性があります。選択されたバリデータリストによって、[シビル攻撃](consensus-protections.html#シビル攻撃)から保護することができます。 - -7 – 2014年11月の時点で、圧倒的多数を表すしきい値として、少なくともピアの80%が検証すべきレジャーに同意する必要があります。これは、コンセンサスのラウンドで要求される割合と同じです。いずれのしきい値も変更される可能性があり、同じである必要はありません。 - -8 – 実際には、サーバーは自身が少数であることを検知してから、すべてのピアの検証を受け取ります。ピアの20%以上から不一致の検証を受け取ると、その検証がしきい値の80%を満たしていないことが分かります。その時点で、レジャーの再計算を始めることができます。 - -9 – 実際には、効率的に実行できるように、検証の完了前に新しいコンセンサスのラウンドが開始されます。 - -10 – `rippled`サーバーはレジャーの履歴全体がなくてもAPIリクエストに応答することができます。サービスやネットワーク接続が中断すると、そのサーバーのレジャー履歴にレジャーの不足や誤差が生じることがあります。時間の経過とともに、`rippled`によってその誤差は埋まります（そのように設定されている場合）。欠落しているトランザクションを検証する場合は、トランザクションが送信されてからLastLedgerSequenceまでの連続した完全なレジャーを持つサーバーに照らして検証することが重要です。特定のサーバーで利用できるcomplete_ledgersを判断するには、RPCサーバーの状態を使用します。 - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/understanding-xrpl/xrpl/consensus-structure.md b/content/concepts/understanding-xrpl/xrpl/consensus-structure.md deleted file mode 100644 index a81a73204c..0000000000 --- a/content/concepts/understanding-xrpl/xrpl/consensus-structure.md +++ /dev/null @@ -1,220 +0,0 @@ ---- -html: consensus-structure.html -parent: consensus.html -blurb: Understand the design decisions for consensus in the XRP Ledger. -labels: - - Blockchain ---- - -# Consensus Structure - -_Written by Dave Cohen, David Schwartz, and Arthur Britto._ - -This article provides a high level overview of the XRP Ledger, the information it stores, and how [transactions](transaction-formats.html) result in changes to the ledger. - -When building applications on the XRP Ledger, it is important to understand this process, so as not to be surprised by the behavior of XRP Ledger APIs and their effects. - - -## Introduction - -The peer-to-peer XRP Ledger network provides a worldwide, shared ledger, which gives applications authoritative information about the state of its contents. This state information includes: - -- settings for each [account](accounts.html) -- balances of XRP and [tokens](tokens.html) -- offers in the distributed exchange -- network settings, such as [transaction costs](transaction-cost.html) and [reserve](reserves.html) amounts -- a timestamp - -For a full, technical description of which data is included in a ledger version, see the [Ledger Format Reference](ledger-data-formats.html). - -{{ include_svg("img/anatomy-of-a-ledger-complete.svg", "Figure 1: XRP Ledger Elements") }} - -_Figure 1: XRP Ledger Elements_ - -The XRP Ledger has a new ledger version every several seconds. When the network agrees on the contents of a ledger version, that ledger version is _validated_, and its contents can never change. The validated ledger versions that preceded it form the ledger history. Even the most recent validated ledger is part of history, as it represents the state of the network as of a short time ago. In the present, the network is evaluating transactions which may be applied and finalized in the next ledger version. While this evaluation is happening, the network has candidate ledger versions that are not yet validated. - -{{ include_svg("img/ledger-history.svg", "Figure 2: XRP Ledger History")}} - -_Figure 2: XRP Ledger History_ - -A ledger version has two identifiers. One identifier is its _ledger index_. Ledger versions are numbered incrementally. For example, if the current ledger version has ledger index of 100, the previous has ledger index 99 and the next has ledger index 101. The other identifier is a _ledger hash_, which is a digital fingerprint of the ledger's contents. - -As servers propose transactions to apply to the ledger, they may create several candidate ledger versions with slightly different contents. These candidate ledger versions have the same ledger index but different ledger hashes. Of the many candidates, only one can become validated. All the other candidate ledger versions are discarded. Thus, there is exactly one validated ledger hash for each ledger index in history. - -User level changes to the ledger are the results of transactions. Examples of [transactions](transaction-formats.html) include payments, changes to account settings or trust lines, and offers to trade. Each transaction authorizes one or more changes to the ledger, and is cryptographically signed by an account owner. Transactions are the only way to authorize changes to an account, or to change anything else in the ledger. - -Each ledger version also contains a set of transactions and metadata about those transactions. The transactions it includes are only the ones that have been applied to the previous ledger version to create the new ledger version. The metadata records the exact effects of the transaction on the ledger's state data. - -{{ include_svg("img/ledger-changes.svg", "Figure 3: Transactions Applied to Ledger Version")}} - -_Figure 3: Transactions Applied to Ledger Version_ - -The set of transactions included in a ledger instance are recorded in that ledger and allow audits of the XRP Ledger history. If an account balance is different in ledger N+1 than it was in ledger N, then ledger N+1 contains the transaction(s) responsible for the change. - -Transactions that appear in a validated ledger may have succeeded in changing the ledger, or may have been processed without doing the requested action. Successful transactions have the **`tesSUCCESS`** [result code](transaction-results.html) which indicates the requested changes are applied to the ledger. Failed transactions in the ledger have **`tec`** class result codes.1 - -All transactions included in a ledger destroy some XRP as a [transaction cost](transaction-cost.html), regardless of whether they had a **`tes`** or **`tec`** code. The exact amount of XRP to destroy is defined by the signed transaction instructions. - -There are other classes of result codes besides **`tes`** and **`tec`**. Any other classes of result code indicate provisional failures returned by API calls. Only **`tes`** and **`tec`** codes appear in ledgers. Transactions that are not included in ledgers cannot have any effect on the ledger state (including XRP balances), but transitions that provisionally failed may still end up succeeding. - -When working with [XRP Ledger APIs](http-websocket-apis.html), applications must distinguish between candidate transactions proposed for inclusion in a ledger versus validated transactions which are included in a validated ledger. Only transaction results found in a validated ledger are immutable. A candidate transaction may eventually be included in a validated ledger, or it may not. - -Important: Some [`rippled` APIs](http-websocket-apis.html) provide provisional results, based on candidate transactions 2. Applications should never rely on provisional results to determine the final outcome of a transaction. The only way to know with certainty that a transaction finally succeeded is to check the status of the transaction until it is both in a validated ledger and has result code `tesSUCCESS`. If the transaction is in a validated ledger with any other result code, it has failed. If the ledger specified in a transaction’s [`LastLedgerSequence`](transaction-common-fields.html) has been validated, yet the transaction does not appear in that ledger or any before it, then that transaction has failed and can never appear in any ledger. An outcome is final only for transactions that appear in a validated ledger or can never appear because of `LastLedgerSequence` restrictions as explained later in this document. - -## The XRP Ledger Protocol – Consensus and Validation - -The peer-to-peer XRP Ledger network consists of many independent XRP Ledger servers (typically running [`rippled`](xrpl-servers.html)) that accept and process transactions. Client applications sign and send transactions to XRP Ledger servers, which relay these candidate transactions throughout the network for processing. Examples of client applications include mobile and web wallets, gateways to financial institutions, and electronic trading platforms. - -{{ include_svg("img/xrp-ledger-network.svg", "Figure 4: Participants in the XRP Ledger Protocol") }} - -_Figure 4: Participants in the XRP Ledger Protocol_ - -The servers that receive, relay and process transactions may be either tracking servers or validators. The major functions of tracking servers include distributing transactions from clients and responding to queries about the ledger. Validating servers perform the same functions as tracking servers and also contribute to advancing the ledger history. 3. - -While accepting transactions submitted by client applications, each tracking server uses the last validated ledger as a starting point. The accepted transactions are candidates. The servers relay their candidate transactions to their peers, allowing the candidate transactions to propagate throughout the network. Ideally, each candidate transaction would be known to all servers, allowing each to consider the same set of transactions to apply to the last validated ledger. As transactions take time to propagate however, the servers do not work with the same set of candidate transactions at all times. To account for this, the XRP Ledger uses a process called consensus to ensure that the same transactions are processed and validated ledgers are consistent across the peer-to-peer XRP Ledger network. - -### Consensus - -The servers on the network share information about candidate transactions. Through the consensus process, validators agree on a specific subset of the candidate transactions to be considered for the next ledger. Consensus is an iterative process in which servers relay proposals, or sets of candidate transactions. Servers communicate and update proposals until a supermajority 4 of chosen validators agree on the same set of candidate transactions. - -During consensus, each server evaluates proposals from a specific set of servers, known as that server's trusted validators, or _Unique Node List (UNL)_.5 Trusted validators represent a subset of the network which, when taken collectively, is "trusted" not to collude in an attempt to defraud the server evaluating the proposals. This definition of "trust" does not require that each individual chosen validator is trusted. Rather, validators are chosen based on the expectation they will not collude in a coordinated effort to falsify data relayed to the network 6. - -{{ include_svg("img/consensus-rounds.svg", "Figure 5: Validators Propose and Revise Transaction Sets") }} - -_Figure 5: Validators Propose and Revise Transaction Sets — At the start of consensus, validators may have different sets of transactions. In later rounds, servers modify their proposals to match what their trusted validators proposed. This process determines which transactions they should apply to the ledger version currently being discussed, and which they should postpone for later ledger versions._ - -Candidate transactions that are not included in the agreed-upon proposal remain candidate transactions. They may be considered again in for the next ledger version. Typically, a transaction which is omitted from one ledger version is included in the next ledger version. - -In some circumstances, a transaction could fail to achieve consensus indefinitely. One such circumstance is if the network increases the required [transaction cost](transaction-cost.html) to a value higher than the transaction provides. The transaction could potentially succeed if the fees are lowered at some point in the future. To ensure that a transaction either succeeds or fails within a limited amount of time, transactions can be set to expire if they are not processed by a certain ledger index. For more information, see [Reliable Transaction Submission](reliable-transaction-submission.html). - -### Validation - -Validation is the second stage of the overall consensus process, which verifies that the servers got the same results and declares a ledger version final. In rare cases, the first stage of [consensus can fail](consensus-principles-and-rules.html#consensus-can-fail); validation provides a confirmation afterward so that servers can recognize this and act accordingly. - -Validation can be broken up into roughly two parts: - -- Calculating the resulting ledger version from an agreed-upon transaction set. -- Comparing results and declaring the ledger version validated if enough trusted validators agree. - -Each server in the network performs validation separately and locally; the consensus process can proceed to tentatively confirm transactions even if no ledger is validated from a given round. - - -#### Calculate and Share Validations - -When the consensus process completes, each server independently computes a new ledger from the agreed-upon set of transactions. Each server calculates the results by following the same rules, which can be summarized as follows: - -1. Start with the previous validated ledger. - -2. Place the agreed-upon transaction set in _canonical order_ so that every server processes them the same way. - - [Canonical order](https://github.com/ripple/rippled/blob/8429dd67e60ba360da591bfa905b58a35638fda1/src/ripple/app/misc/CanonicalTXSet.cpp#L25-L36) is not the order the transactions were received, because servers may receive the same transactions in different order. To prevent participants from competing over transaction ordering, canonical order is hard to manipulate. - -3. Process each transaction according to its instructions, in order. Update the ledger's state data accordingly. - - If the transaction cannot be successfully executed, include the transaction with a [`tec`-class result code](tec-codes.html).1 - - For certain "retriable" transaction failures, instead move the transaction to the end of the canonical order to be retried after other transactions in the same ledger version have executed. - -4. Update the ledger header with the appropriate metadata. - - This includes data such as the ledger index, the identifying hash of the previous validated ledger (this one's "parent"), this ledger version's approximate close time, and the cryptographic hashes of this ledger's contents. - -5. Calculate the identifying hash of the new ledger version. - -{{ include_svg("img/consensus-calculate-validation.svg", "Figure 7: An XRP Ledger Server Calculates a Ledger Validation") }} - -_Figure 7: An XRP Ledger Server Calculates a Ledger Validation — Each server applies agreed-upon transactions to the previous validated ledger. Validators send their results to the entire network._ - -#### Compare Results - -Validators each relay their results in the form of a signed message containing the hash of the ledger version they calculated. These messages, called _validations_, allow each server to compare the ledger it computed with those of its peers. - -{{ include_svg("img/consensus-declare-validation.svg", "Figure 8: Ledger is Validated When Supermajority of Peers Calculate the Same Result Result") }} - -_Figure 8: Ledger is Validated When Supermajority of Peers Calculate the Same Result — Each server compares its calculated ledger with the hashes received from its chosen validators. If not in agreement, the server must recalculate or retrieve the correct ledger._ - -Servers in the network recognize a ledger instance as validated when a supermajority of the peers have signed and broadcast the same validation hash 7. Going forward, transactions are applied to this updated and now validated ledger with ledger index N+1. - -In cases where a server is in the minority, having computed a ledger that differs from its peers, the server disregards the ledger it computed 8. It recomputes the correct ledger, or retrieves the correct ledger as needed. - -If the network fails to achieve supermajority agreement on validations, this implies that transaction volume was too high or network latency too great for the consensus process to produce consistent proposals. In this case, the servers repeat the consensus process for a new ledger version. As time passes since consensus began, it becomes increasingly likely that a majority of the servers have received the same set of candidate transactions, as each consensus round reduces disagreement. The XRP Ledger dynamically adjusts [transaction costs](transaction-cost.html) and the time to wait for consensus in response to these conditions. - -Once they reach supermajority agreement on validations, the servers work with the new validated ledger, ledger index N+1. The consensus and validation process repeats 9, considering candidate transactions that were not included in the last round along with new transactions submitted in the meantime. - - -## Key Takeaways - -Transactions submitted to the XRP Ledger are not processed instantaneously. For a period of time, each transaction remains a candidate. - -The lifecycle of a single transaction is as follows: - -- A transaction is created and signed by an account owner. -- The transaction is submitted to the network. - - Badly formed transactions may be rejected immediately. - - Well formed transactions may provisionally succeed, then later fail. - - Well formed transactions may provisionally fail, then later succeed. -- During consensus, the transaction is included in the ledger. - - The result of a successful consensus round is a validated ledger. - - If a consensus round fails, the consensus process repeats until it succeeds. -- The validated ledger includes the transaction and its effects on the ledger state. - -Applications should only rely on information in validated ledgers, not on the provisional results of candidate transactions. Some [`rippled` APIs](http-websocket-apis.html) initially return provisional results for transactions. The results of a transaction become immutable only when that transaction is included in a validated ledger, or the transaction includes `LastLedgerSequence` and does not appear in any validated ledger with that ledger index or lower. - -Best practices for applications submitting transactions include: - -- Use the `LastLedgerSequence` parameter to ensure that transactions validate or fail in a deterministic and prompt fashion. -- Check the results of transactions in validated ledgers. - - Until a ledger containing the transaction is validated, or `LastLedgerSequence` has passed, results are provisional. - - Transactions with result code **`tesSUCCESS`** and `"validated": true` have immutably succeeded. - - Transactions with other result codes and `"validated": true` have immutably failed. - - Transactions that fail to appear in any validated ledger up to and including the validated ledger identified by the transaction’s `LastLedgerSequence` have immutably failed. - - Take care to use a server with a continuous ledger history to detect this case 10. - - It may be necessary to check the status of a transaction repeatedly until the ledger identified by `LastLedgerSequence` is validated. - -## See Also - -- **Concepts:** - - [Introduction to Consensus](intro-to-consensus.html) - - [Consensus Research](consensus-research.html) - - [The Consensus Mechanism (YouTube)](https://www.youtube.com/watch?v=k6VqEkqRTmk&list=PLJQ55Tj1hIVZtJ_JdTvSum2qMTsedWkNi&index=2) -- **Tutorials:** - - [Reliable Transaction Submission](reliable-transaction-submission.html) - - [Run `rippled` as a Validator](run-rippled-as-a-validator.html) -- **References:** - - [Ledger Format Reference](ledger-data-formats.html) - - [Transaction Format Reference](transaction-formats.html) - - [consensus_info method][] - - [validator_list_sites method][] - - [validators method][] - - - - - -## Footnotes - -1 – Transactions with [**tec** result codes](tec-codes.html) do not perform the requested action, but do have effects on the ledger. To prevent abuse of the network and to pay for the cost of distributing the transaction, they destroy the XRP [transaction cost](transaction-cost.html). To not block other transactions submitted by the same sender around the same time, they increment the sending account's [sequence number](basic-data-types.html#account-sequence). Transactions with `tec`-class results sometimes also perform maintenance such as deleting expired objects or unfunded trade offers. - -2 – For example, consider a scenario where Alice has $100, and sends all of it to Bob. If an application first submits that payment transaction, then immediately after checks Alice’s balance, the API returns $0. This value is based on the provisional result of a candidate transaction. There are circumstances in which the payment fails and Alice’s balance remains $100 (or, due to other transactions, become some other amount). The only way to know with certainty that Alice’s payment to Bob succeeded is to check the status of the transaction until it is both in a validated ledger and has result code **`tesSUCCESS`**. If the transaction is in a validated ledger with any other result code, the payment has failed. - -3 – Strictly speaking, validators are a subset of tracking servers. They provide the same features and additionally send "validation" messages. Tracking servers may be further categorized by whether they keep full vs. partial ledger history. - -4 – Transactions fail to pass a round of consensus when the percentage of peers recognizing the transaction falls below a threshold. Each round is an iterative process. At the start of the first round, at least 50% of peers must agree. The final threshold for a consensus round is 80% agreement. These specific values are subject to change - -5 – Each server defines its own trusted validators, but the consistency of the network depends on different servers choosing lists that have a high degree of overlap. For this reason, Ripple publishes a list of recommended validators. - -6 – If proposals from all validators were evaluated, instead of exclusively from the validators chosen not to collude, a malicious attacker could run more validators to gain disproportionate power over the validation process, so they could introduce invalid transactions or omit valid transactions from proposals. The chosen validator list [defends against Sybil attacks](consensus-protections.html#sybil-attacks). - -7 – The supermajority threshold, as of November 2014, requires that at least 80% of peers must agree for a ledger to be validated. This happens to be the same percentage required by a round of consensus. Both thresholds are subject to change and need not be equal. - -8 – In practice, the server detects that it is in the minority before receiving validations from all peers. It knows when it receives non-matching validations from over 20% of peers that its validation cannot meet the 80% threshold. At that point, it can begin to recalculate a ledger. - -9 – In practice, the XRP Ledger runs more efficiently by starting a new round of consensus concurrently, before validation has completed. - -10 – A `rippled` server can respond to API requests even without a complete ledger history. Interruptions in service or network connectivity can lead to missing ledgers, or gaps, in the server’s ledger history. Over time, if configured to, `rippled` fills in gaps in its history. When testing for missing transactions, it is important to verify against a server with continuous complete ledgers from the time the transaction was submitted until its `LastLedgerSequence`. Use the [server_info method][] to determine which ledgers are available to a particular server. - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/understanding-xrpl/xrpl/consensus.md b/content/concepts/understanding-xrpl/xrpl/consensus.md deleted file mode 100644 index 6284949713..0000000000 --- a/content/concepts/understanding-xrpl/xrpl/consensus.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -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). - -[![Proposed Ledgers](img/consensus1-proposed-ledgers.png)](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. - -[![Proposed Ledgers](img/consensus2-agreed-transactions.png)](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. - -[![Proposed Ledgers](img/consensus3-updates.png)](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). diff --git a/content/concepts/understanding-xrpl/xrpl/double-spend.md b/content/concepts/understanding-xrpl/xrpl/double-spend.md deleted file mode 100644 index 1150acb361..0000000000 --- a/content/concepts/understanding-xrpl/xrpl/double-spend.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -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. \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/xrpl/fee-voting.md b/content/concepts/understanding-xrpl/xrpl/fee-voting.md deleted file mode 100644 index 11ebcb1734..0000000000 --- a/content/concepts/understanding-xrpl/xrpl/fee-voting.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -html: fee-voting.html -parent: consensus.html -blurb: Validators can vote for changes in the cost of transactions and reserve requirements. -labels: - - Ledgers ---- -# Fee Voting - -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 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. - -The parameters you can set are as follows: - -| Parameter | Description | Recommended Value | -|-----------|-------------|-------------------| -| `reference_fee` | Amount of XRP, in _drops_ (1 XRP = 1 million drops.), that must be destroyed to send the reference transaction, the cheapest possible transaction. The actual transaction cost is a multiple of this value, scaled dynamically based on the load of individual servers. | `10` (0.00001 XRP) | -| `account_reserve` | Minimum amount of XRP, in _drops_, that an account must have on reserve. This is the smallest amount that can be sent to fund a new account in the ledger. | `10000000` (10 XRP) | -| `owner_reserve` | How much more XRP, in _drops_, that an address must hold for _each_ object it owns in the ledger. | `2000000` (2 XRP) | - -## Voting Process - -Every 256th ledger is called a "flag" ledger. (A flag ledger is defined such that the `ledger_index` [modulo](https://en.wikipedia.org/wiki/Modulo_operation) `256` is equal to `0`.) In the ledger immediately before the flag ledger, each validator whose account reserve or transaction cost preferences are different than the current network setting distributes a "vote" message alongside its ledger validation, indicating the values that validator prefers. - -In the flag ledger itself, nothing happens, but validators receive and take note of the votes from other validators they trust. - -After counting the votes of other validators, each validator attempts to compromise between its own preferences and the preferences of a majority of validators it trusts. (For example, if one validator wants to raise the minimum transaction cost from 10 to 100, but most validators only want to raise it from 10 to 20, the one validator settles on the change to raise the cost to 20. However, the one validator never settles on a value lower than 10 or higher than 100.) If a compromise is possible, the validator inserts a [SetFee pseudo-transaction](setfee.html) into its proposal for the ledger following the flag ledger. Other validators who want the same change insert the same SetFee pseudo-transaction into their proposals for the same ledger. (Validators whose preferences match the existing network settings do nothing.) If a SetFee pseudo-transaction survives the consensus process to be included in a validated ledger, then the new transaction cost and reserve settings denoted by the SetFee pseudo-transaction take effect starting with the following ledger. - -In short: - -* **Flag ledger -1**: Validators submit votes. -* **Flag ledger**: Validators tally votes and decide what SetFee to include, if any. -* **Flag ledger +1**: Validators insert SetFee pseudo-transaction into their proposed ledgers. -* **Flag ledger +2**: New settings take effect, if a SetFee pseudo-transaction achieved consensus. - -## Maximum Fee Values - -The maximum possible values for the fees are limited by the internal data types stored in the [FeeSettings ledger object](feesettings.html). These values are as follows: - -| Parameter | Maximum Value (drops) | Maximum Value (XRP) -|-----------|-----------------------|----| -| `reference_fee` | 264 | (More XRP than has ever existed.) | -| `account_reserve` | 232 drops | Approximately 4294 XRP | -| `owner_reserve` | 232 drops | Approximately 4294 XRP | - - -## See Also - -- **Concepts:** - - [Amendments](amendments.html) - - [Transaction Cost](transaction-cost.html) - - [Reserves](reserves.html) \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/xrpl/invariant-checking.md b/content/concepts/understanding-xrpl/xrpl/invariant-checking.md deleted file mode 100644 index ebecc398a0..0000000000 --- a/content/concepts/understanding-xrpl/xrpl/invariant-checking.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -html: invariant-checking.html -parent: consensus.html -blurb: Understand what Invariant Checking is, why it exists, how it works, and what invariant checks are active. -labels: - - Blockchain - - Security ---- -# 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). - - - - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/understanding-xrpl/xrpl/ledger-close-times.md b/content/concepts/understanding-xrpl/xrpl/ledger-close-times.md deleted file mode 100644 index 21286e75e2..0000000000 --- a/content/concepts/understanding-xrpl/xrpl/ledger-close-times.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -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 - - - -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. - -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. diff --git a/content/concepts/understanding-xrpl/xrpl/ledger-structure.md b/content/concepts/understanding-xrpl/xrpl/ledger-structure.md deleted file mode 100644 index a4f10578f6..0000000000 --- a/content/concepts/understanding-xrpl/xrpl/ledger-structure.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -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. - -[![Ledger Version](img/ledger.png)](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. - -[![Sequence Number](img/ledger1-sequence-number.png)](img/ledger1-sequence-number.png) - -Each ledger version also identifies itself with a unique 64-character hexidecimal _hash number_. - -[![Hash Number](img/ledger2-unique-hash.png)](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. - -[![Parent Version](img/ledger3-parent-version.png)](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. - -[![Transactions](img/ledger4-transactions.png)](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. - -[![State Data](img/ledger5-state-data.png)](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. - -[![Available XRP](img/ledger6-available-xrp.png)](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. - -[![Close Flags](img/ledger7-close-flags.png)](img/ledger7-close-flags.png) - -_Close Time_ is the official timestamp when the final validated ledger version is created and closed. - -[![Close Time](img/ledger8-close-time.png)](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. - -[![Validated Ledger](img/ledger.png)](img/ledger.png) - - -## Tree Format - - - -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. - - - - - diff --git a/content/concepts/understanding-xrpl/xrpl/ledgers.md b/content/concepts/understanding-xrpl/xrpl/ledgers.md deleted file mode 100644 index 39c4f1f9a4..0000000000 --- a/content/concepts/understanding-xrpl/xrpl/ledgers.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -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. - diff --git a/content/concepts/understanding-xrpl/xrpl/negative-unl.md b/content/concepts/understanding-xrpl/xrpl/negative-unl.md deleted file mode 100644 index e182066a35..0000000000 --- a/content/concepts/understanding-xrpl/xrpl/negative-unl.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -html: negative-unl.html -parent: consensus.html -blurb: Negative UNL improves the network's ability to make progress during a partial outage. -labels: - - Ledgers ---- - -# Negative UNL - -_Added by the [NegativeUNL Amendment](known-amendments.html#negativeunl)._ - -The _Negative UNL_ is a feature of the XRP Ledger [consensus protocol](consensus.html) that improves _liveness_, the network's ability to make forward progress during a partial outage. Using the Negative UNL, servers adjust their effective UNLs based on which validators are currently online and operational, so that a new [ledger version](ledgers.html) can be declared _validated_ even if several trusted validators are offline. - -The Negative UNL has no impact on how the network processes transactions or what transactions' outcomes are, except that it improves the network's ability to declare outcomes final during some types of partial outages. - -## Background - -Each server in the XRP Ledger protocol has its own UNL (Unique Node List), a list of validators it trusts not to collude, and each server independently decides when a ledger version is validated based on the consensus when enough of its trusted validators agree on a new ledger version. (The default configuration uses a recommended UNL, signed by Ripple, consisting of validators Ripple considers to be sufficiently unique, reliable, and independent.) The standard quorum requirement is at least 80% of trusted validators must agree. - -If more than 20% of trusted validators go offline or become unable to communicate with the rest of the network, the network stops validating new ledgers because it cannot reach a quorum. This is a design choice to ensure that no transactions' outcomes can be changed after they are declared final. During such a situation, the remaining servers would still be online and could provide past and tentative transaction data, but could not confirm the final, immutable outcome of new transactions. - -However, this means that the network could stop making forward progress if a few widely-trusted validators went offline. As of 2020-10-06, there are 34 validators in Ripple's recommended UNL, so the network would stop making forward progress if 7 or more of them were offline. Furthermore, if one or two validators are out for an extended period of time, the network has less room for disagreement between the remaining validators, which can make it take longer to achieve a consensus. - -## Summary - -It is not reasonable to expect a diverse set of validators to maintain 100% uptime: many things can cause a validator to become temporarily unavailable, such as: hardware maintenance, software upgrades, internet connectivity problems, targeted attacks, human error, hardware failures, and outside circumstances like natural disasters. - -The "Negative UNL" is **a list of trusted validators which are believed to be offline or malfunctioning**, as declared by a consensus of the remaining validators. Validators in the Negative UNL are ignored for determining if a new ledger version has attained a consensus. - -When a validator that is on the Negative UNL comes back online and sends consistent validation votes, the remaining validators remove it from the Negative UNL after a short time. - -In cases where validators go offline one or two at a time, the remaining validators can use the Negative UNL to gradually adjust their effective UNLs, so that the network only ever needs 80% of the _online_ validators to achieve a quorum. To prevent the network from fragmenting, the quorum has a hard minimum of 60% of _total_ validators. - -If more than 20% of validators suddenly go offline all at once, the remaining servers cannot achieve the quorum necessary to validate a new ledger, so no new ledgers could be validated. However, those servers can still make tentative forward progress through successive consensus rounds. Over time, the remaining validators would continue to apply changes to the Negative UNL to the tentative ledgers and adjust their effective UNLs; eventually, if the situation persists, the network could resume fully validating ledgers by using the adjusted Negative UNL from the tentative ledger versions. - -Negative UNL has no effect on [stand-alone mode](rippled-server-modes.html) since the server does not use consensus in stand-alone mode. - - -## Enabling the Negative UNL for Testing - -Negative UNL functionality is currently available for testing on [Devnet](parallel-networks.html). You can test the Negative UNL feature by adding or modifying a `[features]` stanza in your `rippled.cfg` file, as described in [Connect Your rippled to a Parallel Network](connect-your-rippled-to-the-xrp-test-net.html). - - - -## How It Works - -The Negative UNL is closely tied to the [consensus process](consensus.html) and is designed with safeguards to maintain the continuity and reliability of the network in adverse situations. When all trusted validators are operating normally, the Negative UNL is unused and has no effect. When some validators appear to be offline or out of sync, the Negative UNL rules take effect. - -The Negative UNL is intentionally designed to change at a slow rate, to avoid any time-based disagreements about which Negative UNL should apply to a given ledger version's consensus process. - - -### Reliability Measurement - -Each server in the network has a UNL, the list of validators it trusts not to collude. (By default, a server's exact UNL is configured implicitly based on the recommended validator list Ripple publishes.) Each server tracks the _reliability_ of its trusted validators using a single metric: the percentage of the last 256 ledgers where the validator's validation vote matched the server's view of consensus. In other words: - -> Reliability = Va ÷ 256 - -Va is the total number of validation votes received from one validator for the last 256 ledgers that matched the server's own view of consensus. - -This metric of reliability measures the availability of a validator _and_ the behavior of that validator. A validator should have a high reliability score if it is in sync with the rest of the network and following the same protocol rules as the server scoring it. A validator's reliability score can suffer for any of the following reasons: - -- The validator's validation votes are not reaching the server due to poor network connectivity between them. -- The validator stops operating or gets overloaded. -- The validator is not following the same protocol rules as the server, for a variety of reasons. Possibilities include misconfiguration, software bugs, intentionally following a [different network](parallel-networks.html), or malicious behavior. - -If a validator's reliability is **less than 50%**, it is a candidate to be added to the Negative UNL. To be removed from the Negative UNL, a validator's reliability must be **greater than 80%**. - -Each server, including validators, independently calculates reliability scores for all of its trusted validators. Different servers may reach different conclusions about a validator's reliability, either because that validator's votes reached one server and not the other, or because they happened to disagree about specific ledgers more or less often. To add or remove a validator from the Negative UNL, a consensus of trusted validators must agree that a particular validator is above or below the reliability threshold. - -**Tip:** Validators track their own reliability, but do not propose adding themselves to the Negative UNL. A validator's measure of its own reliability cannot take into account how successfully its validation votes propagate through the network, so it is less dependable than measurements from outside servers. - - - -### Modifying the Negative UNL - -A ledger version is considered a _flag ledger_ if its ledger index is evenly divisible by 256. The Negative UNL can be modified only on flag ledgers. (Flag ledgers occur about once every 15 minutes on the XRP Ledger Mainnet. They may be farther apart in test networks that have low transaction volume.) - -Each flag ledger, all of the following changes apply: - -1. Changes to the Negative UNL that were scheduled in the previous flag ledger go into effect for the following ledger version. The consensus process for validating this flag ledger itself does not use the scheduled change. - - **Note:** This is one of the only times a ledger's state data is modified without a [transaction](transaction-basics.html) or [pseudo-transaction](pseudo-transaction-types.html). - -2. If the Negative UNL is not full, each server proposes adding **up to 1** validator to the Negative UNL from among its trusted validators with less than 50% reliability. -3. If the Negative UNL is not empty, each server proposes removing **up to 1** validator from the Negative UNL. A server can propose removing a validator from the Negative UNL for two reasons: - - It scores that validator with > 80% reliability. - - It does not have that validator in its UNL. (If a validator goes down permanently, this rule ensures that it gets removed from the on-ledger Negative UNL after it has been removed from servers' configured UNLs.) -4. If a proposed change to the Negative UNL achieves a consensus, the change is scheduled to go into effect in the following flag ledger. Up to one addition and one removal can be scheduled this way. - -The proposals to add and remove validators from the Negative UNL take the form of [UNLModify pseudo-transactions][]. The consensus process determines whether each pseudo-transaction achieves a consensus or gets thrown out, in the same way as other [pseudo-transactions](pseudo-transaction-types.html). In other words, for a particular validator to be added or removed from the Negative UNL, a consensus of servers must propose the same change. - -Scheduled and effective changes to the Negative UNL are tracked in the [NegativeUNL object](negativeunl.html) in the ledger's state data. - - -### Negative UNL Limits - -To prevent the network from fragmenting into two two or more sub-networks, the Negative UNL cannot reduce the quorum requirement to less than 60% of the _total_ UNL entries. To enforce this, a server considers the Negative UNL to be "full" if the number of validators on the Negative UNL is 25% (rounded down) of the number of validators in the server's configured UNL. (The 25% is based on the calculation that if 25% of validators are removed, an 80% consensus of the remaining 75% equals 60% of the original number.) If a server considers the Negative UNL to be full, it won't propose new additions to the Negative UNL; but, as usual, the final outcome depends on what a consensus of trusted validators do. - - -### Choosing From Multiple Candidate Validators - -It is possible that multiple validators may be candidates to be added to the Negative UNL, based on the reliability threshold. Since at most one validator can be added to the Negative UNL at a time, servers must choose which validator to propose adding. If there are multiple candidates, the server chooses which one to propose with the following mechanism: - -1. Start with the ledger hash of the parent ledger version. -0. Take the public key of each candidate validator. -0. Calculate the exclusive-or value (XOR) of the candidate validator and the parent ledger's hash. -0. Propose the validator the numerically lowest result of the XOR operation. - -If there are multiple candidates to be removed from the Negative UNL in a given flag ledger, servers use the same mechanism to choose among them. - -This mechanism has several useful properties: - -- It uses information that is readily available to all servers and can be calculated quickly. -- Most servers choose the same candidate even if they calculated slightly different scores for their trusted validators. This holds even if those servers disagree on which validator is _least_ or _most_ reliable. This even holds in many cases where the servers disagree on whether some validators are above or below the reliability thresholds. So, the network is likely to achieve a consensus on which validator to add or remove. -- It does not always give the same results each ledger version. If one proposed change to the Negative UNL fails to achieve a consensus, the network does not get stuck with some servers trying and failing to add or remove that one validator every time. The network can attempt to add or remove a different candidate to the Negative UNL in a later flag ledger. - - -### Filtering Validations - -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. - -The Negative UNL has no impact on the other parts of the consensus process, such as choosing which transactions to include in the proposed transaction set. Those steps always rely on the configured UNL, and the thresholds are based on how many trusted validators are actively participating in the consensus round. Even a validator that is in the Negative UNL can participate in the consensus process. - -### Example - -The following example demonstrates how the Negative UNL affects the consensus process: - -1. Suppose your server's UNL consists of 38 trusted validators, so an 80% quorum is at least 31 of 38 trusted validators. - -{{ include_svg("img/negative-unl-01.svg", "Diagram: Normal case: Negative UNL unused, quorum is 80% of configured validators.") }} - -2. Imagine 2 of those validators, named MissingA and UnsteadyB, appear to have gone offline. (Both of them have reliability scores < 50%.) During the consensus process for ledger _N_, many of the remaining validators propose adding UnsteadyB to the negative UNL. The motion passes via a quorum of at least 31 of the remaining validators, and ledger _N_ becomes validated with UnsteadyB scheduled to be disabled. - -{{ include_svg("img/negative-unl-02.svg", "Diagram: UnsteadyB is scheduled to be disabled.") }} - - -3. For ledgers _N+1_ through _N+256_, the consensus process continues without changes. - -4. In the next flag ledger, ledger _N+256_, UnsteadyB gets automatically moved from "scheduled" to the "disabled" list in the ledger. Also, since MissingA is still offline, a consensus of validators schedules MissingA to be disabled in the next flag ledger. - -{{ include_svg("img/negative-unl-04.svg", "Diagram: UnsteadyB gets disabled and MissingA is scheduled to be disabled, too.") }} - -5. For ledgers _N+257_ through _N+512_, the quorum is now 30 of 37 validators. - -6. UnsteadyB comes back online in ledger _N+270_. It sends validation votes that agree with the rest of the network for ledgers _N+270_ through _N+511_, giving it a reliability score of > 80%. - -{{ include_svg("img/negative-unl-06.svg", "Diagram: UnsteadyB comes back online, but it's still disabled.") }} - -7. In the next flag ledger, _N+256_, MissingA gets automatically moved to the disabled list, as scheduled. Meanwhile, a consensus of validators schedule UnsteadyB to be removed from the Negative UNL, due to its improved reliability score. - -{{ include_svg("img/negative-unl-07.svg", "Diagram: MissingA is disabled and UnsteadyB is scheduled to be re-enabled.") }} - -8. For ledgers _N+513_ through _N+768_, the quorum is 29 of 36 validators. UnsteadyB continues to send validations stably while MissingA remains offline. - -9. In flag ledger _N+768_, UnsteadyB gets automatically removed from the disabled list, as scheduled. - -{{ include_svg("img/negative-unl-09.svg", "Diagram: UnsteadyB is removed from the disabled list.") }} - -10. Eventually, you decide that MissingA is probably not coming back, so you remove it from your server's configured UNL. Your server starts proposing removing MissingA from the Negative UNL each flag ledger thereafter. - -{{ include_svg("img/negative-unl-10.svg", "Diagram: After removing MissingA from the configured UNL, it's proposed for removal from the Negative UNL, too.") }} - -11. As validator operators remove MissingA from their configured UNLs, their validators vote to also remove MissingA from the Negative UNL. When enough validators have done so, the proposal to remove MissingA achieves a consensus, and MissingA is scheduled, then finally removed from the Negative UNL. - -{{ include_svg("img/negative-unl-11.svg", "Diagram: MissingA is removed from the Negative UNL.") }} - - -## See Also - -- **Concepts:** - - [Consensus Protocol](consensus.html) -- **Tutorials:** - - [Connect Your `rippled` to a Parallel Network](connect-your-rippled-to-the-xrp-test-net.html) - - [Run `rippled` as a Validator](run-rippled-as-a-validator.html) -- **References:** - - [NegativeUNL Object](negativeunl.html) - - [UNLModify pseudo-transaction][] - - [ledger_entry method][] - - [consensus_info method][] diff --git a/content/concepts/understanding-xrpl/xrpl/open-closed-validated-ledgers.md b/content/concepts/understanding-xrpl/xrpl/open-closed-validated-ledgers.md deleted file mode 100644 index 63d60df308..0000000000 --- a/content/concepts/understanding-xrpl/xrpl/open-closed-validated-ledgers.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -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) diff --git a/content/concepts/understanding-xrpl/xrpl/validation.md b/content/concepts/understanding-xrpl/xrpl/validation.md deleted file mode 100644 index 262be8bc41..0000000000 --- a/content/concepts/understanding-xrpl/xrpl/validation.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -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. - -[![Validation Rounds](img/consensus-rounds.svg)](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). \ No newline at end of file diff --git a/content/concepts/understanding-xrpl/xrpl/xrpl-ecosystem.md b/content/concepts/understanding-xrpl/xrpl/xrpl-ecosystem.md deleted file mode 100644 index 0894a83247..0000000000 --- a/content/concepts/understanding-xrpl/xrpl/xrpl-ecosystem.md +++ /dev/null @@ -1,53 +0,0 @@ -# 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. - -[![Peer-to-Peer Network](../../../img/ecosystem1-peer-to-peer.png)](../../../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. - -[![Programming Libraries](../../../img/ecosystem2-programming-libraries.png)](../../../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. - -[![Middleware](../../../img/ecosystem3-middleware.png)](../../../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. - -[![Apps & Services](../../../img/ecosystem4-apps.png)](../../../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. - - \ No newline at end of file diff --git a/content/concepts/xrpl-servers/clustering.ja.md b/content/concepts/xrpl-servers/clustering.ja.md deleted file mode 100644 index fa4d6109eb..0000000000 --- a/content/concepts/xrpl-servers/clustering.ja.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -html: clustering.html -parent: xrpl-servers.html -blurb: 暗号処理の負荷を分散させるためにクラスターでrippledサーバーを運用できます。 -labels: - - コアサーバー ---- -# クラスター化 - -1つのデータセンターで複数の`rippled`サーバーを運用している場合は、これらのサーバーをクラスターに編成して、効率性を最大化できます。`rippled`サーバーをクラスターで運用するメリットは以下のとおりです。 - -- クラスター化`rippled`サーバーは暗号処理を共有します。1台のサーバーがメッセージの真正性をすでに検証している場合、クラスターの他のサーバーはそのメッセージを信頼し、再検証を行いません。 -- クラスター化サーバーは、ネットワークで不適切な活動をしているかまたはネットワークを不正使用しているピアとAPIクライアントに関する情報を共有します。このため、クラスター内のすべてのサーバーを同時に攻撃することが難しくなります。 -- クラスター化サーバーは、一部のサーバーでの現行の負荷ベースのトランザクション手数料にトランザクションが対応していない場合を含め、常にクラスター全体にトランザクションを伝搬します。 - -バリデータを[プライベートピア](peer-protocol.html#プライベートピア)として実行している場合は、`rippled`サーバーのクラスターをプロキシサーバーとして使用することが推奨されます。 - -クラスターでのサーバーの設定方法に関するチュートリアルについては、[`rippled`サーバーのクラスター化](cluster-rippled-servers.html)を参照してください。 - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/xrpl-servers/clustering.md b/content/concepts/xrpl-servers/clustering.md deleted file mode 100644 index 3bc9acbf91..0000000000 --- a/content/concepts/xrpl-servers/clustering.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -html: clustering.html -parent: xrpl-servers.html -blurb: Run rippled servers in a cluster to share the load of cryptography between them. -labels: - - Core Server ---- -# Clustering - -If you are running multiple `rippled` servers in a single datacenter, you can configure those servers into a cluster to maximize efficiency. Running your `rippled` servers in a cluster provides the following benefits: - -- Clustered `rippled` servers share the work of cryptography. If one server has verified the authenticity of a message, the other servers in the cluster trust it and do not re-verify. -- Clustered servers share information about peers and API clients that are misbehaving or abusing the network. This makes it harder to attack all servers of the cluster at once. -- Clustered servers always propagate transactions throughout the cluster, even if the transaction does not meet the current load-based transaction fee on some of them. - -If you are running a validator as a [private peer](peer-protocol.html#private-peers), Ripple recommends using a cluster of `rippled` servers as proxy servers. - -## See Also - -- **Tutorials:** - - [Cluster `rippled` Servers](cluster-rippled-servers.html) - - [Run rippled as a Validator](run-rippled-as-a-validator.html) -- **References:** - - [peers method][] - - [connect method][] - - [Peer Crawler](peer-crawler.html) - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/xrpl-servers/ledger-history/history-sharding.ja.md b/content/concepts/xrpl-servers/ledger-history/history-sharding.ja.md deleted file mode 100644 index 7ba0ab25d8..0000000000 --- a/content/concepts/xrpl-servers/ledger-history/history-sharding.ja.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -html: history-sharding.html -parent: ledger-history.html -blurb: 履歴シャーディングは、履歴レジャーデータを保持する任務をrippledサーバー間で分担するようにします。 -labels: - - データ保持 - - コアサーバー ---- -# 履歴シャーディング - -[導入: rippled 0.90.0][] - -稼働中のサーバーは、ネットワーク実行時に検知または取得したレジャーに関するデータを格納したデータベースを作成します。各`rippled`サーバーは、そのレジャーのデータをレジャーストアーに保存しますが、保存されたレジャー数が設定された容量制限を超えると、オンライン削除ロジックによりこれらのデータベースがローテーションされます。 - -履歴シャーディングは、XRP Ledgerのトランザクション履歴をシャードと呼ばれるセグメントに分割し、XRP Ledgerネットワークのサーバー全体に分散します。シャードは、一連のレジャーです。`rippled`サーバーは、レジャーストアーとシャードストアーの両方にレジャーを同じ方法で保存します。 - -履歴シャーディング機能を使用すると、個々の`rippled`サーバーが履歴データの保存する役割を担い、すべての履歴（数テラバイト）を保存する必要がなくなります。シャードストアーはレジャーストアーに代わるものではありませんが、XRP Ledgerネットワーク上の分散レジャー履歴への信頼性の高いパスを実現します。 - -[![XRP Ledgerネットワーク: レジャーストアーとシャードストアーの図](img/xrp-ledger-network-ledger-store-and-shard-store.ja.png)](img/xrp-ledger-network-ledger-store-and-shard-store.ja.png) - - - -## 履歴シャードの取得と共有 - -`rippled` サーバーは履歴シャードを取得して保存します（この動作には設定が必要です）。このようなサーバーでは、ネットワークとの同期を実行し、設定された数の最新レジャーへのレジャー履歴の埋め戻しが完了した後で、シャードの取得が開始されます。ネットワークアクティビティがあまり発生しないこの期間に、`shard_db`を維持するように設定されている`rippled`サーバー が、シャードストアーに追加するシャードをランダムに選択します。ネットワークレジャー履歴が均等に分散される確率を高めるため、取得対象のシャードはランダムに選択され、現行シャードが特に優先されることはありません。 - -シャードが選択されたら、レジャー取得プロセスが開始されます。最初にシャードの最後のレジャーのシーケンスが取得され、最初のシャードに向けて逆方向に処理が進められます。取得プロセスでは最初に、サーバーがローカルでデータを確認します。取得できないデータについては、サーバーはピア`rippled`サーバーにデータを要求します。要求された期間のデータを供給できるサーバーは、履歴で応答します。要求側サーバーはこれらの応答を結合し、シャードを作成します。シャードに特定範囲のレジャーがすべて含まれた状態になれば、シャードが完成します。 - -`rippled`サーバーが1つのシャードを完全に取得する前に容量不足になった場合、空き容量ができて処理を続行できるようになるまで取得プロセスを停止します。この後、古いシャードは完成された最新のシャードに置き換えられます。ディスク容量が十分にある場合は、`rippled`サーバーはシャードに割り当てられている最大ディスク容量（`max_size_gb`）に達するまで、ランダムに選択された追加のシャードを取得し、シャードストアーに追加します。 - -## XRP Ledgerネットワークデータの整合性 - -すべてのレジャーの履歴は、特定範囲の履歴レジャーを維持することに同意したサーバー間で共有されます。これにより、各サーバーは維持することに同意したデータがすべてあることを確認し、プルーフツリーまたはレジャーデルタを作成できるようになります。履歴シャーディングが設定されている`rippled`サーバーは、保存するシャードをランダムに選択するため、すべての閉鎖済みレジャーの履歴全体が正規分布曲線で保存され、XRP Ledgerネットワークで履歴が均一に維持される確率が高くなります。 - -## 関連項目 - -- [履歴シャーディングの設定](configure-history-sharding.html) -- [download_shardメソッド][] -- [crawl_shardsメソッド][] - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/xrpl-servers/ledger-history/history-sharding.md b/content/concepts/xrpl-servers/ledger-history/history-sharding.md deleted file mode 100644 index de978ec8dd..0000000000 --- a/content/concepts/xrpl-servers/ledger-history/history-sharding.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -html: history-sharding.html -parent: ledger-history.html -blurb: History sharding divides the work of keeping historical ledger data among rippled servers. -labels: - - Data Retention - - Core Server ---- -# History Sharding - -[Introduced in: rippled 0.90.0][] - -As XRP Ledger servers run, they naturally produce a database containing data about the ledgers they witnessed or acquired during network runtime. Each server stores that ledger data in its _ledger store_, but [online deletion](online-deletion.html) removes old ledgers' data automatically over time. History sharding provides a separate storage system for older ledger history so that the network can divide up the work of recording the entire (multiple terabyte) history of the XRP Ledger. - -Historical sharding distributes the transaction history of the XRP Ledger into segments, called shards, across servers in the XRP Ledger network. A shard is a range of ledgers. A server uses mostly the same format for ledgers in both the ledger store and the shard store, but the two stores are separate. - -[![XRP Ledger Network: Ledger Store and Shard Store Diagram](img/xrp-ledger-network-ledger-store-and-shard-store.png)](img/xrp-ledger-network-ledger-store-and-shard-store.png) - - - -## Acquiring and Sharing History Shards - -Servers acquire and store history shards only if configured to do so. Acquiring shards begins after synchronizing with the network and backfilling ledger history to the configured number of recent ledgers. During this time of lower network activity, a server set to maintain a shard database randomly chooses a shard to add to its shard store. To increase the probability for an even distribution of the network ledger history, shards are randomly selected for acquisition, and the most recent shard is given no special consideration. - -Once a shard is selected, the ledger acquire process begins by fetching the sequence of the last ledger in the shard and working backwards toward the first. The retrieval process begins with the server checking for the data locally. For data that is not available, the server requests data from its peers. Those servers that have the data available for the requested period respond with their history. The requesting server combines those responses to create the shard. The shard is complete when it contains all the ledgers in a specific range. - -The server selects and downloads additional shards until it reaches the maximum number of shards it is configured to store. If a server runs out of space before completely acquiring a shard, it stops its retrieval process until it has space available to continue. - -## XRP Ledger Network Data Integrity - -The history of all ledgers is shared by servers agreeing to keep particular ranges of historical ledgers. This makes it possible for servers to confirm that they have all the data they agreed to maintain, and produce "proof trees" or "ledger deltas" which shows how each ledger in the blockchain's history was the result of applying transactions to the previous state. Since servers that are configured with history sharding randomly select the shards that they store, the entire history of all closed ledgers is stored in a normal distribution curve, increasing the probability that the XRP Ledger Network evenly maintains the history. - -History shards are recorded in a deterministic format, so that any two servers assembling the same shard produce binary-identical data regardless of what order they acquired the data and where they got it from. This makes it possible to compare checksums or cryptographic hashes of the shard data to verify the integrity of the data, and it is possible to share and import history shards through other formats. (For example, you could download shard data using Bittorrent or acquire physical media with the shard data pre-loaded on it, and verify that it matches the data that can be downloaded from the network.) [New in: rippled 1.8.1][] - - -## See Also - -- **Concepts:** - - [Ledgers](ledgers.html) - - [Introduction to Consensus](intro-to-consensus.html) -- **Tutorials:** - - [Capacity Planning](capacity-planning.html) - - [Configure `rippled`](configure-rippled.html) - - [Configure History Sharding](configure-history-sharding.html) -- **References:** - - [crawl_shards method][] - - [download_shard method][] - - [Peer Crawler](peer-crawler.html) - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/xrpl-servers/ledger-history/ledger-history.ja.md b/content/concepts/xrpl-servers/ledger-history/ledger-history.ja.md deleted file mode 100644 index 4cd4fbc154..0000000000 --- a/content/concepts/xrpl-servers/ledger-history/ledger-history.ja.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -html: ledger-history.html -parent: xrpl-servers.html -blurb: rippledサーバーはトランザクションの変動金額と状態の履歴をローカルに保管します。 -labels: - - データ保持 - - ブロックチェーン - - コアサーバー ---- -# レジャー履歴 - -[コンセンサスプロセス](intro-to-consensus.html)により、[検証済みレジャーバージョン](ledgers.html)のチェーンが作成されます。各バージョンは、以前のバージョンに[トランザクション](transaction-basics.html)のセットを適用して生成されます。各[`rippled`サーバー](xrpl-servers.html)には、レジャーバージョンとトランザクション履歴がローカルに保管されます。サーバーに保管されるトランザクション履歴の量は、サーバーがオンラインであった期間と、サーバーが取得し、保持する履歴量の設定に応じて異なります。 - -ピアツーピアのXRP Ledgerネットワーク内のサーバーは、コンセンサスプロセスの一環としてトランザクションやその他のデータを相互に共有します。各サーバーは個別に新しいレジャーバージョンを作成し、その結果を信頼できるバリデータと比較して、整合性を維持します。（信頼できるバリデータのコンセンサスがサーバーの結果と一致しない場合は、サーバーがピアから必要なデータを取得して整合性を維持します。）サーバーはピアから古いデータをダウンロードして、利用可能な履歴のギャップを埋めることができます。レジャーはデータの暗号[ハッシュ](basic-data-types.html#ハッシュ)を使用した構造となっているため、すべてのサーバーがデータの整合性の検証を行えます。 - -## データベース - -サーバーはレジャーの状態データとトランザクションを _レジャーストアー_ と呼ばれるkey-valueストアで保持します。また、`rippled`にはいくつかのSQLiteデータベースファイルが維持されているので、トランザクション履歴などへより柔軟にアクセスし、特定の設定変更を追跡できます。 - -一般に、`rippled`サーバーが稼働していないときにはそのサーバーのすべてのデータベースファイルを安全に削除できます。（たとえばサーバーのストレージ設定を変更する場合や、Test Netから本番環境ネットワークに切り替える場合に、このような削除が必要となることがあります。） - -## 利用可能な履歴 - -設計上、XRP Ledgerのすべてのデータとトランザクションは公開されており、誰でもすべてのデータを検索または照会できます。ただし、サーバーが検索できるデータは、そのサーバーがローカルで使用できるデータに限られます。サーバーで利用できないレジャーバージョンやトランザクションを照会しようとすると、そのデータが見つからないという応答がサーバーから返されます。必要な履歴を保持している他のサーバーに対して同じ照会を実行すると、正常な応答が返されます。XRP Ledgerデータを使用する企業では、サーバーで利用可能な履歴の量に注意してください。 - -[server_infoメソッド][]は、サーバーで利用可能なレジャーバージョンの数を`complete_ledgers`フィールドで報告します。 - -## 履歴の取得 - -`rippled`サーバーは起動されると、最優先で最新の検証済みレジャーの完全なコピーを取得します。その後、サーバーは常にレジャーの進行状況を把握します。レジャー履歴を埋め戻すように設定されているサーバーでは、レジャー履歴が設定量に達するまで埋め戻されます。この設定量は、オンライン削除による削除が開始されるカットオフ値以下でなければなりません。 - -サーバーは同期される前から履歴の埋め戻しを行い、同期後にも収集した履歴のギャップを埋めることができます。（レジャー履歴のギャップは、サーバーの使用率が一時的に高くなりネットワークと同期をとることができない場合、ネットワークとの接続が失われた場合、またはその他の一時的な問題の影響を受けた場合に発生する可能性があります。）履歴を埋め戻すため、サーバーはピア`rippled`サーバーにデータを要求します。サーバーが埋め戻す量は、`[ledger_history]`設定で定義されます。 - -XRP Ledgerは、コンテンツの一意のハッシュを使用して（さまざまなレベルの）データを識別します。XRP Ledgerの状態データには、レジャーの履歴の概要が[LedgerHashesオブジェクトタイプ](ledgerhashes.html)の形式で含まれています。サーバーはLedgerHashesオブジェクトを使用して取得するレジャーバージョンを認識し、受信するレジャーデータが正しく完全であることを確認します。 - -履歴の埋め戻しは、サーバーでは最も優先度の低い処理の1つであるため、サーバーの使用率が高い場合やハードウェアとネットワークのスペックが十分ではない場合には、欠落している履歴を埋めるのに時間がかかることがあります。推奨されるハードウェアスペックについては、[容量の計画](capacity-planning.html)を参照してください。履歴の埋め戻しでは、サーバーのダイレクトピアの1つ以上に当該の履歴が保持されている必要もあります。 - -### 指示による削除の使用 - -[オンライン削除](online-deletion.html)と指示による削除の両方が有効な場合、サーバーでは、まだ削除が許可されていない最も古いレジャーまでのデータが自動的に埋め戻されます。これにより、`[ledger_history]`設定と`online_delete`設定で構成されているレジャーバージョンの数よりも多いデータが取得されることがあります。[can_deleteメソッド][]を実行すると、削除可能なレジャーバージョンがサーバーに通知されます。 - - -## すべての履歴 - -XRP Ledgerネットワーク内の一部のサーバーは、「すべての履歴が記録される」サーバーとして設定されています。これらのサーバーは、使用可能なすべてのXRP Ledgerの履歴を収集しますが、**オンライン削除は使用しません**。このため他の追跡サーバーよりもかなり多くのディスク容量が必要です。 - -Rippleは、`s2.ripple.com`ですべての履歴が記録される一連の公開サーバーを公開サービスとして提供しています。このサービスは、より大きなXRPコミュニティーのために提供されています。Rippleは、サーバーを悪用するユーザーや、公平な量を超えるサーバーのリソースを使用するユーザーをブロックする権利を留保しています。 - -**ヒント:** 一部の暗号資産ネットワークとは異なり、XRP Ledgerのサーバーは、現在の状態を認識して最新のトランザクションを把握するのにすべての履歴を必要としません。 - -すべての履歴の設定については、[完全な履歴の設定](configure-full-history.html)を参照してください。 - -## 履歴シャーディング - -XRP Ledgerのすべての履歴を1台の高価なマシンに保管する代わりに、複数のサーバーがレジャー履歴の一部分を保管するように構成できます。これは[履歴シャーディング](history-sharding.html)機能によって実現します。一定範囲のレジャー履歴が _シャードストアー_ という個別の保管領域に保管されます。ピアサーバーから（上記の[履歴の取得](#履歴の取得)で説明したとおり）特定のデータが要求されると、サーバーはレジャーストアーまたはシャードストアーのデータを使用して応答できます。 - -オンライン削除ではシャードストアーのデータは削除**されません**。ただし、32768個以上のレジャーバージョンをサーバーのレジャーストアーに保持するようにオンライン削除が設定されていれば、レジャーストアーからデータが自動的に削除される前に、サーバーはレジャーストアーからシャードストアーにすべてのシャードをコピーできます。 - -詳細は、[履歴シャーディングの設定](configure-history-sharding.html)を参照してください。 - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/xrpl-servers/ledger-history/ledger-history.md b/content/concepts/xrpl-servers/ledger-history/ledger-history.md deleted file mode 100644 index 1b7496033c..0000000000 --- a/content/concepts/xrpl-servers/ledger-history/ledger-history.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -html: ledger-history.html -parent: xrpl-servers.html -blurb: rippled servers store a variable amount of transaction and state history locally. -labels: - - Data Retention - - Blockchain - - Core Server ---- -# Ledger History - -The [consensus process](intro-to-consensus.html) creates a chain of [validated ledger versions](ledgers.html), each derived from the previous one by applying a set of [transactions](transaction-basics.html). Every [`rippled` server](xrpl-servers.html) stores ledger versions and transaction history locally. The amount of transaction history a server stores depends on how long that server has been online and how much history it is configured to fetch and keep. - -Servers in the peer-to-peer XRP Ledger network share transactions and other data with each other as part of the consensus process. Each server independently builds each new ledger version and compares results with its trusted validators to ensure consistency. (If a consensus of trusted validators disagrees with a server's results, that server fetches the necessary data from its peers to achieve consistency.) Servers can download older data from their peers to fill gaps in their available history. The structure of the ledger uses cryptographic [hashes](basic-data-types.html#hashes) of the data so that any server can verify the integrity and consistency of the data. - -## Databases - -Servers keep ledger state data and transactions in a key-value store called the _ledger store_. Additionally, `rippled` maintains a few SQLite database files for more flexible access to things like transaction history, and to track certain settings changes. - -It is generally safe to delete all of a `rippled` server's database files when that server is not running. (You may want to do this, for example, if you change the server's storage settings or if you are switching from a test net to the production network.) - -## Available History - -By design, all data and transactions in the XRP Ledger are public, and anyone can search or query anything. However, your server can only search data that it has available locally. If you try to query for a ledger version or transaction that your server does not have available, your server replies that it cannot find that data. Other servers that have the necessary history can respond successfully to the same query. If you have a business that uses XRP Ledger data, you should be mindful of how much history your server has available. - -The [server_info method][] reports how many ledger versions your server has available in the `complete_ledgers` field. - -## Fetching History - -When an XRP Ledger server starts, its first priority is to get a complete copy of the latest validated ledger. From there, it keeps up with advances in the ledger progress. The server fills in any gaps in its ledger history that occur after syncing, and can backfill history from before it became synced. (Gaps in ledger history can occur if a server temporarily becomes too busy to keep up with the network, loses its network connection, or suffers other temporary issues.) When downloading ledger history, the server requests the missing data from its [peer servers](peer-protocol.html), and verifies the data's integrity using cryptographic [hashes][Hash]. - -Backfilling history is one of the server's lowest priorities, so it may take a long time to fill missing history, especially if the server is busy or has less than sufficient hardware and network specs. For recommendations on hardware specs, see [Capacity Planning](capacity-planning.html). Backfilling history also requires that at least one of the server's direct peers has the history in question. For more information on managing your server's peer-to-peer connections, see [Configure Peering](configure-peering.html). - -The XRP Ledger identifies data (on several different levels) by a unique hash of its contents. The XRP Ledger's state data contains a short summary of the ledger's history, in the form of the [LedgerHashes object type](ledgerhashes.html). Servers use the LedgerHashes objects to know which ledger versions to fetch, and to confirm that the ledger data they receive is correct and complete. - - - -### Backfilling -[Updated in: rippled 1.6.0][] - -The amount of history a server attempts to download depends on its configuration. The server automatically tries to fill gaps by downloading history up to **the oldest ledger it already has available**. You can use the `[ledger_history]` setting to make the server backfill history beyond that point. However, the server never downloads ledgers that would be scheduled for [deletion](online-deletion.html). - -The `[ledger_history]` setting defines a minimum number of ledgers to accumulate from before the current validated ledger. Use the special value `full` to download the [full history](#full-history) of the network. If you specify a number of ledgers, it must be equal to or more than the `online_deletion` setting; you cannot use `[ledger_history]` to make the server download _less_ history. To reduce the amount of history a server stores, change the [online deletion](online-deletion.html) settings instead. - - - -## Full History - -Some servers in the XRP Ledger network are configured as "full-history" servers. These servers, which require significantly more disk space than other tracking servers, collect all available XRP Ledger history and **do not use online deletion**. - -The XRP Ledger Foundation provides access to a set of full history servers operated by community members (see [xrplcluster.com](https://xrplcluster.com) for more details). -Ripple also provides a set of public full-history servers as a public service at `s2.ripple.com`. - -Providers of Full History servers reserve the right to block access that is found to abuse resources, or put inordinate load on the systems. - -**Tip:** Unlike some cryptocurrency networks, servers in the XRP Ledger do not need full history to know the current state and keep up with current transactions. - -For instructions on setting up full history, see [Configure Full History](configure-full-history.html). - -## History Sharding - -An alternative to storing the full history of the XRP Ledger on a single expensive machine is to configure many servers to each store a portion of ledger history. The [History Sharding](history-sharding.html) feature makes this possible, storing ranges of ledger history in a separate storage area called the _shard store_. When a peer server asks for specific data (as described in [fetching history](#fetching-history) above), a server can answer using data from either its ledger store or shard store. - -Online deletion **does not** delete from the shard store. However, if you configure online deletion to keep at least 32768 ledger versions in your server's ledger store, your server can copy full shards from the ledger store to the shard store before automatically deleting them from the ledger store. - -For more information, see [Configure History Sharding](configure-history-sharding.html). - - -## See Also - -- **Concepts:** - - [Ledgers](ledgers.html) - - [Introduction to Consensus](intro-to-consensus.html) -- **Tutorials:** - - [Configure `rippled`](configure-rippled.html) - - [Configure Online Deletion](configure-online-deletion.html) - - [Configure Advisory Deletion](configure-advisory-deletion.html) - - [Configure History Sharding](configure-history-sharding.html) - - [Configure Full History](configure-full-history.html) -- **References:** - - [ledger method][] - - [server_info method][] - - [ledger_request method][] - - [can_delete method][] - - [ledger_cleaner method][] - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/xrpl-servers/ledger-history/online-deletion.ja.md b/content/concepts/xrpl-servers/ledger-history/online-deletion.ja.md deleted file mode 100644 index 8ef30b6c55..0000000000 --- a/content/concepts/xrpl-servers/ledger-history/online-deletion.ja.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -html: online-deletion.html -parent: ledger-history.html -blurb: オンライン削除は古いトランザクションと状態の履歴を消去します。 -labels: - - データ保持 - - コアサーバー ---- -# オンライン削除 -[[ソース]
](https://github.com/ripple/rippled/blob/master/src/ripple/app/misc/SHAMapStoreImp.cpp "Source") - -オンライン削除機能により、`rippled`サーバーはレジャーの古いバージョンのローカルコピーを削除できます。これにより、時間とともにディスク使用量が急増しないようにできます。デフォルトの構成ファイルにはオンライン削除の自動実行が設定されていますが、指示があった場合にのみオンライン削除を実行するようにも設定できます。[新規: rippled 0.27.0][] - -サーバーは、レジャーおよびそのすべての残高と設定を、常に完全かつ _最新_ の状態に維持します。削除されるデータには、保存されている履歴よりも古いレジャー状態の古いトランザクションやバージョンがあります。 - -デフォルトの構成ファイルは、`rippled`サーバーが2000の最新レジャーバージョンを保持し、古いデータを自動的に削除するように設定されています。 - -**ヒント:** オンライン削除を使用しても、同一期間のレジャーデータを保管するのに必要なディスク容量は時間の経過とともに増加します。これは、個々のレジャーバージョンのサイズが時間とともに増加する傾向にあるためです。蓄積データが増加するペースは、古いレジャーを削除しない場合に比べると、非常にゆっくりとしています。必要なディスク容量に関する詳細は、[容量の計画](capacity-planning.html)を参照してください。 - - -## 背景 - -`rippled`サーバーでは[レジャー履歴](ledger-history.html)がその _レジャーストアー_ に保管されます。このデータは時間とともに蓄積されます。 - -レジャーストアー内ではレジャーデータの「重複排除」が行われます。つまり、バージョン間で変更されていないデータは1回だけ保存されます。レジャーストアーのレコード自体には、レコードが記録されているレジャーバージョンの記載はありません。オンライン削除処理において、古いレジャーバージョンでのみ使用されるレコードが特定されます。この処理には時間がかかり、またディスクI/Oとアプリケーションキャッシュに影響するため、レジャーを閉鎖するたびに古いデータを削除することは現実的ではありません。 - - -## オンライン削除の動作 - -オンライン削除の設定では、`rippled`サーバーがレジャーストアーで使用可能な状態で維持するレジャーバージョンの数が設定されます。ただし、指定される数は目安であり、厳格に適用されるものではありません。 - -- サーバーでは、設定された数のレジャーバージョンよりも新しいデータが削除されることはありませんが、長期にわたってサーバーが稼働していない場合や、ネットワークとの同期が失われた場合には、サーバーに含まれるレジャーバージョンの数が使用可能な数よりも少ないことがあります。（サーバーは一部の履歴の埋め戻しを試みます。詳細は、[履歴の取得](ledger-history.html#履歴の取得)を参照してください。） -- オンライン削除の自動実行が設定されている場合、設定されているレジャーバージョンの数の2倍を超える数まで保存できる可能性があります。（オンライン削除を実行するたびに、保管されるレジャーバージョンの数が削減され、設定数に近くなります。） - - ＰＣサーバーがビジーのためオンライン削除が遅延すると、レジャーバージョンが蓄積し続けることがあります。正常に動作している場合には、サーバー内のレジャーバージョン数が設定された数の2倍に達した時点でオンライン削除が開始されますが、さらにいくつかのレジャーバージョンが蓄積するまではオンライン削除が完了しないことがあります。 - -- 指示による削除が有効な場合、管理者が[can_deleteメソッド][]を呼び出すまで、サーバーが取得および作成したすべてのレジャーバージョンがサーバーに保存されます。 - - サーバーに保存されるデータ量は、[can_delete][can_deleteメソッド]を呼び出す頻度と、`online_delete`設定に指定されている期間の長さに応じて異なります。 - - - `online_delete`の間隔よりも頻繁に`can_delete`を呼び出す場合、サーバーには最大で **`online_delete`の値の2倍** にほぼ相当するレジャーバージョンが保存されます。（削除後には、この数はほぼ`online_delete`の値まで減少します。） - - たとえば`now`値を指定した`can_delete`を1日1回呼び出し、`online_delete`に値50,000を指定している場合、削除実行前のサーバーには通常、最大100,000のレジャーバージョンが蓄積されます。削除実行後は、少なくとも50,000のレジャーバージョン（約 2日分）がサーバーに保持されます。この設定では、約1回おきに`can_delete`を呼び出しした場合、変更が生じません。これは、削除するのに十分な数のレジャーバージョンがサーバーにないためです。 - - - `online_delete`の間隔 _よりも少ない頻度で_ `can_delete`を呼び出す場合、最大で **`can_delete`呼び出しの間隔のほぼ2倍** の期間にわたりレジャーバージョンがサーバーに保管されます。（削除後には、この数は約1間隔分のデータまで減少します。） - - たとえば`now`値を指定した`can_delete`を1日1回呼び出し、`online_delete`値に2000を指定している場合、サーバーでは通常、削除が実行されるまでに最大で2日間分のレジャーバージョンが保管されます。削除の実行後は、サーバーには約1日分のレジャーバージョン（約25,000）が保持されますが、このレジャーバージョンの数が2000を下回ることはありません。 - - -オンライン削除が有効であり、自動的に実行される場合（つまり指示による削除が無効な場合）、保管されるレジャーデータの量は、最低でもサーバーに設定された保持レジャーバージョン数に相当し、最大でその約2倍です。 - -オンライン削除が実行されても、ディスク上のSQLiteデータベースファイルのサイズは減少しません。これらのファイルの中に新しいデータを入れるのに再利用できるスペースが確保されるだけです。オンライン削除によって、レジャーストアーが含まれるRocksDB または NuDB データベースファイルのサイズは _減少します_ 。 - -サーバーでは、削除範囲を決定する際に検証済みレジャーバージョンの数だけがカウントされます。（ローカルネットワーク接続が停止していたか、グローバルXRP Ledgerネットワークがコンセンサスに達しなかったことが原因で）サーバーが新しいレジャーバージョンを検証できない例外的な状況にある場合、ネットワークが復旧した際に迅速に回復できるように、`rippled`は引き続きレジャーを閉鎖します。この場合、サーバーには未検証の閉鎖済みレジャーが多数蓄積されます。このような未検証レジャーは、オンライン削除の実行までにサーバーに保持される _検証済み_ レジャーの数には影響しません。 - -### オンライン削除の中断 - -[サーバーの状態](rippled-server-states.html)が`full`より優先順位の低い状態になると、オンライン削除は自動的に停止します。この場合、サーバーはプレフィクス`SHAMapStore::WRN`が付いたログメッセージを書き込みます。サーバーは完全に同期された後、次の検証済みレジャーバージョン以降からオンライン削除の再開を試みます。 - -サーバーを停止した場合や、オンライン削除の実行中にサーバーがクラッシュした場合には、サーバーが再起動し、完全に同期されれば、オンライン削除が再開されます。 - -オンライン削除を一時的に無効にするには、引数`never`を指定した[can_deleteメソッド][]を使用できます。この変更は、[can_delete][can_delete method] をもう一度呼び出してオンライン削除を再度有効にするまで保持されます。オンライン削除の実行時点の制御についての詳細は、[指示による削除](#指示による削除)を参照してください。 - - -## 設定 - -オンライン削除に関連する設定は以下のとおりです。 - -- **`online_delete`** - 維持する検証済みレジャーバージョンの数を指定します。サーバーは、この数よりも古いレジャーバージョンをすべて定期的に削除します。数を指定しなければ、レジャーは削除されません。 - - デフォルトの構成ファイルでは、この値は2000に設定されています。この値に256未満の数は設定はできません。これは、[手数料投票](fee-voting.html)や[Amendmentプロセス](amendments.html#amendmentプロセス)などのイベントで一度に更新されるレジャーの数が256であるためです。 - - **注意:**`online_delete`を無効にして`rippled`を実行し、その後`online_delete`を有効にしてサーバーを再起動すると、`online_delete`が無効の間にサーバーがダウンロードした既存のレジャー履歴は無視されますが、削除されません。ディスク容量を節約するには、`online_delete`設定の変更後にサーバーを再起動する前に、既存の履歴を削除します。 - -- **`[ledger_history]`** - 検証済みレジャーの数（`online_delete`の値以下）を指定します。サーバーの検証済みレジャーバージョンの数がこの数よりも少ない場合、ピアからデータを取得してバージョンを埋め戻す操作が試行されます。 - - この設定のデフォルト値はレジャー256個です。 - - 次の図は、`online_delete`設定と`ledger_history`設定の関係を示します。 - - ![`online_delete`より古いレジャーは自動的に削除されます。`ledger_history`よりも新しいレジャーは埋め戻されます。その間に位置するレジャーは、使用可能な場合は保持されますが、埋め戻しは行われません](img/online_delete-vs-ledger_history.ja.png) - -- **`advisory_delete`** - 有効な場合、オンライン削除は自動的にスケジュールされません。代わりに管理者が手動でオンライン削除をトリガーする必要があります。無効にするには値`0`を使用し、有効にするには`1`を使用します。 - - この設定はデフォルトで無効になっています。 - -- **`[fetch_depth]`** - 検証済みレジャーバージョンの数を指定します。サーバーは、指定されている数のレジャーバージョンよりも古い履歴データに対するピアからの取得要求を受け入れません。使用可能なすべてのデータをピアに提供するには、値`full`を指定します。 - - `fetch_depth`のデフォルトは`full`です（使用可能なすべてのデータを提供します）。 - - `fetch_depth`設定と`online_delete`設定の両方が指定されている場合、`fetch_depth`には`online_delete`よりも大きな値を設定できません。`fetch_depth`に大きな値が設定されている場合、サーバーは`fetch_depth`の値が`online_delete`と同等であるものとして扱います。 - - 次の図は、fetch_depthの仕組みを示します。 - - ![fetch_depthよりも古いレジャーバージョンはピアに提供されません](img/fetch_depth.ja.png) - -さまざまな量の履歴の保管に必要なディスク容量の見積もりについては、[容量の計画](capacity-planning.html#ディスク容量)を参照してください。 - -### 指示による削除 - -デフォルトの構成ファイルでは、オンライン削除が定期的に自動で実行されるように設定されています。構成ファイルに`online_delete`間隔が指定されていない場合、オンライン削除は実行されません。構成ファイルで`advisory_delete`設定が有効になっている場合、オンライン削除は、管理者が[can_deleteメソッド][]を使用してオンライン削除をトリガーしたときにのみ実行されます。 - -指示による削除とスケジュール済みジョブを使用すれば、閉鎖済みレジャーバージョン数の代わりに、時刻に基づいて自動削除をトリガーできます。サーバーの使用率が高い場合、オンライン削除によって負荷が追加されるとサーバーの処理が遅延し、コンセンサスネットワークと一時的に非同期になることがあります。この場合は、指示による削除を使用して、オンライン削除をオフピーク期間にのみ実行するようにスケジュールできます。 - -指示による削除はその他の目的でも使用できます。たとえば、トランザクションデータを削除する前に、そのデータが別のサーバーにバックアップされていることを手動で確認できます。あるいは、トランザクションデータを削除する前に、別のタスクによるそのデータの処理が完了していることを手動で確認できます。 - -`can_delete` API メソッドは、構成ファイルで `advisory_delete` が有効になっている場合は、一般的な自動削除または特定のレジャーバージョンまでの自動削除を有効または無効にできます。`rippled`サーバーの再起動前に構成ファイルで`advisory_delete`を無効にしている場合を除き、これらの設定はサーバーを再起動しても維持されます。 - - -## 仕組み - -オンライン削除では2つのデータベースが作成されます。このため、「古い」読み取り専用データベースと、書き込み可能な「現行」データベースが常に存在します。`rippled`サーバーはいずれかのデータベースからオブジェクトを読み取ることができます。このため、現行レジャーバージョンにはいずれかのデータベースのオブジェクトが含まれます。レジャーバージョン間でレジャー内のオブジェクトに変更がない場合、そのオブジェクトのコピーが1つだけデータベースに残ります。これにより、オブジェクトのコピーが重複してサーバーに保存されることはありません。レジャーバージョンの更新によりオブジェクトが変更されると、サーバーは変更されたオブジェクトを「新しい」データベースに保存し、古いバージョンのオブジェクト（古いレジャーバージョンで使用されているオブジェクト）は「古い」データベースに残ります。 - -オンライン削除を実行する場合、サーバーはまず、最も古いレジャーバージョンの中から保持するものを確認し、そのレジャーバージョンのすべてのオブジェクトを読み取り専用の「古い」データベースから「現行」データベースにコピーします。これにより、「現行」データベースには、選択したレジャーバージョンとそれ以降のすべての新しいバージョンで使用されるオブジェクトがすべて含まれることになります。次に、サーバーは「古い」データベースを削除し、既存の「現行」データベースを「古い」読み取り専用データベースにします。これ以降、サーバーは新しい「現行」データベースを始動し、新たな変更をすべてこのデータベースに保存します。 - -![オンライン削除で2つのデータベースがどのように使用されるかを示す図](img/online-deletion-process.ja.png) - -## 関連項目 - -- [容量の計画](capacity-planning.html) -- [can_deleteメソッド][] - APIリファレンス資料 -- [オンライン削除の設定](configure-online-deletion.html) -- [指示による削除の設定](configure-advisory-deletion.html) -- [完全な履歴の設定](configure-full-history.html) - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/xrpl-servers/ledger-history/online-deletion.md b/content/concepts/xrpl-servers/ledger-history/online-deletion.md deleted file mode 100644 index 2908260c63..0000000000 --- a/content/concepts/xrpl-servers/ledger-history/online-deletion.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -html: online-deletion.html -parent: ledger-history.html -blurb: Online deletion purges outdated transaction and state history. -labels: - - Data Retention - - Core Server ---- -# Online Deletion -[[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/app/misc/SHAMapStoreImp.cpp "Source") - -The online deletion feature lets the `rippled` server delete the server's local copy of old ledger versions to keep disk usage from rapidly growing over time. The default config file sets online deletion to run automatically, but online deletion can also be configured to run only when prompted. [New in: rippled 0.27.0][] - -The server always keeps the complete _current_ state of the ledger, with all the balances and settings it contains. The deleted data includes older transactions and versions of the ledger state that are older than the stored history. - -The default config file sets the `rippled` server to keep the most recent 2000 ledger versions and automatically delete older data. - -**Tip:** Even with online deletion, the amount of disk space required to store the same time span's worth of ledger data increases over time, because the size of individual ledger versions tends to grow over time. This growth is very slow in comparison to the accumulation of data that occurs without deleting old ledgers. For more information on disk space needs, see [Capacity Planning](capacity-planning.html). - - -## Background - -The `rippled` server stores [ledger history](ledger-history.html) in its _ledger store_. This data accumulates over time. - -Inside the ledger store, ledger data is "de-duplicated". In other words, data that doesn't change from version to version is only stored once. The records themselves in the ledger store do not indicate which ledger version(s) contain them; part of the work of online deletion is identifying which records are only used by outdated ledger versions. This process is time consuming and affects the disk I/O and application cache, so it is not feasible to delete old data on every ledger close. - - -## Online Deletion Behavior - -The online deletion settings configure how many ledger versions the `rippled` server should keep available in the ledger store at a time. However, the specified number is a guideline, not a hard rule: - -- The server never deletes data more recent than the configured number of ledger versions, but it may have less than that amount available if it has not been running for long enough or if it lost sync with the network at any time. (The server attempts to backfill at least some history; see [fetching history](ledger-history.html#fetching-history) for details.) -- The server may store up to slightly over twice the configured number of ledger versions if online deletion is set to run automatically. (Each time it runs, it reduces the number of stored ledger versions to approximately the configured number.) - - If online deletion is delayed because the server is busy, ledger versions can continue to accumulate. When functioning normally, online deletion begins when the server has twice the configured number of ledger versions, but it may not complete until after several more ledger versions have accumulated. - -- If advisory deletion is enabled, the server stores all the ledger versions that it has acquired and built until its administrator calls the [can_delete method][]. - - The amount of data the server stores depends on how often you call [can_delete][can_delete method] and how big an interval of time your `online_delete` setting represents: - - - If you call `can_delete` _more often_ than your `online_delete` interval, the server stores at most a number of ledger versions approximately equal to **twice the `online_delete` value**. (After deletion, this is reduced to approximately the `online_delete` value.) - - For example, if you call `can_delete` with a value of `now` once per day and an `online_delete` value of 50,000, the server typically stores up to 100,000 ledger versions before running deletion. After running deletion, the server keeps at least 50,000 ledger versions (about two days' worth). With this configuration, approximately every other `can_delete` call results in no change because the server does not have enough ledger versions to delete. - - - If you call `can_delete` _less often_ than your `online_delete` interval, the server stores at most ledger versions spanning an amount of time that is approximately **twice the interval between `can_delete` calls**. (After deletion, this is reduced to approximately one interval's worth of data.) - - For example, if you call `can_delete` with a value of `now` once per day and an `online_delete` value of 2000, the server typically stores up to two full days' worth of ledger versions before running deletion. After running deletion, the server keeps approximately one day's worth (about 25,000 ledger versions), but never fewer than 2000 ledger versions. - - -With online deletion enabled and running automatically (that is, with advisory delete disabled), the total amount of ledger data stored should remain at minimum equal to the number of ledger versions the server is configured to keep, with the maximum being roughly twice that many. - -When online deletion runs, it does not reduce the size of SQLite database files on disk; it only makes space within those files available to be reused for new data. Online deletion _does_ reduce the size of RocksDB or NuDB database files containing the ledger store. - -The server only counts validated ledger versions when deciding how far back it can delete. In exceptional circumstances where the server is unable to validate new ledger versions (either because of an outage in its local network connection or because the global XRP Ledger network is unable to reach a consensus) `rippled` continues to close ledgers so that it can recover quickly when the network is restored. In this case, the server may accumulate many closed but not validated ledger versions. These unvalidated ledgers do not affect how many _validated_ ledger versions the server keeps before running online deletion. - -### Interrupting Online Deletion - -Online deletion automatically stops if the [server state](rippled-server-states.html) becomes less than `full`. If this happens, the server writes a log message with the prefix `SHAMapStore::WRN`. The server attempts to start online deletion again after the next validated ledger version after becoming fully synced. - -If you stop the server or it crashes while online deletion is running, online deletion resumes after the server is restarted and the server becomes fully synced. - -To temporarily disable online deletion, you can use the [can_delete method][] with an argument of `never`. This change persists until you re-enable online deletion by calling [can_delete][can_delete method] again. For more information on controlling when online deletion happens, see [Advisory Deletion](#advisory-deletion). - - -## Configuration - -The following settings relate to online deletion: - -- **`online_delete`** - Specify a number of validated ledger versions to keep. The server periodically deletes any ledger versions that are older than this number. If not specified, no ledgers are deleted. - - The default config file specifies 2000 for this value. This cannot be less than 256, because some events like [Fee Voting](fee-voting.html) and the [Amendment Process](amendments.html#amendment-process) update only every 256 ledgers. - - **Caution:** If you run `rippled` with `online_delete` disabled, then later enable `online_delete` and restart the server, the server disregards but does not delete existing ledger history that your server already downloaded while `online_delete` was disabled. To save disk space, delete your existing history before re-starting the server after changing the `online_delete` setting. - -- **`[ledger_history]`** - Specify a number of validated ledgers, equal to or less than `online_delete`. If the server does not have at least this many validated ledger versions, it attempts to backfill them by fetching the data from peers. - - The default for this setting is 256 ledgers. - - The following diagram shows the relationship between `online_delete` and `ledger_history` settings: - - {{ include_svg("img/online_delete-vs-ledger_history.svg", "Ledgers older than `online_delete` are automatically deleted. Ledgers newer than `ledger_history` are backfilled. Ledgers in between are kept if available but not backfilled") }} - -- **`advisory_delete`** - If enabled, online deletion is not scheduled automatically. Instead, an administrator must manually trigger online deletion. Use the value `0` for disabled or `1` for enabled. - - This setting is disabled by default. - -- **`[fetch_depth]`** - Specify a number of ledger versions. The server does not accept fetch requests from peers for historical data that is older than the specified number of ledger versions. Specify the value `full` to serve any available data to peers. - - The default for `fetch_depth` is `full` (serve all available data). - - The `fetch_depth` setting cannot be higher than `online_delete` if both are specified. If `fetch_depth` is set higher, the server treats it as equal to `online_delete` instead. - - The following diagram shows how `fetch_depth` works: - - {{ include_svg("img/fetch_depth.svg", "Ledger versions older than fetch_depth are not served to peers") }} - -For estimates of how much disk space is required to store different amounts of history, see [Capacity Planning](capacity-planning.html#disk-space). - -### Advisory Deletion - -The default config file schedules online deletion to happen automatically and periodically. If the config file does not specify an `online_delete` interval, online deletion does not occur. If config file enables the `advisory_delete` setting, online deletion only happens when an administrator triggers it using the [can_delete method][]. - -You can use advisory deletion with a scheduled job to trigger automatic deletion based on clock time instead of the number of ledger versions closed. If your server is heavily used, the extra load from online deletion can cause your server to fall behind and temporarily de-sync from the consensus network. If this is the case, you can use advisory deletion and schedule online deletion to happen only during off-peak times. - -You can use advisory deletion for other reasons. For example, you may want to manually confirm that transaction data is backed up to a separate server before deleting it. Alternatively, you may want to manually confirm that a separate task has finished processing transaction data before you delete that data. - -The `can_delete` API method can enable or disable automatic deletion, in general or up to a specific ledger version, as long as `advisory_delete` is enabled in the config file. These settings changes persist even if you restart the `rippled` server, unless you disable `advisory_delete` in the config file before restarting. - - -## How It Works - -Online deletion works by creating two databases: at any given time, there is an "old" database, which is read-only, and a "current" database, which is writable. The `rippled` server can read objects from either database, so current ledger versions may contain objects in either one. If an object in a ledger does not change from ledger version to ledger version, only one copy of that object remains in the database, so the server does not store redundant copies of that object. When a new ledger version modifies an object, the server stores the modified object in the "new" database, while the previous version of the object (which is still used by previous ledger versions) remains in the "old" database. - -When it comes time for online deletion, the server first walks through the oldest ledger version to keep, and copies all objects in that ledger version from the read-only "old" database into the "current" database. This guarantees that the "current" database now contains all objects used in the chosen ledger version and all newer versions. Then, the server deletes the "old" database, and changes the existing "current" database to become "old" and read-only. The server starts a new "current" database to contain any newer changes after this point. - -{{ include_svg('img/online-deletion-process.svg', "Diagram showing how online deletion uses two databases") }} - -## See Also - -- **Concepts:** - - [Ledgers](ledgers.html) - - [Introduction to Consensus](intro-to-consensus.html) -- **Tutorials:** - - [Capacity Planning](capacity-planning.html) - - [Configure `rippled`](configure-rippled.html) - - [Configure Online Deletion](configure-online-deletion.html) - - [Configure Advisory Deletion](configure-advisory-deletion.html) - - [Configure History Sharding](configure-history-sharding.html) - - [Configure Full History](configure-full-history.html) -- **References:** - - [ledger method][] - - [server_info method][] - - [ledger_request method][] - - [can_delete method][] - - [ledger_cleaner method][] - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/xrpl-servers/peer-protocol.ja.md b/content/concepts/xrpl-servers/peer-protocol.ja.md deleted file mode 100644 index 075d60ac16..0000000000 --- a/content/concepts/xrpl-servers/peer-protocol.ja.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -html: peer-protocol.html -parent: xrpl-servers.html -blurb: ピアプロトコルは、rippledサーバーが互いに通信する言語を指定します。 -labels: - - コアサーバー - - ブロックチェーン ---- -# ピアプロトコル - -XRP Ledgerのサーバーは、XRP Ledgerピアプロトコル（RTXP）を使用して相互に通信します。 - -ピアプロトコルは、XRP Ledgerのサーバー間のメイン通信モードです。XRP Ledgerの動作、進捗状況、接続に関するすべての情報がピアプロトコルを通じて伝達されます。ピアツーピア通信の例を以下に示します。 - -- ピアツーピアネットワーク内の他のサーバーへの接続の要求、または接続スロットの使用可能性についてのアドバタイズ。 -- ネットワークのその他の部分との候補トランザクションの共有。 -- 履歴レジャーへのレジャーデータの要求、またはレジャーデータの提供。 -- コンセンサスのための一連のトランザクションの提示、またはコンセンサストランザクションセットの適用に関する算出結果の共有。 - -ピアツーピア接続を確立するには、サーバーどうしをHTTPSで接続し、一方のサーバーはRTXPへの切り替えのために[HTTPアップグレード](https://tools.ietf.org/html/rfc7230#section-6.7)を要求します。（詳細は、[`rippled`リポジトリ](https://github.com/ripple/rippled)の[Overlay Network](https://github.com/ripple/rippled/blob/906ef761bab95f80b0a7e0cab3b4c594b226cf57/src/ripple/overlay/README.md#handshake)を参照してください。） - -## ピアの検出 - -XRP Ledgerでは、「ゴシップ」プロトコルを使用して、XRP Ledgerネットワーク内でサーバーが互いを識別できるようにします。サーバーは、起動するたびに、以前に接続したその他のあらゆるピアに再接続します。フォールバックとして、[ハードコーディングされた公開ハブ](https://github.com/ripple/rippled/blob/fa57859477441b60914e6239382c6fba286a0c26/src/ripple/overlay/impl/OverlayImpl.cpp#L518-L525)を使用します。サーバーがピアに正常に接続されると、ピアを探している他のXRP Ledgerサーバーの接続情報（通常はIPアドレスとポート）をそのピアに要求します。その後、サーバーはそれらのサーバーに接続し、ピア接続するXRP Ledgerサーバーの接続情報をさらに要求できます。このプロセスにより、サーバーは十分なピア接続を確立し、単一のピアへの接続が失われた場合でも、ネットワークの残りの部分にその後も接続されます。 - -通常、サーバーが公開ハブに接続する必要があるのは1回のみです。他のピアを見つけるために、短時間のみ接続します。そうすることで、ネットワーク接続の安定性、ハブのビジー状態、およびサーバーが検出する他の高品質ピアの数に応じて、ハブにサーバーを引き続き接続するかどうかが異なります。サーバーでは、これらの他のピアのアドレスを保存するため、ネットワークの停止後または再起動後、それらのピアへの直接再接続を試行できます。 - -[peersメソッド][]は、サーバーが現在接続しているピアのリストを示します。 - -価値の高いサーバー（重要な[バリデータ](rippled-server-modes.html#rippledサーバーのモード)など）によっては、ピア検出プロセスを通じて、サーバーを信頼性の低いピアに接続しないようにする場合があります。この場合、[プライベートピア](#プライベートピア)のみを使用するようにサーバーを構成できます。 - - -## ピアプロトコルポート - -XRP Ledgerに参加するため、`rippled`サーバーはピアプロトコルを使用して任意のピアに接続します。（すべてのピアは、現行サーバーで[クラスター化されている](clustering.html)場合を除き、信頼できないものとして扱われます。） - -サーバーがピアポートで接続を送信 _かつ_ 受信できることが理想的です。`rippled`サーバーに、[ファイアウォール経由でピアプロトコルに使用するポートを転送する](forward-ports-for-peering.html)必要があります。 - -[デフォルトの`rippled`構成ファイル](https://github.com/ripple/rippled/blob/master/cfg/rippled-example.cfg)は、すべてのネットワークインターフェイスにおいて、ポート51235で着信ピアプロトコル接続をリッスンします。使用するポートを変更するには、`rippled.cfg`ファイル内の該当するスタンザを編集します。 - -例: - -``` -[port_peer] -port = 51235 -ip = 0.0.0.0 -protocol = peer -``` - -ピアプロトコルポートは[特殊なPeer Crawler APIメソッド](peer-crawler.html)も処理します。 - -## ノードキーペア - -サーバーを初めて起動すると、ピアプロトコル通信でサーバー自体を識別するための _ノードキーペア_ が生成されます。サーバーはこのキーを使用して、ピアプロトコル通信のすべてに署名します。これにより、ピアツーピアネットワーク内の別のサーバーからのメッセージの整合性を、信頼できる方法で識別、検証できます。これは、そのサーバーのメッセージが信頼できないピアにより中継される場合も同様です。 - -ノードキーペアはデータベースに保存され、サーバーの再起動時に再利用されます。サーバーのデータベースを削除すると、新しいノードキーペアが作成され、異なるアイデンティティでオンラインになります。データベースが削除されても同じキーペアを再利用するには、`[node_seed]`スタンザを使用してサーバーを設定できます。`[node_seed]`スタンザでの使用に適した値を生成するには、[validation_createメソッド][]を使用します。 - -また、ノードキーペアは、[ピアスロットの](#固定ピアとピアリザベーション)[クラスタリング](clustering.html)または[確保](#固定ピアとピアリザベーション)のために他のサーバーも識別します。サーバークラスターを使用している場合、一意の`[node_seed]`設定を使用してクラスター内の各サーバーを構成する必要があります。クラスターの設定についての詳細は、[`rippled`サーバーのクラスター化](cluster-rippled-servers.html)を参照してください。 - - -## 固定ピアとピアリザベーション - -通常、`rippled`サーバーでは多数のピアを維持するよう試みるため、信頼性の低いピアの最大数まで自動接続されます。特定のピアサーバーへの接続を維持するように`rippled`サーバーを構成するには、いくつかの方法があります。 - -- **固定ピア**を使用して、IPアドレスに基づき特定の他のピアへの接続を維持します。これは、ピアのIPアドレスが固定されている場合にのみ機能します。固定ピアを構成するには、構成スタンザ`[ips_fixed]`を使用します。これは、[クラスタリング](clustering.html)または[プライベートピア](#プライベートピア)の重要な部分です。固定ピアは構成ファイルで定義されているため、変更を適用するにはサーバーを再起動する必要があります。サーバーが同じユーザーまたは組織によって実行されている場合、固定ピアは、サーバーの接続状態を維持するのに最も有益です。 -- **ピアリザベーション**を使用して、特定のピアに優先順位を付けます。サーバーに特定のピアのピアリザベーションがある場合、既に最大数のピアに接続されていても、サーバーは常にそのピアからの接続要求を受け入れます。（これにより、サーバーでのピアの最大接続数を*超える*可能性があります。）[ノードキーペア](#ノードキーペア)によって確保済みピアを識別するため、可変IPアドレスを持つピアに対してもこれを行うことができます。ピアリザベーションは、管理コマンドを使用して構成され、サーバーデータベースに保存されるため、サーバーがオンラインの場合に調整することができ、再起動後も保存されます。ピアリザベーションは、さまざまなユーザーや組織が運営するサーバーを接続するのに最も有益です。[新規: rippled 1.4.0][] - -次の場合、`rippled`サーバーは、信頼性の低いピアには接続されません。 - -- [プライベートピア](#プライベートピア)として構成されている場合、サーバーは固定ピアに _のみ_ 接続されます。 -- [スタンドアロンモード](rippled-server-modes.html#rippledサーバーをスタンドアロンモードで実行する理由)で実行されている場合、サーバーは _どの_ ピアにも接続されません。 - - -## プライベートピア - -`rippled`サーバーが「プライベート」サーバーとして動作するように設定し、そのIPアドレスを非公開にすることができます。これは、信頼できるバリデータなどの重要な`rippled`サーバーへのサービス拒否攻撃や侵入の試みに対する予防対策として有用です。ピアツーピアネットワークに参加するには、プライベートサーバーは1つ以上の非プライベートサーバーに接続するように設定されている必要があります。この非プライベートサーバーにより、メッセージがネットワークのその他の部分へ中継されます。 - -**注意:** [固定ピア](#固定ピアとピアリザベーション)を使用せずにプライベートサーバーを構成すると、サーバーはネットワークに接続できないため、ネットワークの状態を認識したり、トランザクションをブロードキャストしたり、コンセンサスプロセスに参加したりすることができません。 - -サーバーをプライベートサーバーとして設定すると次のさまざまな影響が生じます。 - -- サーバーがピアツーピアネットワーク内の他のサーバーに接続するように明示的に設定されていない場合、サーバーは他のサーバーに発信接続しません。 -- サーバーは、他のサーバーからの接続を受け入れるように明示的に設定されていない場合、他のサーバーからの着信接続を受け入れません。 -- サーバーはそのダイレクトピアに対し、信頼できない通信（[ピアクローラーAPI応答](peer-crawler.html)を含む）の中ではサーバーのIPアドレスを公開しないように指示します。これは、[peers adminメソッド][peersメソッド]などの信頼できる通信には影響しません。 - - プライベートサーバーの設定に関係なく、バリデータは常にそのピアに対し、バリデータのIPアドレスを非公開にするように指示します。これにより、バリデータがサービス拒否攻撃を受け過剰な負荷がかかることから保護されます。[新規: rippled 1.2.1][] - - **注意:** サーバーのソースコードを改ざんして、サーバーがこの要求を無視し、直近のピアのIPアドレスを共有する可能性があります。プライベートサーバーを、このように改ざんされていないことが確認されているサーバーにのみ接続するように設定してください。 - -### ピア接続設定のメリットとデメリット - -XRP Ledgerで使用できるように、`rippled`サーバーをピアツーピアのオープンネットワークの残りの部分に接続する必要があります。大まかに言えば、`rippled`サーバーがネットワークに接続する方法には、次の3種類の構成があります。 - -- **検出されたピア**を使用します。サーバーは、検出された信頼の低いサーバーに接続し、それらのサーバーが適切に動作する限り接続を維持します。（たとえば、要求するデータはそれほど多くなく、ネットワーク接続は安定しているため、同じ[ネットワーク](parallel-networks.html)をフォローしているように見えます。）デフォルトでは、この構成に設定されています。 -- 同じユーザーまたは組織が実行する**プロキシを使用したプライベートサーバー**として使用します。プロキシは、プライベートサーバーとの固定ピア接続を維持するストック用の`rippled`サーバーです（検出されたピアにも接続されます）。 -- **公開ハブを使用するプライベートサーバー**として使用します。プロキシを使用する構成と似ていますが、サードパーティーによって異なります。 - -各構成のメリットとデメリットは次のとおりです。 - - - - - - - - - - - - - - - - - - - - -
設定 メリット デメリット
検出されたピア
    -

  • 最もシンプルな構成。メンテナンスの負担が抑えられます。

    • -

  • ダイレクトピア接続の機会が多数得られます。ダイレクトピア接続には、いくつかのメリットがあります。サーバーは、複数のピアから並行して履歴を取得できます。同期時と履歴の埋め戻し時のいずれも可能です。履歴は、すべてのピアで完全に保持されているわけではないため、アクセスするピアを増やすことで、幅広い履歴データにアクセスすることもできます。

    • -

  • 切断されたピアを新しいピアに置き換えることができるため、サーバーがネットワークから切断される可能性を抑えることができます。

    • -
    -

  • サーバーのピアを選択することはできません。つまり、ピアによって悪意のある動作が行われるかどうかは不明です。「rippled」サーバーは悪意のあるピアから保護するように設計されていますが、悪意のあるピアがソフトウェアの欠陥を悪用してサーバーに影響を及ぼすリスクは常にあります。

    • -

  • サーバーのピアは頻繁に切断または変更される場合があります。

    • -
プロキシを使用したプライベートサーバー
    -

  • 最も安全で信頼できる構成（効率的に実装された場合）。

    • -

  • 信頼性と冗長性を実現します。

    • -

  • クラスタリングによって、プライベートサーバーのパフォーマンスを最適化できます。

    • -

  • 必要な数のダイレクトピア接続を作成できます。プライベートサーバーでは、複数のピアから並行して履歴を取得できます。複数のピアを実行するため、各ピアで保持するレジャー履歴の量も制御します。

    • -
    -

  • 複数のサーバーを実行することで、メンテナンスの負担とコストは高くなります。

    • -

  • ピア接続が停止する可能性が完全に排除されるわけではありません。実行するプロキシの数に関係なく、それらがすべて同じサーバーラックに存在する場合は、1つのネットワーク停止または停電によって、すべてのプロキシに影響が及ぶ可能性があります。

    • -
公開ハブを使用するプライベートサーバー
    -

  • 構成がシンプルでメンテナンスの負担を低減できます。

    • -

  • 安全なネットワーク接続に簡単にアクセスできます。

    • -

  • プロキシを使用して接続する場合と比較して、同時ピア停止によりプライベートサーバーがネットワークから切断される可能性を低減できます。

    • -
    -

  • 信頼性を維持できるように、評判の高いサードパーティー製品を使用します。

    • -
  • -

    使用する公開ハブが混雑している場合、サーバーはネットワークから切断される可能性があります。公開ハブの性質上、ユーザー数が多いため、すべてのユーザーに安定した接続を確保することが困難な場合があります。

    -

    この問題を回避するには、使用するハブを増やします。多いほど効果的です。また、デフォルト以外のハブを使用することをお勧めします。ビジー状態になる可能性が低くなります。

    -
    • -
- -### プライベートサーバーの設定 - -サーバーをプライベートサーバーとして設定するには、設定ファイルの`[peer_private]`を`1`に設定します。詳細な手順については、[プライベートサーバーの設定](configure-a-private-server.html)を参照してください。 - - -## 関連項目 - -- **コンセプト:** - - [コンセンサス](consensus.html) - - [並列ネットワーク](parallel-networks.html) -- **チュートリアル:** - - [rippledサーバーのクラスター化](cluster-rippled-servers.html) - - [プライベートサーバーの設定](configure-a-private-server.html) - - [ピアクローラーの設定](configure-the-peer-crawler.html) - - [ピアリングのポート転送](forward-ports-for-peering.html) - - [特定のピアへの手動接続](manually-connect-to-a-specific-peer.html) - - [ピアの最大数の設定](set-max-number-of-peers.html) - - [ピアリザベーション](use-a-peer-reservation.html) -- **リファレンス:** - - [peersメソッド][] - - [peer_reservations_addメソッド][] - - [peer_reservations_delメソッド][] - - [peer_reservations_listメソッド][] - - [connectメソッド][] - - [fetch_infoメソッド][] - - [ピアクローラー](peer-crawler.html) - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/xrpl-servers/peer-protocol.md b/content/concepts/xrpl-servers/peer-protocol.md deleted file mode 100644 index d5f8da8175..0000000000 --- a/content/concepts/xrpl-servers/peer-protocol.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -html: peer-protocol.html -parent: xrpl-servers.html -blurb: The peer protocol specifies the language rippled servers speak to each other. -labels: - - Core Server - - Blockchain ---- -# Peer Protocol - -Servers in the XRP Ledger communicate to each other using the XRP Ledger peer protocol. - -The peer protocol is the main mode of communication between servers in the XRP Ledger. All information about the behavior, progress, and connectivity of the XRP Ledger passes through the peer protocol. Examples of peer-to-peer communications include all of the following: - -- Requesting a connection to other servers in the peer-to-peer network, or advertising that connection slots are available. -- Sharing candidate transactions with the rest of the network. -- Requesting ledger data from historical ledgers, or providing that data. -- Proposing a set of transactions for consensus, or sharing the calculated outcome of applying a consensus transaction set. - -To establish a peer-to-peer connection, one server connects to another via HTTPS and requests an [HTTP upgrade](https://tools.ietf.org/html/rfc7230#section-6.7) to switch to the `XRPL/2.0` protocol (formerly `RTXP/1.2`). (For more information, see the [Overlay Network](https://github.com/ripple/rippled/blob/96bbabbd2ece106779bb544aa0e4ce174e99fdf6/src/ripple/overlay/README.md#handshake) article in the [`rippled` repository](https://github.com/ripple/rippled).) - -## Peer Discovery - -The XRP Ledger uses a "gossip" protocol to help find servers find others to connect to in the XRP Ledger network. Whenever a server starts up, it reconnects to any other peers it previously connected to. As a fallback, it uses the [hardcoded public hubs](https://github.com/ripple/rippled/blob/fa57859477441b60914e6239382c6fba286a0c26/src/ripple/overlay/impl/OverlayImpl.cpp#L518-L525). After a server successfully connects to a peer, it asks that peer for the contact information (generally, IP address and port) of other XRP Ledger servers that may also be seeking peers. The server can then connect to those servers, and ask them for the contact information of yet more XRP Ledger servers to peer with. Through this process, the server establishes enough peer connections that it can remain reliably connected to the rest of the network even if it loses a connection to any single peer. - -Typically, a server needs to connect to a public hub only once, for a short amount of time, to find other peers. After doing so, the server may or may not remain connected to the hub, depending on how stable its network connection is, how busy the hub is, and how many other high-quality peers the server finds. The server saves the addresses of these other peers so it can try reconnecting directly to those peers later, after a network outage or a restart. - -The [peers method][] shows a list of peers your server is currently connected to. - -For certain high-value servers (such as important [validators](rippled-server-modes.html#rippled-server-modes)) you may prefer not to have your server connect to untrusted peers through the peer discovery process. In this case, you can configure your server to use [private peers](#private-peers) only. - - -## Peer Protocol Port - -To participate in the XRP Ledger, `rippled` servers connect to arbitrary peers using the peer protocol. (All peers are treated as untrusted, unless they are [clustered](clustering.html) with the current server.) - -Ideally, the server should be able to send _and_ receive connections on the peer port. You should [forward the port used for the peer protocol through your firewall](forward-ports-for-peering.html) to the `rippled` server. - -IANA [has assigned port **2459**](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=2459) for the XRP Ledger peer protocol, but for compatibility with legacy systems, the [default `rippled` config file](https://github.com/ripple/rippled/blob/master/cfg/rippled-example.cfg) listens for incoming peer protocol connections on **port 51235** on all network interfaces. If you run a server, you can configure which port(s) your server listens on using the `rippled.cfg` file. - -Example: - -``` -[port_peer] -port = 2459 -ip = 0.0.0.0 -protocol = peer -``` - -The peer protocol port also serves [special peer port methods](peer-port-methods.html). - -## Node Key Pair - -When a server first starts up, it generates a _node key pair_ to use to identify itself in peer protocol communications. The server uses its key to sign all its peer protocol communications. This makes it possible to reliably identify and verify the integrity of messages from another server in the peer-to-peer network even if that server's messages are being relayed by untrusted peers. - -The node key pair is saved in the database and reused when the server restarts. If you delete the server's databases, it creates a new node key pair, effectively coming online with a different identity. To reuse the same key pair even if the databases are deleted, you can configure the server with a `[node_seed]` stanza. To generate a value suitable for use in the `[node_seed]` stanza, use the [validation_create method][]. - -The node key pair also identifies other servers for purposes of [clustering](clustering.html) or [reserving peer slots](#fixed-peers-and-peer-reservations). If you have a cluster of servers, you should configure each server in the cluster with a unique `[node_seed]` setting. For more information on setting up a cluster, see [Cluster `rippled` Servers](cluster-rippled-servers.html). - - -## Fixed Peers and Peer Reservations - -Normally, a `rippled` server attempts to maintain a healthy number of peers, and automatically connects to untrusted peers up to a maximum number. You can configure a `rippled` server to remain connected to specific peer servers in several ways: - -- Use **Fixed Peers** to remain always connected to specific other peers based on their IP addresses. This only works if the peers have fixed IP addresses. Use the `[ips_fixed]` config stanza to configure fixed peers. This is a necessary part of [clustering](clustering.html) or [private peers](#private-peers). Fixed peers are defined in the config file, so changes only apply after restarting the server. Fixed peers are most useful for keeping servers connected if those servers are run by the same person or organization. -- Use **Peer Reservations** to prioritize specific peers. If your server has a peer reservation for a specific peer, then your server always accepts connection requests from that peer even if your server is already at its maximum number of connected peers. (This can cause your server to go _over_ the maximum number of peers.) You identify a reserved peer by its [node key pair](#node-key-pair), so you can do this even for peers with variable IP addresses. Peer reservations are configured through admin commands and saved in the server databases, so they can be adjusted while the server is online and are saved across restarts. Peer reservations are most useful for connecting servers run by different people or organizations. [New in: rippled 1.4.0][] - -In the following cases, a `rippled` server does not connect to untrusted peers: - -- If the server is configured as a [private peer](#private-peers), it connects _only_ to its fixed peers. -- If the server is running in [stand-alone mode][] it does not connect to _any_ peers. - - -## Private Peers - -You can configure a `rippled` server to act as a "private" server to keep its IP address hidden from the general public. This can be a useful precaution against denial of service attacks and intrusion attempts on important `rippled` servers such as trusted validators. To participate in the peer-to-peer network, a private server must be configured to connect to at least one non-private server, which relays its messages to the rest of the network. - -**Caution:** If you configure a private server without any [fixed peers](#fixed-peers-and-peer-reservations), the server cannot connect to the network, so it cannot know network state, broadcast transactions, or participate in the consensus process. - -Configuring a server as a private server has several effects: - -- The server does not make outgoing connections to other servers in the peer-to-peer network unless it has been explicitly configured to connect to those servers. -- The server does not accept incoming connections from other servers unless it has been explicitly configured to accept connections from those servers. -- The server asks its direct peers not to reveal its IP address in untrusted communications, including the [peer crawler API response](peer-crawler.html). This does not affect trusted communications such as the [peers admin method][peers method]. - - Validators always ask their peers to hide the validators' IP addresses, regardless of the private server settings. This helps protect validators from being overloaded by denial of service attacks. [New in: rippled 1.2.1][] - - **Caution:** It is possible to modify a server's source code so that it ignores this request and shares its immediate peers' IP addresses anyway. You should configure your private server to connect only to servers that you know are not modified in this way. - -### Pros and Cons of Peering Configurations - -To be part of the XRP Ledger, a `rippled` server must be connected to the rest of the open peer-to-peer network. Roughly speaking, there are three categories of configurations for how a `rippled` server connects to the network: - -- Using **discovered peers**. The server connects to any untrusted servers it finds and stays connected as long as those servers behave appropriately. (For example, they don't request too much data, their network connections are stable, and they appear to be following the same [network](parallel-networks.html).) This is the default. -- As a **private server using proxies** run by the same person or organization. The proxies are stock `rippled` servers (also connected to discovered peers) that maintain a fixed peering connection with the private server. -- As a **private server using public hubs**. This is similar to using proxies, but it relies on specific third parties. - -The pros and cons of each configuration are as follows: - - - - - - - - - - - - - - - - - - - - -
Configuration Pros Cons
Discovered Peers
    -

  • Simplest configuration, with a low maintenance burden.

    • -

  • Creates the opportunity for a lot of direct peer connections. Having more direct peers comes with several benefits. Your server can fetch history from multiple peers in parallel, both when syncing and when backfilling history. Since not all peers maintain full history, having access to more peers can also provide access to a wider range of historical data.

    • -

  • Lowers the possibility of disconnecting from the network because your server can replace disconnected peers with new ones.

    • -
    -

  • Doesn't allow you to select your server's peers, which means that you have no idea whether your peers may decide to act maliciously. Although `rippled` servers are designed to protect against malicious peers, there is always a risk that malicious peers could exploit software flaws to affect your server.

    • -

  • Your server's peers may disconnect or change often.

    • -
Private Server Using Proxies
    -

  • Most secure and reliable configuration when implemented effectively.

    • -

  • As reliable and as redundant as you make it.

    • -

  • Can optimize the private server's performance with clustering.

    • -

  • Enables you to create as many direct peer connections as you want. Your private server can fetch history from multiple peers in parallel. Since you run the peers, you also control how much ledger history each peer keeps.

    • -
    -

  • Higher maintenance burden and cost from running multiple servers.

    • -

  • Does not completely eliminate the possibility of peer connection outages. No matter how many proxies you run, if they all exist on the same server rack, then one network or power outage can affect all of them.

    • -
Private Server Using Public Hubs
    -

  • Low maintenance burden with a small amount of configuration.

    • -

  • Provides access to safe connections to the network.

    • -

  • Compared to connecting using proxies, may be less likely to cause your private server to disconnect from the network due to a simultaneous peer outage.

    • -
    -

  • Depends on high-reputation third parties to remain reliable.

    • -
  • -

    May cause your server to become disconnected from the network if the public hubs you rely on are too busy. Due to the nature of public hubs, they are the most popular and may not be able to keep a steady connection open to everyone.

    -

    To help avoid this issue, use more public hubs; the more the better. It can also help to use non-default hubs, which are less likely to be busy.

    -
    • -
- -### Configuring a Private Server - -To configure your server as a private server, set the `[peer_private]` setting to `1` in the config file. For detailed instructions, see [Configure a Private Server](configure-a-private-server.html). - - -## See Also - -- **Concepts:** - - [Consensus](consensus.html) - - [Parallel Networks](parallel-networks.html) -- **Tutorials:** - - [Cluster rippled Servers](cluster-rippled-servers.html) - - [Configure a Private Server](configure-a-private-server.html) - - [Configure the Peer Crawler](configure-the-peer-crawler.html) - - [Forward Ports for Peering](forward-ports-for-peering.html) - - [Manually Connect to a Specific Peer](manually-connect-to-a-specific-peer.html) - - [Set Maximum Number of Peers](set-max-number-of-peers.html) - - [Use a Peer Reservation](use-a-peer-reservation.html) -- **References:** - - [peers method][] - - [peer_reservations_add method][] - - [peer_reservations_del method][] - - [peer_reservations_list method][] - - [connect method][] - - [fetch_info method][] - - [Peer Crawler](peer-crawler.html) - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/xrpl-servers/rippled-server-modes.ja.md b/content/concepts/xrpl-servers/rippled-server-modes.ja.md deleted file mode 100644 index 71e31d1542..0000000000 --- a/content/concepts/xrpl-servers/rippled-server-modes.ja.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -html: rippled-server-modes.html -parent: xrpl-servers.html -blurb: ストックサーバー、バリデータサーバー、スタンドアロンモードで運用されるrippledサーバーなど、rippledサーバーのモードについて説明します。 -labels: - - コアサーバー ---- -# rippledサーバーのモード - -`rippled`サーバーソフトウェアは、その設定に応じて以下のようなさまざまなモードで実行できます。 - -* ストックサーバー - レジャーのローカルコピーを保持し、ネットワークをフォローします。 -* 検証サーバー（ _バリデータ_ ）- コンセンサスの参加者（ストックサーバーの処理もすべて行います）。 -* `rippled`スタンドアロンモードのサーバー - テスト用。他の`rippled`サーバーと通信しません。 - -また、[`rippled` API](http-websocket-apis.html)にローカルでアクセスするためのクライアントアプリケーションとして、`rippled`実行可能ファイルを実行できます。（この場合同じバイナリの2つのインスタンスを並列して実行できます。1つのインスタンスをサーバーとして実行し、もう1つのインスタンスをクライアントとして一時的に実行して終了します。） - -各モードでrippledを実行するためのコマンドについては、[rippledコマンドライン使用リファレンス](commandline-usage.html)を参照してください。 - - -## ストックサーバーを運用する理由 - -独自の`rippled`サーバーを運用する理由は多数ありますが、その最たる理由として、独自サーバーが信頼できるものであり、自身でその負荷を管理でき、サーバーにアクセスするタイミングとアクセス方法を他のユーザーに依存せずに決めることができる点があげられます。もちろん、独自サーバーを不正使用者から保護するために適切なネットワークセキュリティ対策を講じなければなりません。 - -使用する`rippled`を信頼する必要があります。悪意のあるサーバーに接続してしまうと、そのサーバーはさまざまな方法であなたを利用して資金を失わせることができます。例: - -* 悪意のあるサーバーは、実際には行われていないあなたへの支払いが行われたと報告することがあります。 -* ペイメントパスと通貨取引オファーを選択的に表示または非表示にし、最適なディールをあなたに提示せずに不正使用者の利益になるようにします。 -* 悪意のあるサーバーにアドレスのシークレットキーを送信すると、このサーバーがあなたの代理として任意のトランザクションを実行し、アドレスが保有する資金全額を送金または消却することがあります。 - -さらに、独自サーバーを運用することでサーバーを制御できるようになり、重要な管理者専用コマンドや負荷の高いコマンドを実行できます。共有サーバーを使用する場合は、同じサーバーを利用する他のユーザーとサーバーのコンピューティング能力をめぐって競合することに注意する必要があります。WebSocket APIのコマンドの多くは、サーバーに大きな負荷をかけるため、`rippled`には必要に応じてその応答を縮小できるオプションがあります。サーバーを他のユーザーと共有する場合には、常に最適の結果を得られるとは限りません。 - -最後に、各自で検証サーバーを運用する場合には、ストックサーバーをパブリックネットワークへのプロキシとして使用し、ストックサーバー経由でのみ外部にアクセス可能なプライベートサブネット上で検証サーバーを維持することができます。これにより、検証サーバーの整合性を危うくすることはさらに難しくなります。 - -### 公開ハブ - -公開ハブは、他のサーバーへの[ピアプロトコル接続](peer-protocol.html)が多数あるストックサーバーを指します。ストックサーバーを公開ハブとして実行することで、XRP Ledgerネットワークの効率的な接続を維持できます。適切に運用されている公開ハブには、以下の特徴があります。 - -- 十分な帯域幅。 - -- 多数の信頼できるピアとの接続。 - -- メッセージを確実に中継する能力。 - - - -## バリデータを運用する理由 - -XRP Ledgerの堅牢性は、バリデータが相互に接続されたネットワークに依存しています。各バリデータは、他の何人かのバリデータが _共謀しない_ と信頼しています。利害の異なるバリデータ運用オペレーターが増えるほど、ネットワークの各メンバーは、ネットワークが引き続き公平に運営されることに確信が持てるようになります。XRP Ledgerを使用している組織や個人の場合、コンセンサスプロセスへ参加することが自らの利益につながります。 - -すべての`rippled`サーバーをバリデータとする必要はありません。信頼する同一オペレーターのサーバーの数が増えても、共謀の発生をよりよく防止できるわけではありません。組織が自然災害などの緊急事態に備えて冗長性を保つために、複数の地域でバリデータを運用することがあります。 - -組織が検証サーバーを運用している場合は、1つ以上のストックサーバーを実行して、APIアクセスの計算負荷のバランスを取ったり、それらを検証サーバーと外部ネットワーク間のプロキシとすることもできます。 - -バリデータの実行についての詳細は、[バリデータとしての`rippled`の実行](run-rippled-as-a-validator.html)を参照してください。 - - - -## `rippled`サーバーをスタンドアロンモードで実行する理由 - -信頼できるサーバーのコンセンサスなしでも、`rippled`をスタンドアロンモードで実行できます。スタンドアロンモードでは、`rippled`はXRP Ledgerピアツーピアネットワーク内のその他のサーバーとは通信しませんが、同じ操作のほとんどをローカルサーバーのみで実行できます。スタンドアロンでは、本番環境ネットワークに接続せずに`rippled`の動作をテストできます。たとえば、分散型ネットワークにAmendmentが反映される前に、[Amendmentの効果をテスト](amendments.html#amendmentのテスト)できます。 - -`rippled`をスタンドアロンモードで実行する場合、どのレジャーバージョンから開始するかを指示する必要があります。 - -* [新しいジェネシスレジャー](start-a-new-genesis-ledger-in-stand-alone-mode.html)を最初から作成する。 -* ディスクから[既存のレジャーバージョンを読み込む](load-a-saved-ledger-in-stand-alone-mode.html)。 - -**注意:** スタンドアロンモードでは[レジャーを手動で進める](advance-the-ledger-in-stand-alone-mode.html)必要があります。 - -## レポーティングモード -[導入: rippled 1.7.0][][] - - -Reporting mode is specialized mode for serving API requests more efficiently. In this mode, the server gets the latest validated ledger data over [gRPC](https://xrpl.org/configure-grpc.html) from a separate `rippled` server running in P2P Mode, then loads that data into a relational database ([PostgreSQL](https://www.postgresql.org/)). The reporting mode server does not directly participate in the peer-to-peer network, though it can forward requests such as transaction submission to the P2P Mode server it uses. - -Multiple reporting mode servers can share access to a PostgreSQL database and [Apache Cassandra](https://cassandra.apache.org/) cluster to serve a large amount of history without each server needing a redundant copy of all the data. Reporting mode servers provide this data through the same [`rippled` APIs](http-websocket-apis.html) with some slight changes to accommodate for the differences in how they store the underlying data. - -Most notably, reporting mode servers do not report pending, non-validated ledger data or transactions. This limitation is relevant to certain use cases that rely on rapid access to in-flux data, such as performing arbitrage in the [decentralized exchange](decentralized-exchange.html). - - - -## 関連項目 - -- **リファレンス:** - - [コマンドライン使用リファレンス](commandline-usage.html) - すべての`rippled`サーバーモードのコマンドラインオプションに関する詳細情報。 - - [ledger_acceptメソッド][] - スタンドアロンモードでレジャーを手動で進めます。 - - [featureメソッド][] - 現在有効になっている既知の[Amendment](amendments.html)を確認します。 -- **チュートリアル:** - - [`rippled`の構成](configure-rippled.html) - - [バリデータとしての`rippled`の実行](run-rippled-as-a-validator.html) - - [スタンドアロンモードでのrippledの使用](use-stand-alone-mode.html): - - [スタンドアロンモードでの新しいジェネシスレジャーの開始](start-a-new-genesis-ledger-in-stand-alone-mode.html) - - [スタンドアロンモードでの保存済みレジャーの読み込み](load-a-saved-ledger-in-stand-alone-mode.html) - - [スタンドアロンモードでレジャーを進める](advance-the-ledger-in-stand-alone-mode.html) - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/xrpl-servers/rippled-server-modes.md b/content/concepts/xrpl-servers/rippled-server-modes.md deleted file mode 100644 index a37feede04..0000000000 --- a/content/concepts/xrpl-servers/rippled-server-modes.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -html: rippled-server-modes.html -parent: xrpl-servers.html -blurb: Learn about rippled server modes, including stock servers, validator servers, and rippled servers run in stand-alone mode. -labels: - - Core Server ---- -# rippled Server Modes - -The `rippled` server software can run in several modes depending on its configuration, including: - -- [**P2P Mode**](#p2p-mode) - This is the main mode of the server: it follows the peer-to-peer network, processes transactions, and maintains some amount of [ledger history](ledger-history.html). This mode can be configured to do any or all of the following roles: - - [**Validator**](#validators) - Helps secure the network by participating in consensus - - [**API Server**](#api-servers) - Provides [API access](get-started-using-http-websocket-apis.html) to read data from the shared ledger, submit transactions, and watch activity in the ledger. Optionally, this can be a [**Full History Server**](#full-history-servers), which keeps a complete record of transaction and ledger history. - - [**Hub Server**](#public-hubs) - Relays messages between many other members of the peer-to-peer network. -- [**Reporting mode**](#reporting-mode) - A specialized mode for serving API requests from a relational database. It does not participate in the peer-to-peer network, so you need to run a P2P Mode server and connect the reporting mode server using a trusted gRPC connection. [New in: rippled 1.7.0][] -- [**Stand-alone mode**](#stand-alone-mode) - An offline mode for testing. Does not connect to the peer-to-peer network or use consensus. - -You can also run the `rippled` executable as a client application for accessing [`rippled` APIs](http-websocket-apis.html) locally. (Two instances of the same binary can run side-by-side in this case; one as a server, and the other running briefly as a client and then terminating.) - -For information on the commands to run `rippled` in each of these modes, see the [Commandline Reference](commandline-usage.html). - - -## P2P Mode - -P2P Mode is the main and default mode of the `rippled` server, and it can handle almost anything you might want your server to do. These servers form a peer-to-peer network that processes transactions and maintains the shared state of the XRP Ledger. If you want to submit transactions, read ledger data, or otherwise participate in the network, your requests must go through a P2P Mode server at some point. - -P2P Mode servers can be further configured to provide additional functionality. A server running in P2P Mode with a minimally-modified config file is also called a _stock server_. Other configurations include: - -- [Validator](#validators) -- [API Server](#api-servers) -- [Public Hubs](#public-hubs) - -P2P Mode servers connect to [Mainnet](parallel-networks.html) by default. - - -### API Servers - -All P2P Mode servers provide [APIs](http-websocket-apis.html) for purposes like submitting transactions, checking balances and settings, and administering the server. If you query the XRP Ledger for data or submit transactions for business use, it can be useful to [run your own server](xrpl-servers.html#reasons-to-run-your-own-server). - -#### Full History Servers - -Unlike some other blockchains, the XRP Ledger does not require servers to have a complete transaction history to know the current state and process new transactions. As a server operator, you decide how much [ledger history](ledger-history.html) to store at a time. However, a P2P Mode server can only answer API requests using the ledger history it has locally available. For example, if you keep six months of history, your server can't describe the outcome of a transaction from a year ago. API servers with [full history](ledger-history.html#full-history) can report all transactions and balances since the start of the XRP Ledger. - - -### Public Hubs - -A hub server is a P2P Mode server with lots of [peer protocol connections](peer-protocol.html) to other servers. Hub servers, especially _public hubs_ that allow connections from the open internet, help the XRP Ledger network maintain efficient connectivity. Successful public hubs embody the following traits: - -- Good bandwidth. - -- Connections with a lot of reliable peers. - -- Ability to relay messages reliably. - -To configure your server as a hub, increase the maximum number of peers allowed and make sure you've [forwarded the appropriate ports](forward-ports-for-peering.html) through your firewall and NAT (network address translation) router as appropriate. - - -### Validators - -The robustness of the XRP Ledger depends on an interconnected web of _validators_ who each trust some other validators _not to collude_. In addition to processing each transaction and calculating ledger state exactly like other P2P Mode servers, validators participate actively in the [consensus protocol](consensus.html). If you or your organization relies on the XRP Ledger, it is in your interest to contribute to the consensus process by running _one_ server as a validator. - -Validation uses only a small amount of computing resources, but there is not much benefit to a single entity or organization running multiple validators because doing so does not provide more protections against collusion. Each validator identifies itself with a unique cryptographic key pair that must be carefully managed; multiple validators must not share a key pair. For these reasons, validation is disabled by default. - -You can safely enable validation on a server that is also used for other purposes; this type of configuration is called an _all-purpose server_. Alternatively, you can run a _dedicated validator_ that does not perform other tasks, possibly in a [cluster](clustering.html) with other P2P Mode `rippled` servers. - -For more information about running a validator, see [Run `rippled` as a Validator](run-rippled-as-a-validator.html). - - -## Reporting Mode -[New in: rippled 1.7.0][] - -Reporting mode is specialized mode for serving API requests more efficiently. In this mode, the server gets the latest validated ledger data over [gRPC](https://xrpl.org/configure-grpc.html) from a separate `rippled` server running in P2P Mode, then loads that data into a relational database ([PostgreSQL](https://www.postgresql.org/)). The reporting mode server does not directly participate in the peer-to-peer network, though it can forward requests such as transaction submission to the P2P Mode server it uses. - -Multiple reporting mode servers can share access to a PostgreSQL database and [Apache Cassandra](https://cassandra.apache.org/) cluster to serve a large amount of history without each server needing a redundant copy of all the data. Reporting mode servers provide this data through the same [`rippled` APIs](http-websocket-apis.html) with some slight changes to accommodate for the differences in how they store the underlying data. - -Most notably, reporting mode servers do not report pending, non-validated ledger data or transactions. This limitation is relevant to certain use cases that rely on rapid access to in-flux data, such as performing arbitrage in the [decentralized exchange](decentralized-exchange.html). - - - - -## Stand-Alone Mode - -In stand-alone mode, the server operates without attempting to connect to the peer-to-peer network or follow the consensus process. The server still provides API access as normal and uses the same transaction processing engine, so you can test `rippled` behavior without being tied to the live network. For example, you can: - -- [Test the effects of Amendments](amendments.html#testing-amendments) before those Amendments have gone into effect across the decentralized network. -- [Create a new genesis ledger](start-a-new-genesis-ledger-in-stand-alone-mode.html) from scratch. -- [Load an existing ledger version](load-a-saved-ledger-in-stand-alone-mode.html) from disk, then replay specific transactions to re-create their outcomes or test other possibilities. - -**Caution:** In stand-alone mode, you must [manually advance the ledger](advance-the-ledger-in-stand-alone-mode.html). - - -## See Also - -- **References:** - - [Commandline Usage Reference](commandline-usage.html) - Detailed information on command-line options for all `rippled` server modes. - - [ledger_accept method][] - Manually advance the ledger in stand-alone mode. - - [feature method][] - Check [amendments](amendments.html) currently known and enabled. -- **Tutorials:** - - [Configure `rippled`](configure-rippled.html) - - [Run `rippled` as a Validator](run-rippled-as-a-validator.html) - - [Use rippled in Stand-Alone Mode](use-stand-alone-mode.html): - - [Start a New Genesis Ledger in Stand-Alone Mode](start-a-new-genesis-ledger-in-stand-alone-mode.html) - - [Load a Saved Ledger in Stand-Alone Mode](load-a-saved-ledger-in-stand-alone-mode.html) - - [Advance the Ledger in Stand-Alone Mode](advance-the-ledger-in-stand-alone-mode.html) - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/xrpl-servers/the-clio-server.md b/content/concepts/xrpl-servers/the-clio-server.md deleted file mode 100644 index 086119b453..0000000000 --- a/content/concepts/xrpl-servers/the-clio-server.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -html: the-clio-server.html -parent: xrpl-servers.html -blurb: Clio is an XRP Ledger server optimized for API calls. ---- -# The Clio Server - -Clio is an XRP Ledger API server optimized for WebSocket or HTTP API calls for validated ledger data. - -A Clio server does not connect to the peer-to-peer network. Instead, it extracts data from a specified `rippled` server which is connected to the P2P network. By handling API calls efficiently, Clio servers can help reduce the load on `rippled` servers running in P2P mode. - -Clio stores validated historical ledger and transaction data in a space efficient format, using up to 4 times less space than `rippled`. Clio uses Cassandra or ScyllaDB, allowing for scalable read throughput. Multiple Clio servers can share access to the same dataset, thereby enabling you to build a highly available cluster of Clio servers without the need for redundant data storage or computation. - -Clio requires access to a `rippled` server, which can run on the same machine as Clio or separately. - -While Clio offers the complete [HTTP / WebSocket APIs](http-websocket-apis.html), by default, it only returns validated data. For any requests that require access to the P2P network, Clio automatically forwards the request to the `rippled` server on the P2P network and passes the response back. - -## Why Should I Run a Clio Server? - -There are lots of reasons you might want to run your own Clio server, but most of them can be summarized as: reduced load on `rippled` server(s) connected to the P2P network, lower memory usage and storage overhead, easier horizontal scaling, and higher throughput for API requests. - -* Reduced load on `rippled` server(s) - A Clio server does not connect to the peer-to-peer network. It uses gRPC to get validated data from one or more trusted `rippled` servers that are connected to the P2P network. Thus, a Clio server handles requests more efficiently and reduces the load on `rippled` servers running in P2P mode. - -* Lower memory usage and storage overhead - Clio uses Cassandra as a database and stores data in a space efficient format, using up to 4 times less space than `rippled`. - -* Easier horizontal scaling - Multiple Clio servers can share access to the same dataset, thus enabling you to build a highly available cluster of Clio servers. - -* Higher throughput for API requests - A Clio server extracts validated data from one or more trusted `rippled` servers and stores this data efficiently. Thus, handling API calls efficiently, resulting in a higher throughput and in some cases, lower latency as well. - - -## How does a Clio Server Work? - -{{ include_svg("img/clio-basic-architecture.svg", "Figure 1: How does a Clio server work?") }} - -A Clio server stores validated ledger data such as transaction metadata, account states, and ledger headers in a persistent datastore. - -When a Clio server receives an API request, it looks up data from these data stores. For requests that require data from the P2P network, the Clio server forwards the request to a P2P server, and then passes the response back to the client. - - -## See Also - -- [Clio source code](https://github.com/XRPLF/clio) -- **Tutorials:** - - [Install Clio server on Ubuntu](install-clio-on-ubuntu.html) diff --git a/content/concepts/xrpl-servers/transaction-censorship-detection.ja.md b/content/concepts/xrpl-servers/transaction-censorship-detection.ja.md deleted file mode 100644 index dafe198ec1..0000000000 --- a/content/concepts/xrpl-servers/transaction-censorship-detection.ja.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -html: transaction-censorship-detection.html -parent: xrpl-servers.html -blurb: XRP Ledgerでは取引検閲の自動検知機能がすべてのrippledサーバーで有効になっています。 -labels: - - ブロックチェーン ---- -# 取引検閲の検知 - -[新規: rippled 1.2.0][] - -XRP Ledgerは、高い検閲耐性を実現できるように設計されています。この設計をサポートするために、XRP Ledgerでは、取引検閲の自動検知機能がすべての`rippled`サーバーで有効になっており、検閲によるネットワークへの影響の有無を、すべての参加者が確認できます。 - -`rippled`サーバーがネットワークと同期している間、検知機能は、`rippled`サーバーの観点から、[コンセンサス](intro-to-consensus.html)の最終ラウンドで受け入れられ、最後に検証されたレジャーに取り込まれるトランザクションをすべて追跡します。検知機能では、数回のコンセンサスラウンド後、検証済みのレジャーに取り込まれていないトランザクションの重大度が高くなるというログメッセージを発行します。 - - - -## 仕組み - -取引検閲検知機能の仕組みの概要を以下に示します。 - -1. 検知機能は、`rippled`サーバーの最初のコンセンサス提案のすべてのトランザクションをトラッカーに追加します。 - -2. コンセンサスラウンドの終了時に、検知機能によって、検証済みのレジャーに取り込まれているトランザクションはすべて、トラッカーから削除されます。 - -3. 検知機能は、15個のレジャーのトラッカーに残っているトランザクションについて、ログで[警告メッセージ](#警告メッセージの例)を発行し、潜在的に検閲されたトランザクションとして表面化します。この時点でトラッカーにトランザクションが存在する場合は、15ラウンドのコンセンサスの後、検証済みのレジャーに取り込まれていないことを意味します。トランザクションが別の15個のレジャーのトラッカーに残っている場合は、検知機能によって、ログに別の警告メッセージが発行されます。 - - トランザクションがトラッカーに残っている限り、最大5つの警告メッセージに対して、検知機能は15個のレジャーごとにログに警告メッセージを発行し続けます。警告メッセージが5回発行されると、検知機能は、ログに最終的な[エラーメッセージ](#エラーメッセージの例)を発行し、警告およびエラーメッセージの発行を停止します。 - - `rippled`サーバーログにこれらのメッセージが表示される場合、他のサーバーでトランザクションを取り込むことができない理由を調査する必要があります。まず、原因が悪意のある検閲よりも[誤検知](#誤検知の可能性)（無害なバグ）である可能性が高いと仮定します。 - - - -## 警告メッセージの例 - -トランザクションE08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7がレジャー18851530～18851545までの15個のレジャーのトラッカーに残っている場合に、取引検閲検知機能によって発行される警告メッセージの例を次に示します。 - -```text -LedgerConsensus:WRN Potential Censorship: Eligible tx E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7, which we are tracking since ledger 18851530 has not been included as of ledger 18851545. -``` - - -## エラーメッセージの例 - -トランザクションE08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7がレジャー18851530～18851605までの75個のレジャー（15個のレジャーの5セット）のトラッカーに残っている場合に、取引検閲検知機能によって発行されるエラーメッセージの例を以下に示します。 - -```text -LedgerConsensus:ERR Potential Censorship: Eligible tx E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7, which we are tracking since ledger 18851530 has not been included as of ledger 18851605.Additional warnings suppressed. -``` - - -## 誤検知の可能性 - -シナリオによっては、取引検閲検知機能で誤検知が発生する場合があります。この場合、誤検知とは、15個以上のレジャーについてトラッカーに残っているトランザクションにフラグが立てられたことを意味しますが、これによる問題はありません。 - -検知機能で誤検知メッセージが発行される可能性のあるシナリオを次に示します。 - -- `rippled`サーバーでは、ネットワークの他の部分とは異なるコードでビルドを実行しています。そのため、トランザクションは`rippled`サーバー上で別の方法で適用され、結果として誤検知の原因になります。このような誤検知が発生することはほとんどありませんが、一般的に、正しいバージョンの`rippled`を実行することが重要です。 - -- `rippled`サーバーはネットワークと同期されていないため、現時点で認識されていません。 - -- ネットワーク内の`rippled`サーバー（自身のサーバーも含まれる可能性が高い）は、`rippled`サーバーがトランザクションをネットワーク内の他の`rippled`サーバーに一貫性なく中継するバグのクラスの影響を受けています。 - - 現在、この予期しない動作の原因となる既知のバグはありません。ただし、バグの疑いがある影響を確認した場合は、[RippleのBug Bounty](https://ripple.com/bug-bounty/)プログラムへのご報告をお願いいたします。 - - -## 関連項目 - -- **コンセプト:** - - [コンセンサスの原理とルール](consensus-principles-and-rules.html) - - [トランザクションキュー](transaction-queue.html) -- **チュートリアル:** - - [信頼できるトランザクションの送信](reliable-transaction-submission.html) - - [ログメッセージについて](understanding-log-messages.html) -- **リファレンス:** - - [トランザクションの結果](transaction-results.html) - - -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/xrpl-servers/transaction-censorship-detection.md b/content/concepts/xrpl-servers/transaction-censorship-detection.md deleted file mode 100644 index 37db439584..0000000000 --- a/content/concepts/xrpl-servers/transaction-censorship-detection.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -html: transaction-censorship-detection.html -parent: xrpl-servers.html -blurb: XRP Ledger provides an automated transaction censorship detector that is available on all rippled servers. -labels: - - Blockchain ---- -# Transaction Censorship Detection - -[New in: rippled 1.2.0][] - -The XRP Ledger is designed to be censorship resistant. In support of this design, the XRP Ledger provides an automated transaction censorship detector that is available on all `rippled` servers, enabling all participants to see if censorship is affecting the network. - -While a `rippled` server is in sync with the network, the detector tracks all transactions that, in the view of the `rippled` server, should have been accepted in the last round of [consensus](intro-to-consensus.html) and included in the last validated ledger. The detector issues log messages of increasing severity for transactions that have not been included in a validated ledger after several rounds of consensus. - - - -## How It Works - -At a high-level, here’s how the transaction censorship detector works: - -1. The detector adds all transactions in a `rippled` server's initial consensus proposal to the tracker. - -2. At the close of the consensus round, the detector removes all transactions included in the resulting validated ledger from the tracker. - -3. The detector issues a [warning message](#example-warning-message) in the log for any transaction that remains in the tracker for 15 ledgers, surfacing it as a potentially censored transaction. The transaction's presence in the tracker at this time means that is has not been included in a validated ledger after 15 rounds of consensus. If the transaction remains in the tracker for another 15 ledgers, the detector issues another warning message in the log. - - For as long as the transaction remains in the tracker, the detector continues to issue a warning message in the log every 15 ledgers, for up to five warning messages. After the fifth warning message, the detector issues a final [error message](#example-error-message) in the log and then stops issuing warning and error messages. - - If you see these messages in your `rippled` server log, you should investigate why other servers are failing to include the transaction, starting with the assumption that the cause is more likely to be a [false positive](#potential-false-positives) (innocent bug) than malicious censorship. - - - -## Example Warning Message - -This is an example warning message issued by the transaction censorship detector after transaction E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7 remained in the tracker for 15 ledgers, from ledger 18851530 to ledger 18851545. - -```text -LedgerConsensus:WRN Potential Censorship: Eligible tx E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7, which we are tracking since ledger 18851530 has not been included as of ledger 18851545. -``` - - -## Example Error Message - -This is an example error message issued by the transaction censorship detector after transaction E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7 remained in the tracker for 75 ledgers (5 sets of 15 ledgers), from ledger 18851530 to ledger 18851605. - -```text -LedgerConsensus:ERR Potential Censorship: Eligible tx E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7, which we are tracking since ledger 18851530 has not been included as of ledger 18851605. Additional warnings suppressed. -``` - - -## Potential False Positives - -The transaction censorship detector may issue false positives in certain scenarios. In this case, a false positive means that the detector has flagged a transaction that has remained in the tracker for 15 ledgers or more, but for innocent reasons. - -Here are some scenarios that could cause the detector to issue false positive messages: - -- Your `rippled` server is running a build with code that is different from the rest of the network. This may cause your `rippled` server to apply transactions differently, resulting in false positives. While this type of false positive is unlikely, in general, it is crucial that you run the correct version of `rippled`. - -- Your `rippled` server is out of sync with the network and has not yet realized it. - -- `rippled` servers in the network, including possibly your own server, are being impacted by a class of bug that causes `rippled` servers to inconsistently relay transactions to other `rippled` servers in the network. - - Currently, there are no known bugs that cause this unexpected behavior. However, if you see the impact of what you suspect is a bug, consider reporting it to the [Ripple Bug Bounty](https://ripple.com/bug-bounty/) program. - - -## See Also - -- **Concepts:** - - [Consensus Principles and Rules](consensus-principles-and-rules.html) - - [Transaction Queue](transaction-queue.html) -- **Tutorials:** - - [Reliable Transaction Submission](reliable-transaction-submission.html) - - [Understanding Log Messages](understanding-log-messages.html) -- **References:** - - [Transaction Results](transaction-results.html) - - -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/xrpl-servers/xrpl-servers.md b/content/concepts/xrpl-servers/xrpl-servers.md deleted file mode 100644 index 02ce25b757..0000000000 --- a/content/concepts/xrpl-servers/xrpl-servers.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -html: xrpl-servers.html -parent: concepts.html -blurb: rippled is the core peer-to-peer server that manages the XRP Ledger. -template: pagetype-category.html.jinja ---- -# XRP Ledger Servers - -There are two main types of server software that power the XRP Ledger: - -- The core server, `rippled`, runs the the peer-to-peer network which processes transactions and reaches a consensus on their outcome. -- The API server, [Clio](the-clio-server.html), provides a powerful interface for fetching or querying data from the ledger. - -Anyone can run instances of one or both of these types of servers based on their needs. - -## Reasons to Run Your Own Server - -For lighter use cases and individual servers, you can often rely on free [public servers][]. However, the more serious your use of the XRP Ledger becomes, the more important it becomes to have your own infrastructure. - -There are lots of reasons you might want to run your own servers, but most of them can be summarized as: you can trust your own server, you have control over its workload, and you're not at the mercy of others to decide when and how you can access it. Of course, you must practice good network security to protect your server from malicious hackers. - -You need to trust the server you use. If you connect to a malicious server, there are many ways that it can take advantage of you or cause you to lose money. For example: - -* A malicious server could report that you were paid when no such payment was made. -* It could selectively show or hide payment paths and currency exchange offers to guarantee its own profit while not providing you the best deal. -* If you sent it your address's secret key, it could make arbitrary transactions on your behalf, and even transfer or destroy all the money your address holds. - -Additionally, running your own server gives you [admin access](get-started-using-http-websocket-apis.html#admin-access), which allows you to run important admin-only and load-intensive commands. If you use a shared server, you have to worry about other users of the same server competing with you for the server's computing power. Many of the commands in the WebSocket API can put a lot of strain on the server, so the server has the option to scale back its responses when it needs to. If you share a server with others, you may not always get the best results possible. - -Finally, if you run a validating server, you can use a stock server as a proxy to the public network while keeping your validating server on a private network only accessible to the outside world through the stock server. This makes it more difficult to compromise the integrity of your validating server. - -## Server Features and Topics - - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/dactyl-config.yml b/dactyl-config.yml index 5c6e6f5007..8b93c26a8e 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -196,49 +196,49 @@ pages: # About tab -------------------------------------------------------------------- # "XRP Ledger" Grouping - - name: XRPL Overview - template: page-xrpl-overview.html.jinja - html: xrp-ledger-overview.html - parent: index.html - top_nav_name: About - top_nav_grouping: XRP Ledger - sidebar: disabled - blurb: An introduction to the key benefits and features of the XRP Ledger, a public blockchain driven by the XRPL developer community. - targets: - - en - - - name: XRPL オーバービュー - template: page-xrpl-overview.html.jinja - html: xrp-ledger-overview.html - parent: index.html - top_nav_name: アバウト - top_nav_grouping: XRP Ledger - sidebar: disabled - targets: - - ja - - # Redirect from the old overview.html - - name: XRP Ledger Overview - html: overview.html - template: pagetype-redirect.html.jinja - nav_omit: true - redirect_url: xrp-ledger-overview.html - targets: - - en - - ja - - # Redirect for rename from 'wallet server' to 'stock server' - - name: Run rippled as a Stock Server - html: run-rippled-as-a-wallet-server.html - template: pagetype-redirect.html.jinja - nav_omit: true - redirect_url: run-rippled-as-a-stock-server.html - targets: - - en - # This redirect needs to be added to the Japanese target *after* - # renaming the original file in that target and translating the changes - # - ja - +# - name: XRPL Overview +# template: page-xrpl-overview.html.jinja +# html: xrp-ledger-overview.html +# parent: index.html +# top_nav_name: About +# top_nav_grouping: XRP Ledger +# sidebar: disabled +# blurb: An introduction to the key benefits and features of the XRP Ledger, a public blockchain driven by the XRPL developer community. +# targets: +# - en +# +# - name: XRPL オーバービュー +# template: page-xrpl-overview.html.jinja +# html: xrp-ledger-overview.html +# parent: index.html +# top_nav_name: アバウト +# top_nav_grouping: XRP Ledger +# sidebar: disabled +# targets: +# - ja +# +# # Redirect from the old overview.html +# - name: XRP Ledger Overview +# html: overview.html +# template: pagetype-redirect.html.jinja +# nav_omit: true +# redirect_url: xrp-ledger-overview.html +# targets: +# - en +# - ja +# +# # Redirect for rename from 'wallet server' to 'stock server' +# - name: Run rippled as a Stock Server +# html: run-rippled-as-a-wallet-server.html +# template: pagetype-redirect.html.jinja +# nav_omit: true +# redirect_url: run-rippled-as-a-stock-server.html +# targets: +# - en +# # This redirect needs to be added to the Japanese target *after* +# # renaming the original file in that target and translating the changes +# # - ja +# - name: Use Cases & Featured Projects template: page-uses.html.jinja html: uses.html @@ -258,24 +258,24 @@ pages: targets: - ja - - name: History - template: page-history.html.jinja - html: history.html - parent: xrp-ledger-overview.html - blurb: The history of the XRP Ledger (XRPL), launched in 2012 as a faster, scalable, more sustainable blockchain. - top_nav_grouping: XRP Ledger - sidebar: disabled - targets: - - en - - - name: 沿革 - template: page-history.html.jinja - html: history.html - parent: xrp-ledger-overview.html - top_nav_grouping: XRP Ledger - sidebar: disabled - targets: - - ja +# - name: History +# template: page-history.html.jinja +# html: history.html +# parent: xrp-ledger-overview.html +# blurb: The history of the XRP Ledger (XRPL), launched in 2012 as a faster, scalable, more sustainable blockchain. +# top_nav_grouping: XRP Ledger +# sidebar: disabled +# targets: +# - en +# +# - name: 沿革 +# template: page-history.html.jinja +# html: history.html +# parent: xrp-ledger-overview.html +# top_nav_grouping: XRP Ledger +# sidebar: disabled +# targets: +# - ja - name: Ledger Explorer html: https://livenet.xrpl.org/ @@ -284,67 +284,67 @@ pages: targets: - en - - name: XRP Ledger エクスプローラ - html: https://livenet.xrpl.org/ - parent: xrp-ledger-overview.html - top_nav_grouping: XRP Ledger - targets: - - ja - - - name: XRP - template: page-xrp-overview.html.jinja - html: xrp-overview.html - parent: xrp-ledger-overview.html - blurb: Learn more about XRP Ledger’s native digital asset, XRP. - top_nav_grouping: XRP - top_nav_name: XRP Overview - sidebar: disabled - targets: - - en - - ja - - - name: Impact - html: impact.html - parent: xrp-ledger-overview.html - template: page-impact.html.jinja - top_nav_grouping: Sustainability - blurb: Learn how the XRP Ledger helps move money around the world faster, cheaper and more sustainably than any other currency available today. - sidebar: disabled - targets: - - en - - - name: インパクト - html: impact.html - parent: xrp-ledger-overview.html - template: page-impact.html.jinja - top_nav_grouping: Sustainability - sidebar: disabled - targets: - - ja - - - name: Carbon Calculator - html: carbon-calculator.html - parent: xrp-ledger-overview.html - template: page-calculator.html.jinja - top_nav_grouping: Sustainability - sidebar: disabled - blurb: Whether it's cash, credit, or crypto, every transaction you make consumes energy. Use the XRPL cryptocurrency carbon calculator to compare. - fb_card: currency-calculator-card-fb.png - twitter_card: currency-calculator-card-tw.png - targets: - - en - - - name: 二酸化炭素電卓 - html: carbon-calculator.html - parent: xrp-ledger-overview.html - template: page-calculator.html.jinja - top_nav_grouping: Sustainability - sidebar: disabled - blurb: 現金、クレジットカード、暗号資産でもエネルギー消費する。インタラクティブツールで消費量を比較しましょう。 - fb_card: currency-calculator-card-fb.png - twitter_card: currency-calculator-card-tw.png - targets: - - ja +# - name: XRP Ledger エクスプローラ +# html: https://livenet.xrpl.org/ +# parent: xrp-ledger-overview.html +# top_nav_grouping: XRP Ledger +# targets: +# - ja +# +# - name: XRP +# template: page-xrp-overview.html.jinja +# html: xrp-overview.html +# parent: xrp-ledger-overview.html +# blurb: Learn more about XRP Ledger’s native digital asset, XRP. +# top_nav_grouping: XRP +# top_nav_name: XRP Overview +# sidebar: disabled +# targets: +# - en +# - ja +# +# - name: Impact +# html: impact.html +# parent: xrp-ledger-overview.html +# template: page-impact.html.jinja +# top_nav_grouping: Sustainability +# blurb: Learn how the XRP Ledger helps move money around the world faster, cheaper and more sustainably than any other currency available today. +# sidebar: disabled +# targets: +# - en +# +# - name: インパクト +# html: impact.html +# parent: xrp-ledger-overview.html +# template: page-impact.html.jinja +# top_nav_grouping: Sustainability +# sidebar: disabled +# targets: +# - ja +# +# - name: Carbon Calculator +# html: carbon-calculator.html +# parent: xrp-ledger-overview.html +# template: page-calculator.html.jinja +# top_nav_grouping: Sustainability +# sidebar: disabled +# blurb: Whether it's cash, credit, or crypto, every transaction you make consumes energy. Use the XRPL cryptocurrency carbon calculator to compare. +# fb_card: currency-calculator-card-fb.png +# twitter_card: currency-calculator-card-tw.png +# targets: +# - en +# +# - name: 二酸化炭素電卓 +# html: carbon-calculator.html +# parent: xrp-ledger-overview.html +# template: page-calculator.html.jinja +# top_nav_grouping: Sustainability +# sidebar: disabled +# blurb: 現金、クレジットカード、暗号資産でもエネルギー消費する。インタラクティブツールで消費量を比較しましょう。 +# fb_card: currency-calculator-card-fb.png +# twitter_card: currency-calculator-card-tw.png +# targets: +# - ja - name: XRPL Foundation html: https://foundation.xrpl.org/ @@ -388,27 +388,28 @@ pages: top_nav_name: Docs top_nav_shortcuts: # Programming Languages - - get-started-using-python.html - - get-started-using-javascript.html - - get-started-using-java.html - - get-started-using-http-websocket-apis.html - # Popular pages - - send-xrp.html - - reserves.html - - xrp-testnet-faucet.html - - run-rippled-as-a-validator.html - - build-run-rippled-in-reporting-mode.html - #- intro-to-consensus.html - - public-api-methods.html + - +# - get-started-using-python.html +# - get-started-using-javascript.html +# - get-started-using-java.html +# - get-started-using-http-websocket-apis.html +# # Popular pages +# - send-xrp.html +# - reserves.html +# - xrp-testnet-faucet.html +# - run-rippled-as-a-validator.html +# - build-run-rippled-in-reporting-mode.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? - - send-xrp.html - - reserves.html - - xrp-testnet-faucet.html - - run-rippled-as-a-validator.html - - build-run-rippled-in-reporting-mode.html - #- intro-to-consensus.html - - public-api-methods.html +# popular_pages: #TODO: find a way so this isn't a partial duplicate of top_nav_shortcuts? +# - send-xrp.html +# - reserves.html +# - xrp-testnet-faucet.html +# - run-rippled-as-a-validator.html +# - build-run-rippled-in-reporting-mode.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. filters: @@ -505,693 +506,278 @@ pages: - en - ja - - 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 - - ja +# - 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 +# - ja - - md: concepts/understanding-xrpl/xrpl/ledgers.md - parent: understanding-xrpl.html + - md: concepts/server/rippled-server.md + parent: concepts.html targets: - en - ja - - md: concepts/understanding-xrpl/xrpl/ledger-structure.md + - md: concepts/xrpl/ledgers.md + parent: concepts.html + targets: + - en + - ja + + - md: concepts/xrpl/ledger-structure.md parent: ledgers.html targets: - en - ja - - md: concepts/understanding-xrpl/xrpl/validation.md + - md: concepts/xrpl/validation.md parent: ledgers.html targets: - en - ja - - md: concepts/understanding-xrpl/xrpl/consensus.md + - md: concepts/xrpl/consensus.md parent: validation.html targets: - en - ja - - md: concepts/understanding-xrpl/xrpl/consensus-structure.md + - md: concepts/xrpl/consensus-structure.md parent: consensus.html targets: - en - ja - - md: concepts/understanding-xrpl/xrpl/double-spend.md + - md: concepts/xrpl/double-spend.md parent: consensus.html targets: - en - ja - - md: concepts/understanding-xrpl/xrpl/consensus-principles-and-rules.md + - md: concepts/xrpl/consensus-principles-and-rules.md parent: consensus.html targets: - en - ja - - md: concepts/understanding-xrpl/xrpl/consensus-protections.md + - md: concepts/xrpl/consensus-protections.md parent: consensus.html targets: - en - ja - - md: concepts/understanding-xrpl/xrpl/fee-voting.md + - md: concepts/xrpl/fee-voting.md parent: consensus.html targets: - en - ja - - md: concepts/understanding-xrpl/xrpl/negative-unl.md + - md: concepts/xrpl/negative-unl.md parent: consensus.html targets: - en - ja - - md: concepts/understanding-xrpl/xrpl/invariant-checking.md + - md: concepts/xrpl/invariant-checking.md parent: consensus.html targets: - en - ja - - md: concepts/understanding-xrpl/xrpl/consensus-research.md + - md: concepts/xrpl/consensus-research.md parent: consensus.html targets: - en - ja - - md: concepts/understanding-xrpl/xrpl/open-closed-validated-ledgers.md + - md: concepts/xrpl/open-closed-validated-ledgers.md parent: validation.html targets: - en - ja - - md: concepts/understanding-xrpl/xrpl/ledger-close-times.md + - md: concepts/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 + - md: concepts/transactions/transactions.md + parent: concepts.html targets: - en - ja - - md: concepts/understanding-xrpl/transactions/transaction-structure.md + - md: concepts/transactions/transaction-structure.md parent: transactions.html targets: - en - ja - - md: concepts/understanding-xrpl/transactions/transaction-metadata-concept.md + - md: concepts/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 - template: pagetype-category.html.jinja - blurb: One of the primary purposes of the XRP Ledger is payment processing. Learn more about key concepts that will help you understand the XRP Ledger payment system. - targets: - - en - - - name: 支払いシステムの基本 - html: payment-system-basics.html - parent: concepts.html - template: pagetype-category.html.jinja - blurb: XRP Ledgerの主な狙いは決済処理です。主要なコンセプトを詳しく学んで、XRP Ledgerの決済システムの理解を深めましょう。 - targets: - - ja - - - md: concepts/payment-system-basics/accounts/accounts.md - targets: - - en - - - md: concepts/payment-system-basics/accounts/accounts.ja.md - targets: - - ja - - - md: concepts/payment-system-basics/accounts/cryptographic-keys.md - targets: - - en - - # TODO: update translation based on latest English version - - md: concepts/payment-system-basics/accounts/cryptographic-keys.ja.md - targets: - - ja - - - md: concepts/payment-system-basics/accounts/multi-signing.md - targets: - - en - - - md: concepts/payment-system-basics/accounts/multi-signing.ja.md - targets: - - ja - - - md: concepts/payment-system-basics/accounts/reserves.md - targets: - - en - - - md: concepts/payment-system-basics/accounts/reserves.ja.md - targets: - - ja - - - md: concepts/payment-system-basics/accounts/tickets.md - targets: - - en - - - md: concepts/payment-system-basics/accounts/tickets.ja.md - targets: - - ja - - - md: concepts/payment-system-basics/accounts/depositauth.md - targets: - - en - - - md: concepts/payment-system-basics/accounts/depositauth.ja.md - targets: - - ja - - - md: concepts/payment-system-basics/fees.md - targets: - - en - - - md: concepts/payment-system-basics/fees.ja.md - targets: - - ja - -# - 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 - targets: - - ja - - - md: concepts/payment-system-basics/transaction-basics/transaction-basics.md - targets: - - en - - - md: concepts/payment-system-basics/transaction-basics/transaction-basics.ja.md - targets: - - ja - -# - md: concepts/payment-system-basics/transaction-basics/transaction-cost.md -# targets: -# - en - - - md: concepts/payment-system-basics/transaction-basics/transaction-cost.ja.md - targets: - - ja - - - md: concepts/payment-system-basics/transaction-basics/finality-of-results.md - targets: - - en - - - md: concepts/payment-system-basics/transaction-basics/finality-of-results.ja.md - targets: - - ja - - - md: concepts/payment-system-basics/transaction-basics/source-and-destination-tags.md - targets: - - en - - # TODO: Somehow this page's blurb got translated into Japanese but the page itself wasn't? - # For now we overwrite the blurb but use the page otherwise as-is. - - md: concepts/payment-system-basics/transaction-basics/source-and-destination-tags.md - blurb: 多目的アドレスとの間で支払いのやり取りをする具体的な目的を示すためにソースタグと宛先タグを使用します。 - untranslated_warning: true - targets: - - ja - - - name: Payment Types - html: payment-types.html - parent: concepts.html - template: pagetype-category.html.jinja - blurb: The XRP Ledger supports point-to-point XRP payments alongside other, more specialized payment types. - targets: - - en - - - name: 支払いのタイプ - html: payment-types.html - parent: concepts.html - template: pagetype-category.html.jinja - blurb: XRP LedgerはポイントツーポイントのXRPペイメントのほかに、より専門化した支払いタイプをサポートしています。 - targets: - - ja - - # Redirect from the old landing name/URL - - name: Complex Payment Types - html: complex-payment-types.html - template: pagetype-redirect.html.jinja - nav_omit: true - redirect_url: payment-types.html - targets: - - en - - ja - - - md: concepts/payment-types/direct-xrp-payments.md - targets: - - en - - - md: concepts/payment-types/direct-xrp-payments.ja.md - targets: - - ja - - - md: concepts/payment-types/cross-currency-payments.md - targets: - - en - - - md: concepts/payment-types/cross-currency-payments.ja.md - targets: - - ja - - - md: concepts/payment-types/checks.md - targets: - - en - - - md: concepts/payment-types/checks.ja.md - targets: - - ja - - - md: concepts/payment-types/escrow.md - targets: - - en - - - md: concepts/payment-types/escrow.ja.md - targets: - - ja - - - md: concepts/payment-types/partial-payments.md - targets: - - en - - - md: concepts/payment-types/partial-payments.ja.md - targets: - - ja - - - md: concepts/payment-types/payment-channels.md - targets: - - en - - - md: concepts/payment-types/payment-channels.ja.md - targets: - - ja - - - md: concepts/tokens/tokens.md - targets: - - en - - - md: concepts/tokens/tokens.ja.md - targets: - - ja - - # Redirects from old (emptyish) landing pages. - - name: Tokens - html: issued-currencies.html - template: pagetype-redirect.html.jinja - redirect_url: tokens.html - blurb: Anyone can make tokens representing digital value on the XRP Ledger. - targets: - - en - - - name: トークン - html: issued-currencies.html - template: pagetype-redirect.html.jinja - redirect_url: tokens.html - blurb: XRP Ledgerでは、XRP以外の通貨はすべて発行済み通貨とされます。XRP Ledgerで発行済み通貨がどのように機能するか説明します。 - targets: - - ja - - - md: concepts/tokens/trust-lines-and-issuing.md - targets: - - en - - - md: concepts/tokens/trust-lines-and-issuing.ja.md - targets: - - ja - - - md: concepts/tokens/authorized-trust-lines.md - targets: - - en - - - md: concepts/tokens/authorized-trust-lines.ja.md - targets: - - ja - - - md: concepts/tokens/non-fungible-tokens.md - targets: - - en - - ja - - - md: concepts/tokens/non-fungible-token-transfers.md - targets: - - en - - ja - - - md: concepts/tokens/nftoken-batch-minting.md - targets: - - en - - ja - - - md: concepts/tokens/freezes.md - targets: - - en - - - md: concepts/tokens/freezes.ja.md - targets: - - ja - - - md: concepts/tokens/common-misconceptions-about-freezes.md - targets: - - en - - ja - - - md: concepts/tokens/rippling.md - targets: - - en - - - md: concepts/tokens/rippling.ja.md - targets: - - ja - - - md: concepts/tokens/transfer-fees.md - targets: - - en - - - md: concepts/tokens/transfer-fees.ja.md - targets: - - ja - - - md: concepts/tokens/issuing-and-operational-addresses.md - targets: - - en - - - md: concepts/tokens/issuing-and-operational-addresses.ja.md - targets: - - ja - - - md: concepts/tokens/paths.md - targets: - - en - - - md: concepts/tokens/paths.ja.md - targets: - - ja - - - md: concepts/tokens/demurrage.md - targets: - - en - - - md: concepts/tokens/demurrage.ja.md - targets: - - ja - - - md: concepts/decentralized-exchange/decentralized-exchange.md - - - name: 分散型取引所 - html: decentralized-exchange.html - parent: concepts.html - template: pagetype-category.html.jinja - blurb: XRP Ledgerには多機能な取引所が含まれており、この取引所を利用してユーザーは発行済み通貨をXRPに、あるいはXRPを発行済み通貨に交換できます。 - targets: - - ja - - - md: concepts/decentralized-exchange/offers.md - targets: - - en - - - md: concepts/decentralized-exchange/offers.ja.md - targets: - - ja - - - md: concepts/decentralized-exchange/autobridging.md - targets: - - en - - - md: concepts/decentralized-exchange/autobridging.ja.md - targets: - - ja - - - md: concepts/decentralized-exchange/ticksize.md - targets: - - en - - - md: concepts/decentralized-exchange/ticksize.ja.md - 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: rippledサーバー - html: xrpl-servers.html - parent: concepts.html - template: pagetype-category.html.jinja - blurb: rippledは、XRP Ledgerを管理するコアのピアツーピアサーバーです。このセクションではコンセプトについて説明します。XRP Ledgerの基本的な部分の背景に「何があるか」、「なぜなのか」を学ぶことができます。 - targets: - - ja - - - md: concepts/xrpl-servers/rippled-server-modes.md - targets: - - en - - # TODO: Update this translation for the latest English version - - md: concepts/xrpl-servers/rippled-server-modes.ja.md - targets: - - ja - - - md: concepts/xrpl-servers/clustering.md - targets: - - en - - - md: concepts/xrpl-servers/clustering.ja.md - targets: - - ja - - - md: concepts/xrpl-servers/ledger-history/ledger-history.md - targets: - - en - - - md: concepts/xrpl-servers/ledger-history/ledger-history.ja.md - targets: - - ja - - - md: concepts/xrpl-servers/ledger-history/online-deletion.md - targets: - - en - - - md: concepts/xrpl-servers/ledger-history/online-deletion.ja.md - targets: - - ja - - - md: concepts/xrpl-servers/ledger-history/history-sharding.md - targets: - - en - - - md: concepts/xrpl-servers/ledger-history/history-sharding.ja.md - targets: - - ja - - - md: concepts/xrpl-servers/peer-protocol.md - targets: - - en - - - md: concepts/xrpl-servers/peer-protocol.ja.md - targets: - - ja - - - md: concepts/xrpl-servers/transaction-censorship-detection.md - targets: - - en - - - md: concepts/xrpl-servers/transaction-censorship-detection.ja.md - targets: - - ja - - - md: concepts/xrpl-servers/the-clio-server.md - targets: - - en - - ja - - # Redirect old "the-rippled-server.html" - - name: The rippled Server - html: the-rippled-server.html - template: pagetype-redirect.html.jinja - redirect_url: xrpl-servers.html - blurb: Learn about the core servers that power the XRP Ledger. - nav_omit: true - targets: - - en - - ja - - # Redirect old NFT articles - - name: Non-fungible Tokens (NFTs) - html: nft-concepts.html - template: pagetype-redirect.html.jinja - redirect_url: non-fungible-tokens.html - blurb: Explore XRPL-native support for NFTs. - nav_omit: true - targets: - - en - - ja - - - name: NFT Conceptual Overview - html: nft-conceptual-overview.html - template: pagetype-redirect.html.jinja - redirect_url: non-fungible-tokens.html - blurb: Explore XRPL-native support for NFTs. - nav_omit: true - targets: - - en - - ja + - md: concepts/transactions/trust-lines-and-issuing.md + parent: transactions.html + targets: + - en + - ja + + - md: concepts/transactions/transaction-cost.md + parent: transactions.html + targets: + - en + - ja + + - md: concepts/transactions/multi-signing.md + parent: transactions.html + targets: + - en + - ja + + - md: concepts/transactions/source-and-destination-tags.md + parent: transactions.html + targets: + - en + - ja + + - md: concepts/transactions/tickets.md + parent: transactions.html + targets: + - en + - ja + + - md: concepts/transactions/transaction-malleability.md + parent: transactions.html + targets: + - en + - ja + + - md: concepts/transactions/finality-of-results.md + parent: transactions.html + targets: + - en + - ja + + - md: concepts/transactions/about-canceling-a-transaction.md + parent: transactions.html + targets: + - en + - ja + + - md: concepts/transactions/transaction-history.md + parent: transactions.html + targets: + - en + - ja + + - md: concepts/transactions/transaction-results/transaction-results-concepts.md + parent: transactions.html + targets: + - en + - ja + + - md: concepts/transactions/transaction-results/tec-codes-concepts.md + parent: transaction-results-concepts.html + targets: + - en + - ja + + - md: concepts/transactions/transaction-results/tef-codes-concepts.md + parent: transaction-results-concepts.html + targets: + - en + - ja + + - md: concepts/transactions/transaction-results/tel-codes-concepts.md + parent: transaction-results-concepts.html + targets: + - en + - ja + + - md: concepts/transactions/transaction-results/tem-codes-concepts.md + parent: transaction-results-concepts.html + targets: + - en + - ja + + - md: concepts/transactions/transaction-results/ter-codes-concepts.md + parent: transaction-results-concepts.html + targets: + - en + - ja + + - md: concepts/transactions/transaction-results/tes-success-concepts.md + parent: transaction-results-concepts.html + targets: + - en + - ja + + - md: concepts/transactions/payments/payments.md + parent: transactions.html + targets: + - en + - ja + + - md: concepts/transactions/payments/direct-xrp-payments.md + parent: payments.html + targets: + - en + - ja + + - md: concepts/transactions/payments/cross-currency-payments.md + parent: payments.html + targets: + - en + - ja + + - md: concepts/transactions/payments/payment-channels.md + parent: payments.html + targets: + - en + - ja + + - md: concepts/transactions/payments/checks.md + parent: payments.html + targets: + - en + - ja + + - md: concepts/transactions/payments/escrow.md + parent: payments.html + targets: + - en + - ja + + - md: concepts/transactions/payments/partial-payments.md + parent: payments.html + targets: + - en + - ja + + + + ############ + ## Do Payments next. + ############ + + - md: concepts/tokens/tokens.md + parent: concepts.html + targets: + - en + - ja + + - md: concepts/accounts/accounts.md + parent: concepts.html + targets: + - en + - ja # Tutorials --------------------------------------------------------------------