Jędrzej Stuczyński
f328f3fa9e
* Squashing all the changes initial router started expanding the API initial empty openapi/swagger populated build-info endpoint wip: populating rest of swagger missing swagger data + using closure capture for immutable state running the api as a proper task in gateway 'run' fixing some version/feature clashes refactored routes structures initial host information endpoint expanded on gateway-related endpoints signing host information moved all models to separate crate unified http api client routes unification + node api client new generic cache and refresher nym-api caching node self described information removed old cache type temporarily wired up NymContractCache to NodeDescriptionProvider caching self reported host info clients using self-described gateway information fixed request timeouts for wasm fixed wasm builds post rebase fixes cargo fmt brought in wg routes into nym-node router added ErrorResponse for wireguard routes basic swagger support for wg endpoints turns out swagger can be happy with strongly typed requests output type support for wg routes using concrete error type for nym node request error fixed the registration test landing page configurability increased configurability fixed build and lints of other crates added default user-agent to http-api-client reduced severity of gateway details lookup failure changed default http port from 80 to 8080 nym-api using new default port for queries added health endpoint nym-api trying multiple ports for the client using camelcase for node status corrected health endpoint description restored and revamped 'force_tls' flag to filter all gateways that support the wss protocol fixed 'pub_key' path param in open api schema derived Debug on 'NymNodeDescription' ensuring valid public ips added init and run flags to set hostname and public ips fixed listening address being pushed to public ip fixed the positional local flag logging remote ip address of the request updated helper function to query for described gateways enabled tls in gateway client removed hack-opts from mix fetch additional changes after rebasing against origin/develop * clippy * wasm-related target locking * more clippy, but this time in tests
Ephemera - reliable broadcast protocol implementation
Ephemera does reliable broadcast for blocks.
Short Overview
All Ephemera nodes accept messages submitted by clients. Node then gossips these to other nodes in the cluster. After certain interval, a node collects messages and produces a block. Then it does reliable broadcast for the block with other nodes in the cluster.
Ephemera doesn't have the concept of (decentralised) leader at the moment. It's up to an Application to decide which block to use. For example in case of Nym-Api, it is the first block submitted to a "Smart Contract".
At the same time, the purpose of blocks is to reach consensus about which messages are included. It's just that Ephemera doesn't make the final decision, instead it leaves that to an Application.
Main concepts
- Node - a single instance of Ephemera.
- Cluster - a set of nodes participating in reliable broadcast.
- EphemeraMessage - a message submitted by a client.
- Block - a set of messages collected by a node.
- Application(ABCI) - a trait which Ephemera users implement to accept messages and blocks.
- check_tx
- check_block
- accept_block
How to run
HTTP API
See Rust
Endpoints
NODE
/ephemera/node/health/ephemera/node/config
BLOCKS
/ephemera/broadcast/block/{hash}/ephemera/broadcast/block/height/{height}/ephemera/broadcast/blocks/last/ephemera/broadcast/block/certificates/{hash}/ephemera/broadcast/block/broadcast_info/{hash}
GROUP
/ephemera/broadcast/group/info
MESSAGES
/ephemera/broadcast/submit_message
DHT
/ephemera/dht/query/{key}/ephemera/dht/store
Rust API
Almost identical to HTTP API.
See Rust
Application(Ephemera ABCI)
Cosmos style ABCI application hook
check_txcheck_blockdeliver_block
See Rust
Examples
Ephemera HTTP and WS external interfaces example/tests
See README.md
Nym Api simulation
See README.md
http API example/tests
See README.md
Membership over HTTP API example/tests
See README.md
About reliable broadcast and consensus
In blockchain technology blocks have two main purposes:
- To maintain chain of blocks, so that the validity of each block can be cryptographically verified by the previous blocks
- As a unit of consensus, each block contains a set of transactions/messages/actions that are agreed upon by the network. This set of transactions is chosen from the global set of all possible transactions that are pending. We call the set of transactions in a block consensus because the set of nodes trying to achieve global shared state agreed on this particular set of transactions.
Ephemera is not a blockchain. But it uses blocks to agree on the set of transactions in a block. But at the same time it doesn't behave like a blockchain consensus algorithm. We may say that it allows each application that uses Ephemera to "propose" something what can be afterwards to be used to achieve consensus.
In Summary
- Ephemera provides functionality to reach agreement on a single value between a set of nodes.
- Ephemera also provides the concept of a block, which application can take advantage of to reach consensus externally.
Reliable broadcast, consensus and blocks
In distributed systems(including byzantine), we try to solve the problem of reaching to a commons state between a set of nodes.
One way to define this problem is using the following properties: 1. 1) Agreement: All nodes agree on the same value.(TODO clarify) 2) Consensus: All nodes agree on the same value.(TODO clarify) 2. Validity: All nodes agree on a value that is valid. 3. Termination: All nodes eventually agree on a value.
Reliable broadcast ensures the properties of 1.1 and 1.2. It's left to a particular consensus algorithm to ensure the termination property.
One important feature of consensus in blockchain is that it guarantees total ordering of transactions. Reliable broadcast with blocks helps to ensure this total ordering.
Ephemera specific properties
Because Ephemera doesn't use the idea of leader, we can say that it solves consensus partially. It allows each instance to create a block. And then it's up to an application to decide which block to use.
Also, as it doesn't implement a full consensus algorithm, it doesn't ensure the termination. There's no algorithm in place what tries to reach a consensus about a single block globally and sequentially in time.
When a block contains a single message, then it's semantically equivalent to a reliable broadcast.
But when a block contains multiple messages, then it can be part of a consensus process. Except that in Ephemera each node can create a block. To achieve consensus in a more traditional sense, it needs an application help if more strict consensus is required.
For example, Nym-Api allows each node to create a block but uses external coordinator(a smart contract) to decide which block to use.