最終更新:
編集

Payment

[ソース]

Paymentトランザクションは、アカウント間での価値の移動を表現するものです(通過するパスによっては、非可分的に発生する追加的な価値交換を伴うことがあります)。このトランザクションタイプはいくつかの支払いの種類に使用することがでできます。

Paymentは、アカウントを作成する唯一の手段でもあります。

PaymentのJSONの例

{
  "TransactionType" : "Payment",
  "Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
  "Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
  "Amount" : {
     "currency" : "USD",
     "value" : "1",
     "issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
  },
  "Fee": "12",
  "Flags": 2147483648,
  "Sequence": 2,
}

Query example transaction. >

Payment フィールド

共通フィールドに加えて、Paymentトランザクションは以下のフィールドを使用します。

フィールドJSONの型内部の型説明
Amount通貨額Amount送金する通貨額。XRP以外の金額の場合、入れ子フィールドの名前では、アルファベットの小文字のみ使用してください。tfPartialPaymentフラグが設定されている場合は、この金額を 上限 とする金額を送金します。
Destination文字列AccountID支払いを受取るアカウントの一意アドレス。
DestinationTag数値UInt32(省略可) 宛先(支払先となる、ホスティングされている受取人)への支払い理由を明確にするための任意のタグ。
InvoiceID文字列Hash256(省略可) この支払いの具体的な理由または識別子を表現する任意の256ビットハッシュ。
Pathsパス配列の配列PathSet(省略可。自動入力可能)このトランザクションに使用される支払いパスの配列。XRP間のトランザクションでは省略する必要があります。
SendMax通貨額Amount(省略可) 送金手数料、為替レート、スリッページを含め、このトランザクションに関して支払い元通貨での負担を許容する上限額。トランザクションの送信コストとして消却されるXRPは含めないでください。XRP以外の金額の場合、入れ子フィールドの名前では、アルファベットの小文字のみ使用してください。クロスカレンシー支払いまたは複数のトークンを伴う支払いについては、このフィールドを入力する必要があります。XRP間の支払いでは省略する必要があります。
DeliverMin通貨額Amount(省略可) このトランザクションで送金する、宛先通貨での最少金額。Partial Paymentsの場合のみ有効になります。XRP以外の金額の場合、入れ子フィールドの名前では、アルファベットの小文字のみ使用してください。

Paymentの種類

Paymentトランザクションタイプは、いくつかの異なるタイプの抽象的なアクションを表現することができる汎用ツールです。下の表で説明するように、トランザクションのフィールドに基づいてトランザクションタイプを識別することができます。

Paymentの種類AmountSendMaxPathsAddress = Destination?説明
XRP同士の直接支払いString (XRP)省略省略いいえアカウント間でへ直接XRPを送金します。常に正確な金額を送信します。基本的な取引コスト以外の手数料は適用されません。
発行通貨の作成・償還ObjectObject (任意)任意いいえXRP Ledgerに追跡されているXRP以外の通貨や資産の量を増減させます。送金手数料凍結は、直接送金・換金する際には適用されません。
クロスカレンシー(通貨間)決済Object (non-XRP) / String (XRP)Object (non-XRP) / String (XRP)通常は必須いいえ発行された通貨を保有者から別の保有者に送信します。AmountSendMaxの両方をXRPにすることはできません。これらの支払いは、発行者を介してリップリングし、トランザクションがパスセットを指定した場合、複数の仲介者を介してより長いパスを取ることができます。トランザクション形式には、発行者が設定した送金手数料 が適用されます。これらのトランザクションは、異なる通貨間や、場合によっては同じ通貨コードで異なる発行者の通貨間を接続するために、分散型取引所のオファーを利用します。
Partial paymentObject (non-XRP) / String (XRP)Object (non-XRP) / String (XRP)通常は必須いいえ任意の通貨を特定の金額まで送ります。tfPartialPayment フラグを使用します。トランザクションが成功するための最小値を指定する DeliverMin 値を含めることができます。トランザクションが DeliverMin を指定しない場合、任意の正の値 を指定して成功させることができる。
通貨変換Object (non-XRP) / String (XRP)Object (non-XRP) / String (XRP)必須はい分散型取引所のオファーを消費して、ある通貨を別の通貨に交換し、裁定取引の機会を得ることが出来ます。AmountSendMax の両方を XRP にすることはできません。Data API は、このタイプの取引を "payment" ではなく、"exchange" として追跡しています。

SendMaxおよびAmountで使用する特殊なissuerの値

ほとんどの場合、XRP以外の通貨額issuerフィールドは、金融機関の発行アドレスを示しています。ただし、支払いを記述するにあたって、支払いのAmountフィールドとSendMaxフィールドにあるissuerフィールドについては、特殊なルールが存在します。

  • 2つのアドレス間で、同一の通貨に関して存在する残高は常に1つです。つまり、金額のissuerフィールドが実際に表しているのは、イシュアンスを作成したアドレスではなく、イシュアンスを換金する相手方であることがあります。
  • 宛先AmountフィールドのissuerフィールドがDestinationアドレスと一致している場合、「宛先が受け入れるあらゆるイシュアー」を意味する特殊なケースとして取り扱われます。これには、他のトラストラインで保持されている宛先によって作成されたイシュアンスに加え、宛先が当該アドレスまでトラストラインを延長しているすべてのアドレスが含まれます。
  • SendMaxフィールドのissuerフィールドが送信元アカウントのアドレスと一致している場合、「送信元が使用できるあらゆるイシュアー」を意味する特殊なケースとして取り扱われます。これには、他のアカウントが送信元アカウントまで延長しているトラストラインで新しいイシュアンスを作成すること、送信元アカウントが保持しているイシュアンスを他のイシュアーから送信することが含まれます。

アカウントの作成

Payment型のトランザクションでは、資金供給のないアドレスに対して十分なXRPを送金することで、XRP Ledgerに新規のアカウントを作成できます。資金供給のないアドレスに対するその他のトランザクションは、常に失敗します。

詳細は、アカウントをご覧ください。

パス

Pathsフィールドが存在する場合、Pathフィールドには、 パスセット (パス配列の配列)が記述されていなければなりません。個々のパスは、さまざまな仲介アカウントやオーダーブックを経由して、送信者から受信者へと価値が1つの方向へ流れることを表します。単一のトランザクションで、複数のパスを使用する可能性もあります。例えば、トランザクションで複数のオーダーブックやAMMを使用して、最も有利なレートで通貨を交換する場合です。

以下の場合を含め、直接の支払いではPathsフィールドを省略する必要があります。

  • XRP間の送金。
  • 送信者と受信者を接続するトラストライン上での直接送金。

Pathsフィールドを指定すると、サーバは、提供されたセットと デフォルトパス の中から、使用するパス(指定されたアカウントに接続する上で、最も直行となる経路)をトランザクション処理時に判別します。このように決定された判別は、コストを最小化しようとするものですが、完璧であることは保証されません。

Pathsフィールドを、空の配列としたり、メンバーがすべて空の配列あるような配列としたりすることはできません。

詳細は、Pathsをご覧ください。

Paymentのフラグ

Payment型のトランザクションについては、Flagsフィールドで以下の値が追加でサポートされます。

フラグの名前16進値10進値説明
tfNoRippleDirect0x0001000065536デフォルトパスを使用せず、Pathsフィールドに含まれているパスのみ使用します。これによりトランザクションは強制的に裁定機会を活用することになります。ほとんどのクライアントでは、これは必要ありません。
tfPartialPayment0x00020000131072SendMaxを超えていないのに指定されたAmountを送金できない場合、即座に失敗とするのではなく、受取られる額を減額します。詳細は、Partial Paymentsをご覧ください。
tfLimitQuality0x00040000262144すべての変換で、入力と出力との比率がAmountSendMaxとの比率と同一であるか、さらに有利となるパスのみを採用します。詳細は、クオリティの制限をご覧ください。

Partial Payments

Partial Paymentsを利用すると、受取られる金額を減額することによって、支払いを成功させることができます。Partial Paymentsが有用なのは、追加的なコストを発生させずに支払いを返金する場合です。その一方で、成功したトランザクションのAmountフィールドに、送金された金額が常に正しく記述されていることを前提としている環境において、悪用されるおそれもあります。

Partial Paymentsとは、tfPartialPaymentフラグが有効になっているPaymentトランザクションです。Partial Paymentsは、SendMax値を超える金額を送金することなく、DeliverMinフィールド以上の正の金額(DeliverMinが指定されていない場合、任意の正の金額)を送金する場合に成功します。

支払いのメタデータにあるdelivered_amountフィールドは、宛先アカウントが実際に受け取る通貨の金額を示しています。

詳細は、Partial Paymentsの全文をご覧ください。

クオリティの制限

XRP Ledgerでは、ある通貨での入金額と別の通貨での出金額の比率として、通貨取引の「クオリティ」を定義します。例えば、2米ドルと引き換えに1イギリスポンドを受け取る場合、その交換の「クオリティ」は0.5です。

tfLimitQualityフラグを使用すると、実行する変換のクオリティについて下限を設定できます。このクオリティの制限は、宛先のAmountSendMaxの金額(通貨にかかわらず金額のみ)で除算することによって定義します。設定した場合、支払い処理エンジンは、クオリティの制限よりもクオリティ(為替レート)が低い(数値が小さい)パスの使用を回避します。

tfLimitQualityフラグは、それ自体、トランザクションが成功する状況を減少させるものになります。具体的には、好ましくない変換が支払いの一部で使用されている場合、支払いにおける変換の平均的なクオリティが全体としてクオリティの制限と同一か、それ以上であっても、支払いが拒否されます。支払いがこの形で拒否される場合、トランザクションの結果tecPATH_DRYです。

次の例を考えてみます。100人民元(Amount = 100人民元)を最大20米ドル(SendMax = 20米ドル)と引き換えに相手方に送金しようとする場合、クオリティの制限は5です。あるトレーダーが15米ドルと引き換えに95人民元をオファーしているものの(米ドルあたり約6.3人民元の比率)、市場の次善のオファーが2ドルに対して5人民元であるとします(米ドルあたり2.5人民元の比率)。両方のオファーを受諾して相手方に100人民元を送金する場合、送信元が負担するコストは17米ドルであり、平均のクオリティは約5.9です。

tfLimitQualityフラグが設定されていない場合、17米ドルというコストは指定されたSendMaxに収まっているため、このトランザクションは成功します。一方、tfLimitQualityフラグが有効になっている場合は失敗します。2番目のオファーを受諾するためのパスのクオリティは2.5であり、5というクオリティの制限よりも低いためです。

tfLimitQualityフラグが最も有用となるのは、Partial Paymentsと組み合わせる場合です。tfPartialPaymenttfLimitQualityの両方がトランザクションに対して設定されている場合、トランザクションでは、クオリティの制限よりも低い変換を使用することなく、送金可能な最大限の宛先Amountが送金されます。

95人民元/15米ドルのオファーと5人民元/2米ドルのオファーがある上の例で、トランザクションに関してtfPartialPaymentとtfLimitQualityの両方が有効になっている場合、状況は異なります。20米ドルのSendMaxおよび100人民元の宛先Amountを維持する場合も、クオリティの制限は5です。ただし、実行しようとするのはPartial Paymentsであるため、宛先に対する送金の全額を一度で送金できない場合、トランザクションを失敗とするのではなく、送金可能な最大限の金額が送金されます。つまり、トランザクションでは、クオリティが約6.3である95人民元/15米ドルのオファーは受け入れますが、5人民元/2米ドルのオファーはクオリティが2.5であり、クオリティの制限の5より低いため、拒否します。最終的に、トランザクションで送金されるのは満額の100人民元ではなく95人民元になりますが、不利な為替レートで資金を浪費することを避けられます。