Add DepositPreauth (#958)

* Expose parseAccountFlags() and add docs * Add example snippet * Default to node v10 for nvm * Maintain existing behavior for getSettings * Increase max line length from 80 to 120 (ter-max-len)
2025-11-29 08:35:49 +00:00 · 2018-10-31 16:27:32 -07:00
parent 89e4ff328c
commit 418987476e
17 changed files with 336 additions and 25 deletions
--- a/.nvmrc
+++ b/.nvmrc
@@ -1 +1 @@
-v8
+v10
--- a/HISTORY.md
+++ b/HISTORY.md
@@ -1,5 +1,9 @@
 # ripple-lib Release History

+## UNRELEASED
+
+ Add [DepositPreauth](https://developers.ripple.com/depositauth.html) ([#958](https://github.com/ripple/ripple-lib/pull/958))
+
 ## 1.0.2 (2018-10-16)

 + Fix #954: Exclude SendMax from all XRP to XRP payments (thanks @jefftrudeau)
--- a/docs/index.md
+++ b/docs/index.md
@@ -58,6 +58,8 @@
  - [getAccountObjects](#getaccountobjects)
  - [getPaymentChannel](#getpaymentchannel)
  - [getLedger](#getledger)
+  - [parseAccountFlags](#parseaccountflags)
+  - [prepareTransaction](#preparetransaction)
  - [preparePayment](#preparepayment)
  - [prepareTrustline](#preparetrustline)
  - [prepareOrder](#prepareorder)
@@ -4109,6 +4111,100 @@ return api.getLedger()
 ```


+## parseAccountFlags
+
+`parseAccountFlags(Flags: number): object`
+
+Parse an `AccountRoot` object's [`Flags`](https://developers.ripple.com/accountroot.html#accountroot-flags).
+
+### Parameters
+
+This method takes one parameter, the AccountRoot `Flags` number to parse. Note that flags have different mappings on other types of objects or in transactions such as AccountSet.
+
+### Return Value
+
+This method returns an object with containing a key for each AccountRoot flag known to this version of RippleAPI. Each flag has a boolean value of `true` or `false`.
+
+### Example
+
+```javascript
+const account_info = await api.request('account_info', {account: 'rKsdkGhyZH6b2Zzd5hNnEqSv2wpznn4n6N'})
+const flags = api.parseAccountFlags(account_info.account_data.Flags)
+console.log(JSON.stringify(flags, null, 2))
+```
+
+```json
+{
+  "passwordSpent": false,
+  "requireDestinationTag": false,
+  "requireAuthorization": false,
+  "depositAuth": true,
+  "disallowIncomingXRP": false,
+  "disableMasterKey": false,
+  "noFreeze": false,
+  "globalFreeze": false,
+  "defaultRipple": false
+}
+```
+
+## prepareTransaction
+
+`prepareTransaction(address: string, transaction: object, instructions: object): Promise<object>`
+
+Prepare a transaction. The prepared transaction must subsequently be [signed](#sign) and [submitted](#submit).
+
+This method works with any of [the transaction types supported by rippled](https://developers.ripple.com/transaction-types.html).
+
+Notably, this is the preferred method for preparing a `DepositPreauth` transaction (added in rippled 1.1.0).
+
+### Parameters
+
+Name | Type | Description
+---- | ---- | -----------
+transaction | [transaction](https://developers.ripple.com/transaction-formats.html) | The specification (JSON) of the transaction to prepare. Set `Account` to the address of the account that is creating the transaction. You may omit auto-fillable fields like `Fee`, `Flags`, and `Sequence` to have them set automatically.
+instructions | [instructions](#transaction-instructions) | *Optional* Instructions for executing the transaction.
+
+### Return Value
+
+This method returns a promise that resolves with an object with the following structure:
+
+<aside class="notice">
+All "prepare*" methods have the same return type.
+</aside>
+
+Name | Type | Description
+---- | ---- | -----------
+txJSON | string | The prepared transaction in rippled JSON format.
+instructions | object | The instructions for how to execute the transaction after adding automatic defaults.
+*instructions.* fee | [value](#value) | An exact fee to pay for the transaction. See [Transaction Fees](#transaction-fees) for more information.
+*instructions.* sequence | [sequence](#account-sequence-number) | The initiating account's sequence number for this transaction.
+*instructions.* maxLedgerVersion | integer,null | The highest ledger version that the transaction can be included in. Set to `null` if there is no maximum.
+*instructions.* maxLedgerVersion | string,null | The highest ledger version that the transaction can be included in. Set to `null` if there is no maximum.
+
+### Example
+
+```javascript
+async function preparedPreauth() {
+  const address = 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59';
+  return api.prepareTransaction({
+    TransactionType: 'DepositPreauth',
+    Account: address,
+    Authorize: 'rMyVso4p83khNyHdV1m1PggV9QNadCj8wM'
+  });
+}
+```
+
+```javascript
+{
+  txJSON: '{"TransactionType":"DepositPreauth","Account":"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59","Authorize":"rMyVso4p83khNyHdV1m1PggV9QNadCj8wM","Flags":2147483648,"LastLedgerSequence":13561714,"Fee":"12","Sequence":1}',
+  instructions: {
+    fee: '0.000012',
+    sequence: 1,
+    maxLedgerVersion: 13561714
+  }
+}
+```
+
 ## preparePayment

 `preparePayment(address: string, payment: object, instructions: object): Promise<object>`
@@ -4961,6 +5057,10 @@ sign(txJSON: string, keypair: object, options: object): {signedTransaction: stri

 Sign a prepared transaction. The signed transaction must subsequently be [submitted](#submit).

+This method can sign any of [the transaction types supported by ripple-binary-codec](https://github.com/ripple/ripple-binary-codec/blob/cfcde79c19c359e9a0466d7bc3dc9a3aef47bb99/src/enums/definitions.json#L1637). When a new transaction type is added to the XRP Ledger, it will be unrecognized until `ripple-binary-codec` is updated. If you try to sign an unrecognized transaction type, this method throws an error similar to the following:
+
+`Error: [TRANSACTION_TYPE] is not a valid name or ordinal for TransactionType`
+
 ### Parameters

 Name | Type | Description
--- a/docs/src/index.md.ejs
+++ b/docs/src/index.md.ejs
@@ -28,6 +28,8 @@
 <% include getAccountObjects.md.ejs %>
 <% include getPaymentChannel.md.ejs %>
 <% include getLedger.md.ejs %>
+<% include parseAccountFlags.md.ejs %>
+<% include prepareTransaction.md.ejs %>
 <% include preparePayment.md.ejs %>
 <% include prepareTrustline.md.ejs %>
 <% include prepareOrder.md.ejs %>
--- a/docs/src/parseAccountFlags.md.ejs
+++ b/docs/src/parseAccountFlags.md.ejs
@@ -0,0 +1,35 @@
+## parseAccountFlags
+
+`parseAccountFlags(Flags: number): object`
+
+Parse an `AccountRoot` object's [`Flags`](https://developers.ripple.com/accountroot.html#accountroot-flags).
+
+### Parameters
+
+This method takes one parameter, the AccountRoot `Flags` number to parse. Note that flags have different mappings on other types of objects or in transactions such as AccountSet.
+
+### Return Value
+
+This method returns an object with containing a key for each AccountRoot flag known to this version of RippleAPI. Each flag has a boolean value of `true` or `false`.
+
+### Example
+
+```javascript
+const account_info = await api.request('account_info', {account: 'rKsdkGhyZH6b2Zzd5hNnEqSv2wpznn4n6N'})
+const flags = api.parseAccountFlags(account_info.account_data.Flags)
+console.log(JSON.stringify(flags, null, 2))
+```
+
+```json
+{
+  "passwordSpent": false,
+  "requireDestinationTag": false,
+  "requireAuthorization": false,
+  "depositAuth": true,
+  "disallowIncomingXRP": false,
+  "disableMasterKey": false,
+  "noFreeze": false,
+  "globalFreeze": false,
+  "defaultRipple": false
+}
+```
--- a/docs/src/prepareTransaction.md.ejs
+++ b/docs/src/prepareTransaction.md.ejs
@@ -0,0 +1,50 @@
+## prepareTransaction
+
+`prepareTransaction(address: string, transaction: object, instructions: object): Promise<object>`
+
+Prepare a transaction. The prepared transaction must subsequently be [signed](#sign) and [submitted](#submit).
+
+This method works with any of [the transaction types supported by rippled](https://developers.ripple.com/transaction-types.html).
+
+Notably, this is the preferred method for preparing a `DepositPreauth` transaction (added in rippled 1.1.0).
+
+### Parameters
+
+Name | Type | Description
+---- | ---- | -----------
+transaction | [transaction](https://developers.ripple.com/transaction-formats.html) | The specification (JSON) of the transaction to prepare. Set `Account` to the address of the account that is creating the transaction. You may omit auto-fillable fields like `Fee`, `Flags`, and `Sequence` to have them set automatically.
+instructions | [instructions](#transaction-instructions) | *Optional* Instructions for executing the transaction.
+
+### Return Value
+
+This method returns a promise that resolves with an object with the following structure:
+
+<aside class="notice">
+All "prepare*" methods have the same return type.
+</aside>
+
+<%- renderSchema("output/prepare.json") %>
+
+### Example
+
+```javascript
+async function preparedPreauth() {
+  const address = 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59';
+  return api.prepareTransaction({
+    TransactionType: 'DepositPreauth',
+    Account: address,
+    Authorize: 'rMyVso4p83khNyHdV1m1PggV9QNadCj8wM'
+  });
+}
+```
+
+```javascript
+{
+  txJSON: '{"TransactionType":"DepositPreauth","Account":"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59","Authorize":"rMyVso4p83khNyHdV1m1PggV9QNadCj8wM","Flags":2147483648,"LastLedgerSequence":13561714,"Fee":"12","Sequence":1}',
+  instructions: {
+    fee: '0.000012',
+    sequence: 1,
+    maxLedgerVersion: 13561714
+  }
+}
+```
--- a/docs/src/sign.md.ejs
+++ b/docs/src/sign.md.ejs
@@ -7,6 +7,10 @@ sign(txJSON: string, keypair: object, options: object): {signedTransaction: stri

 Sign a prepared transaction. The signed transaction must subsequently be [submitted](#submit).

+This method can sign any of [the transaction types supported by ripple-binary-codec](https://github.com/ripple/ripple-binary-codec/blob/cfcde79c19c359e9a0466d7bc3dc9a3aef47bb99/src/enums/definitions.json#L1637). When a new transaction type is added to the XRP Ledger, it will be unrecognized until `ripple-binary-codec` is updated. If you try to sign an unrecognized transaction type, this method throws an error similar to the following:
+
+`Error: [TRANSACTION_TYPE] is not a valid name or ordinal for TransactionType`
+
 ### Parameters

 <%- renderSchema("input/sign.json") %>
--- a/package.json
+++ b/package.json
@@ -23,7 +23,7 @@
    "jsonschema": "1.2.2",
    "lodash": "^4.17.4",
    "ripple-address-codec": "^2.0.1",
-    "ripple-binary-codec": "^0.1.13",
+    "ripple-binary-codec": "0.2.0",
    "ripple-hashes": "^0.3.1",
    "ripple-keypairs": "^0.10.1",
    "ripple-lib-transactionparser": "0.7.1",
--- a/snippets/parseAccountFlags.js
+++ b/snippets/parseAccountFlags.js
@@ -0,0 +1,11 @@
+const RippleAPI = require('../dist/npm').RippleAPI
+const api = new RippleAPI({server: 'wss://s.altnet.rippletest.net:51233'})
+
+parseAccountFlags()
+
+async function parseAccountFlags() {
+  await api.connect()
+  const account_info = await api.request('account_info', {account: 'rKsdkGhyZH6b2Zzd5hNnEqSv2wpznn4n6N'})
+  const flags = api.parseAccountFlags(account_info.account_data.Flags)
+  console.log(JSON.stringify(flags, null, 2))
+}
--- a/src/api.ts
+++ b/src/api.ts
@@ -23,7 +23,7 @@ import getBalanceSheet from './ledger/balance-sheet'
 import getPaths from './ledger/pathfind'
 import getOrders from './ledger/orders'
 import getOrderbook from './ledger/orderbook'
-import getSettings from './ledger/settings'
+import {getSettings, parseAccountFlags} from './ledger/settings'
 import getAccountInfo from './ledger/accountinfo'
 import getAccountObjects from './ledger/accountobjects'
 import getPaymentChannel from './ledger/payment-channel'
@@ -302,6 +302,7 @@ class RippleAPI extends EventEmitter {
  getAccountObjects = getAccountObjects
  getPaymentChannel = getPaymentChannel
  getLedger = getLedger
+  parseAccountFlags = parseAccountFlags

  preparePayment = preparePayment
  prepareTrustline = prepareTrustline
--- a/src/ledger/parse/deposit-preauth.ts
+++ b/src/ledger/parse/deposit-preauth.ts
@@ -0,0 +1,21 @@
+import * as assert from 'assert'
+import {removeUndefined} from '../../common'
+
+export type FormattedDepositPreauth = {
+  // account (address) of the sender to preauthorize
+  authorize: string,
+
+  // account (address) of the sender whose preauthorization should be revoked
+  unauthorize: string
+}
+
+function parseDepositPreauth(tx: any): FormattedDepositPreauth {
+  assert(tx.TransactionType === 'DepositPreauth')
+
+  return removeUndefined({
+    authorize: tx.Authorize,
+    unauthorize: tx.Unauthorize
+  })
+}
+
+export default parseDepositPreauth
--- a/src/ledger/parse/transaction.ts
+++ b/src/ledger/parse/transaction.ts
@@ -1,4 +1,3 @@
-import * as assert from 'assert'
 import {parseOutcome} from './utils'
 import {removeUndefined} from '../../common'
 import parsePayment from './payment'
@@ -12,6 +11,7 @@ import parseEscrowCancellation from './escrow-cancellation'
 import parseCheckCreate from './check-create'
 import parseCheckCash from './check-cash'
 import parseCheckCancel from './check-cancel'
+import parseDepositPreauth from './deposit-preauth'
 import parsePaymentChannelCreate from './payment-channel-create'
 import parsePaymentChannelFund from './payment-channel-fund'
 import parsePaymentChannelClaim from './payment-channel-claim'
@@ -19,29 +19,33 @@ import parseFeeUpdate from './fee-update'
 import parseAmendment from './amendment'

 function parseTransactionType(type) {
+  // Ordering matches https://developers.ripple.com/transaction-types.html
  const mapping = {
-    Payment: 'payment',
-    TrustSet: 'trustline',
-    OfferCreate: 'order',
-    OfferCancel: 'orderCancellation',
    AccountSet: 'settings',
-    SetRegularKey: 'settings',
+    CheckCancel: 'checkCancel',
+    CheckCash: 'checkCash',
+    CheckCreate: 'checkCreate',
+    DepositPreauth: 'depositPreauth',
+    EscrowCancel: 'escrowCancellation',
    EscrowCreate: 'escrowCreation',
    EscrowFinish: 'escrowExecution',
-    EscrowCancel: 'escrowCancellation',
-    CheckCreate: 'checkCreate',
-    CheckCash: 'checkCash',
-    CheckCancel: 'checkCancel',
+    OfferCancel: 'orderCancellation',
+    OfferCreate: 'order',
+    Payment: 'payment',
+    PaymentChannelClaim: 'paymentChannelClaim',
    PaymentChannelCreate: 'paymentChannelCreate',
    PaymentChannelFund: 'paymentChannelFund',
-    PaymentChannelClaim: 'paymentChannelClaim',
+    SetRegularKey: 'settings',
    SignerListSet: 'settings',
-    SetFee: 'feeUpdate', // pseudo-transaction
-    EnableAmendment: 'amendment' // pseudo-transaction
+    TrustSet: 'trustline',
+
+    EnableAmendment: 'amendment', // pseudo-transaction
+    SetFee: 'feeUpdate' // pseudo-transaction
  }
  return mapping[type] || null
 }

+// includeRawTransaction: undefined by default (getTransaction)
 function parseTransaction(tx: any, includeRawTransaction: boolean): any {
  const type = parseTransactionType(tx.TransactionType)
  const mapping = {
@@ -56,6 +60,7 @@ function parseTransaction(tx: any, includeRawTransaction: boolean): any {
    'checkCreate': parseCheckCreate,
    'checkCash': parseCheckCash,
    'checkCancel': parseCheckCancel,
+    'depositPreauth': parseDepositPreauth,
    'paymentChannelCreate': parsePaymentChannelCreate,
    'paymentChannelFund': parsePaymentChannelFund,
    'paymentChannelClaim': parsePaymentChannelClaim,
@@ -63,8 +68,15 @@ function parseTransaction(tx: any, includeRawTransaction: boolean): any {
    'amendment': parseAmendment
  }
  const parser: Function = mapping[type]
-  assert(parser !== undefined, 'Unrecognized transaction type')
-  const specification = parser(tx)
+
+  const specification = parser ? parser(tx) : {
+    UNAVAILABLE: 'Unrecognized transaction type.',
+    SEE_RAW_TRANSACTION: 'Since this type is unrecognized, `rawTransaction` is included in this response.'
+  }
+  if (!parser) {
+    includeRawTransaction = true
+  }
+
  const outcome = parseOutcome(tx)
  return removeUndefined({
    type: type,
--- a/src/ledger/settings.ts
+++ b/src/ledger/settings.ts
@@ -10,11 +10,17 @@ export type SettingsOptions = {
  ledgerVersion?: number
 }

-function parseFlags(value) {
+export function parseAccountFlags(
+    value: number,
+    options: {excludeFalse?: boolean} = {}) {
  const settings = {}
  for (const flagName in AccountFlags) {
    if (value & AccountFlags[flagName]) {
      settings[flagName] = true
+    } else {
+      if (!options.excludeFalse) {
+        settings[flagName] = false
+      }
    }
  }
  return settings
@@ -22,12 +28,12 @@ function parseFlags(value) {

 function formatSettings(response: AccountInfoResponse) {
  const data = response.account_data
-  const parsedFlags = parseFlags(data.Flags)
+  const parsedFlags = parseAccountFlags(data.Flags, {excludeFalse: true})
  const parsedFields = parseFields(data)
  return _.assign({}, parsedFlags, parsedFields)
 }

-async function getSettings(
+export async function getSettings(
  this: RippleAPI, address: string, options: SettingsOptions = {}
 ): Promise<FormattedSettings> {
  // 1. Validate
@@ -41,5 +47,3 @@ async function getSettings(
  // 3. Return Formatted Response
  return formatSettings(response)
 }
-
-export default getSettings
--- a/src/transaction/sign.ts
+++ b/src/transaction/sign.ts
@@ -79,6 +79,12 @@ function sign(
      options
    )
  } else {
+    if (!keypair && !secret) {
+      // Clearer message than 'ValidationError: instance is not exactly one from [subschema 0],[subschema 1]'
+      throw new utils.common.errors.ValidationError(
+        'sign: Missing secret or keypair.'
+      )
+    }
    return signWithKeypair(
      this,
      txJSON,
--- a/test/api-test.js
+++ b/test/api-test.js
@@ -883,6 +883,54 @@ describe('RippleAPI', function () {
          'prepare'));
  });

+  it('prepareTransaction - DepositPreauth - Authorize', function () {
+    const localInstructions = _.defaults({
+      maxFee: '0.000012'
+    }, instructions)
+
+    const txJSON = {
+      TransactionType: 'DepositPreauth',
+      Account: address,
+      Authorize: 'rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo'
+    }
+
+    return this.api.prepareTransaction(txJSON, localInstructions).then(response => {
+      const expected = {
+        txJSON: '{"TransactionType":"DepositPreauth","Account":"' + address + '","Authorize":"rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo","Flags":2147483648,"LastLedgerSequence":8820051,"Fee":"12","Sequence":23}',
+        instructions: {
+          fee: '0.000012',
+          sequence: 23,
+          maxLedgerVersion: 8820051
+        }
+      }
+      return checkResult(expected, 'prepare', response)
+    })
+  })
+
+  it('prepareTransaction - DepositPreauth - Unauthorize', function () {
+    const localInstructions = _.defaults({
+      maxFee: '0.000012'
+    }, instructions)
+
+    const txJSON = {
+      TransactionType: 'DepositPreauth',
+      Account: address,
+      Unauthorize: 'rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo'
+    }
+
+    return this.api.prepareTransaction(txJSON, localInstructions).then(response => {
+      const expected = {
+        txJSON: '{"TransactionType":"DepositPreauth","Account":"' + address + '","Unauthorize":"rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo","Flags":2147483648,"LastLedgerSequence":8820051,"Fee":"12","Sequence":23}',
+        instructions: {
+          fee: '0.000012',
+          sequence: 23,
+          maxLedgerVersion: 8820051
+        }
+      }
+      return checkResult(expected, 'prepare', response)
+    })
+  })
+
  describe('prepareTransaction - Payment', function () {

    it('normal', function () {
--- a/tslint.json
+++ b/tslint.json
@@ -57,7 +57,7 @@
    "triple-equals": true,
    "forin": false,
    "handle-callback-err": true,
-    "ter-max-len": [true, 80],
+    "ter-max-len": [true, 120],
    "new-parens": true,
    "object-curly-spacing": [true, "never"],
    "object-literal-shorthand": false,
--- a/yarn.lock
+++ b/yarn.lock
@@ -4828,7 +4828,20 @@ ripple-address-codec@^2.0.1:
    hash.js "^1.0.3"
    x-address-codec "^0.7.0"

-ripple-binary-codec@^0.1.0, ripple-binary-codec@^0.1.13:
+ripple-binary-codec@0.2.0:
+  version "0.2.0"
+  resolved "https://registry.yarnpkg.com/ripple-binary-codec/-/ripple-binary-codec-0.2.0.tgz#cef049f671f398de255e5c190b9f6545c7c7c36f"
+  integrity sha512-qCf3syhtwPFq70JIh/7VSegynj5gWXVNI5T5I7dobqiNxY3fZQvOePRnchnN1OzC0jMh8x0b2ASmkvIlf259zQ==
+  dependencies:
+    babel-runtime "^6.6.1"
+    bn.js "^4.11.3"
+    create-hash "^1.1.2"
+    decimal.js "^5.0.8"
+    inherits "^2.0.1"
+    lodash "^4.12.0"
+    ripple-address-codec "^2.0.1"
+
+ripple-binary-codec@^0.1.0:
  version "0.1.13"
  resolved "https://registry.yarnpkg.com/ripple-binary-codec/-/ripple-binary-codec-0.1.13.tgz#c68951405a17a71695551e789966ff376da552e4"
  integrity sha1-xolRQFoXpxaVVR54mWb/N22lUuQ=