eris-db
v0.15.12
Published
Javascript library that calls an erisdb server over rpc.
Downloads
105
Readme
erisdb-js (Alpha)
This is a JavaScript API for communicating with a ErisDB server.
Installation
Prerequisites
- Git
- Monax Eris version 0.12
- Node.js version 6 or higher
You can check the installed version of Node.js with the command:
$ node --version
If your distribution of Linux has a version older than 6 then you can update it using NodeSource's distribution.
To Install
$ npm install eris-db
Usage
If you created an ErisDB server using the Eris CLI tool, you can find out its IP address using the following command:
$ eris chains inspect <name of ErisDB server> NetworkSettings.IPAddress
The main class is ErisDB
. A standard ErisDB
instance is created like this:
var edbFactory = require('eris-db');
var edb = edbFactory.createInstance("http://<IP address>:1337/rpc");
The parameters for createInstance
is the server URL as a string. The client-type is chosen based on the URL scheme. As of now, the supported schemes are: http
and ws
(websockets). No additional configuration is needed.
API Reference
There are bindings for all the RPC methods. All functions are on the form function(param1, param2, ... , callback)
, where the callback is a function on the form function(error,data)
(it is documented under the name methodCallback
). The data
object is the same as you would get by calling the corresponding RPC method directly.
This is the over-all structure of the library. The unsafe
flag means a private key is either sent or received, so should be used with care (dev only).
NOTE: There will be links to the proper jsdoc and integration with erisindustries.com. For now, the components point to the actual code files and methods points to the web-API method in question.
ErisDB
| Component Name | Accessor | | :------------- | :------- | | Accounts | ErisDB.accounts() | | Blockchain | ErisDB.blockchain() | | Consensus | ErisDB.consensus() | | Events | ErisDB.events() | | NameReg | ErisDB.namereg() | | Network | ErisDB.network() | | Transactions | ErisDB.txs() |
Components
Accounts
The accounts object has methods for getting account and account-storage data.
| Method | RPC method | Notes | | :----- | :--------- | :---- | | Accounts.getAccounts | erisdb.getAccounts | | | Accounts.getAccount | erisdb.getAccount | | | Accounts.getStorage | erisdb.getStorage | | | Accounts.getStorageAt | erisdb.getStorageAt | | | Accounts.genPrivAccount | erisdb.genPrivAccount | unsafe |
BlockChain
The accounts object has methods for getting blockchain-related data, such as a list of blocks, or individual blocks, or the hash of the genesis block.
| Method | RPC method | Notes | | :----- | :--------- | :---- | | BlockChain.getInfo | erisdb.getBlockchainInfo | | | BlockChain.getChainId | erisdb.getChainId | | | BlockChain.getGenesisHash | erisdb.getGenesisHash | | | BlockChain.getLatestBlockHeight | erisdb.getLatestBlockHeight | | | BlockChain.getLatestBlock | erisdb.getLatestBlock | | | BlockChain.getBlocks | erisdb.getBlocks | | | BlockChain.getBlock | erisdb.getBlock | |
Consensus
The consensus object has methods for getting consensus-related data.
| Method | RPC method | Notes | | :----- | :--------- | :---- | | Consensus.getState | erisdb.getConsensusState | | | Consensus.getValidators | erisdb.getValidators | |
Events
The tendermint client will generate and fire off events when important things happen, like when a new block has been committed, or someone is transacting to an account. It is possible to subscribe to these events. These are the methods for subscribing, un-subscribing and polling.
| Method | RPC method | Notes | | :----- | :--------- | :---- | | Events.subscribe | erisdb.eventSubscribe | | | Events.unsubscribe | erisdb.eventUnsubscribe | | | Events.poll | erisdb.eventPoll | |
Helpers
The helper functions makes it easier to manage subscriptions. Normally you'd be using these functions rather then managing the subscriptions yourself.
Helper functions always contain two callback functions - a createCallback(error, data)
and an eventCallback(error, data)
.
The createCallback
data is an EventSub object, that can be used to do things like getting the event ID, the subscriber ID, and to stop the subscription.
The eventCallback
data is the event object. This object is different depending on the event type. In the case of NewBlock
it will be a block, the consensus events is a transaction object, etc. More info can be found in the api doc.
| Method | Arguments |
| :----- | :-------- |
| Events.subAccountInput | account address <string>
|
| Events.subAccountOutput | account address <string>
|
| Events.subAccountReceive | account address <string>
|
| Events.subLogEvent | account address <string>
|
| Events.subSolidityEvent | account address <string>
|
| Events.subNewBlocks | -
|
| Events.subForks | -
|
| Events.subBonds | -
|
| Events.subUnbonds | -
|
| Events.subRebonds | -
|
| Events.subDupeouts | -
|
subSolidityEvent
and subLogEvent
are two different names for the same type of subscription (log events).
NameReg
The NameReg object has methods for accessing the name registry.
| Method | RPC method | Notes | | :----- | :--------- | :---- | | NameReg.getEntry | erisdb.getNameRegEntry | | | NameReg.getEntries | erisdb.getNameRegEntries | |
Network
The accounts object has methods for getting network-related data, such as a list of all peers. It could also have been named "node".
Client Version may be a bit misplaced
| Method | RPC method | Notes | | :----- | :--------- | :---- | | Network.getInfo | erisdb.getNetworkInfo | | | Network.getClientVersion | erisdb.getClientVersion | | | Network.getMoniker | erisdb.getMoniker | | | Network.isListening | erisdb.isListening | | | Network.getListeners | erisdb.getListeners | | | Network.getPeers | erisdb.getPeers | | | Network.getPeer | erisdb.getPeer | |
Transactions
A transaction is the equivalence of a database write
operation. They can be done in two ways. There's the "dev" way, which is to call transact
and pass along the target address (if any), data, gas, and a private key used for signing. It is very similar to the old Ethereum way of transacting, except Tendermint does not keep accounts in the client, so a private key needs to be sent along. This means the server should either run on the same machine as the tendermint client, or in the same, private network.
Transacting via broadcastTx
will be the standard way of doing things if you want the key to remain on the users machine. This requires a browser plugin for doing the actual signing, which we will add later. For now, you should stick to the transact
method.
To get a private key for testing/developing, you can run tendermint gen_account
if you have it installed. You can also run tools/pa_generator.js
if you have a local node running. It will take the url as command line argument at some point...
Calls
Calls provide read-only access to the smart contracts. It is used mostly to get data out of a contract-accounts storage by using the contracts accessor methods, but can be used to call any method that does not change any data in any account. A trivial example would be a contract function that takes two numbers as input, adds them, and then simply returns the sum.
There are two types of calls. Call
takes a data string and an account address and calls the code in that account (if any) using the provided data as input. This is the standard method for read-only operations.
CallCode
works the same except you don't provide an account address but the actual compiled code instead. It's a dev tool for accessing the VM directly. "Code-execution as a service".
| Method | RPC method | Notes | | :----- | :--------- | :---- | | Transactions.broadcastTx | erisdb.broadcastTx | see below | | Transactions.getUnconfirmedTxs | erisdb.getUnconfirmedTxs | | | Transactions.call | erisdb.call | | | Transactions.callCode | erisdb.callCode | | | Transactions.transact | erisdb.transact | unsafe | | Transactions.transactAndHold | erisdb.transactAndHold | unsafe | | Transactions.transactNameReg | erisdb.transactNameReg | unsafe |
broadcastTx
is useless until we add a client-side signing solution.
Documentation
Generate documentation using the command npm run doc
.
Testing
To test the library against pre-recorded vectors:
npm test
To test the library against Eris DB while recording vectors:
TEST=record npm test
To test Eris DB against pre-recorded vectors without exercising the library:
TEST=server npm test
Debugging
Debugging information will display on stderr
if the library is run with NODE_DEBUG=eris
in the environment.
Copyright
Copyright 2015 Monax
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.