Skip to content

Latest commit

 

History

History
252 lines (184 loc) · 8.11 KB

GUIDES.md

File metadata and controls

252 lines (184 loc) · 8.11 KB
Raw

#Guides

This file provides step-by-step walkthroughs for some of the most common usages of ripple-lib.

###In this document

  1. Connecting to the Ripple network with Remote
  2. Using Remote functions and Request objects
  3. Listening to the network
  4. Submitting a payment to the network
  5. Submitting a trade offer to the network

###Also see

  1. The ripple-lib README
  2. The ripple-lib API Reference

##Connecting to the Ripple network

  1. Get ripple-lib
  2. Load the ripple-lib module into a Node.js file or webpage:
/* Loading ripple-lib with Node.js */
var Remote = require('ripple-lib').Remote;

/* Loading ripple-lib in a webpage */
// var Remote = ripple.Remote;
  1. Create a new Remote and connect to the network:
var options = {
  trace :         false,
  trusted:        true,
  local_signing:  true,
  servers: [
    { host: 's-west.ripple.com', port: 443, secure: true }
  ]
};

var remote = new Remote(options);

remote.connect(function(err, res) {
  /* remote connected, use some remote functions here */
});

NOTE: See the API Reference for available Remote options

  1. You're connected! Read on to see what to do now.

##Generating a new Ripple Wallet

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

  // subscribing to a server allows for more entropy
  var remote = new ripple.Remote({
    servers: [
      { host: 's1.ripple.com', port: 443, secure: true }
    ]
  });

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

  // Wait for randomness to have been added.
  // The entropy of the random generator is increased
  // by random data received from a rippled
  remote.once('random', function(err, info) {
    var wallet = ripple.Wallet.generate();
    console.log(wallet);
    // { address: 'rEf4sbVobiiDGExrNj2PkNHGMA8eS6jWh3',
    //   secret: 'shFh4a38EZpEdZxrLifEnVPAoBRce' }
  });

##Sending rippled API requests

Remote contains functions for constructing a Request object.

A Request is an EventEmitter so you can listen for success or failure events -- or, instead, you can provide a callback.

Here is an example, using requestServerInfo.

  • Constructing a Request with event listeners
var request = remote.requestServerInfo();

request.on('success', function onSuccess(res) {
  //handle success
});

request.on('error', function onError(err) {
  //handle error
});

request.request();
  • Using a callback:
remote.request('server_info', function(err, res) {
  if (err) {
    //handle error
  } else {
    //handle success
  }
});

NOTE: See the API Reference for available Remote functions

##Listening to the network

See the wiki for details on subscription requests.

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

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

  var remote = new Remote({options});

  remote.connect(function() {
    var remote = new Remote({
      // see the API Reference for available options
      servers: [ 'wss://s1.ripple.com:443' ]
    });

    remote.connect(function() {
      console.log('Remote connected');

      var streams = [
        'ledger',
        'transactions'
      ];

      var request = remote.requestSubscribe(streams);

      request.on('error', function(error) {
        console.log('request error: ', error);
      });


      // the `ledger_closed` and `transaction` will come in on the remote
      // since the request for subscribe is finalized after the success return
      // the streaming events will still come in, but not on the initial request
      remote.on('ledger_closed', function(ledger) {
        console.log('ledger_closed: ', JSON.stringify(ledger, null, 2));
      });

      remote.on('transaction', function(transaction) {
        console.log('transaction: ', JSON.stringify(transaction, null, 2));
      });

      remote.on('error', function(error) {
        console.log('remote error: ', error);
      });

      // fire the request
      request.request();
    });
  });

##Submitting a payment to the network

Submitting a payment transaction to the Ripple network involves connecting to a Remote, creating a transaction, signing it with the user's secret, and submitting it to the rippled server. Note that the Amount module is used to convert human-readable amounts like '1XRP' or '10.50USD' to the type of Amount object used by the Ripple network.

/* Loading ripple-lib Remote and Amount modules in Node.js */
var Remote = require('ripple-lib').Remote;
var Amount = require('ripple-lib').Amount;

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

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

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

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

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

  transaction.submit(function(err, res) {
    /* handle submission errors / success */
  });
});

###A note on transaction fees

A full description of network transaction fees can be found on the Ripple Wiki.

In short, transaction fees are very small amounts (on the order of ~10) of XRP drops spent and destroyed with every transaction. They are largely used to account for network load and prevent spam. With ripple-lib, transaction fees are calculated locally by default and the fee you are willing to pay is submitted along with your transaction.

Since the fee required for a transaction may change between the time when the original fee was calculated and the time when the transaction is submitted, it is wise to use the fee_cushion to ensure that the transaction will go through. For example, suppose the original fee calculated for a transaction was 10 XRP drops but at the instant the transaction is submitted the server is experiencing a higher load and it has raised its minimum fee to 12 XRP drops. Without a fee_cusion, this transaction would not be processed by the server, but with a fee_cusion of, say, 1.5 it would be processed and you would just pay the 2 extra XRP drops.

The max_fee option can be used to avoid submitting a transaction to a server that is charging unreasonably high fees.

##Submitting a trade offer to the network

Submitting a trade offer to the network is similar to submitting a payment transaction. Here is an example offering to sell 1 USD in exchange for 100 XRP:

/* Loading ripple-lib Remote and Amount modules in Node.js */
var Remote = require('ripple-lib').Remote;
var Amount = require('ripple-lib').Amount;

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

var MY_ADDRESS = 'rrrMyAddress';
var MY_SECRET  = 'secret';
var GATEWAY = 'rrrGateWay';

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

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

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

  transaction.submit(function(err, res) {
    /* handle submission errors / success */
  });
});