api.md

Eris DB web APIs (draft)

for eris-db version 0.11.x

Eris DB allows remote access to its functionality over http and websocket. It currently supports JSON-RPC 2.0, and REST-like http. There is also javascript bindings available in the erisdb-js library.

TOC

• HTTP Requests
• JSON-RPC 2.0
• REST-like HTTP
• Common objects and formatting
• Event-system
• Methods
• NameReg
• Filters

HTTP Requests

The only data format supported is JSON. All post requests needs to use Content-Type: application/json. The charset flag is not supported (json is utf-8 encoded by default).

JSON RPC 2.0

The default endpoints for JSON-RPC (2.0) is /rpc for http based, and /socketrpc for websocket. The namespace for the JSON-RPC service is erisdb.

It does not yet support notifications or batched requests.

Objects

Errors

PARSE_ERROR      = -32700
INVALID_REQUEST  = -32600
METHOD_NOT_FOUND = -32601
INVALID_PARAMS   = -32602
INTERNAL_ERROR   = -32603

#####Request

{
	jsonrpc: <string>
	method:  <string>
	params:  <Object>
	id:      <string>
}

#####Response

{
	jsonrpc: <string>
	id:      <string>
	result:  <Object>
	error:   <Error>
}

#####Error

{
    code:    <number>
    message: <string>
}

Id can be any string value. Parameters are named, and wrapped in objects. Also, params, result and error params may be null.

#####Example

Request:

{
	jsonrpc: "2.0", 
	method: "erisdb.getAccount", 
	params: {address: "37236DF251AB70022B1DA351F08A20FB52443E37"}, 
	id="25"
}

Response:

{
    address: "37236DF251AB70022B1DA351F08A20FB52443E37",
    pub_key: null,
    sequence: 0,
    balance: 110000000000,
    code: "",
    storage_root: ""
}

REST-like HTTP

The REST-like API provides the typical endpoint structure i.e. endpoints are named as resources, parameters can be put in the path, and queries are used for filtering and such. It is not fully compatible with REST; partly because some GET requests can contain sizable input so POST is used instead. There are also some modeling issues but those will most likely be resolved before version 1.0.

##Common objects and formatting

This section contains some common objects and explanations of how they work.

###Numbers and strings

Numbers are always numbers, and never strings. This is different from Ethereum where currency values are so high they need string representations. The only thing hex strings are used for is to represent byte arrays.

Hex strings are never prefixed.

#####Examples

"some_number_field" : 5892,
"another_number_field" : 0x52
"hex_string" : "37236DF251AB70022B1DA351F08A20FB52443E37"

###Keys and addresses

Public and Private keys in JSON data are either null, or on the form: [type, hex], where type is the public, or private key type, and hex is the hex-string representation of the key bytes.

• A public address is a 20 byte hex string.
• A public key is a 32 byte hex string.
• A private key is a 64 byte hex string.

#####WARNING

When using a client-server setup, do NOT send public keys over non-secure connections. The only time this is fine is during development when the keys are nothing but test data and does not protect anything of value. Normally they should either be kept locally and used to sign transactions locally, held on the server where the blockchain client is running, or be passed over secure channels.

#####Examples

A public address: "37236DF251AB70022B1DA351F08A20FB52443E37"

The corresponding Ed25519 public key: [1, "CB3688B7561D488A2A4834E1AEE9398BEF94844D8BDBBCA980C11E3654A45906"]

The corresponding Ed25519 private key: [1, "6B72D45EB65F619F11CE580C8CAED9E0BADC774E9C9C334687A65DCBAD2C4151CB3688B7561D488A2A4834E1AEE9398BEF94844D8BDBBCA980C11E3654A45906"]

###The transaction types

These are the types of transactions. Note that in DApp programming you would only use the CallTx, and maybe NameTx.

####SendTx

{
	inputs:  [<TxInput>]
	outputs: [<TxOutput>]
}

####CallTx

{
	input:     <TxInput>
	address:   <string>
	gas_limit: <number>
	fee:       <number>
	data:      <string>
}

####NameTx

{
	input:  <TxInput>
	name:   <string>
	data:   <string>
	amount: <number>
	fee:    <number>
}

####BondTx

{
	pub_key:   <PubKey>
	signature: <string>
	inputs:    [<TxInput>]
	unbond_to: [<TxOutput>]
}

####UnbondTx

{
	address:   <string>
	height:    <number>
	signature: <string>
}

####RebondTx

{
	address:   <string>
	height:    <number>
	signature: <string>
}

####DupeoutTx

{
	address: <string>
	vote_a:  <Vote>
	vote_b:  <Vote>
}

These are the support types that are referenced in the transactions:

####TxInput

{
	address:   <string>
	amount:    <number>
	sequence:  <number>
	signature: <string>
	pub_key:   <string>
}

####TxOutput

{
	address: <string>
	amount:  <number>
}

####Vote

{
	height:     <number>
	type:       <number>
	block_hash: <string>
	block_parts: {
		total: <number>
		hash:  <string>
	}
	signature: <string>
}

##Event system

Tendermint events can be subscribed to regardless of what connection type is used. There are three methods for this:

• EventSubscribe is used to subscribe to a given event, using an event-id string as argument. The response will contain a subscription ID, which can be used to close down the subscription later, or poll for new events if using HTTP. More on event-ids below.
• EventUnsubscribe is used to unsubscribe to an event. It requires you to pass the subscription ID as an argument.
• EventPoll is used to get all the events that has accumulated since the last time the subscription was polled. It takes the subscription ID as a parameter. NOTE: This only works over HTTP. Websocket connections will automatically receive events as they happen. They are sent as regular JSON-RPC 2.0 responses with the subscriber ID as response id.

There is another slight difference between polling and websocket, and that is the data you receive. If using sockets, it will always be one event at a time, whereas polling will give you an array of events.

Event types

These are the type of events you can subscribe to.

The "Account" events are triggered when someone transacts with the given account, and can be used to keep track of account activity.

NewBlock and Fork happens when a new block is committed or a fork happens, respectively.

The other events are directly related to consensus. You can find out more about the Tendermint consensus system in the Tendermint white paper. There is also information in the consensus sources, although a normal user would not be concerned with the consensus mechanisms, but would mostly just listen to account- and perhaps block-events.

Account Input

This notifies you when an account is receiving input.

Event ID: Acc/<address>/Input

Example: Acc/B4F9DA82738D37A1D83AD2CDD0C0D3CBA76EA4E7/Input will subscribe to input events from the account with address: B4F9DA82738D37A1D83AD2CDD0C0D3CBA76EA4E7.

Event object:

{
	tx:        <Tx>
	return:    <string>
	exception: <string>
}

Account Output

This notifies you when an account is yielding output.

Event ID: Acc/<address>/Output

Example: Acc/B4F9DA82738D37A1D83AD2CDD0C0D3CBA76EA4E7/Output will subscribe to output events from the account with address: B4F9DA82738D37A1D83AD2CDD0C0D3CBA76EA4E7.

Event object:

<Tx>

Account Call

This notifies you when an account is the target of a call. This event is emitted when CallTxs (transactions) that target the given account has been finalized. It is possible to listen to this event when creating new contracts as well; it will fire when the transaction is committed (or not, in which case the 'exception' field will explain why it failed).

NOTE: The naming here is a bit unfortunate. Ethereum uses 'transaction' for (state-changing) transactions to a contract account, and 'call' for read-only calls like is used for accessor functions and such. Tendermint on the other hand, which uses many types of transactions uses 'CallTx' for a transaction made to a contract account, since it calls the code in that contract, and refers to these simply as 'calls'. Read-only calls is normally referred to as 'simulated calls'.

Event ID: Acc/<address>/Call

Example: Acc/B4F9DA82738D37A1D83AD2CDD0C0D3CBA76EA4E7/Call will subscribe to events from the account with address: B4F9DA82738D37A1D83AD2CDD0C0D3CBA76EA4E7.

{
	call_data: {
		caller: <string>
    	callee: <string>
    	data:   <string>
    	value:  <number>
    	gas:    <number>
	}
	origin:     <string>
	tx_id:      <string>
	return:     <string>
	exception:  <string>
}

Log

This notifies you when the VM fires a log-event. This happens for example when a solidity event is fired.

Event ID: Log/<address>

Example: Log/B4F9DA82738D37A1D83AD2CDD0C0D3CBA76EA4E7/Input will subscribe to all log events from the account with address: B4F9DA82738D37A1D83AD2CDD0C0D3CBA76EA4E7.

type Log struct { Address Word256 Topics []Word256 Data []byte Height uint64 }

Event object:

{
	address: <string>
	topics:  []<string>
	data:    <string>
	height   <number>
}

address is the address of the account that created the log event.

topics is the parameters listed as topics. In a (named) Solidity event they would be the hash of the event name, followed by each param with the indexed modifier.

data the data. In a Solidity event these would be the params without the indexed modifier.

height is the current block-height.

New Block

This notifies you when a new block is committed.

Event ID: NewBlock

Event object:

<Block>

Fork

This notifies you when a fork event happens.

Event ID: Fork

Event object:

TODO

<Block>

Bond

This notifies you when a bond event happens.