Send a Check
Sending a Check is like writing permission for an intended recipient to pull a payment from you. The outcome of this process is a Check object in the ledger which the recipient can cash later.
In many cases, you want to send a Payment instead of a Check, since that delivers the money directly to the recipient in one step. However, if your intended recipient uses DepositAuth, you cannot send them Payments directly, so a Check is a good alternative.
This tutorial uses the example of a fictitious company, BoxSend SG (whose XRP Ledger address is rBXsgNkPcDN2runsvWmwxk3Lh97zdgo9za
) paying a fictitious cryptocurrency consulting company named Grand Payments (with XRP Ledger address rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis
) for some consulting work. Grand Payments prefers be paid in XRP, but to simplify their taxes and regulation, only accepts payments they've explicitly approved.
Outside of the XRP Ledger, Grand Payments sends an invoice to BoxSend SG with the ID 46060241FABCF692D4D934BA2A6C4427CD4279083E38C77CBE642243E43BE291
, and requests a Check for 100 XRP be sent to Grand Payments' XRP Ledger address of rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis
.
Prerequisites
To send a Check with this tutorial, you need the following:
- The address and secret key of a funded account to send the Check from.
- You can use the XRP Ledger Test Net Faucet to get a funded address and secret with 10,000 Test Net XRP.
- The address of a funded account to receive the Check.
- A secure way to sign transactions.
- A client library or any HTTP or WebSocket library.
1. Prepare the CheckCreate transaction
Decide how much money the Check is for and who can cash it. Figure out the values of the CheckCreate transaction fields. The following fields are the bare minimum; everything else is either optional or can be auto-filled when signing:
Field | Value | Description |
---|---|---|
TransactionType | String | Use the string CheckCreate here. |
Account | String (Address) | The address of the sender who is creating the Check. (In other words, your address.) |
Destination | String (Address) | The address of the intended recipient who can cash the Check. |
SendMax | String or Object (Amount) | The maximum amount the sender can be debited when this Check gets cashed. For XRP, use a string representing drops of XRP. For tokens, use an object with currency , issuer , and value fields. See Specifying Currency Amounts for details. If you want the recipient to be able to cash the Check for an exact amount of a non-XRP currency with a transfer fee, remember to include an extra percentage to pay for the transfer fee. (For example, for the recipient to cash a Check for 100 CAD from an issuer with a 2% transfer fee, you must set the SendMax to 102 CAD from that issuer.) |
Example CheckCreate Preparation
The following example shows a prepared Check from BoxSend SG (rBXsgNkPcDN2runsvWmwxk3Lh97zdgo9za
) to Grand Payments (rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis
) for 100 XRP. As additional (optional) metadata, BoxSend SG adds the ID of the invoice from Grand Payments so Grand Payments knows which invoice this Check is intended to pay.
'use strict' const RippleAPI = require('ripple-lib').RippleAPI // This example connects to a public Test Net server const api = new RippleAPI({server: 'wss://s.altnet.rippletest.net:51233'}) api.connect().then(() => { console.log('Connected') const sender = 'rBXsgNkPcDN2runsvWmwxk3Lh97zdgo9za' const receiver = 'rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis' const options = { // Allow up to 60 ledger versions (~5 min) instead of the default 3 versions // before this transaction fails permanently. "maxLedgerVersionOffset": 60 } return api.prepareCheckCreate(sender, { "destination": receiver, "sendMax": { "currency": "XRP", "value": "100" // RippleAPI uses decimal XRP, not integer drops }, "invoiceID": "46060241FABCF692D4D934BA2A6C4427CD4279083E38C77CBE642243E43BE291" }, options) }).then(prepared => { console.log("txJSON:", prepared.txJSON); // Disconnect and return }).then(() => { api.disconnect().then(() => { console.log('Disconnected') process.exit() }) }).catch(console.error) // Example output: // // Connected // txJSON: {"Account":"rBXsgNkPcDN2runsvWmwxk3Lh97zdgo9za", // "TransactionType":"CheckCreate", // "Destination":"rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis", // "SendMax":"100000000", // "Flags":2147483648, // "InvoiceID": "46060241FABCF692D4D934BA2A6C4427CD4279083E38C77CBE642243E43BE291", // "LastLedgerSequence":7835917,"Fee":"12","Sequence":2} // Disconnected
2. Sign the CheckCreate transaction
The most secure way to sign a transaction is to sign locally with a client library. Alternatively, if you run your own rippled
node you can sign the transaction using the sign method, but this must be done through a trusted and encrypted connection, or through a local (same-machine) connection.
In all cases, note the signed transaction's identifying hash for later.
Example Request
'use strict' const RippleAPI = require('ripple-lib').RippleAPI // Can sign offline if the txJSON has all required fields const api = new RippleAPI() const txJSON = '{"Account":"rBXsgNkPcDN2runsvWmwxk3Lh97zdgo9za", \ "TransactionType":"CheckCreate", \ "Destination":"rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis", \ "SendMax":"100000000", \ "Flags":2147483648, \ "LastLedgerSequence":7835923, \ "Fee":"12", \ "Sequence":2}' // Be careful where you store your real secret. const secret = 's████████████████████████████' const signed = api.sign(txJSON, secret) console.log("tx_blob is:", signed.signedTransaction) console.log("tx hash is:", signed.id)
Example Response
tx_blob is: 12001022800000002400000002201B0077911368400000000000000C694000000005F5E100732103B6FCD7FAC4F665FE92415DD6E8450AD90F7D6B3D45A6CFCF2E359045FF4BB400744630440220181FE2F945EBEE632966D5FB03114611E3047ACD155AA1BDB9DF8545C7A2431502201E873A4B0D177AB250AF790CE80621E16F141506CF507586038FC4A8E95887358114735FF88E5269C80CD7F7AF10530DAB840BBF6FDF8314A8B6B9FF3246856CADC4A0106198C066EA1F9C39 tx hash is: C0B27D20669BAB837B3CDF4B8148B988F17CE1EF8EDF48C806AE9BF69E16F441
3. Submit the signed transaction
Take the signed transaction blob from the previous step and submit it to a rippled
server. You can do this safely even if you do not run the rippled
server. The response contains a provisional result, which should be tesSUCCESS
, but this result is usually not final. A provisional response of terQUEUED
is also OK, since queued transactions are generally included in the next open ledger version (usually about 10 seconds after submission).
Tip: If the preliminary result is tefMAX_LEDGER
, the transaction has failed permanently because its LastLedgerSequence
parameter is lower than the current ledger. This happens when you take longer than the expected number of ledger versions between preparing and submitting the transaction. If this occurs, start over from step 1 with a higher LastLedgerSequence
value.
Example Request
'use strict' const RippleAPI = require('ripple-lib').RippleAPI // This example connects to a public Test Net server const api = new RippleAPI({server: 'wss://s.altnet.rippletest.net:51233'}) api.connect().then(() => { console.log('Connected') const tx_blob = "12001022800000002400000002201B0077911368400000000000000"+ "C694000000005F5E100732103B6FCD7FAC4F665FE92415DD6E8450AD90F7D6B3D45A6"+ "CFCF2E359045FF4BB400744630440220181FE2F945EBEE632966D5FB03114611E3047"+ "ACD155AA1BDB9DF8545C7A2431502201E873A4B0D177AB250AF790CE80621E16F1415"+ "06CF507586038FC4A8E95887358114735FF88E5269C80CD7F7AF10530DAB840BBF6FD"+ "F8314A8B6B9FF3246856CADC4A0106198C066EA1F9C39" return api.submit(tx_blob) }).then(response => { console.log("Preliminary transaction result:", response.resultCode) // Disconnect and return }).then(() => { api.disconnect().then(() => { console.log('Disconnected') process.exit() }) }).catch(console.error)
Example Response
Connected
Preliminary transaction result: tesSUCCESS
Disconnected
4. Wait for validation
On a live network (including Mainnet, Testnet, or Devnet), you can wait 4-7 seconds for the ledger to close automatically.
If you're running rippled
in stand-alone mode, use the [ledger_accept method][] to manually close the ledger.
5. Confirm final result
Use the tx method with the CheckCreate transaction's identifying hash to check its status. Look for a "TransactionResult": "tesSUCCESS"
field in the transaction's metadata, indicating that the transaction succeeded, and the field "validated": true
in the result, indicating that this result is final.
Look for a CreatedNode
object in the transaction metadata with a LedgerEntryType
of "Check"
. This indicates that the transaction created a Check ledger object. The LedgerIndex
of this object is the ID of the Check. In the following example, the Check's ID is 84C61BE9B39B2C4A2267F67504404F1EC76678806C1B901EA781D1E3B4CE0CD9
.
Example Request
'use strict' const RippleAPI = require('ripple-lib').RippleAPI const decodeAddress = require('ripple-address-codec').decodeAddress; const createHash = require('crypto').createHash; // This example connects to a public Test Net server const api = new RippleAPI({server: 'wss://s.altnet.rippletest.net:51233'}) api.connect().then(() => { console.log('Connected') const tx_hash = "C0B27D20669BAB837B3CDF4B8148B988F17CE1EF8EDF48C806AE9BF69E16F441" return api.getTransaction(tx_hash) }).then(response => { console.log("Final transaction result:", response) // Re-calculate checkID to work around issue ripple-lib#876 const checkIDhasher = createHash('sha512') checkIDhasher.update(Buffer.from('0043', 'hex')) checkIDhasher.update(new Buffer(decodeAddress(response.address))) const seqBuf = Buffer.alloc(4) seqBuf.writeUInt32BE(response.sequence, 0) checkIDhasher.update(seqBuf) const checkID = checkIDhasher.digest('hex').slice(0,64).toUpperCase() console.log("Calculated checkID:", checkID) // Disconnect and return }).then(() => { api.disconnect().then(() => { console.log('Disconnected') process.exit() }) }).catch(console.error)
Example Response
Connected Final transaction result: { type: 'checkCreate', address: 'rBXsgNkPcDN2runsvWmwxk3Lh97zdgo9za', sequence: 2, id: 'C0B27D20669BAB837B3CDF4B8148B988F17CE1EF8EDF48C806AE9BF69E16F441', specification: { destination: 'rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis', sendMax: { currency: 'XRP', value: '100' } }, outcome: { result: 'tesSUCCESS', timestamp: '2018-03-27T20:47:40.000Z', fee: '0.000012', balanceChanges: { rBXsgNkPcDN2runsvWmwxk3Lh97zdgo9za: [Array] }, orderbookChanges: {}, ledgerVersion: 7835887, indexInLedger: 0 } } Calculated checkID: CEA5F0BD7B2B5C85A70AE735E4CE722C43C86410A79AB87C11938AA13A11DBF9 Disconnected