Ethereum for Ruby

A straightforward library to build, sign, and broadcast Ethereum transactions. It allows the separation of key and node management. Sign transactions and handle keys anywhere you can run Ruby and broadcast transactions through any local or remote node. Sign messages and recover signatures for authentication.

Note, this repository is just a public archive of the no longer maintained ethereum gem. For the partial rewrite and merge with the eth gem see q9f/eth.rb.

Highlights

Simple syntax, programmer friendly
Deploy and interact with contracts on the blockchain
Contract - ruby object mapping to solidity contract
Signing transactions with ruby-eth gem.
Compile Solidity contracts with solc compiler from ruby
Receive events from contract
Make direct json rpc calls to node from ruby application
Connect to node via IPC or HTTP
Helpful rake tasks for common actions

Installation

Before installing the gem make sure you meet all prerequisites, especially that you have:

compatible ethereum node installed
compatible solidity compiler installed
wallet with some ethereum on it

Before you run a program check that the node is running and accounts you want to spend from are unlocked.

To install gem simply add this line to your application's Gemfile:

gem 'ethereum.rb'

And then execute:

$ bundle

Or install it yourself as:

$ gem install ethereum.rb

Basic Usage

You can create a contract from solidity source and deploy it to the blockchain, with the following code:

contract = Ethereum::Contract.create(file: "greeter.sol")
address = contract.deploy_and_wait("Hello from ethereum.rb!")

Deployment may take up to a couple of minutes. Once deployed you can start interacting with the contract, e.g. calling it's methods:

contract.call.greet # => "Hello from ethereum.rb!"

You can see example contract greeter here.

If contract method name uses camel case you must convert it to snake case when use call: call.your_method.

Smart contracts

Compile multiple contracts at once

If you want to complie multiple contracts at once, you can create new instances using newly declared ruby clasess:

Ethereum::Contract.create(file: "mycontracts.sol", client: client)
contract = MyContract1.new
contract = contract.deploy_and_wait
contract2 = MyContract2.new
contract2 = contract.deploy_and_wait

All names used to name contract in solidity source will translate to name of classes in ruby (camelized).

Note: If class of given name exist it will be undefined first to avoid name collision.

Get contract from blockchain

The other way to obtain a contract instance is to get one that already exists on the blockchain. To do so you need a contract name, contract address and ABI definition.

contract = Ethereum::Contract.create(name: "MyContract", address: "0x01a4d1A62F01ED966646acBfA8BB0b59960D06dd ", abi: abi)

Note that you need to specify a contract name, that will be used to define new class in ruby, as it is not a part of the ABI definition.

Alternatively you can obtain the abi definition and name from a contract source file:

contract = Ethereum::Contract.create(file: "MyContract.sol", address: "0x01a4d1A62F01ED966646acBfA8BB0b59960D06dd ")

If you want to create a new contract, that is not yet deployed from ABI definition you will need also to supply binary code:

contract = Ethereum::Contract.create(name: "MyContract", abi: abi, code: "...")

Simple Truffle integration

If you use Truffle to build and deploy contracts, you can pick up the Truffle artifacts to initialize a contract. For example, if you have a MyContract in the Truffle directory at /my/truffle/project:

contract = Ethereum::Contract.create(name: "MyContract", truffle: { paths: [ '/my/truffle/project' ] }, client: client, address: '0x01a4d1A62F01ED966646acBfA8BB0b59960D06dd')

The contract factory will attempt to load the deployed address from the Truffle artifacts if the client's network is present:

contract = Ethereum::Contract.create(name: "MyContract", truffle: { paths: [ '/my/truffle/project' ] }, client: client)

Interacting with contract

Functions defined in a contract are exposed using the following conventions:

contract.transact.[function_name](params)
contract.transact_and_wait.[function_name](params)
contract.call.[function_name](params)

Example Contract in Solidity

contract SimpleRegistry {
  event LogRegister(bytes32 key, string value);
  mapping (bytes32 => string) public registry;

  function register(bytes32 key, string value) {
    registry[key] = value;
    LogRegister(key, value);
  }

  function get(bytes32 key) public constant returns(string) {
    return registry[key];
  }

}

For contract above here is how to access it's methods:

contract.transact_and_wait.register("performer", "Beastie Boys")

Will send transaction to the blockchain and wait for it to be mined.

contract.transact.register("performer", "Black Eyed Peas")

Will send transaction to the blockchain return instantly.

contract.call.get("performer") # => "Black Eyed Peas"

Will call method of the contract and return result. Note that no transaction need to be send to the network as method is read-only. On the other hand register method will change contract state, so you need to use transact or transact_and_wait to call it.

Receiving Contract Events

Using the example smart contract described above, one can listen for LogRegister events by using filters.

You can get a list of events from a certain block number to the latest:

require 'ostruct'

event_abi = contract.abi.find {|a| a['name'] == 'LogRegister'}
event_inputs = event_abi['inputs'].map {|i| OpenStruct.new(i)}
decoder = Ethereum::Decoder.new

filter_id = contract.new_filter.log_register(
  {
    from_block: '0x0',
    to_block: 'latest',
    address: '0x....',
    topics: []
  }
)

events = contract.get_filter_logs.log_register(filter_id)

events.each do |event|
  transaction_id = event[:transactionHash]
  transaction = ethereum.eth_get_transaction_receipt(transaction_id)
  args = decoder.decode_arguments(event_inputs, entry['data'])
  puts "#{transaction.inspect} with args: #{args}"
end

IPC Client Connection

By default methods interacting with contracts will use default Json RPC Client that will handle connection to ethereum node. Default client communicate via IPC. If you want to create custom client or use multiple clients you can create them yourself.

To create IPC client instance of simply create Ethereum::IpcClient:

client = Ethereum::IpcClient.new

You can also customize it with path to ipc file path and logging flag:

client = Ethereum::IpcClient.new("~/.parity/mycustom.ipc", false)

If no ipc file path given, IpcClient looks for ipc file in default locations for parity and geth. The second argument is optional. If it is true then logging is on.

By default logging is on and logs are saved in "/tmp/ethereum_ruby_http.log".

To create Http client use following:

client = Ethereum::HttpClient.new('http://localhost:8545')

You can supply client when creating a contract:

contract = Ethereum::Contract.create(client: client, ...)

You can also obtain default client:

client = Ethereum::Singleton.instance

Calling json rpc methods

Ethereum.rb allows you to interact directly with Ethereum node using json rpc api calls. Api calls translates directly to client methods. E.g. to call eth_gasPrice method:

client.eth_gas_price # => {"jsonrpc"=>"2.0", "result"=>"0x4a817c800", "id"=>1}

Note: methods are translated to underscore notation using metaprogramming (See client.rb for more information).

Full list of json rpc methods is available here

Signed transactions

Ethereum.rb supports signing transactions with key using ruby-eth gem.

To create a new key simply do the following:

key = Eth::Key.new

Then you

Ethereum.rb

Install / Use

README