@theblock/ethrpc-promise NPM

ethrpc-promise

A thin es6-promise wrapper around eth-rpc calls as exposed by eth, geth, parity, etc. In addition to making it promise-able, it tries to be as light as possible, with little external fat.

This is a from-the-ground up interface around the RPC spec, with no shared code from other modules that exist. Since RPC by definition is async, it doesn't try to hide the fact, rather embraces it with standards-based promise implementations.

browser/node dependencies

Despite the attempt at 'no fat', some external dependencies are required -

bignumber.js (required for parameter encoding)
js-sha3 (required for method name encoding)
utf8 (required for string encoding/decoding)

polyfill dependencies

In addition, the environment needs to support ES6 Promises and the fetch api. To polyfill support in all browsers/environments, these are recommended -

es6-promise (or any other Promise polyfill)
isomorphic-fetch (or any other fetch polyfill, selected due to Node & browser applicability)

limitations

This is currently not a full-fledged implementation, rather the bare minimum (as used elsewhere) is implemented. The following caveats exists -

All eth, net, personal (via geth & partity source-code), shh & web3 RPC endpoints are implemented
call & sendTransaction can only use singular types (exception: string), no arrays/variable types are supported as input types, output type support are limited to singular and byte8-256 types. (These will be expanded as use-cases pop up, mostly driven by own library use)

usage

const HOST = '127.0.0.1';
const PORT = 8545;

// const rpc = require('ethrpc-promise')(HOST, PORT); // node.js
const rpc = window.ethrpc(HOST, PORT);

rpc.eth
  .getBalance(accountId)
  .then((balance) => {
    console.log(`the balance for ${accountId} is ${balance}`);
  });

rpc apis

For a list of the exposed APIs, along with their parameters, the following exist. These implement the calls as listed on the official JSON Ethereum RPC definition.

rpc.eth.<...>

In most cases, the interfaces maps through to the RPC eth_<interface> definition.

accounts() - returns a list of accounts associated with the current running instance
blockNumber() - returns the current blockNumber
call(options, blockNumber = 'latest') - performs a call
coinbase() - returns the current coinbase (base account) for the running instance
compile[LLL|Serpent|Solidity](code) - compiles the supplied code using the required compiler
estimateGas(options) - performs a fake call uisng the options, returning the used gas
gasPrice() - returns the current gas price
getBalance(address, blockNumber = 'latest') - returns the current address balance as at blockNumber

TODO complete the rest

rpc.web3.<...>

clientVersion() - returns the version of the RPC client
sha3(hexStr) - returns a keccak256 of the hexStr input

utility apis

In addition, the following utility functions are exposed, dealing with contracts and often-used operations.

rpc.contract.<...>

To attach a contract, an abi interface is required, i.e.

const rpc = ... // get rpc-promise interface
const instance = rpc.contract(abi); // attach the abi to a contract
const instance = rcp.contract.new(...args); // deploy a new contract, settign the address

From here, the ABI can be associated to an address, instance.at(address). From here the abi exposed on the interface via interface.abi contains the call(options, blockNumber), sendTransaction(options) & estimateGas(options) functions for each ABI which maps to the underlying eth_<functions> exposed for the specific endpoint.

In addition a parseTransactionEvents(receipt) function is exposed on the actual interface.