Add getPaymentChannel

docs/index.md

@@ -47,6 +47,7 @@
   - [getOrderbook](#getorderbook)
   - [getSettings](#getsettings)
   - [getAccountInfo](#getaccountinfo)
+  - [getPaymentChannel](#getpaymentchannel)
   - [getLedger](#getledger)
   - [preparePayment](#preparepayment)
   - [prepareTrustline](#preparetrustline)
@@ -607,7 +608,7 @@ Name | Type | Description
 ---- | ---- | -----------
 amount | [value](#value) | Amount of XRP for sender to set aside in this channel.
 destination | [address](#ripple-address) | Address to receive XRP claims against this channel.
-settleDelay | number | Amount of time the source address must wait before closing the channel if it has unclaimed XRP.
+settleDelay | number | Amount of seconds the source address must wait before closing the channel if it has unclaimed XRP.
 publicKey | string | Public key of the key pair the source will use to sign claims against this channel.
 cancelAfter | date-time string | *Optional* Time when this channel expires.
 destinationTag | integer | *Optional* Destination tag.
@@ -2814,6 +2815,61 @@ return api.getAccountInfo(address).then(info =>
 ```
 
 
+## getPaymentChannel
+
+`getPaymentChannel(id: string): Promise<Object>`
+
+Returns specified payment channel.
+
+### Parameters
+
+Name | Type | Description
+---- | ---- | -----------
+id | string | 256-bit hexadecimal channel identifier.
+
+### Return Value
+
+This method returns a promise that resolves with an object with the following structure:
+
+Name | Type | Description
+---- | ---- | -----------
+account | [address](#ripple-address) | Address that created the payment channel.
+destination | [address](#ripple-address) | Address to receive XRP claims against this channel.
+amount | [value](#value) | The total amount of XRP funded in this channel.
+balance | [value](#value) | The total amount of XRP delivered by this channel.
+settleDelay | number | Amount of seconds the source address must wait before closing the channel if it has unclaimed XRP.
+previousAffectingTransactionID | string | Hash value representing the most recent transaction that affected this payment channel.
+previousAffectingTransactionLedgerVersion | integer | The ledger version that the transaction identified by the `previousAffectingTransactionID` was validated in.
+cancelAfter | date-time string | *Optional* Time when this channel expires as specified at creation.
+destinationTag | integer | *Optional* Destination tag.
+expiration | date-time string | *Optional* Time when this channel expires.
+publicKey | string | *Optional* Public key of the key pair the source will use to sign claims against this channel.
+sourceTag | integer | *Optional* Source tag.
+
+### Example
+
+```javascript
+const channelId =
+  'E30E709CF009A1F26E0E5C48F7AA1BFB79393764F15FB108BDC6E06D3CBD8415';
+return api.getPaymentChannel(channelId).then(channel =>
+  {/* ... */});
+```
+
+
+```json
+{
+  "account": "r6ZtfQFWbCkp4XqaUygzHaXsQXBT67xLj",
+  "amount": "10",
+  "balance": "0",
+  "destination": "rQf9vCwQtzQQwtnGvr6zc1fqzqg7QBuj7G",
+  "publicKey": "02A05282CB6197E34490BACCD9405E81D9DFBE123B0969F9F40EC3F9987AD9A97D",
+  "settleDelay": 10000,
+  "previousAffectingTransactionID": "F939A0BEF139465403C56CCDC49F59A77C868C78C5AEC184E29D15E9CD1FF675",
+  "previousAffectingTransactionLedgerVersion": 151322
+}
+```
+
+
 ## getLedger
 
 `getLedger(options: Object): Promise<Object>`

docs/src/getPaymentChannel.md.ejs

@@ -0,0 +1,26 @@
+## getPaymentChannel
+
+`getPaymentChannel(id: string): Promise<Object>`
+
+Returns specified payment channel.
+
+### Parameters
+
+<%- renderSchema('input/get-payment-channel.json') %>
+
+### Return Value
+
+This method returns a promise that resolves with an object with the following structure:
+
+<%- renderSchema('output/get-payment-channel.json') %>
+
+### Example
+
+```javascript
+const channelId =
+  'E30E709CF009A1F26E0E5C48F7AA1BFB79393764F15FB108BDC6E06D3CBD8415';
+return api.getPaymentChannel(channelId).then(channel =>
+  {/* ... */});
+```
+
+<%- renderFixture('responses/get-payment-channel.json') %>

docs/src/index.md.ejs

@@ -21,6 +21,7 @@
 <% include getOrderbook.md.ejs %>
 <% include getSettings.md.ejs %>
 <% include getAccountInfo.md.ejs %>
+<% include getPaymentChannel.md.ejs %>
 <% include getLedger.md.ejs %>
 <% include preparePayment.md.ejs %>
 <% include prepareTrustline.md.ejs %>

src/api.js

@@ -32,6 +32,7 @@ const getOrders = require('./ledger/orders')
 const getOrderbook = require('./ledger/orderbook')
 const getSettings = require('./ledger/settings')
 const getAccountInfo = require('./ledger/accountinfo')
+const getPaymentChannel = require('./ledger/payment-channel')
 const preparePayment = require('./transaction/payment')
 const prepareTrustline = require('./transaction/trustline')
 const prepareOrder = require('./transaction/order')
@@ -131,6 +132,7 @@ _.assign(RippleAPI.prototype, {
   getOrderbook,
   getSettings,
   getAccountInfo,
+  getPaymentChannel,
   getLedger,
 
   preparePayment,

src/common/schema-validator.js

@@ -66,6 +66,7 @@ function loadSchemas() {
     require('./schemas/output/get-orderbook.json'),
     require('./schemas/output/get-orders.json'),
     require('./schemas/output/order-change.json'),
+    require('./schemas/output/get-payment-channel.json'),
     require('./schemas/output/prepare.json'),
     require('./schemas/output/ledger-event.json'),
     require('./schemas/output/get-paths.json'),
@@ -84,6 +85,7 @@ function loadSchemas() {
     require('./schemas/input/get-orders.json'),
     require('./schemas/input/get-orderbook.json'),
     require('./schemas/input/get-paths.json'),
+    require('./schemas/input/get-payment-channel.json'),
     require('./schemas/input/api-options.json'),
     require('./schemas/input/get-settings.json'),
     require('./schemas/input/get-account-info.json'),

src/common/schemas/input/get-payment-channel.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "title": "getPaymentChannelParameters",
+  "description": "Parameters for getPaymentChannel",
+  "type": "object",
+  "properties": {
+    "id": {
+      "$ref": "hash256",
+      "description": "256-bit hexadecimal channel identifier."
+    }
+  },
+  "additionalProperties": false,
+  "required": ["id"]
+}

src/common/schemas/output/get-payment-channel.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "title": "getPaymentChannel",
+  "type": "object",
+  "properties": {
+    "account": {
+      "$ref": "address",
+      "description": "Address that created the payment channel."
+    },
+    "destination": {
+      "$ref": "address",
+      "description": "Address to receive XRP claims against this channel."
+    },
+    "amount": {
+      "$ref": "value",
+      "description": "The total amount of XRP funded in this channel."
+    },
+    "balance": {
+      "$ref": "value",
+      "description": "The total amount of XRP delivered by this channel."
+    },
+    "settleDelay": {
+      "type": "number",
+      "description": "Amount of seconds the source address must wait before closing the channel if it has unclaimed XRP."
+    },
+    "expiration": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Time when this channel expires."
+    },
+    "publicKey": {
+      "$ref": "publicKey",
+      "description": "Public key of the key pair the source will use to sign claims against this channel."
+    },
+    "cancelAfter": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Time when this channel expires as specified at creation."
+    },
+    "sourceTag": {
+      "$ref": "tag",
+      "description": "Source tag."
+    },
+    "destinationTag": {
+      "$ref": "tag",
+      "description": "Destination tag."
+    },
+    "previousAffectingTransactionID": {
+      "$ref": "hash256",
+      "description": "Hash value representing the most recent transaction that affected this payment channel."
+    },
+    "previousAffectingTransactionLedgerVersion": {
+      "$ref": "ledgerVersion",
+      "description": "The ledger version that the transaction identified by the `previousAffectingTransactionID` was validated in."
+    }
+  },
+  "required": [
+    "account",
+    "destination",
+    "amount",
+    "balance",
+    "settleDelay",
+    "previousAffectingTransactionID",
+    "previousAffectingTransactionLedgerVersion"
+  ],
+  "additionalProperties": false
+}

src/common/schemas/specifications/payment-channel-create.json

@@ -14,7 +14,7 @@
     },
     "settleDelay": {
       "type": "number",
-      "description": "Amount of time the source address must wait before closing the channel if it has unclaimed XRP."
+      "description": "Amount of seconds the source address must wait before closing the channel if it has unclaimed XRP."
     },
     "publicKey": {
       "$ref": "publicKey",

src/common/validate.js

@@ -33,6 +33,7 @@ module.exports = {
   getOrders: _.partial(validateOptions, 'getOrdersParameters'),
   getOrderbook: _.partial(validateOptions, 'getOrderbookParameters'),
   getTransaction: _.partial(validateOptions, 'getTransactionParameters'),
+  getPaymentChannel: _.partial(validateOptions, 'getPaymentChannelParameters'),
   getLedger: _.partial(validateOptions, 'getLedgerParameters'),
   preparePayment: _.partial(schemaValidate, 'preparePaymentParameters'),
   prepareOrder: _.partial(schemaValidate, 'prepareOrderParameters'),

src/ledger/parse/payment-channel.js

@@ -0,0 +1,37 @@
+/* @flow */
+'use strict' // eslint-disable-line strict
+const _ = require('lodash')
+const utils = require('./utils')
+
+type PaymentChannelResponse = {
+  account: string,
+  balance: string,
+  publicKey: number,
+  destination: string,
+  settleDelay: number,
+  expiration?: number,
+  cancelAfter?: number,
+  sourceTag?: number,
+  destinationTag?: number,
+  previousAffectingTransactionID: string,
+  previousAffectingTransactionLedgerVersion: number
+}
+
+function parsePaymentChannel(data: Object): PaymentChannelResponse {
+  return utils.removeUndefined({
+    account: data.Account,
+    amount: utils.dropsToXrp(data.Amount),
+    balance: utils.dropsToXrp(data.Balance),
+    destination: data.Destination,
+    publicKey: data.PublicKey,
+    settleDelay: data.SettleDelay,
+    expiration: utils.parseTimestamp(data.Expiration),
+    cancelAfter: utils.parseTimestamp(data.CancelAfter),
+    sourceTag: data.SourceTag,
+    destinationTag: data.DestinationTag,
+    previousAffectingTransactionID: data.PreviousTxnID,
+    previousAffectingTransactionLedgerVersion: data.PreviousTxnLgrSeq
+  })
+}
+
+module.exports = parsePaymentChannel

src/ledger/payment-channel.js

@@ -0,0 +1,58 @@
+/* @flow */
+'use strict' // eslint-disable-line strict
+const _ = require('lodash')
+const utils = require('./utils')
+const parsePaymentChannel = require('./parse/payment-channel')
+const {validate, removeUndefined} = utils.common
+const NotFoundError = utils.common.errors.NotFoundError
+
+type PaymentChannel = {
+  Sequence: number,
+  Account: string,
+  Balance: string,
+  PublicKey: number,
+  Destination: string,
+  SettleDelay: number,
+  Expiration?: number,
+  CancelAfter?: number,
+  SourceTag?: number,
+  DestinationTag?: number,
+  OwnerNode: string,
+  LedgerEntryType: string,
+  PreviousTxnID: string,
+  PreviousTxnLgrSeq: number,
+  index: string
+}
+
+type LedgerEntryResponse = {
+  node: PaymentChannel,
+  ledger_current_index?: number,
+  ledger_hash?: string,
+  ledger_index: number,
+  validated: boolean
+}
+
+function formatResponse(response: LedgerEntryResponse) {
+  if (response.node !== undefined &&
+      response.node.LedgerEntryType === 'PayChannel')
+  {
+    return parsePaymentChannel(response.node)
+  } else {
+    throw new NotFoundError('Payment channel ledger entry not found')
+  }
+}
+
+function getPaymentChannel(id: string): Promise<PaymentChannelResponse> {
+  validate.getPaymentChannel({id})
+
+  const request = {
+    command: 'ledger_entry',
+    index: id,
+    binary: false,
+    ledger_index: 'validated'
+  }
+
+  return this.connection.request(request).then(_.partial(formatResponse))
+}
+
+module.exports = getPaymentChannel

test/api-test.js

@@ -1113,6 +1113,45 @@ describe('RippleAPI', function() {
 
   });
 
+  it('getPaymentChannel', function() {
+    const channelId =
+      'E30E709CF009A1F26E0E5C48F7AA1BFB79393764F15FB108BDC6E06D3CBD8415';
+    return this.api.getPaymentChannel(channelId).then(
+      _.partial(checkResult, responses.getPaymentChannel.normal,
+        'getPaymentChannel'));
+  });
+
+  it('getPaymentChannel - full', function() {
+    const channelId =
+      'D77CD4713AA08195E6B6D0E5BC023DA11B052EBFF0B5B22EDA8AE85345BCF661';
+    return this.api.getPaymentChannel(channelId).then(
+      _.partial(checkResult, responses.getPaymentChannel.full,
+        'getPaymentChannel'));
+  });
+
+  it('getPaymentChannel - not found', function() {
+    const channelId =
+      'DFA557EA3497585BFE83F0F97CC8E4530BBB99967736BB95225C7F0C13ACE708';
+    return this.api.getPaymentChannel(channelId).then(() => {
+      assert(false, 'Should throw entryNotFound');
+    }).catch(error => {
+      assert(error instanceof this.api.errors.RippledError);
+      assert(_.includes(error.message, 'entryNotFound'));
+    });
+  });
+
+  it('getPaymentChannel - wrong type', function() {
+    const channelId =
+      '8EF9CCB9D85458C8D020B3452848BBB42EAFDDDB69A93DD9D1223741A4CA562B';
+    return this.api.getPaymentChannel(channelId).then(() => {
+      assert(false, 'Should throw NotFoundError');
+    }).catch(error => {
+      assert(_.includes(error.message,
+        'Payment channel ledger entry not found'));
+      assert(error instanceof this.api.errors.NotFoundError);
+    });
+  });
+
   it('getServerInfo', function() {
     return this.api.getServerInfo().then(
       _.partial(checkResult, responses.getServerInfo, 'getServerInfo'));

test/fixtures/responses/get-payment-channel-full.json

@@ -0,0 +1,12 @@
+{
+  "account": "r6ZtfQFWbCkp4XqaUygzHaXsQXBT67xLj",
+  "amount": "10",
+  "balance": "3",
+  "destination": "rQf9vCwQtzQQwtnGvr6zc1fqzqg7QBuj7G",
+  "publicKey": "02A05282CB6197E34490BACCD9405E81D9DFBE123B0969F9F40EC3F9987AD9A97D",
+  "settleDelay": 10000,
+  "cancelAfter": "2017-04-08T00:00:00.000Z",
+  "expiration": "2017-04-07T06:09:31.000Z",
+  "previousAffectingTransactionID": "39C47AD0AF1532D6A796EEB90BDA1A61B3EE4FA96C7A08070B78B33CE24F2160",
+  "previousAffectingTransactionLedgerVersion": 156978
+}

test/fixtures/responses/get-payment-channel.json

@@ -0,0 +1,10 @@
+{
+  "account": "r6ZtfQFWbCkp4XqaUygzHaXsQXBT67xLj",
+  "amount": "10",
+  "balance": "0",
+  "destination": "rQf9vCwQtzQQwtnGvr6zc1fqzqg7QBuj7G",
+  "publicKey": "02A05282CB6197E34490BACCD9405E81D9DFBE123B0969F9F40EC3F9987AD9A97D",
+  "settleDelay": 10000,
+  "previousAffectingTransactionID": "F939A0BEF139465403C56CCDC49F59A77C868C78C5AEC184E29D15E9CD1FF675",
+  "previousAffectingTransactionLedgerVersion": 151322
+}

test/fixtures/responses/index.js

@@ -16,6 +16,10 @@ module.exports = {
     XrpToXrp: require('./get-paths-xrp-to-xrp.json'),
     sendAll: require('./get-paths-send-all.json')
   },
+  getPaymentChannel: {
+    normal: require('./get-payment-channel.json'),
+    full: require('./get-payment-channel-full.json')
+  },
   getServerInfo: require('./get-server-info.json'),
   getSettings: require('./get-settings.json'),
   getTransaction: {

test/fixtures/rippled/escrow.json

@@ -0,0 +1,24 @@
+{
+  "id": 0,
+  "status": "success",
+  "type": "response",
+  "result" : {
+    "node" : {
+      "index" : "8EF9CCB9D85458C8D020B3452848BBB42EAFDDDB69A93DD9D1223741A4CA562B",
+      "Destination" : "r6ZtfQFWbCkp4XqaUygzHaXsQXBT67xLj",
+      "LedgerEntryType" : "Escrow",
+      "Flags" : 0,
+      "PreviousTxnID" : "0E85B685CEF53E0364829384C226E5479058FF94AFC27EC4D9A49B3E072708D3",
+      "PreviousTxnLgrSeq" : 150441,
+      "OwnerNode" : "0000000000000000",
+      "CancelAfter" : 544838400,
+      "Amount" : "1000000",
+      "Account" : "r6ZtfQFWbCkp4XqaUygzHaXsQXBT67xLj",
+      "Condition" : "A0258020E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855810100"
+    },
+    "index" : "8EF9CCB9D85458C8D020B3452848BBB42EAFDDDB69A93DD9D1223741A4CA562B",
+    "validated" : true,
+    "ledger_hash" : "6000B3C351D7DC87A1D1EE30603519E164903B104BD0476A2F908877E121BC88",
+    "ledger_index" : 174353
+  }
+}

test/fixtures/rippled/index.js

@@ -26,12 +26,16 @@ module.exports = {
     normal: require('./account-tx'),
     one: require('./get-transactions-one')
   },
+  escrow: require('./escrow'),
   gateway_balances: require('./gateway-balances'),
   book_offers: {
     fabric: require('./book-offers'),
     usd_xrp: require('./book-offers-usd-xrp'),
     xrp_usd: require('./book-offers-xrp-usd')
   },
+  ledger_entry: {
+    error: require('./ledger-entry-error')
+  },
   server_info: {
     normal: require('./server-info'),
     noValidated: require('./server-info-no-validated'),
@@ -46,6 +50,10 @@ module.exports = {
     srcActNotFound: require('./path-find-srcActNotFound'),
     sourceAmountLow: require('./path-find-srcAmtLow')
   },
+  payment_channel: {
+    normal: require('./payment-channel'),
+    full: require('./payment-channel-full')
+  },
   tx: {
     Payment: require('./tx/payment.json'),
     AccountSet: require('./tx/account-set.json'),

test/fixtures/rippled/ledger-entry-error.json

@@ -0,0 +1,14 @@
+{
+  "ledger_index" : 172450,
+  "validated" : true,
+  "error" : "entryNotFound",
+  "ledger_hash" : "9A8B034D72FA6CAE2D69425335FDD59D67DEB18A40DD83DF7331D08B19669A19",
+  "status" : "error",
+  "request" : {
+     "index" : "DFA557EA3497585BFE83F0F97CC8E4530BBB99967736BB95225C7F0C13ACE708",
+     "binary" : false,
+     "ledger_index" : "validated",
+     "command" : "ledger_entry"
+  },
+  "type": "response"
+}

test/fixtures/rippled/payment-channel-full.json

@@ -0,0 +1,27 @@
+{
+  "id": 0,
+  "status": "success",
+  "type": "response",
+  "result" : {
+    "node" : {
+      "Account" : "r6ZtfQFWbCkp4XqaUygzHaXsQXBT67xLj",
+      "Amount" : "10000000",
+      "Balance" : "3000000",
+      "CancelAfter" : 544924800,
+      "Destination" : "rQf9vCwQtzQQwtnGvr6zc1fqzqg7QBuj7G",
+      "Expiration" : 544860571,
+      "Flags" : 0,
+      "LedgerEntryType" : "PayChannel",
+      "OwnerNode" : "0000000000000000",
+      "PreviousTxnID" : "39C47AD0AF1532D6A796EEB90BDA1A61B3EE4FA96C7A08070B78B33CE24F2160",
+      "PreviousTxnLgrSeq" : 156978,
+      "PublicKey" : "02A05282CB6197E34490BACCD9405E81D9DFBE123B0969F9F40EC3F9987AD9A97D",
+      "SettleDelay" : 10000,
+      "index" : "D77CD4713AA08195E6B6D0E5BC023DA11B052EBFF0B5B22EDA8AE85345BCF661"
+    },
+    "index" : "D77CD4713AA08195E6B6D0E5BC023DA11B052EBFF0B5B22EDA8AE85345BCF661",
+    "validated" : true,
+    "ledger_hash" : "15CEA3135B7F450C12E4CD0B01140551FA16E5FDA3A7083F9B96BBE24CCBABB9",
+    "ledger_index" : 157007
+  }
+}

test/fixtures/rippled/payment-channel.json

@@ -0,0 +1,25 @@
+{
+  "id": 0,
+  "status": "success",
+  "type": "response",
+  "result" : {
+    "node" : {
+      "Balance" : "0",
+      "SettleDelay" : 10000,
+      "LedgerEntryType" : "PayChannel",
+      "Flags" : 0,
+      "Amount" : "10000000",
+      "index" : "E30E709CF009A1F26E0E5C48F7AA1BFB79393764F15FB108BDC6E06D3CBD8415",
+      "Destination" : "rQf9vCwQtzQQwtnGvr6zc1fqzqg7QBuj7G",
+      "OwnerNode" : "0000000000000000",
+      "Account" : "r6ZtfQFWbCkp4XqaUygzHaXsQXBT67xLj",
+      "PublicKey" : "02A05282CB6197E34490BACCD9405E81D9DFBE123B0969F9F40EC3F9987AD9A97D",
+      "PreviousTxnID" : "F939A0BEF139465403C56CCDC49F59A77C868C78C5AEC184E29D15E9CD1FF675",
+      "PreviousTxnLgrSeq" : 151322
+    },
+    "index" : "E30E709CF009A1F26E0E5C48F7AA1BFB79393764F15FB108BDC6E06D3CBD8415",
+    "validated" : true,
+    "ledger_hash" : "5EFF42C5C5DD539D62DC176AF638ED11F2B8B13ACD007D973FF40C44CDC49870",
+    "ledger_index" : 151336
+  }
+}

test/mock-rippled.js

@@ -220,6 +220,22 @@ module.exports = function createMockRippled(port) {
     }
   });
 
+  mock.on('request_ledger_entry', function(request, conn) {
+    assert.strictEqual(request.command, 'ledger_entry');
+    if (request.index ===
+        'E30E709CF009A1F26E0E5C48F7AA1BFB79393764F15FB108BDC6E06D3CBD8415') {
+      conn.send(createResponse(request, fixtures.payment_channel.normal));
+    } else if (request.index ===
+        'D77CD4713AA08195E6B6D0E5BC023DA11B052EBFF0B5B22EDA8AE85345BCF661') {
+      conn.send(createResponse(request, fixtures.payment_channel.full));
+    } else if (request.index ===
+        '8EF9CCB9D85458C8D020B3452848BBB42EAFDDDB69A93DD9D1223741A4CA562B') {
+      conn.send(createResponse(request, fixtures.escrow));
+    } else {
+      conn.send(createResponse(request, fixtures.ledger_entry.error));
+    }
+  });
+
   mock.on('request_tx', function(request, conn) {
     assert.strictEqual(request.command, 'tx');
     if (request.transaction === hashes.VALID_TRANSACTION_HASH) {