/
Web API

Web API

Aug 04, 2020

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-point

URI

Implementation

Comments

Entry-point

URI

Implementation

Comments

Client → Peer

Maintenance

Look Maintenance RFC

Transactions

/transaction

Torii + Queue

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

Transactions can be send from Clients, Bridges or other Peers

Query

/query

Torii + WSV

Web API for Queries which will work with World State View of the Peer

Peer ↔ Peer

Block synchronization

/block

Torii + Kura

Web API for data synchronization and propagation between Peers

Consensus

/vote

Torii + Sumeragi

Web 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)