API Specs for blockchain network management on peer node

gnulib commented 6 years ago

Description

As a developer,

I would like to know API specifications for a peer node to create/update a blockchain network,

so that I can manage a blockchain network dynamically.

Acceptance Criteria

a REST API is defined to configure and create a new blockchain network on a peer node
a REST API is defined to update configuration for an existing blockchain network on a peer node
it is assumed that peer node will also act as default boot node for the network
membership to a blockchain network still needs to be explicitly requested with membership APIs

gnulib commented 6 years ago

Start Bootnode API Specs

A blockchain network needs following minimum information:

network ID (or shard ID) <-- this uniquely identifies the network, and hence need to be globally unique
~membership key <-- this is the shared secret to authenticate peer membership entitlement~ (actually peer membership verification should be application level logic, part of handshake)

Q: Hmm, it seems like there is no value in an API just for creating a blockchain network. It might be better to just use the membership API -- i.e. join a network "ad-hoc" while joining the membership? A: We might still want the "boot node" capability. Hence, it might be useful to have a "configure" API, instead of "create" API, to make a node start acting as an ad-hoc boot-node for a blockchain network. (~In fact, we might want to only allow membership on a node that is configured as boot node, or listener, for a network explicitly~, actually boot node is different from listener, we need boot nodes for p2p network setup, regardless of membership)

Method: POST /bootnodes/start
Request Body:
```
{
'id': 'network id'
}
```
success response:
```
201 Created
```

{ 'url' : 'boot node url' }

* failure response:

409 Conflict

{ 'code' : '409', 'error' : 'boot node already exists for network id' }

* failure response:

503 Service Unavailable

{ 'code' : '503', 'error' : 'boot node capacity exceeded' }


## Stop Bootnode API Specs
This API will be used to stop a boot node on specified network ID.

* Method: `POST /bootnodes/stop`
* Request Body:

{ 'id': 'network id' }

* success response:

204 No Content

* failure response:

404 Not Found

{ 'code' : '404', 'error' : 'boot node does not exists for network id' }


## List Bootnodes API Specs
This API will be used to get a list of current boot nodes for different networks, running on this node.

* Method: `GET /bootnodes`
* Response:

[ { 'id' : 'network id 1', 'url' : 'boot node url for network id 1' }, { 'id' : 'network id 2', 'url' : 'boot node url for network id 2' } ]

gnulib commented 6 years ago

Genesis???

But what about the Genesis block? How can a blockchain be created without a genesis block?

Ok, this is the reason we need to have a network configuration API, separate from membership join/leave API. A network configuration will need to be created first (with genesis hash and all other network initialization info). Then one or memberships can be requested for that configured network (so a node can host multiple members for a network, if needed -- but is that reasonable? for non-mining network it makes sense, its like having virtualization/multi-tenancy at the node level)

However, reading at the genesis block example, it seems genesis block has all values as null values -- except for "pre-funding" some accounts. This means we can safely assume that a private network can be initialized with default null values, and the only explicit parameter needed is the network id (or chain-id, from ethereum world). There is still one other parameter that can be specified -- the protocol (e.g. ETH, RTU/ET, etc), based on which a specific DLT stack will get instantiated. However, for now we'll only support RTU/ET, i.e., trust-net protocol. So, back to our last stand, we only need "bootnode" configurations, to enable rendezvous points. Any actual blockchain/DLT stack instantiation will occur during membership request, and will only need bootnode, network id, and protocol param (and of-course public key).

trust-net / go-sdb-node