api.md

```

#####Return value

```
{
	
	header: {
		chain_id:        <string>
		height:          <number>
		time:            <string>
		fees:            <number>
		num_txs:         <number>
		last_block_hash: <string>
		last_block_parts: {
			total: <number>
			hash:  <string>
		}
		state_hash: <string>
	}
	validation: {
		commits: [<Commit>]
		TODO those other two.
	}
	data: {
		txs: [<Tx>]
		TODO that other field.
	}
}
```

The `Commit` object:

```
{
	address:   <string>
	round:     <number>
	signature: <string>
}
```

#####Additional info

TODO

See [The transaction types](#the-transaction-types) for more info on the `Tx` types. 

***

<a name="consensus"></a>
###Consensus

***

<a name="get-consensus-state"></a>
####GetConsensusState

Get the current consensus state. 

#####HTTP

Method: GET

Endpoint: `/consensus`

#####JSON-RPC

Method: `erisdb.getConsensusState`

Parameter: -

#####Return value

```
{
	height:      <number>
	round:       <number>
	step:        <number>
	start_time:  <string>
	commit_time: <string>
	validators:  [<Validator>]
	proposal: {
		height: <number>
		round:  <number>
		block_parts: {
			total: <number>
			hash:  <string>
		}
		pol_parts: {
			total: <number>
			hash:  <string>
		}
		signature: <string>
	}
}
```

#####Additional info

TODO

See the GetValidators method right below for info about the `Validator` object.

***

<a name="get-validators"></a>
####GetValidators

Get the validators. 

#####HTTP

Method: GET

Endpoint: `/consensus/validators`

#####JSON-RPC

Method: `erisdb.getValidators`

Parameter: -

#####Return value

```
{
	block_height:         <number>
	bonded_validators:    [<Validator>]
	unbonding_validators: [<Validator>]
}
```

The `Validator` object:

```
{
	address:            <string>
	pub_key:            <PubKey>
	bon_height:         <number>
	unbond_height:      <number>
	last_commit_height: <number>
	voting_power:       <number>
	accum:              <number>
}
```

#####Additional info

TODO

***

<a name="events"></a>
###Events

***

<a name="event-subscribe"></a>
####EventSubscribe

Subscribe to a given type of event.  

#####HTTP

Method: POST

Endpoint: `/event_subs/`

Body: See JSON-RPC parameter.

#####JSON-RPC

Method: `erisdb.eventSubscribe`

Parameter: 

```
{
	event_id: <string>
}
```

#####Return value

```
{
	sub_id: <string>
}
```

#####Additional info

For more information about events and the event system, see the [Event system](#event-system) section.

***

<a name="event-unsubscribe"></a>
####EventUnubscribe

Unsubscribe to an event type.  

#####HTTP

Method: DELETE

Endpoint: `/event_subs/:id`

#####JSON-RPC

Method: `erisdb.eventUnsubscribe`

Parameter: -

#####Return value

```
{
	result: <bool>
}
```

#####Additional info

For more information about events and the event system, see the [Event system](#event-system) section.

***

<a name="event-poll"></a>
####EventPoll

Poll a subscription. Note this cannot be done if using websockets, because then the events will be passed automatically over the socket.

#####HTTP

Method: GET

Endpoint: `/event_subs/:id`

#####JSON-RPC

Method: `erisdb.eventPoll`

#####Return value

```
{
	events: [<Event>]
}
```

#####Additional info

For more information about events and the event system, see the [Event system](#event-system) section. This includes info about the `Event` object.

***


<a name="name-registry"></a>
####Name-registry

<a name="get-namereg-entries"></a>
####GetNameRegEntries

This will return a list of name reg entries. Filters may be used.

#####HTTP

Method: GET

Endpoint: `/namereg`

#####JSON-RPC

Method: `erisdb.getNameRegEntries`

Parameter:

```
{
	filters: [<FilterData>]
}
```

##### Filters

| Field | Underlying type | Ops | Example Queries |
| :---- | :-------------- | :-- | :-------------- |
| `expires` | int | `<`, `>`, `<=`, `>=`, `==` | `q=expires:<=50` |
| `owner` | byte[] | `==`, `!=` | `q=owner:1010101010101010101010101010101010101010` |
| `name` | string | `==`, `!=` | `q=name:!=somekey` |
| `data` | string | `==`, `!=` | `q=name:!=somedata` |

NOTE: While it is supported, there is no point in using `name:==...`, as it would search the entire map of names for that entry. Instead you should use the method `GetNameRegEntry` which takes the name (key) as argument.

#####Return value

```
{
	block_height: <number>
	names:        <NameRegEntry>
}
```

#####Additional info

See GetNameRegEntry below for more info on the `NameRegEntry` object.

See the section on [Filters](#queries-filters) for info on the `FilterData` object.

***

<a name="get-namereg-entry"></a>
####GetNameRegEntry

Get a namereg entry by its key.

#####HTTP

Method: GET 

Endpoint: `/namereg/:name`

Params: The key (a string)


#####JSON-RPC

Method: `erisdb.getNameRegEntry`

Parameter:

```
{
	name: <string>
}
```

#####Return value

```
{
	owner:   <string>
	name:    <string>
	data:    <string>
	expires: <number>
}
```

***

<a name="network"></a>
###Network

***

<a name="get-network-info"></a>
####GetNetworkInfo

Get the network information. This includes the blockchain client moniker, peer data, and other things.

#####HTTP

Method: GET

Endpoint: `/network`

#####JSON-RPC

Method: `erisdb.getNetworkInfo`

Parameters: -

#####Return value

```
{
	client_version: <string>
	moniker: <string>
	listening: <boolean>
	listeners: [<string>]
	peers: [<Peer>]
}
```

#####Additional info

`client_version` is the version of the running client, or node.
`moniker` is a moniker for the node.
`listening` is a check if the node is listening for connections.
`listeners` is a list of active listeners.
`peers` is a list of peers.

See [GetPeer](#get-peer) for info on the `Peer` object.

***

<a name="get-client-version"></a>
####GetClientVersion

Get the version of the running client (node).

#####HTTP

Method: GET

Endpoint: `/network/client_version`

#####JSON-RPC

Method: `erisdb.getClientVersion`

Parameters: -

#####Return value

```
{
	client_version: <string>
}
```

***

<a name="get-moniker"></a>
####GetMoniker

Get the node moniker, or nickname.

#####HTTP

Method: GET

Endpoint: `/network/moniker`

#####JSON-RPC

Method: `erisdb.getMoniker`

Parameters: -

#####Return value

```
{
	moniker: <string>
}
```

***

<a name="is-listening"></a>
####IsListening

Check whether or not the node is listening for connections.

#####HTTP

Method: GET

Endpoint: `/network/listening`

#####JSON-RPC

Method: `erisdb.isListening`

Parameters: -

#####Return value

```
{
	listening: <boolean>
}
```

***

<a name="get-listeners"></a>
####GetListeners

Get a list of all active listeners.

#####HTTP

Method: GET

Endpoint: `/network/listeners`

#####JSON-RPC

Method: `erisdb.getListeners`

Parameters: -

#####Return value

```
{
	listeners: [<string>]
}
```

***

<a name="get-peers"></a>
####GetPeers

Get a list of all peers.

#####HTTP

Method: GET

Endpoint: `/network/peers`

#####JSON-RPC

Method: `erisdb.getPeers`

Parameters: -

#####Return value

```
{
	peers: [<Peer>]
}
```

See [GetPeer](#get-peer) below for info on the `Peer` object.

***

<a name="get-peer"></a>
####GetPeer

Get the peer with the given IP address.

#####HTTP

Method: GET

Endpoint: `/network/peer/:address`

#####JSON-RPC

Method: `erisdb.getPeer`

Parameters: 

```
{
	address: <string>
}
```

#####Return value

This is the peer object.

```
{
	is_outbound: <boolean>
	moniker:     <string>
	chain_id:    <string>
	version:     <string>
	host:        <string>
	p2p_port:    <number>
	rpc_port:    <number>
}
```


#####Additional info

TODO

***

<a name="transactions"></a>
###Transactions 

***

<a name="broadcast-tx"></a>
####BroadcastTx 

Broadcast a given (signed) transaction to the node. It will be added to the tx pool if there are no issues, and if it is accepted by all validators it will eventually be committed to a block.

WARNING: BroadcastTx will not be useful until we add a client-side signing solution. 

#####HTTP

Method: POST

Endpoint: `/txpool`

Body:

```
<Tx>
```

#####JSON-RPC

Method: `erisdb.BroadcastTx`

Parameters: 

```
<Tx>
```

#####Return value

```
{
	tx_hash:          <string>
	creates_contract: <number>
	contract_addr:    <string>
}
```

#####Additional info

`tx_hash` is the hash of the transaction (think digest), and can be used to reference it.

`creates_contract` is set to `1` if a contract was created, otherwise it is 0.

If a contract was created, then `contract_addr` will contain the address. NOTE: This is no guarantee that the contract will actually be commited to the chain. This response is returned upon broadcasting, not when the transaction has been committed to a block.

See [The transaction types](#the-transaction-types) for more info on the `Tx` types. 

***

<a name="get-unconfirmed-txs"></a>
####GetUnconfirmedTxs

Get a list of transactions currently residing in the transaction pool. These have been admitted to the pool, but has not yet been committed.

#####HTTP

Method: GET

Endpoint: `/txpool`

#####JSON-RPC

Method: `erisdb.getUnconfirmedTxs`

Parameters: -

#####Return value

```
{
	txs: [<Tx>]
}
```


#####Additional info

See [The transaction types](#the-transaction-types) for more info on the `Tx` types. 

***

<a name="calls"></a>
###Code execution (calls) 

***

<a name="call"></a>
####Call

Call a given (contract) account to execute its code with the given in-data. 

#####HTTP

Method: POST

Endpoint: `/calls`

Body: See JSON-RPC parameter.

#####JSON-RPC

Method: `erisdb.call`

Parameters: 

```
{
	address: <string>
	data: <string>
}
```

#####Return value

```
{
	return:   <string>
	gas_used: <number>
}
```

#####Additional info

`data` is a string of data formatted in accordance with the.

***

<a name="call-code"></a>
####CallCode

Pass contract code and tx data to the node and have it executed in the virtual machine. This is mostly a dev feature.

#####HTTP

Method: POST

Endpoint: `/codecalls`

Body: See JSON-RPC parameter.

#####JSON-RPC

Method: `erisdb.callCode`

Parameters: 

```
{
	code: <string>
	data: <string>
}
```

#####Return value

```
{
	return: <string>
	gas_used: <number>
}
```

#####Additional info

`code` is a hex-string representation of compiled contract code.
`data` is a string of data formatted in accordance with the [contract ABI](TODO).

***

<a name="unsafe"></a>
###Unsafe 

These methods are unsafe because they require that a private key is either transmitted or received. They are supposed to be used only in development.

***

<a name="transact"></a>
####Transact

Convenience method for sending a transaction. It will do the following things:

* Use the private key to create a private account object (i.e. generate public key and address).
* Use the other parameters to create a `CallTx` object.
* Sign the transaction.
* Broadcast the transaction.

#####HTTP

Method: POST

Endpoint: `/unsafe/txpool`

Body: See JSON-RPC parameters.

#####JSON-RPC

Method: `erisdb.transact`

Parameters: 

```
{
	priv_key:  <string>
	data:      <string>
	address:   <string>
	fee:       <number>
	gas_limit: <number>
}
```

private key is the hex string only.

#####Return value

The same as with BroadcastTx:

```
{
	tx_hash:          <string>
	creates_contract: <number>
	contract_addr:    <string>
}
```

#####Additional info

See [The transaction types](#the-transaction-types) for more info on the `CallTx` type. 

***


<a name="transact-name-reg"></a>
####TransactNameReg

Convenience method for sending a transaction to the name registry. It will do the following things:

* Use the private key to create a private account object (i.e. generate public key and address).
* Use the other parameters to create a `NameTx` object.
* Sign the transaction.
* Broadcast the transaction.

#####HTTP

Method: POST

Endpoint: `/unsafe/namereg/txpool`

Body: See JSON-RPC parameters.

#####JSON-RPC

Method: `erisdb.transactNameReg`

Parameters: 

```
{
	priv_key:  <string>
	name:      <string>
	data:      <string>
	fee:       <number>
	amount:    <number>
}
```

#####Return value

The same as with BroadcastTx:

```
{
	tx_hash:          <string>
	creates_contract: <number> (always 0)
	contract_addr:    <string> (always empty)
}
```

#####Additional info

See [The transaction types](#the-transaction-types) for more info on the `NameTx` type. 

***

<a name="gen-priv-account"></a>
####GenPrivAccount

Convenience method for generating a `PrivAccount` object, which contains a private key and the corresponding public key and address.

#####HTTP

Method: POST

Endpoint: `/unsafe/pa_generator`
#####JSON-RPC

Method: `erisdb.genPrivAccount`

Parameters: -

#####Return value

```
{
	address: <string>
	pub_key: <PubKey>
	priv_key: <PrivKey>
}
```

#####Additional info

TODO fix endpoint and method.

Again - This is unsafe. Be warned.

***

<a name="queries-filters"></a>
##Filters

Filters are used in searches. The structure is similar to that of the [Github api (v3)](https://developer.github.com/v3/search/).

###JSON-RPC

Filters are added as objects in the request parameter. Methods that supports filtering includes an array of filters somewhere in their params object.

Filter:

```
{
    field: <string>
    op:    <string>
    value: <string> 
}
```

* The `field` must be one that is supported by the collection items in question.
* The `op` is a relational operation `[>, <, >=, <=, ==, !=]`. Different fields supports different subsets.
* The `value` is the value to match against. It is always a string.
* Range queries are done simply by adding two filters - one for the minimum value and one for the maximum.

#####Examples

We want an account filter that only includes accounts that has code in them (i.e. contract accounts):

```
{
    field: "code"
    op: "!="
    value: "" 
}
```

We want an account filter that only includes accounts with a balance less then 1000:

```
{
    field: "balance"
    op: "<"
    value: "1000"
}
```

We want an account filter that only includes accounts with a balance higher then 0, but less then 1000.

```
{
    field: "balance"
    op: ">"
    value: "0"
}
```

```
{
    field: "balance"
    op: "<"
    value: "1000"
}
```

The field `code` is supported by accounts. It allows for the `==` and `!=` operators. The value `""` means the empty hex string.

If we wanted only non-contract accounts then we would have used the same object but changed it to `op: "=="`. 

###HTTP Queries

The structure of a normal query is: `q=field:[op]value+field2:[op2]value2+ ... `.

- `q` means it's a query.
- `+` is the filter separator.
- `field` is the field name.
- `:` is the field:relation separator.
- `op` is the relational operator, `>, <, >=, <=, ==, !=`.
- `value` is the value to compare against, e.g. `balance:>=5` or `language:==golang`. 

There is also support for [range queries](https://help.github.com/articles/search-syntax/): `A..B`, where `A` and `B` are number-strings. You may use the wildcard `*` instead of a number. The wildcard is context-sensitive; if it is put on the left-hand side it is the minimum value, and on the right-hand side it means the maximum value. Let `height` be an unsigned byte with no additional restrictions. `height:*..55` would then be the same as `height:0..55`, and `height:*..*` would be the same as `height:0..255`.

NOTE: URL encoding applies as usual. Omitting it here for clarity.

`op` will default to (`==`) if left out, meaning `balance:5` is the same as `balance:==5` 

`value` may be left out if the field accepts the empty string as input. This means if `code` is a supported string type,  `code:==` would check if the code field is empty. We could also use the inferred `==` meaning this would be equivalent: `code:`.  The system may be extended so that the empty string is automatically converted to the null-type of the underlying field, no matter what that type is. If balance is a number then `balance:` would be the same as `balance:==0` (and `balance:0`).

#####Example

We want to use the same filter as in the JSON version; one that finds all contract accounts.

`q=code:!=`

One that finds those with balance less then 1000:

`q=balance:<1000`