xahau.js/docs/REFERENCE.md

#API Reference

(More examples coming soon!)

###In this document:

1. Remote options
2. Request constructors

• Server requests
• Ledger requests
• Transaction requests
• Account requests
• Orderbook requests
• Transaction requests

3. Transaction constructors

• Transaction events

###Also see:

1. The ripple-lib README
2. The ripple-lib GUIDES

#Remote options

/* Loading ripple-lib with Node.js */
var Remote = require('ripple-lib').Remote;

/* Loading ripple-lib in a webpage */
// var Remote = ripple.Remote;

var options = { };

var remote = new Remote(options);

A new Remote can be created with the following options:

• trace boolean default: false Log all of the events emitted
• max_listeners number default: 0 Set maxListeners for servers
• trusted boolean default: false, if remote is trusted (boolean)
• local_signing boolean default: true
• local_fee boolean default: true Set whether the transaction fee range will be set locally, see A note on transaction fees)
• fee_cushion number default: 1.2 Extra fee multiplier to account for async fee changes, see A note on transaction fees)
• max_fee number default: Infinity Maximum acceptable transaction fee, see A note on transaction fees
• servers array Array of server objects of the following form:

{
  host:    <string>,
  port:    <number>,
  secure:  <boolean>
}

or

 'wss://host:port'

#Request constructor functions

##Server requests

server_info([callback])

Returns information about the state of the server. If you are connected to multiple servers and want to select by a particular host, use request.setServer. Example:

var request = remote.request('server_info');

request.setServer('wss://s1.ripple.com');

request.request(function(err, res) {

});

unl_list([callback])

unl_add(addr, comment, [callback])

unl_delete(node, [callback])

requestPeers([callback])

connect(ip, port, [callback])

##Ledger requests

ledger(ledger, [opts], [callback])

ledger_header([callback])

ledger_current([callback])

ledger_entry(type, [callback])

subscribe([streams], [callback])

Start receiving selected streams from the server.

unsubscribe([streams], [callback])

Stop receiving selected streams from the server.

##Account requests

account_info(account, [callback])

Return information about the specified account.

{
  ledger_current_index: <number>,
  account_data: {
    Account:            <string>,
    Balance:            <number>,
    Flags:              <number>,
    LedgerEntryType:    <string>,
    OwnerCount:         <number>,
    PreviousTxnID:      <string>,
    PreviousTxnLgrSeq:  <number>,
    Sequence:           <number> ,
    index:              <string>
  }
}

account_lines(accountID, [account_index], [ledger], [callback])

account_offers(accountID, [account_index], [ledger], [callback])

Return the specified account's outstanding offers.

account_tx(options, [callback])

Fetch a list of transactions that applied to this account.

Options:

• account
• ledger_index_min
• ledger_index_max
• binary false
• count false
• descending false
• offset 0
• limit
• forward false
• fwd_marker
• rev_marker

wallet_accounts(seed, [callback])

Return a list of accounts for a wallet. Requires trusted remote

account_balance(account, [ledger], [callback])

Get the balance for an account. Returns an Amount object.

account_flags(account, [ledger], [callback])

Return the flags for an account.

owner_count(account, [ledger], [callback])

Return the owner count for an account.

ripple_balance(account, issuer, currency, [ledger], [callback])

Return a request to get a ripple balance

##Orderbook requests

book_offers(options, [callback])

Return the offers for an order book, also called a snapshot

var request = remote.request('book_offers', {
  taker_gets: {
    'currency':'XRP'
  },
  taker_pays: {
    'currency':'USD',
    'issuer': 'rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B'
  }
});

request.request(function(err, offers) {
  //handle offers
});

##Transaction requests

transaction_entry(hash, [ledger_hash], [callback])

Searches a particular ledger for a transaction hash. Default ledger is the open ledger.

tx(hash, [callback])

Searches ledger history for validated transaction hashes.

sign(secret, tx_json, [callback])

Sign a transaction. Requires trusted remote

submit([callback])

Submit a transaction to the network. This command is used internally to submit transactions with a greater degree of reliability. See Submitting a payment to the network for details.

ripple_path_find(src_account, dst_account, dst_amount, src_currencies, [callback])

#Transaction constructors

Use remote.createTransaction('TransactionType', [options]) to construct a transaction. To submit, use transaction.submit([callback]).

Payment

var transaction = remote.createTransaction('Payment', {
  account: MY_ADDRESS,
  destination: DEST_ADDRESS,
  amount: AMOUNT
});

AccountSet

var transaction = remote.createTransaction('AccountSet', {
  account: MY_ADDRESS,
  set: 'RequireDest',
  clear: 'RequireAuth'
});

TrustSet

var transaction = remote.createTransaction('TrustSet', {
  account: MY_ADDRESS,
  limit: '1/USD/rrrrrrrrrrrrrrrrrrrrBZbvji'
});

OfferCreate

var transaction = remote.createTransaction('OfferCreate', {
  account: MY_ADDRESS,
  taker_pays: '1',
  taker_gets: '1/USD/rrrrrrrrrrrrrrrrrrrrBZbvji'
});

##Transaction events

Transaction objects are EventEmitters. They may emit the following events.

• final Transaction has erred or succeeded. This event indicates that the transaction has finished processing.
• error Transaction has erred. This event is a final state.
• success Transaction succeeded. This event is a final state.
• presubmit Immediately before transaction is submitted
• postsubmit Immediately after transaction is submitted
• submitted Transaction has been submitted to the network. The submission may result in a remote error or success.
• resubmitted Transaction is beginning resubmission.
• proposed Transaction has been submitted successfully to the network. The transaction at this point is awaiting validation in a ledger.
• timeout Transaction submission timed out. The transaction will be resubmitted.
• fee_adjusted Transaction fee has been adjusted during its pending state. The transaction fee will only be adjusted if the remote is configured for local fees, which it is by default.
• abort Transaction has been aborted. Transactions are only aborted by manual calls to #abort.
• missing Four ledgers have closed without detecting validated transaction
• lost Eight ledgers have closed without detecting validated transaction. Consider the transaction lost and err/finalize.

##Complete payment example

remote.setSecret(MY_ADDRESS, MY_SECRET);

var transaction = remote.createTransaction('Payment', {
  account: MY_ADDRESS,
  destination: DEST_ADDRESS,
  amount: AMOUNT
});

transaction.on('resubmitted', function() {
  // initial submission failed, resubmitting
});

transaction.submit(function(err, res) {
 // submission has finalized with either an error or success.
 // the transaction will not be retried after this point
});

#Amount objects

Coming Soon