Skip to content

Javascript library that calls an erisdb server over rpc.

License

Notifications You must be signed in to change notification settings

Manna-Inc/eris-db.js

Repository files navigation

erisdb-js (Alpha)

This is a JavaScript API for communicating with a ErisDB server.

Installation

$ 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");

edb.start(function(error){
    if(!error){
        console.log("Ready to go");
    }
});

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.

If you want to specify what client to use, you do that through the createInstanceFromClient method.

var edbFactory = require('eris-db');

var wsClient = new edbFactory.clients.WebSocketClient("ws://<IP address>:1337/socketrpc")

var edb = edbFactory.createInstanceFromClient(wsClient);

edb.start(function(error){
    if(!error){
        console.log("Ready to go");
    }
});

Clients can be found in edbFactory.clients. We currently provide two - WebSocketClient and HTTPClient + the base classes (Client and TWCClient) which is only used to implement other protocols.

HTTP

If you use http(s), the start command will do nothing, so it can just be called and no callback used.

WebSocket

If you use websocket, the system will not be ready until the start callback fires.

The start callback must be on the following format: function(error).

The websocket-client has a number of additional connection-related methods:

WebSocketClient.shutDown(callback) - Technically this method is available in all clients but does not do anything with the http client. If called on an edb instance with a websocket client (or on the client directly), it will invoke the zero-argument callback function when the socket has been terminated.

WebSocketClient.reconnect(callback) - Will terminate the current connection (if any), and establish a new one. Same callback as with start (callback(error)).

WebSocketClient.setCloseCallback(callback) - If this zero-argument callback is set, it will be invoked when the active connection is closed. The callback will remain until it is set to null. Note that it will also be called when reconnecting if there was an already active connection (since that connection will be closed).

If you want to use several sockets at once (for some reason), you can do that. Just create multiple ErisDB instances through edbFactory.createInstance(...).

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.

Tests

For unit tests, run npm test.

For integration tests:

$ cd test/integration
$ ./test.sh

Documentation

Generate documentation using the command npm run doc.

Browser

This library will be possible to run from a web-browser at some point.

Copyright

Copyright 2015 Eris Industries

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/.

About

Javascript library that calls an erisdb server over rpc.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages