xahau.js/README.md

#Ripple JavaScript Library

This library can connect to the Ripple network via the WebSocket protocol and runs in Node.js as well as in the browser.

• https://ripple.com/wiki/Ripple_JavaScript_library
• https://ripple.com
• https://ripple.com/wiki

##Getting started

ripple-lib.remote is responsible for managing connections to rippled servers.

var Remote = require('ripple-lib').Remote;

var remote = new Remote({
  trusted: true,
  local_signing: true,
  servers: [ 
    { 
        host: 'my.hostname'
      , port: 1337,
      , secure: true
    } 
  ]
});

remote.connect(function() {
  /* remote connected */
});

Once a connection is formed to any of the supplied servers, a connect event is emitted, indicating that the remote is ready to begin fulfilling requests. When there are no more connected servers to fulfill requests, a disconnect event is emitted. If you send requests before ripple-lib is connected to any servers, requests are deferred until the connect event is emitted.

var remote = new Remote({ /* options */ }).connect();

remote.request_server_info(function(err, info) {
 /* will defer until connected */
}); 

##Calling remote commands

Each remote function returns a Request object. This object is an EventEmitter. You may listen for success or failure events from each request, or provide a callback. Example:

var request = remote.request_server_info();
request.on('success', function(res) { 
  //handle success
});
request.on('error', function(err) { 
  //handle error
});
request.request();

Or:

remote.request_server_info(function(err, res) {
  if (err) {
    //handle error
  } else {
    //handle success
  }
});

##Commands available

request_server_info([callback])

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

request_ledger_hash([callback])

request_ledger_header([callback])

request_ledger_current([callback])

request_ledger_entry(type, [callback])

request_subscribe(streams, [callback])

request_unsubscribe(streams, [callback])

request_transaction_entry(tx_hash, [ledger_hash], [callback])

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

request_tx(hash, [callback])

Searches ledger history for validated transaction hashes.

request_account_info(accountID, [callback])

request_account_lines(accountID, account_index, current, [callback])

request_account_offers(accountID, account_index, current, [callback])

request_account_tx(opts, [callback])

request_book_offers(gets, pays, taker, [callback])

request_wallet_accounts(seed, [callback])

• requires trusted remote

request_sign(secret, tx_json, [callback])

• requires trusted remote

request_submit([callback])

request_account_balance(account, current, [callback])

request_account_flags(account, current, [callback])

request_owner_count(account, current, [callback])

request_ripple_balance(account, issuer, currency, current, [callback])

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

request_unl_list([callback])

request_unl_add(addr, comment, [callback])

request_unl_delete(node, [callback])

request_peers([callback])

request_connect(ip, port, [callback])

transaction([destination], [source], [amount], [callback])

• returns a Transaction object

##Submitting a transaction

var Remote = require('ripple-lib').Remote;
var Amount = require('ripple-lib').Amount;

var MY_ADDRESS = 'rrrMyAddress';
var MY_SECRET  = 'secret';
var RECIPIENT  = 'rrrRecipient';
var AMOUNT     = Amount.from_human('1XRP');

var remote = new Remote({ /* configuration */ });

remote.connect(function() {
  remote.set_secret(MY_ADDRESS, MY_SECRET);

  var transaction = remote.transaction();

  transaction.payment(MY_ADDRESS, RECIPIENT, AMOUNT);

  transaction.once('error', function(message) {
    //Transaction failed. This is a final state
  });

  transaction.once('success', function(message) {
    //Transaction succeeded. The transaction was
    //validated to be contained within the ledger.
    //This is a final state
  });

  transaction.once('submitted', function(err, res) {
    //Transaction was submitted. The response may
    //have been an error or success. This event 
    //represents a response from the initial 
    //submission of a tranaction to a server
  });

  transaction.once('proposed', function(err, res) {
    //Transaction was submitted successfully
  });

  transaction.once('pending', function(message) {
    //A ledger was checked for the transaction and
    //the transaction is not yet validated i.e. pending
  });

  transaction.once('missing', function(message) {
    //Four ledgers have passed without finding
    //the transaction
  });

  transaction.once('lost', function(message) {
    //Eight ledgers have passed without finding
    //the transaction. At tis point the transaction
    //is considered lost and failed
  });
  
  transaction.submit(function(err, res) {
    /* handle submission errors / success */
  });
});