0.1.0 • Published 9 years ago

etherest

Licence

ISC

Version

0.1.0

Deps

Vulns

Weekly

Summary Dependency Versions

ETHEREST JavaScript Client

ETHEREST provides a simple way to make calls and transactions to the Ethereum blockchain using a REST-like API. This library is a lightweight and flexible interface to the API which can be used in both Node.js and browser based projects. It's a fast way to start getting data from and mutating the blockchain without running your own node.

Installation

Node.js

You can install ETHEREST as an npm module: npm install etherest

As well as using server side, it's safe to webpack or browserify the npm module for use in browsers.

Browsers

A standalone library for web browsers is also provided which can be embeded onto your page using jsdlvr's npm cdn:

<script src="https://cdn.jsdelivr.net/npm/etherest@0.1/dist/etherest.min.js"></script>

The browser script defines a global variable Etherest which is the same as the entry point of the default export of the npm module.

Example Usage

Call Without an ABI (Sandiwch Shop)

Etherest
.address('0x4dc924EeB4D87ab938f5a72fC0ef4460f6b35a8A')
.method('getSandwichInfoCaloriesPrice')
.param(2, 'uint')
.returns(['string', 'string', 'string', 'uint256'])
.call()
.then(function (result) {
	console.log("Got info from the sandwich shop!");
	console.log(result);
});

Transaction (Rouleth)

Etherest
.address('0x91A57B2F6FA86B373Bce5716eb26C81cbb004223')
.method('betOnNumber')
.param(7, 'uint')
.sendTransaction({
	from: '0xd3c14E7E6Feb41d8210412fc77ef94a72d8B089b',
	privateKey: '5172eb05eb9b27e15d4fe963157967b2d6e13e128e79d9b6dc27acf4dcf654ab',
	value: 0.01
})
.then(function (txid) {
	console.log("Transaction ID: " + txid);
});

Call Using a Public ABI (Basic Attention Token)

Etherest
.address('0x0D8775F648430679A709E98d2b0Cb6250d2887EF')
.loadAbi()
.then(function (basicAttentionToken) {
	basicAttentionToken
	.tokenExchangeRate()
	.then(function (rate) {
		console.log("1 ETH = " + rate + " Basic Attention Tokens");
	});
});

Got a private abi you want to use instead? Just provide it by calling Etherest.address(...).abi([...]). See the full documentation below for a deep dive into the library's full functionality.

Etherest API

To learn more about the ETHEREST API check out some of our getting started guides:

Full Documentation

Etherest

Kind: global class

Etherest
- new Etherest([options])
- .address(address, [network]) ⇒ Address
- .request([options]) ⇒ Promise
- .call([path]) ⇒ Promise
- .sendTransaction([path], options) ⇒ Promise

new Etherest([options])

The main entry point to the client library, can be instantiated or used as a static class upon which all instance methods are available

Returns: Etherest - new Etherest instance

Param	Type	Description
[options]	`Object`	options to pass in to a new etherest instance
[options.server]	`string`	url for the api server to use, allows you to roll your own Etherest instance with our open source code
[options.apiKey]	`string`	api key to send with requests

etherest.address(address, [network]) ⇒ `Address`

Creates a new address object linked to this etherest instance for executing queries against

Kind: instance method of Etherest
Returns: Address - new address instance

Param	Type	Description
address	`string`	the address to instantiate the object with
[network]	`string`	network the address is associated with (ie main, ropsten etc)

etherest.request([options]) ⇒ `Promise`

Executes a request against this instance's etherest server

Kind: instance method of Etherest
Returns: Promise - promise which resolves when the request is complete with the response from etherest

Param	Type	Description
[options]	`Object`	custom options for the request (see request and browser-request for supported options)

etherest.call([path]) ⇒ `Promise`

Executes a call request against the etherest server

Kind: instance method of Etherest
Returns: Promise - promise which resolves when the call is completed with the data returned from etherest

Param	Type	Description
[path]	`string`	path to call relative to the base URL of the server

etherest.sendTransaction([path], options) ⇒ `Promise`

Sends a transaction to the etherest server

Kind: instance method of Etherest
Returns: Promise - a promise which resolves when the transaction has been submitted with an Ethereum txid

Param	Type	Description
[path]	`string`	path to send the transaction to relative to the base URL of the server
options	`Object`	options for the transaction, see options argument of Query.options

Address

Kind: global class

Address
- new Address(etherest, address, [network])
- .query(method, params) ⇒ Query
- .method(name, ...param) ⇒ Query
- .defineMethod(name, params, returns) ⇒ function
- .defineCall(name, params, returns) ⇒ function
- .defineTransaction(name, params) ⇒ function
- .abi(abi) ⇒ Address
- .loadAbi() ⇒ Promise
- .urlEncode(suffix) ⇒ string
- .call(path) ⇒ Promise
- .sendTransaction(path, options) ⇒ Promise

new Address(etherest, address, [network])

Represents an address on the blockchain

Returns: Address - new Address instance

Param	Type	Default	Description
etherest	`Etherest`		etherest connection instance associated with this address
address	`string`		the ethereum address for this instance
[network]	`string`	`"main"`	the network identifier this instance uses (ie main, ropsten, etc)

address.query(method, params) ⇒ `Query`

Creates a new query object which is linked to this address instance

Kind: instance method of Address
Returns: Query - new query instance

Param	Type	Description
method	`string`	name of the method which the query will call/sendTransaction against
params	`Array`	array of params which will be passed with this query, can take the form of an array of values or value/type pairs. See constructor of Query

address.method(name, ...param) ⇒ `Query`

Creates a new query object for a method with params passed in as arguments

Kind: instance method of Address
Returns: Query - new query instance

Param	Type	Description
name	`string`	the name of the method to be used for this query
...param	`*`	params to be passed to the query

address.defineMethod(name, params, returns) ⇒ `function`

Add a method to this instance with a given name and list of param types which returns a query when invoked

Kind: instance method of Address
Returns: function - reference to the function defined

Param	Type	Description
name	`string`	the name of the method to be used for this query
params	`Array`	array of types of the params to be passed to this method as arguments
returns	`string`	the return type of the method

address.defineCall(name, params, returns) ⇒ `function`

Add a method to this instance with a given name and list of param types which performs a call when invoked

Kind: instance method of Address
Returns: function - reference to the function defined

Param	Type	Description
name	`string`	the name of the method to be used for this query
params	`Array`	array of types of the params to be passed to this method as arguments
returns	`string`	the return type of the method

address.defineTransaction(name, params) ⇒ `function`

Add a method to this instance with a given name and list of param types which creates a transaction when invoked

Kind: instance method of Address
Returns: function - reference to the function defined

Param	Type	Description
name	`string`	the name of the method to be used for this query
params	`Array`	array of types of the params to be passed to this method as arguments

address.abi(abi) ⇒ `Address`

Create methods on this instance which match the definitions from a contract abi

Kind: instance method of Address
Returns: Address - reference to this object for chaining calls

Param	Type	Description
abi	`Array`	application binary interface for this address

address.loadAbi() ⇒ `Promise`

Load the abi publically associated with this address on etherest

Kind: instance method of Address
Returns: Promise - promise which resolves when the abi has been loaded with a reference to this address instance

address.urlEncode(suffix) ⇒ `string`

Gets the data for a request against an address encoded as a URL to send to etherest

Kind: instance method of Address
Returns: string - the encoded URL part to execute this query

Param	Type	Description
suffix	`string`	additional string data to add to the end of the URL

address.call(path) ⇒ `Promise`

Executes a call against this address

Kind: instance method of Address
Returns: Promise - a promise which resolves when the call has been completed with the value returned

Param	Type	Description
path	`string`	a relative path from this address to execute the call against

address.sendTransaction(path, options) ⇒ `Promise`

Sends a transaction to the etherest server

Kind: instance method of Address
Returns: Promise - a promise which resolves when the transaction has been submitted with an Ethereum txid

Param	Type	Description
path	`string`	path to send the transaction to relative to this address
options	`Object`	options for the transaction, see options argument of Query.options

Query

Kind: global class

Query
- new Query([address], [method], params)
- .param(value, [type]) ⇒ Query
- .returns(type) ⇒ Query
- .urlEncode() ⇒ string
- .call(address) ⇒ Promise
- .sendTransaction(address, options) ⇒ Promise

new Query([address], [method], params)

Represents a single instance of an interaction with the blockchain, can be executed as a transaction or call

Returns: Query - new Query instance

Param	Type	Description
[address]	`Address`	address instance associated with this query
[method]	`string`	the contract method this query will target
params	`Array`	either a flat array of values which are the parameters or an array of type/value pairs
params[].value	`string`	the value of a param
params[].type	`string`	the type of a param

query.param(value, [type]) ⇒ `Query`

Adds a param to the call/transaction to be sent

Kind: instance method of Query
Returns: Query - instance of this query to chain method calls from

Param	Type	Description
value	`mixed`	the value of the parameter in this query
[type]	`string`	the type of the the parameter if we are not aware of it

query.returns(type) ⇒ `Query`

Set the return type for a query

Kind: instance method of Query
Returns: Query - instance of this query to chain method calls from

Param	Type	Description
type	`string`	the type of the data returned by the query

query.urlEncode() ⇒ `string`

Gets the data for this query encoded as a URL to send to etherest against a particular address

Kind: instance method of Query
Returns: string - the encoded URL part to execute this query

query.call(address) ⇒ `Promise`

Executes this query as a call

Kind: instance method of Query
Returns: Promise - a promise which resolves when the call has been completed with the value returned

Param	Type	Description
address	`Address`	the address to execute the call against, required if the query was not constructed with one

query.sendTransaction(address, options) ⇒ `Promise`

Executes this query as a transaction

Kind: instance method of Query
Returns: Promise - a promise which resolves when the transaction has been submitted to the blockchain with a transaction id string

Param	Type	Default	Description
address	`Address`		the address to send the transaction to, required if the query was not constructed with one
options	`Object`		options for the transaction
options.from	`string`		the address this transaction is being sent from
options.privateKey	`string`		the private key of the address this transaction is being sent from
[options.value]	`number`	`0`	the amount ot eth to send with this transaction (1 = 1.0 Ether sent)
[options.gasPrice]	`number`	`20`	the price to pay for gas for this transaction in gwei
[options.gasLimit]	`number`	`200000`	the maximum amount of gas this transaction is allowed to use

Keywords

ethereum blockchain etherest api