divvy-lib

A JavaScript API for interacting with the XDV Ledger

Features

• Connect to a divvyd server from Node.js or a web browser
• Issue divvyd API requests
• Listen to events on the XDV Ledger (transaction, ledger, etc.)
• Sign and submit transactions to the XDV Ledger

Getting Started

See also: DivvyAPI Beginners Guide

You can use npm, but we recommend using yarn for the added assurance provided by yarn.lock.

• Yarn Installation Instructions

Install divvy-lib:

$ yarn add divvy-lib

Then see the documentation and code samples

Running tests

1. Clone the repository
2. cd into the repository and install dependencies with yarn install
3. yarn test or yarn test --coverage (istanbul will create coverage reports in coverage/lcov-report/)

Generating Documentation

The continuous integration tests require that the documentation stays up-to-date. If you make changes to the JSON schemas, fixtures, or documentation sources, you must update the documentation by running yarn run docgen.

npm may be used instead of yarn in the commands above.

More Information

• Divvy Developer Center

divvy-lib Release History

0.19.0 (2018-03-02)

• Add support for Checks
• Add support for the Deposit Authorization account root flag
• Generate .ts.d TypeScript declaration files
• Improve documentation of getTransactions params
• Add new request interface (private for now)

The SHA-256 checksums for the browser version of this release can be found below.

% shasum -a 256 *
0e7ce4594b7e455fbc57ad81f6fddc391d1e1f349a49c96ad783be50f80fdc14  divvy-0.19.0-debug.js
6d716a0357929e51e476f22136880f7a0e5458fd396ac145ce9308f278ff7cc1  divvy-0.19.0-min.js
6715db1af638f99226ab7f8f244103306aa6e04d1b8c1da47a63431053bacb84  divvy-0.19.0.js

0.18.2 (2018-02-13)

• Fix: Publish updated browser builds to npm so that users can easily use CDNs
• Fix: Browserify fails due to dependency on ws
• Fix: build script fails when node_modules is in path
• Reduce size of published npm package
• Clean up files from Flow (we migrated to TypeScript)
• Typos and code cleanup

The SHA-256 checksums for the browser version of this release can be found below.

% shasum -a 256 *
f08ab61137255be3639e9d210ded2a182b6e0388f257a70d9b372ce7e7e518a6  divvy-0.18.2-debug.js
0604835b8421391167b4314ce93a76b5994780a08bd7edf36d91eb5e8f2643a2  divvy-0.18.2-min.js
fda56ab5c8256e04355e20064877ef4053f26c87f37cfcf861340f22bf89ee40  divvy-0.18.2.js

0.18.1 (2018-01-27)

Note: The package published to npm for this version did not include updated browser builds. If you are using a CDN that pulls from npm, please use 0.18.2 or later.

• Fix: isSameIssue() should check counterparty. This bug caused getOrderbook() to return incorrect values.

The SHA-256 checksums for the browser version of this release can be found below.

% shasum -a 256 *
6871855a2af1dc591ef557d442c11e8c60e01c5932054e13e8cbb84a182f45e0  divvy-0.18.1-debug.js
331f0baff46af44933a8fa31f128132945ff82a147acfff0a7315adb446e3de0  divvy-0.18.1-min.js
26324bb0725d2d484fe3b6086335d49734f45dc647b07c60746e0d8619f1ed3e  divvy-0.18.1.js

0.18.0 (2018-01-25)

• Convert from Flow to TypeScript
• Use ES Module syntax (Babel still compiles these to common.js modules for distribution)
• Docs: Improve escrow creation example/test
• Fix type errors
• Fix lint errors

0.17.9 (2017-11-14)

• Update ws dependency to 3.3.1
• Remove unnecessary polyfills
• Fix lint errors (#786, #808)
• Update divvy-keypairs dependency to 0.10.1

The SHA-256 checksums for the browser version of this release can be found below.

% shasum -a 256 *
b52f251eedac2509d72093eab1e8dba0d0f4a9fe6a28ec1cc90853cfb0fd7110  divvy-0.17.9-debug.js
d577a2bbdbdf7535c5365a1c52a2a31989d1b966e30abcba65c87133a536b9dc  divvy-0.17.9-min.js
ff4c3002842fac72ec2ebbd081e9594b0de6050d4d051a8fd6c06adb9a351488  divvy-0.17.9.js

The SHA-1 checksums for the browser version of this release can be found below.

% shasum *
e1995afc34aef6accd269cfccc55a45619618a41  divvy-0.17.9-debug.js
e6ad9a9c111ab696f5637bfa372d80999e5ae362  divvy-0.17.9-min.js
4866494ec5f9095cc34bea142f1e2b8ac5f7fbf8  divvy-0.17.9.js

0.17.8 (2017-11-06)

• Fix: Freezing in Safari 10.1 (updated bignumber.js) (closes #762)
• Fix: getSettings should include signers
• Update for Node 6
• Update lodash dependency
• Migrate to yarn

0.17.7 (2017-05-08)

• Replace AJV with jsonschema

0.16.5 (2016-01-21)

• Filter insufficient source funds paths from pathfind results

0.16.4

• Update ws to 1.0.1

0.16.2

• Bump divvy-binary-codec dependency version to 0.1.1 to fix issue with computeLedgerHash for transactions with DeliverMin

0.16.1

• FIX: Use assert not assert-diff

0.16.0

BREAKING CHANGES

• Fix types of XDV values in getServerInfo response
• Change error event format and fix crash due to error event on websocket

OTHER CHANGES

• Fix generateAddress docs and add error event listener to boilerplate
• Allow setting maxLedgerVersion to null to specify no maximum
• Add support for client certificates
• getFee returns a string not a float
• Fix parsing of quality for getTrustlines
• Fix DeliverMin value when specifying minAmount
• http server example

0.15.2

• Fix support for proxy credentials in proxy URL and fix error when there are more than 10 outstanding requests

0.15.1

• Fix babel-polyfill require
• Fix samples
• Add unit tests for DivvyAPIBroadcast

0.15.0

BREAKING CHANGES

• "servers" parameter changed to single "server"

OTHER CHANGES

• Fix handling memos in prepareSettings
• Docs: SusPay warnings, offline mode, and other tweaks
• Fix prepareOrderCancellation documentation

0.14.0

BREAKING CHANGES

• prepareOrderCancellation now takes orderCancellation specification
• Rename "ledgerClosed" event to "ledger" and change format

OTHER CHANGES

• Fix proxy support and add support for proxy authorization
• Fix trace option
• Allow memos on all transaction types
• Add documentation for DivvyAPI options
• Docs: more on basic types, tx types
• Docs: revised introductory material
• boost coverage to almost 100%

0.13.2

• Fix: Specify send_max when pathfinding with a source amount

0.13.1

• Add documentation for API events
• Fix: Add babel-polyfill
• Fix: Bump version on divvy-hashes

0.13.0

BREAKING CHANGES

• Add new DivvyAPI interface and delete old API
  • DivvyAPI README and samples

OTHER CHANGES

• Removed timeout method of Request and added default timeout
• Add Remote.closeCurrentPathFind function, so current pathfind can be properly closed
• Implement Balance Sheet API
• Fix bugs in orderbook subscription
• Fix crash due to divvyd slowDown error
• Fix: Emit error events and return error on pathfind
• Deprecate core and remove snake case method copying
• Fix RangeSet for validated_ledger as single ledger
• Fix bug where the paths would be set with an empty array
• Fix reserve calculation

0.12.9

• OrderBook performance optimizations

0.12.7 and 0.12.8

• Improve performance of orderbook
• Remove Firefox warning about prototype overwrite
• Fix compare bug in Amount class

0.12.6

• Fix webpack require failure due to "./" notation

0.12.15

• Add offer autobridging
• Prevent crash when listening for "model" events on the OrderBook class
• Fix empty order edgecase
• Fix AutobridgeCalculator (RT-3445)
• Update sjcl and delete custom ripemd160, montgomery, and jacobi
• Fix transaction summary for transactions that fail with remoteError
• Fix serializedobject append for excessively large bytes length
• Switch to sjcl npm module
• Add babel transpiler
• Remove unused float.js and wallet.js
• Remove config singleton to reduce global state

0.12.4

• Improve entropy security
• Remove unused crypt.js file

0.12.3

• Add getLedgerSequence to Remote
• Improve randomness when generating ECDSA signatures
• Improve SerializedObject.append performance
• Add Amount.scale. Multiply an amount’s value by a scale factor

0.12.2

• Check that stack trace is available, fixes logging in browser

0.12.1

BREAKING CHANGES

• Removed support for parsing native amounts in floating point format

OTHER CHANGES

• Fix taker pays funded calculation
• Fix order funded amount calculation
• Fix handling of quality in order book
• Fix currency parsing of non-alphanumeric and no-currency currencies
• Add Amount.strict_mode for toggling range validation
• Add filename and line number to log, use log.warn() for deprecations
• Add GlobalFreeze and NoFreeze flags
• Fix handling of falsy parameters in requestLedger
• Fix Base:decode
• Fix Amount: clone in ratio_human, product_human
• Fix Amount.to_human for very small numbers
• Refactor base conversion
• Update binary transaction format
• Add DefaultDivvy account flag
• Remove Features field requirement in SetFee transaction format
• Remove RegularKey field requirement in SetRegularKey transaction format

0.12.0

BREAKING CHANGES

• REMOVED Remote storage interface
• REMOVED Remote ping configuration
• REMOVED Old/deprecated Remote server configuration (websocket_ip, websocket_port)
• REMOVED browser online reconnect listener
  • Cleanup, deprecations - 2833a7b6
• Remove jsbn and use bignumber.js instead for big number math
• The allow_nan flag has been removed. Results for invalid amounts will always be NaN
  • Refactor to use bignumber.js - d025b4a0
  • Handle invalid input in parse_human - c8f18c8c
  • Check for null in isNumber - b86790c8
  • Cleanup amount.js - d0fb291c

OTHER CHANGES

• Add deprecation warnings to request constructors. The first argument to request constructor functions should be an object containing request properties
• Fix taker_gets_funded exceeding offer.TakerGets
• Fix unsymmetric memo serializing
• Fix IOU value passed to Amount.from_json()
• Update transaction binary parsing to account for XDV delivered amounts
• Bumped dependencies

0.11.0

• Track the funded status of an order based on cumulative account orders and 67d3973
• Remove blobvault client from divvy-lib, use the divvy-vault-client instead 9b3d62b7
• Add support for ledger option in requestBookOffers
• Add support for limit option in requestBookOffers
• Add ledgerSelect request constructor in Remote
• Default to binary data for commands that accept the binary flag
• Fix metadata account check
• Double check tes code before emitting success
• Decrease redundancy in binary account_tx parsing
• Abort server connection on unrecoverable TLS error
• Fix complete ledgers check on subscription that is not initial

0.10.0

• Transaction changes
• Important tef* and tel* and errors will no longer be presented as final. Rather than considering these errors final, divvy-lib will wait until the LastLedgerSequence specified in the transaction is exceeded. This makes failures more definitive, and ensures that no transaction will resubmit indefinitely.
• A new, final tej-class error is introduced to account for transactions that are locally determined to have expired: tejMaxLedger.
• Allow per transaction fees to be set, transaction.setFixedFee()
• Improve memo support
  • Add MemoFormat property for memo
  • Enforce MemoFormat and MemoType to be valid ASCII
  • Support text and json MemoFormat
• Update sjcl library
  • Improved entropy by taking advantage of platform crypto
  • Use jscl's k256 curve instead of altering the c256 curve with k256 configuration
  • Deprecated: The c256 curve is linked to the k256 curve to provide backwards compatibility, this link will be removed in the future
• Fix empty queue check on reconnect

0.9.4

• Normalize offers from book_offers and transaction stream
• Fix: Amount.to_human() precision rounding
• Fix: fractional drops in funded taker_pays setter

0.9.3

• Change presubmit to emit immediately before transaction submit
• Add a "core" browser build of divvy-lib which has a subset of features and smaller file size
• Update binformat with missing fields from divvyd
• Wait for transaction validation before returning tec error
• Change default max_fee on Remote to 1 XDV
• Fix: Request ledger_accept should return the Remote

0.9.2

BREAKING CHANGES

• Change accountRequest method signature

OTHER CHANGES

• Add paging behavior for account requests, account_lines and account_offers
• Add max_fee setter to transactions to set max fee the submitter is willing to pay
• Fix: cap IOU Amounts to their max and min value

Example on how to use paging with account_offers:

// A valid `ledger_index` or `ledger_hash` is required to provide a reliable result.
// Results can change between ledger closes, so the provided ledger will be used as base.
var options = {
    account: < divvyAccount >,
    limit: < Number between 10 and 400 >,
    ledger: < valid ledger_index or ledger_hash >
}

// The `marker` comes back in an account request if there are more results than are returned
// in the current response. The amount of results per response are determined by the `limit`.
if (marker) {
    options.marker = < marker >;
}

var request = remote.requestAccountOffers(options);

Full working example

0.9.1

• Switch account requests to use ledgerSelect rather than ledgerChoose (278df90)
• Deprecated setting ident and account_index on account requests (278df90)
• Change initial account transaction sequence to 1 (a3c1d06)
• Fix: instance transaction without remote (d3b6b81)
• Fix: account root request ledger argument (bc1f9f8)
• Fix: rsign.js local signing and example (d3b6b81 and f1004c6)

0.9.0

BREAKING CHANGES

• Make maxLoops in seed.get_key optional. Example use in tests (23e473b)

OTHER CHANGES

• Add routes to the vault client for KYC attestations (ed2da574)
• Currency: add show_interest flag to show or hide interest in Currency.to_human() and Currency.to_json() Example use in tests
• Configurable maxAttempts for transaction submission (d107092)
• Binformat: added missing TransactionResult options (6abed8d)
• Shrinkwrap packages for dependency locking (2dcd5f9)
• Fix: Amount.to_human() precision bugs (4be209e and 7708c64)
• Fix: change handling of requestLedger options (57b7030)

0.8.2

• Currency: Allow mixed letters and numbers in currencies
• Deprecate account_tx map/reduce/filterg
• Fix: correct requestLedger arguments
• Fix: missing subscription on error events for some server methods
• Fix: orderbook reset on reconnect
• Fix: divvy-lib crashing. Add potential missing error handlers

0.8.1

• Wallet: Add Wallet class that generates wallets
• Make npm test runnable in Windows.
• Fix several stability issues, see merged PR's for details
• Fix bug in Amount.to_human_full()
• Fix undefined fee states when connecting to a divvyd that is syncing

0.8.0

• Orderbook: Added tracking of offer funds for determining when offers are not funded
• Orderbook: Added tests
• Orderbook: Update owner funds
• Transactions: If transaction errs with tefALREADY, wait until all possible submissions err with the same before emitting error. Fixes a client "Transaction malformed" bug.
• Transactions: Track submissions, don't bother submitting to unconnected servers
• Request: request.request() now accepts an array of servers as first argument. Servers can be represented with URL, or the server object itself.
• Request: request.broadcast() now returns the number of servers request was sent to
• Server: Acquire host information from server without additional request
• Amount: Add a constant for the maximum canonical value that can be expressed as a Divvy value
• Amount: Make Constants static fields on the class, instead of a separate export

0.7.39

• Improvements to multi-server support. Fixed an issue where a server's score was not reset and connections would keep dropping after being connected for a significant amount of time.
• Improvements in order book support. Added support for currency pairs with interest bearing currencies. You can request an order book with hex, ISO code or full name for the currency.
• Fix value parsing for amount/currency order pairs, e.g. Amount.from_human("XAU 12345.6789")
• Improved Amount parsing from human readable string given a hex currency, e.g. Amount.from_human("10 015841551A748AD2C1F76FF6ECB0CCCD00000000")
• Improvements to username normalization in the vault client
• Add 2-factor authentication support for vault client
• Removed vestiges of Grunt, switched to Gulp

0.7.37

• Deprecations

  1. Removed humanistic amount detection in transaction.payment. Passing 1XDV as the payment amount no longer works.
  2. remote.setServer uses full server URL rather than hostname. Example: remote.setServer('wss://s.divvy.com:443')`
  3. Removed constructors for deprecated transaction types from transaction.js.
  4. Removed invoiceID option from transaction.payment. Instead, use the transaction.invoiceID method.
  5. Removed transaction.transactionManager getter.

• Improved multi-server support. Servers are now ranked dynamically, and transactions are broadcasted to all connected servers.

• Automatically ping connected servers. Client configuration now should contain ping: <seconds> to specify the ping interval.
• Added transaction.lastLedger to specify LastLedgerSequence. Setting it this way also ensures that the sequence is not bumped on subsequent requests.
• Added optional remote.accountTx binary parsing.

      {
        binary: true,
        parseBinary: false
      }

• Added full currency name support, e.g. Currency.from_json('XDV').to_human({full_name:'Divvys'}) will return XDV - Divvys
• Improved interest bearing currency support, e.g. Currency.from_human('USD - US Dollar (2.5%pa)')
• Improve test coverage
• Added blob vault client. The vault client facilitates interaction with divvy's namespace and blob vault or 3rd party blob vaults using divvy's blob vault software (https://github.com/xdv/divvy-blobvault). A list of the available functions can be found at docs/VAULTCLIENT.md

0.7.35

• LastLedgerSequence is set by default on outgoing transactions. This refers to the last valid ledger index (AKA sequence) for a transaction. By default, this index is set to the current index (at submission time) plus 8. In theory, this allows divvy-lib to deterministically fail a transaction whose submission request timed out, but whose associated server continues to emit ledger_closed events.
• Transactions that err with telINSUF_FEE_P will be automatically resubmitted. This error indicates that the Fee supplied in the transaction submission request was inadequate. Ideally, the Fee is tracked by divvy-lib in real-time, and the resubmitted transaction will most likely succeed.
• Added Transaction.iff(function(callback) { }). Callback expects first argument to be an Error or null, second argument is a boolean which indicates whether or not to proceed with the transaction submission. If an iff function is specified, it will be executed prior to every submission of the transaction (including resubmissions).
• Transactions will now emit presubmit and postsubmit events. They will be emitted before and after a transaction is submitted, respectively.
• Added Transaction.summary(). Returns a summary of a transaction in semi-human-readable form. JSON-stringifiable.
• Remote.requestAccountTx() with binary: true will automatically parse transactions.
• Added Remote.requestAccountTx filter, map, and reduce.

  remote.requestAccountTx({
    account: 'retc',
    ledger_index_min: -1,
    ledger_index_max: -1,
    limit: 100,
    binary: true,

    filter: function(transaction) {
      return transaction.tx.TransactionType === 'Payment';
    },

    map: function(transaction) {
      return Number(transaction.tx.Amount);
    },

    reduce: function(a, b) {
      return a + b;
    },

    pluck: 'transactions'
  }, console.log)

• Added persistence hooks.
• General performance improvements, especially for long-running processes.