Page History

...

...

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?

Requirements from Iurii Vinogradov

...

• HTTP compatible

...

• Iroha

...

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.

Mobile developers has a lot of concerns about usage of `Rust` parts in their codebase, so it looks "native" to provide only HTTP API for 2.0.0 release and give a full freedom about implementation to client-side developers.

Solution

Which can be rephrased as:

Iroha should provide HTTP API.

• Endpoints for:
  • Iroha Special Instructions Submission
  • Iroha Queries Execution Queries 
  • Iroha Cloud Events ConsumptionEvents (under consideration - needed for Substrate)
• MIME type of the HTTP API will be `application/scale`json`
• Clients build their own functionality or use 3rd party clients to establish HTTP connection, sign and construct of transactions and work with SCALE

Decisions

• Iroha HTTP module `iroha::modules::http` will provide additional HTTP Endpoints on top of existing Torii Endpoints, developed as a part of bridge and DEX features from the business point of view
  • `/transaction` for incoming transactions requests
  • `/query` for incoming queries requests
  • `/config` for health check, monitoring and maintenance API
• JS library will use HTTP Endpoints and will not depend on Iroha codebase
• Rust HTTP Client will not be implemented 
• Cloud Events will be implemented via HTTP in addition to WebSockets 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

• 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