Checkの変動金額での換金

Checks Amendmentにより追加されました。

Checkがレジャーに記録されており有効期限切れではない場合は、指定受取人はDeliverMinフィールドを指定したCheckCashトランザクションを送信することで、Checkを変動金額で換金して受領できます。この方法でCheckを換金すると、受取人は送金を最大限受領でき、Checkの送金元からは、CheckのSendMaxの全額が引き落とされるか、または可能な限りの額が引き落とされます。Checkの受取人にDeliverMin以上の額を送金できない場合は換金が失敗します。

Checkから可能な限りの額を受領したい場合には、変動金額でCheckを換金できます。

指定受取人は、Checkを正確な金額で換金することもできます。

前提条件

Checkを換金するための前提条件は、正確な金額を換金する場合も変動金額を換金する場合も同じです。

現在レジャーに記録されているCheckオブジェクトのIDが必要です。
- 例えば、以下の例では、あるCheckのIDとして838766BA2B995C00744175F69A1B11E32C3DBC40E64801A4056FCBD657F57334を使用していますが、各ステップをご自分で行う際には、異なるIDを使用する必要があります。
Checkに記載されている受取人のアドレスと秘密鍵。このアドレスは、CheckオブジェクトのDestinationアドレスと一致している必要があります。
発行済み通貨用のCheckの場合は、ご自身（受取人）にイシュアーに対するトラストラインがある必要があります。このトラストライン上のご自身の限度額は、受け取る金額を追加するための残高より十分高くなければなりません。
- トラストラインと限度額について詳しくは、トークンおよびトラストラインと発行をご覧ください。
トランザクションに安全に署名できる手段。
XRP Ledgerに接続できるクライアントライブラリか、それともHTTPライブラリ、WebSocketライブラリなど。

1. CheckCashトランザクションの準備

CheckCashトランザクションのフィールドの値を決定します。Checkを変動金額で換金する場合、以下のフィールドは必要最小限です。それ以外のフィールドはオプションまたは署名時に自動入力可能なフィールドです。

フィールド	値	説明
`TransactionType`	文字列	値が`CheckCash`の場合、これはCheckCashトランザクションです。
`Account`	文字列（アドレス）	Checkを換金する送信者のアドレス。（あなたのアドレスです。）
`CheckID`	文字列	レジャーで換金するCheckオブジェクトのID。この情報を確認するには、txメソッドを使用してCheckCreateトランザクションのメタデータを調べるか、またはaccount_objectsメソッドを使用してCheckを探します。
`DeliverMin`	文字列またはオブジェクト（額）	Checkから受領する最小額。この額を受領できない場合はCheckの換金が失敗し、Checkがレジャーに残るので、後で換金を再試行できます。XRPの場合、XRPのdrop数を示す文字列でなければなりません。トークンの場合、これは`currency`、`issuer`、および`value` フィールドを持つオブジェクトです。`currency`フィールドと`issuer`フィールドは、Checkオブジェクトの対応するフィールドに一致しており、`value`はCheckオブジェクトの額以下でなければなりません。詳細は、通貨額の指定をご覧ください。

変動金額で換金するCheckCashトランザクションの準備の例

Checkを変動金額で換金するためのトランザクションを準備する手順を以下の例に示します。

{
 "Account": "rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis",
 "TransactionType": "CheckCash",
 "DeliverMin": "95000000",
 "CheckID": "2E0AD0740B79BE0AAE5EDD1D5FC79E3C5C221D23C6A7F771D85569B5B91195C2"
}

2. CheckCashトランザクションの署名

トランザクションに署名する最も安全な方法は、クライアントライブラリを使用してローカルで署名することです。signメソッドを使用してトランザクションに署名することもできますが、その場合は信頼できる暗号化された接続を使用するか、ローカル接続を使用して、自分が管理しているサーバに対してのみに行うようにしてください。

いずれの場合も、後のために、署名したトランザクションの識別用ハッシュを書き留めておいてください。

リクエストの例

rippled sign s████████████████████████████ '{
  "Account": "rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis",
  "TransactionType": "CheckCash",
  "DeliverMin": "95000000",
  "CheckID": "84C61BE9B39B2C4A2267F67504404F1EC76678806C1B901EA781D1E3B4CE0CD9"
}'

レスポンスの例

Loading: "/etc/opt/ripple/rippled.cfg"
2018-Apr-03 00:09:53 HTTPClient:NFO Connecting to 127.0.0.1:5005

{
   "result" : {
      "status" : "success",
      "tx_blob" : "12001122800000002400000004501884C61BE9B39B2C4A2267F67504404F1EC76678806C1B901EA781D1E3B4CE0CD968400000000000000A6A4000000005A995C073210361ACFCB478BCAE01451F95060AF94F70365BF00D7B4661EC2C69EA383762516C7446304402203D7EC220D48AA040D6915C160275D202F7F808E2B58F11B1AB05FB5E5CFCC6C00220304BBD3AD32E13150E0ED7247F2ADFAE83D0ECE329E20CFE0F8DF352934DD2FC8114A8B6B9FF3246856CADC4A0106198C066EA1F9C39",
      "tx_json" : {
         "Account" : "rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis",
         "CheckID" : "84C61BE9B39B2C4A2267F67504404F1EC76678806C1B901EA781D1E3B4CE0CD9",
         "DeliverMin" : "95000000",
         "Fee" : "10",
         "Flags" : 2147483648,
         "Sequence" : 4,
         "SigningPubKey" : "0361ACFCB478BCAE01451F95060AF94F70365BF00D7B4661EC2C69EA383762516C",
         "TransactionType" : "CheckCash",
         "TxnSignature" : "304402203D7EC220D48AA040D6915C160275D202F7F808E2B58F11B1AB05FB5E5CFCC6C00220304BBD3AD32E13150E0ED7247F2ADFAE83D0ECE329E20CFE0F8DF352934DD2FC",
         "hash" : "A0AFE572E4736CBF49FF4D0D3FF8FDB0C4D31BD10CB4EB542230F85F0F2DD222"
      }
   }
}

3. 署名済みCheckCashトランザクションの送信

前のステップで署名したトランザクションblobをrippledサーバに送信します。これはrippledサーバを実行していなくても安全にできます。レスポンスには仮の結果が含まれ、それはtesSUCCESSであるべきですが、この結果は通常は最終的なものではありません。キューに入れられたトランザクションは通常、次のオープンレジャーのバージョンに含まれるからです(通常、送信から約10秒後となります)。

ヒント: 仮の結果が tefMAX_LEDGER であった場合、そのトランザクションのLastLedgerSequenceパラメータが現在のレジャー番号よりも低いため、そのトランザクションが失敗しています。これは、トランザクション情報を準備してから送信するまでに、予想されるレジャーのバージョン数よりも長くかかった場合に起こります。このような場合は、LastLedgerSequenceの値を大きくしてステップ1からやり直してください。

リクエストの例

rippled submit 12001122800000002400000004501884C61BE9B39B2C4A2267F67504404F1EC76678806C1B901EA781D1E3B4CE0CD968400000000000000A6A4000000005A995C073210361ACFCB478BCAE01451F95060AF94F70365BF00D7B4661EC2C69EA383762516C7446304402203D7EC220D48AA040D6915C160275D202F7F808E2B58F11B1AB05FB5E5CFCC6C00220304BBD3AD32E13150E0ED7247F2ADFAE83D0ECE329E20CFE0F8DF352934DD2FC8114A8B6B9FF3246856CADC4A0106198C066EA1F9C39

レスポンスの例

Loading: "/etc/opt/ripple/rippled.cfg"
2018-Apr-03 00:10:30 HTTPClient:NFO Connecting to 127.0.0.1:5005

{
   "result" : {
      "engine_result" : "tesSUCCESS",
      "engine_result_code" : 0,
      "engine_result_message" : "The transaction was applied. Only final in a validated ledger.",
      "status" : "success",
      "tx_blob" : "12001122800000002400000004501884C61BE9B39B2C4A2267F67504404F1EC76678806C1B901EA781D1E3B4CE0CD968400000000000000A6A4000000005A995C073210361ACFCB478BCAE01451F95060AF94F70365BF00D7B4661EC2C69EA383762516C7446304402203D7EC220D48AA040D6915C160275D202F7F808E2B58F11B1AB05FB5E5CFCC6C00220304BBD3AD32E13150E0ED7247F2ADFAE83D0ECE329E20CFE0F8DF352934DD2FC8114A8B6B9FF3246856CADC4A0106198C066EA1F9C39",
      "tx_json" : {
         "Account" : "rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis",
         "CheckID" : "84C61BE9B39B2C4A2267F67504404F1EC76678806C1B901EA781D1E3B4CE0CD9",
         "DeliverMin" : "95000000",
         "Fee" : "10",
         "Flags" : 2147483648,
         "Sequence" : 4,
         "SigningPubKey" : "0361ACFCB478BCAE01451F95060AF94F70365BF00D7B4661EC2C69EA383762516C",
         "TransactionType" : "CheckCash",
         "TxnSignature" : "304402203D7EC220D48AA040D6915C160275D202F7F808E2B58F11B1AB05FB5E5CFCC6C00220304BBD3AD32E13150E0ED7247F2ADFAE83D0ECE329E20CFE0F8DF352934DD2FC",
         "hash" : "A0AFE572E4736CBF49FF4D0D3FF8FDB0C4D31BD10CB4EB542230F85F0F2DD222"
      }
   }
}

4. 検証の待機

本番環境のネットワークやTestnetでは、レジャーが自動的に閉鎖するまでに4～7秒かかる場合があります。

スタンドアロンモードでrippledを実行している場合は、[ledger_acceptメソッド][]を使用してレジャーを手動で閉鎖します。

5. 最終結果の確認

トランザクションのステータスを確認するには、CheckCashトランザクションの識別用ハッシュを指定したtxメソッドを使用します。トランザクションが成功したことを示す"TransactionResult": "tesSUCCESS"フィールドをトランザクションメタデータから検索し、またこの結果が最終結果であることを示す"validated": trueフィールドを結果から検索します。

リクエストの例

rippled tx A0AFE572E4736CBF49FF4D0D3FF8FDB0C4D31BD10CB4EB542230F85F0F2DD222

レスポンスの例

Loading: "/etc/opt/ripple/rippled.cfg"
2018-Apr-03 00:11:17 HTTPClient:NFO Connecting to 127.0.0.1:5005

{
   "result" : {
      "Account" : "rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis",
      "CheckID" : "84C61BE9B39B2C4A2267F67504404F1EC76678806C1B901EA781D1E3B4CE0CD9",
      "DeliverMin" : "95000000",
      "Fee" : "10",
      "Flags" : 2147483648,
      "Sequence" : 4,
      "SigningPubKey" : "0361ACFCB478BCAE01451F95060AF94F70365BF00D7B4661EC2C69EA383762516C",
      "TransactionType" : "CheckCash",
      "TxnSignature" : "304402203D7EC220D48AA040D6915C160275D202F7F808E2B58F11B1AB05FB5E5CFCC6C00220304BBD3AD32E13150E0ED7247F2ADFAE83D0ECE329E20CFE0F8DF352934DD2FC",
      "date" : 576029432,
      "hash" : "A0AFE572E4736CBF49FF4D0D3FF8FDB0C4D31BD10CB4EB542230F85F0F2DD222",
      "inLedger" : 8005386,
      "ledger_index" : 8005386,
      "meta" : {
         "AffectedNodes" : [
            {
               "ModifiedNode" : {
                  "FinalFields" : {
                     "Flags" : 0,
                     "Owner" : "rBXsgNkPcDN2runsvWmwxk3Lh97zdgo9za",
                     "RootIndex" : "3F248A0715ECCAFC3BEE0C63C8F429ACE54ABC403AAF5F2885C2B65D62D1FAC1"
                  },
                  "LedgerEntryType" : "DirectoryNode",
                  "LedgerIndex" : "3F248A0715ECCAFC3BEE0C63C8F429ACE54ABC403AAF5F2885C2B65D62D1FAC1"
               }
            },
            {
               "ModifiedNode" : {
                  "FinalFields" : {
                     "Account" : "rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis",
                     "Balance" : "10099999960",
                     "Flags" : 0,
                     "OwnerCount" : 2,
                     "Sequence" : 5
                  },
                  "LedgerEntryType" : "AccountRoot",
                  "LedgerIndex" : "7939126A732EBBDEC715FD3CCB056EB31E65228CA17E3B2901E7D30B90FD03D3",
                  "PreviousFields" : {
                     "Balance" : "9999999970",
                     "Sequence" : 4
                  },
                  "PreviousTxnID" : "0283465F0D21BE6B1E91ABDE17266C24C1B4915BAAA9A88CC098A98D5ECD3E9E",
                  "PreviousTxnLgrSeq" : 8005334
               }
            },
            {
               "DeletedNode" : {
                  "FinalFields" : {
                     "Account" : "rBXsgNkPcDN2runsvWmwxk3Lh97zdgo9za",
                     "Destination" : "rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis",
                     "DestinationNode" : "0000000000000000",
                     "DestinationTag" : 1,
                     "Flags" : 0,
                     "InvoiceID" : "46060241FABCF692D4D934BA2A6C4427CD4279083E38C77CBE642243E43BE291",
                     "OwnerNode" : "0000000000000000",
                     "PreviousTxnID" : "09D992D4C89E2A24D4BA9BB57ED81C7003815940F39B7C87ADBF2E49034380BB",
                     "PreviousTxnLgrSeq" : 7841263,
                     "SendMax" : "100000000",
                     "Sequence" : 4
                  },
                  "LedgerEntryType" : "Check",
                  "LedgerIndex" : "84C61BE9B39B2C4A2267F67504404F1EC76678806C1B901EA781D1E3B4CE0CD9"
               }
            },
            {
               "ModifiedNode" : {
                  "FinalFields" : {
                     "Account" : "rBXsgNkPcDN2runsvWmwxk3Lh97zdgo9za",
                     "Balance" : "9899999920",
                     "Flags" : 0,
                     "OwnerCount" : 2,
                     "Sequence" : 8
                  },
                  "LedgerEntryType" : "AccountRoot",
                  "LedgerIndex" : "A9A591BA661F69433D5BEAA49F10BA2B8DEA5183EF414B9130BFE5E0328FE875",
                  "PreviousFields" : {
                     "Balance" : "9999999920",
                     "OwnerCount" : 3
                  },
                  "PreviousTxnID" : "54A7A917BE9AC13962251BCF1D09803C7BBE75882B8BFC987B5933A566A48215",
                  "PreviousTxnLgrSeq" : 8004870
               }
            },
            {
               "ModifiedNode" : {
                  "FinalFields" : {
                     "Flags" : 0,
                     "Owner" : "rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis",
                     "RootIndex" : "C6A30AD85346718C7148D161663F84A96A4F0CE7F4D68C3C74D176A6C50BA6B9"
                  },
                  "LedgerEntryType" : "DirectoryNode",
                  "LedgerIndex" : "C6A30AD85346718C7148D161663F84A96A4F0CE7F4D68C3C74D176A6C50BA6B9"
               }
            }
         ],
         "TransactionIndex" : 4,
         "TransactionResult" : "tesSUCCESS"
      },
      "status" : "success",
      "validated" : true
   }
}

エラー処理

Checkの換金がtecクラスコードで失敗した場合は、すべてのトランザクションレスポンスのリストでコードを確認し、適切に対処してください。CheckCashトランザクションでよく返される結果コードの一部を次に示します。

結果コード	意味	対処
`tecEXPIRED`	Checkが有効期限切れです。	Checkを取り消して、以前より長い有効期限を設定して新しいCheckを作成するように送金元に依頼します。
`tecNO_ENTRY`	Check IDが存在していません。	CheckCashトランザクションの`CheckID`が正しいことを確認してください。Checkがまだ取り消されていないこと、または正常に換金されていないことを確認してください。
`tecNO_LINE`	受取人がCheckの通貨のトラストラインを所有していません。	このイシュアーからのこの通貨を保有するには、指定された通貨とイシュアーのトラストラインを作成し、TrustSetトランザクションを使用してこのトラストラインに適切な限度額を設定してから、Checkの換金を再試行します。
`tecNO_PERMISSION`	CheckCashトランザクションの送信者はCheckの`Destination`ではありません。	Checkの`Destination`を再度確認します。
`tecNO_AUTH`	このCheckの通貨のイシュアーはAuthorized Trust Lineを使用していますが、受取人からイシュアーへのトラストラインが承認されていません。	このトラストラインを承認するようイシュアーに依頼し、承認されたらCheckの換金を再試行します。
`tecPATH_PARTIAL`	トラストラインの限度額、または送金元に送金通貨の残高（イシュアーの送金手数料がある場合はこの手数料を含む）が十分になかったことが原因で、Checkでは十分なトークンを送金できませんでした。	原因がトラストラインの限度額である場合は、（希望する場合には）限度額を引き上げるTrustSetトランザクションを送信するか、または通貨の一部を消費して残高を減らしてから、Checkの換金を再試行します。原因が送金元の残高である場合は、送金元にCheckの通貨が積み増しされるまで待つか、または以前よりも低い額でCheckの換金を再試行します。
`tecUNFUNDED_PAYMENT`	Checkで十分なXRPを送金できませんでした。	送金元にXRPが積み増しされるまで待つか、または以前よりも低い額でCheckの換金を再試行します。

6. 送金された額の確認

Checkが変動するDeliverMinの額で換金された場合は、Checkは少なくともDeliverMinの額で換金されたと想定できます。送金された額を正確に得るには、トランザクションメタデータを調べます。メタデータのAffectedNodes配列には、通貨のタイプに応じて、Checkの換金による残高の変更を反映した1～2つのオブジェクトが含まれています。

XRPの場合、Checkの送金元のAccountRootオブジェクトのXRP Balance フィールドから引き落しが行われます。Checkの受取人（CheckCashトランザクションを送信したユーザ）のAccountRootオブジェクトでは、最低でもCheckCashトランザクションのDeliverMinから、トランザクションの送信にかかるトランザクションコストを差し引いた額が、XRP Balanceに入金されます。
たとえば以下のModifiedNodeは、アカウントrGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis（Checkの受取人でありこのCheckCashトランザクションの送信者）のXRP残高が9999999970 dropから10099999960 dropに変更されています。つまり、このトランザクションを処理した結果として、受取人に対し正味 99.99999 XRPが入金されています。
```
{
  "ModifiedNode": {
    "FinalFields": {
       "Account": "rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis",
       "Balance": "10099999960",
       "Flags": 0,
       "OwnerCount": 2,
       "Sequence": 5
    },
    "LedgerEntryType": "AccountRoot",
    "LedgerIndex": "7939126A732EBBDEC715FD3CCB056EB31E65228CA17E3B2901E7D30B90FD03D3",
    "PreviousFields": {
       "Balance": "9999999970",
       "Sequence": 4
    },
    "PreviousTxnID": "0283465F0D21BE6B1E91ABDE17266C24C1B4915BAAA9A88CC098A98D5ECD3E9E",
    "PreviousTxnLgrSeq": 8005334
  }
}
```
正味金額99.99999 XRPは、このCheckCashトランザクションを送信するにあたり、トランザクションコストを支払うために消却された額を差し引いた後の金額です。以下のトランザクション指示（抜粋）は、トランザクションコスト（Feeフィールド）がXRPの10 dropであることを示しています。これを正味残高の変更に追加することで、このCheckの換金のために受取人rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAisに総額 100 XRPが入金されます。
```
"Account" : "rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis",
"TransactionType" : "CheckCash",
"DeliverMin" : "95000000",
"Fee" : "10",
```
Checkの送金元または受取人がイシュアーであるトークンの場合、これらのアカウント間のトラストラインを表すRippleStateオブジェクトでは、BalanceがCheckの受取人に有利な方法で調整されています。
イシュアーが第三者であるトークンの場合、2つのRippleState（送金元からイシュアーへのトラストラインとイシュアーから受取人へのトラストライン）に対する変更があります。Checkの送金元とイシュアーの関係を表すRippleStateオブジェクトではそのBalanceがイシュアーに有利に変更され、イシュアーと受取人の間の関係を表すRippleStateオブジェクトではそのBalanceが受取人に有利に変更されます。
- トークンに送金手数料がある場合、受取人への入金額を上回る額がCheckの送金元から引き落とされます。（この差額が送金手数料であり、これがイシュアーに戻されることによりイシュアーの正味の債務は減少します。）