Web API

Issues

  • We need to define networking format
  • We need to define Iroha Peer entry-points
  • We need to support communication with:
    • Clients (Web, Android, iOS)
    • Bridges (Polkadot)
    • Peers (Iroha)

Current status

We already have `Iroha_Network` library crate with plain TCP API to:

  • send requests
  • listen for requests

Messages encoded via `SCALE` format and send as pure bytes.

iroha:peer:Peer and iroha:torii:Torii currently both use the second `Iroha_Network` API, listening for incoming requests:

As you can see, it's quite similar. Also during discussion with Egor Ivkov we found a way to remove "hardcode" from entry-points.

Proposal

First of all, we want to put listener for incoming Web Requests in one place - `Torii`, while send requests API of `Iroha_Network` crate will be available from several places.

Let's start from the entry-points:

Entry-pointURIImplementationComments
Client → Peer
MaintenanceLook Maintenance RFC
Transactions/transactionTorii + Queue

Web API for incoming Transactions with Instructions to execute on the ledger

Transactions can be send from Clients, Bridges or other Peers

Query/queryTorii + WSVWeb API for Queries which will work with World State View of the Peer
Peer ↔ Peer
Block synchronization/blockTorii + KuraWeb API for data synchronization and propagation between Peers
Consensus/voteTorii + SumeragiWeb API for consensus voting via Sumeragi logic

Protocol and Formats

Right now we do not have application layer protocol and use TCP. All protocol related logic is placed inside `Iroha_Network` crate.

This way Torii as a listener and all "senders" can be decoupled from our decision about Protocol (REST/gRPC). 

Payload Messages format is defined by Iroha lib and encoded via `SCALE` so it's just bytes in Network Message.

Right now our proposal is to stay with pure TCP, use C ABI for Android/iOS clients. Web API should be discussed with the appropriate team.

Configuration as a Contract

To remove hardcoded handlers in our entry-points we want to use ISI and event triggers.

For example this cases can be implemented in compliance with whitepaper, but without hardcode:

  • changes in `Iroha` instances like new `ChangeBlockBuildStepTime` 
  • `AddPeer` instruction will add new peer to WSV:Peer:Peers
  • `ShareNewBlock` event can trigger new block  propagation to peers from WSV:Peer:Peers
  • `Vote` can be implemented as Instruction

Open Questions

  • When Peers send accepted transactions? Right after acceptance or each tick of Block Build Step
  • What is the difference between Block commit message handling and Block synchronization
  • How to update configuration which requires instance reloading (new address, etc)