Stellar::Base

The stellar-base library is the lowest-level stellar helper library. It consists of classes to read, write, hash, and sign the xdr structures that are used in stellard.

Installation

Add this line to your application's Gemfile:

gem 'stellar-base'

And then execute:

$ bundle

Or install it yourself as:

$ gem install stellar-base

Also requires libsodium. Installable via brew install libsodium on OS X.

Usage

Examples are here

In addition to the code generated from the XDR definition files (see ruby-xdr for example usage), this library also provides some stellar specific features. Let's look at some of them.

We wrap rbnacl with Stellar::KeyPair, providing some stellar specific functionality as seen below:

# Create a keypair from a stellar secret seed
signer = Stellar::KeyPair.from_seed("SCBASSEX34FJNIPLUYQPSMZHHYXXQNWOOV42XYZFXM6EGYX2DPIZVIA3")

# Create a keypair from a stellar address
verifier = Stellar::KeyPair.from_address("GBQWWBFLRP3BXD2RI2FH7XNNU2MKIYVUI7QXUAIVG34JY6MQGXVUO3RX")

# Produce a stellar compliant "decorated signature" that is compliant with stellar transactions

signer.sign_decorated("Hello world!") # => #<Stellar::DecoratedSignature ...>

This library also provides an impementation of Stellar's "StrKey" encoding (RFC-4648 Base32 + CCITT-XModem CRC16):

Stellar::Util::StrCheck.check_encode(:account_id, "\xFF\xFF\xFF\xFF\xFF\xFF\xFF") # => "GD777777777764TU"
Stellar::Util::StrCheck.check_encode(:seed, "\x00\x00\x00\x00\x00\x00\x39") # => "SAAAAAAAAAADST3H"

# To prevent interpretation mistakes, you must pass the expected version byte
# when decoding a check_encoded value

encoded = Stellar::Util::StrCheck.check_encode(:account_id, "\x61\x6b\x04\xab\x8b\xf6\x1b")
Stellar::Util::StrCheck.check_decode(:account_id, encoded) # => "\x61\x6b\x04\xab\x8b\xf6\x1b"
Stellar::Util::StrCheck.check_decode(:seed, encoded) # => throws ArgumentError: Unexpected version: :account_id

Updating Generated Code

The generated code of this library must be refreshed each time the Stellar network's protocol is updated. To perform this task, run rake xdr:update, which will download the latest .x files into the xdr folder and will run xdrgen to regenerate the built ruby code.

Caveats

The current integration of user-written code with auto-generated classes is to put it nicely, weird. We intend to segregate the auto-generated code into its own namespace and refrain from monkey patching them. This will happen before 1.0, and hopefully will happen soon.

Contributing