Live Libs for Solidity

Providing reusable Solidity libraries that are live on the Ethereum blockchain.

Install

$ npm install -g live-libs

Setting up your environment

You will need to be connected to an Ethereum network (testrpc, morden, mainnet, etc) when interacting with live-libs. Follow these instructions to install an Ethereum node. The live-libs command line interface defaults to http://localhost:8545 to reach the Ethereum node's RPC interface. You can override this with --rpcurl https://example:8765.

Getting a library's information

It's important to note that live-libs does not store source code, but it does store a library's ABI. In order to compile contracts that use live-libs, you'll need to provide the library interface to the compiler.

Note: If you don't specify the version, the latest version of the library is used.

From the command line:

$ live-libs get LibName [--version 3.5.8]
Version:
3.5.8

Address:
0x3f4845...

ABI:
[{"constant":false,"inputs":...}]

Abstract source:
library LibName {...}

Via Javascript:

var web3 = ... // setup web3 object

var LiveLibs = require('live-libs');
var liveLibs = new LiveLibs(web3);
var libName = "Foo";
var version = "3.5.8"; // optional
liveLibs.get(libName, version).then(function(libInfo) {
  console.log(libInfo.version);
  console.log(libInfo.address);
  console.log(libInfo.abi);
  console.log(libInfo.abstractSource());
  console.log(libInfo.docURL);
  console.log(libInfo.sourceURL);
});

Getting a library's event log

From the command line:

$ live-libs log LibName
Event log for Foo...
2016-04-17T12:34:56Z NewLib! Registered by owner: 0x28bc5a7226a82053aa29c0806c380cfb6a82bb0c
2016-04-17T12:34:56Z NewVersion! 0.0.1
2016-05-17T17:27:37Z NewVersion! 0.0.2

Via Javascript:

liveLibs.log(libName).then(function(events) {
  events.forEach(function(event) {
    console.log(event.type);
    console.log(event.time);
    console.log(event.args);
  });
});

Working with accounts

get and log do not require a transaction, so those calls require no account nor cost any gas. (They use eth_call.) register and contribute require a transaction, costing you gas, and therefore require an unlocked account. (These commands use eth_sendTransaction).

If not specified via --account on the command line, web3.eth.coinbase will be used as your account. Also, you will need to unlock the account in order to use it to spend Ether on transactions. For the command line, you can read the geth docs. For JavaScript, assuming you've started geth with --rpcapi "eth,web3,personal", you can call web3.eth.personal.unlockAccount(address, password, durationSeconds) to unlock it. (source)

How to register a live library

From the command line:

$ live-libs register YourLibName --version 3.5.8 --address 0x45e2... --abi '[...]' \
[--resourceuri docs=http://example.com/docs] [--resourceuri source=http://example.com/source/lib.sol]

Warning: There is no way to remove your library. Once it's live, it's live forever.

Warning: This software is under active development and the live-libs registries (morden and mainnet) will be abandoned without warning. (Other than this warning.)

Setting up your testrpc environment

Running your tests against testrpc is a standard way to speed up your development process. In order to execute the live-libs libraries on your testrpc node, you'll need to deploy the live-libs contract(s) and import the live-libs data. This will require a two-step process:

1. Download the live-libs data from morden (you will need to run a node that connects to that network).
2. Deploy the live-libs contract(s) and data to testrpc.

From the command line:

$ # running a morden node
$ live-libs download
$ # switch to testrpc
$ live-libs deploy

Note: If you restart your testrpc server, you'll need to re-deploy live-libs, but you won't need to re-download the data.

Funding your library

Library authors can receive ether for registering their libraries with live-libs. When an author registers a library, they can optionally pass in a --unlockat flag, followed by a number of wei. This will "lock" the specified version of the library until the specified amount of wei has been contributed. For example:

$ live-libs register YourLibName --version 3.5.8 --address 0x45e2... --abi '[...]' --unlockat 10000000

This will register YourLibName 3.5.8 in live-libs, but when you look it up, it will not be available. To unlock it, people need to contribute ether, which gets immediatly redirected to the Ethereum account that registered this version.

If someone wants to contribute ether in order to unlock a version of a library, they can:

$ live-libs contribute LibName --version 3.5.8 --wei 200000

Note: The idea for this came from Vitalik's story at 2:30 of this podcast.

Where is this headed?

• TODO: a few weeks out
• Roadmap: a few months out

Author

Dave Hoover dave.hoover@consensys.net