...
Page properties | ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||
|
...
Background
Previous assumptions about Iroha Network and Web API in general were usage of iroha-client with encapsulation of underlying (plain TCP) protocols.
New needs from dependent projects require discussion of these assumptions and decision how to work with iroha network.
...
It turns out that `Substrate's` off chain workers provides only HTTP (more high level) API for communications with external resources (like Iroha Peer).
In this discussion we should make a decision - will this situation impact our current solution?
Solution
Requirements from Iurii Vinogradov
- We need Http HTTP compatible interface on Iroha side
We need and Http compatible client library which can support all Iroha user ISI, Query, streams.
HTTP client library should be implemented in Rust for use from Substrate.
We need JS compatible library to interact with Iroha2
The deadline is the middle of August.
- Peer API
- HTTP client library for Instructions, Queries, Events
- Rust client library (for Substrate's Off-chain workers)
- JS Client library
Problem
Different clients environments have different restrictions - the strictest one is Substrate's Off-chain worker runtime which only supports HTTP 1.
Also DevOps team and Client side developers prefer to use JSON as a client-peer communication format. Some scenarios require to have an ability to combine Instructions API with Events API (send transaction and start consuming updates on it).
Solution
As a solution we propose this high-level design. HTTP and WebSocket protocols will be used for communication between Clients and Iroha Peers.Which can be rephrased as:
Iroha should provide HTTP API.
- Endpoints for:
- Iroha Special Instructions Submission
- Iroha Queries Execution Queries
- Iroha Cloud Events Consumption
- Iroha's Rust HTTP client library for Substrate's Off-chain Workers should be developed
- Iroha's JS client library should be developed
Decisions
- Iroha Bridge module will provide additional HTTP Endpoints on top of existing Torii Endpoints
- JS library will use HTTP Endpoints and will not depend on Iroha codebase
- Rust HTTP Client will be implemented as a separate `no-std` crate
- Cloud Events will be implemented via HTTP instead of WebSocket because of Substrate's restrictions
Alternatives
- Iroha provides HTTP API out-of-the-box
- Need to define scope
- Need to not duplicate peer to peer communications logic
- Dedicated HTTP server module on Iroha 2 not included in the core but have an ability to proxy all ISI and queries if needed.
- Iroha Bridge has an additional application as a proxy on top of Iroha API (as a standalone app or service mesh)
- Every client is responsible for HTTP Adapters
Concerns
- Any change in `iroha_network` algorithms and Iroha entities format will break clients
- HTTP implementation of Cloud Events may be very slow and impact the throughput of the whole ledger
- Events (under consideration - needed for Substrate)
- MIME type of the HTTP API will be `application/json`
- Clients build their own functionality or use 3rd party clients to establish HTTP connection, sign and construct transactions
- JSON RPC or RESTfull approach should be discussed
Additionally Iroha should provide WebSocket API.
- Endpoints:
- Iroha Events
- Iroha Special Instructions (under consideration - was requested by client-side developers)
- Iroha Queries (under consideration - was requested by client-side developers)
- JSON RPC can be used as high level protocol over WebSocket
Decisions
- Iroha will provide HTTP and WebSocket API for clients
- JSON format for messages encoding/decoding will be used
Alternatives
- Stay with TCP and use middle ware for protocol and messages transformations - not user friendly
- Use HTTP 2.0 - will not work with Substrate
Concerns
- WebSocket connections should have configuration options to prevent bad performance of Iroha peers under high load
Assumptions
- Bridge clients will use Substrate's Off-chain Workers with an ability to communicate over HTTP only
- JS client has additional restrictions
- All clients will use scale encoding
Risks
- Backward compatibility breakage `[7; 9]`
- Performance regress `[8; 5]`Scale encoding will be hard to implement for non-rust clients `[3; 5]`
Action items
- Iurii VinogradovSalakhiev Kamil Makoto Takemiya review requirements
- Iurii Vinogradov ask for comments from clients' developers
- Nikita Puzankov design the result of the discussion