rcl

RCL Helper Tools

RCL is short for Ripple Consensus Ledger. (Now called "XRP Ledger".)

Install

go get -u github.com/dncohen/rcl/cmd/...

Quick Tutorial

Set up a temporary working directory. We'll use testnet for this example:

mkdir -p /tmp/rcl-altnet
cd /tmp/rcl-altnet

Generate some test net XRP to play with:

curl -s -X POST https://faucet.altnet.rippletest.net/accounts | tee testnet-fund-account.json | python -m json.tool

Note the output of above includes...

"address": "ADDRESS",
"secret": "SECRET"

Create a key file in format that rcl tools requires. Copy the SECRET from the above command into:

  rcl-key generate -nickname fund -secret SECRET

This will write a file ending `.rcl-key`.  Note the output and
confirm that the address shown matches the ADDRESS generated by
the faucet.  Although the rcl-key operation is `generate`, the
`-secret` flag instructs the command to use an existing account.
This puts the secret into a format that `rcl-key sign` can use, as
we'll see in a moment. The `-nickname fund` argument will allow us
to refer to this account as "fund" later.

Next, create a brand new Ripple address and master signing key with rcl-key tool:

rcl-key generate -nickname hot

rcl-key generates a new keypair, and writes both address and secret to a file.

The generated address (with nickname hot) does not become an account on the test net until it is funded with enough XRP to meet the reserve requirement.

Before we use our wallets, its a good practice to make a paper backup of the secret keys. RCL tools provides a backup operation to support this. This step is required, even for testnet keys, because the backup operation writes the public address to a config file needed later.

rcl-key backup *.rcl-key

The rcl-key backup operation walks you through the secrets, giving you a chance to copy each one to paper. (For test accounts, you can skip writing the down the secret; just press [return] a few times.)

As you make a paper backup of each key, the tool writes a configuration file with the address, but not the secret, of each key. At this point your working directory should have files "fund.cfg", "hot.cfg" and two .rcl-key files with secrets.

In order to create our first transaction, the rcl-tx tool must communicate with a rippled server. We're going to use the testnet. To do so, create a configuration file:

echo "rippled=wss://s.altnet.rippletest.net:51233" > testnet.cfg

(RCL tools will inspect all the *.cfg files in a given configuration directory. So when we run rcl-tx, it will read from testnet.cfg as well as fund.cfg and hot.cfg.)

Construct a transaction to send the required XRP to the new address with the rcl-tx send subcommand:

rcl-tx -config . -as fund send hot 100/XRP

The output is an unsigned transaction, encoded in JSON format. The unsigned transaction shows us what will be sent to the XRP ledger; however, it cannot be sent until it is signed and submitted.

RCL tools uses a "pipeline" to first compose transactions, then sign, then submit. We just saw the first step, composing. Here's how to run the tools in a pipeline, to complete the transaction:

rcl-tx -config . -as fund send hot 100/XRP | rcl-key sign | rcl-tx -config . submit

The last command, rcl-tx submit could take several seconds to complete, as it awaits the final status from the XRP ledger network. With a little luck, you should see "tesSUCCESS" in the output.

Finally, let's confirm the hot wallet has received some XRP:

rcl-account -config . show hot

This should show the 100 XRP that we just sent.

Configuration

Most commands require configuration, which is loaded from all *.cfg files in a directory. The default directory is $HOME/.config/rcl/.

Here's an example, save to i.e. "$HOME/.config/rcl/rcl.cfg":

    # Replace this rippled URL with your own trusted rippled
    # Replace with wss://s.altnet.rippletest.net:51233, for the TEST NET
    rippled=wss://s1.ripple.com:51233

    # This creates a nickname, `bitstamp-usd` for the Bitstamp issuing address.
    # optional tag will be used when sending to this address, replace the example below wih your own!
    [bitstamp-usd]
	     address=rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B
	     # Put your destination tag below. Remove the "#", which starts a comment.
	     #tag=99999999

    [bitstamp-xrp]
	     address=rDsbeomae4FXwgQTJp9Rs64Qg9vDiTCdBv
	     #tag=99999999

    # deposit XRP to binance
    [binance]
	     address=rEb8TK3gBgk5auZkwc6sHnwrGVJH8DuaLh
	     #tag=99999999

    # deposit XRP to sfox
    [sfox]
	     address=rHXeKgsvbrTpq1ii3CeBNrnbUfroi24fT7
	     #tag=99999999

    # Add nicknames for your own accounts...

Command rcl-account

Inspect RCL accounts.

Command RCL-account - Operation Monitor

rcl-account monitor <address>

Shows account activity as soon as it is detected.

Command RCL-account - Operation Show

rcl-account show <address> [<address> ...]

Prints in human-readable format the balances of one or more accounts.

Operation cancel

Compose an RCL transaction to cancel an earlier offer.

Command rcl-tx

The rcl-tx command composes transactions for the Ripple Consensus Ledger.

Each subcommand has a -help flag that explains it in more detail. For instance

rcl-tx sell -help

explains the purpose and usage of the sell subcommand.

There is a set of global flags such as -config to specify the configuration directory, where rcl-tx expects to find one or more *.cfg files. These global flags apply to all subcommands.

Each subcommand has its own set of flags, which if used must appear after the subcommand name.

For a list of available subcommands and global flags, run

rcl-tx -help

Operation monitor

Monitor RCL for transaction activity.

Operation save

Save a transaction to disk. Give it a reasonable file name.

Operation sell

Create an offer to sell one asset or issuance for another.

Operation send

Send XRP or issuance.

Operation set

Compose an RCL transaction to change account settings.

Operation submit

Submit command broadcasts signed transactions to a rippled server.

Operation trust

Create or modify a trust line.

Operation fx

TODO(dnc): documentation

Command RCL-data

The rcl-data command retrieves historical data from data.ripple.com/v2/... and displays information about accounts on the Ripple Consensus Ledger.

Each subcommand has a -help flag that explains it in more detail. For instance

rcl-data show -help

explains the purpose and usage of the show subcommand.

There is a set of global flags such as -config to specify the configuration directory, where rcl-data expects to find one or more *.cfg files. These global flags apply to all subcommands.

Each subcommand has its own set of flags, which if used must appear after the subcommand name.

For a list of available subcommands and global flags, run

rcl-data -help

Operation backup

View a generated secret, so that it can be copied to paper.

Command rcl-key - Operation generate

Generate new keypairs and addresses for use on the Ripple Consensus Ledger.

Generated keys are saved to a file named 'rcl-key-

Command rcl-key

The rcl-key command generates keys and signs transactions for the Ripple Consensus Ledger.

Usage:

rcl-key [flags...] <operation> [operation flags...]

Command rcl-key - Operation sign

Sign command expects an encoded unsigned transaction via stdin, and encodes a signed transaction to stdout.