Background
Different Iroha users requested possibility to receive information about things outside of a Iroha Queries scope, like list of rejected transactions or changes in their statuses.
Because storage of this information on the Blockchain may have a big cost another approaches were considered.
Action items
- Nikita Puzankov should collect comments, make final decision and move it to Architecture Decision Records Log
- Vadim Reutskiy should ask mobile and frontend developers to comment this RFC
Problem
During requirements gathering about `Bridge` and `DEX` Iroha Modules and comments on Maintenance Endpoint RFC following needs were found:
- An ability for Clients to watch for Transactions and Block changes in almost real-time manner.
- A security mechanism to filter changes and do not share information that client has no permissions to obtain.
These needs were addressed as additional requirements for Maintenance Endpoint and following issues were created:
Solution
As a standardized format for such an events CloudEvents specification was proposed as CloudNative Computing Foundation incubating project with 1.0 version released.
Maintenance endpoint will provide API marked as "unstable" feature (for release 2.0.0) with an ability to:
- Connect Consumer (Iroha Client) to the Source (Iroha Peer) providing signed filter criteria
- Criteria gives Iroha Peer information about types of Events needed
- Signature gives Iroha Peer information about the client to check permissions
That way we will address all requirements:
- An ability to receive changes in submitted by client Transactions statuses
- An ability to receive changes in Blocks formed by Peers with information inside filtered based on Clients permissions
Decisions
- Iroha Network library will provide protocol for a two-way interactive communications session. Iroha Client library will provide Rust API for more high level functions, like "subscribe_to_block_changes" and "subscribe_to_transaction_changes"
- Iroha Events will align to CloudEvents schema version 1.0
- TCP and WebSocket API will be provided by Iroha Peer
- Functionality should be optional
Alternatives
Concerns
- Some clients may fail to work with low-level TCP API or with rust client library
Assumptions
- We have a two-way interactive communication session between client and peer with streams of changes from peer's side and acceptance confirmations from client's side
- Cloud Events will be marked as "unstable" for 2.0.0 version and may have breaking changes in future minor releases
- In case of network problems or client side errors changes will not be delivered
- Information about these events is not stored by Iroha Peers
Risks
- Cloud Events will increase resources consumption and decrease performance `[4;7]`
- Breaking changes in Events format will require additional updates in client libraries `[9;5]`
1 Comment
Iurii Vinogradov
Not sure what sense of block status changes subscription if the client can subscribe to transaction status changes. Transaction status changes stream will give an opportunity to see if transactions included in block or not. Especially if the transaction status stream will contain information about block transaction is included in.
For bridge functionality, Additional block endpoint needed not as a realtime stream, but as an ability to request data of blocks that were loosed by the client because of network problems or downtime. So this endpoint looks more like a request get by block number endpoint with all user transactions committed in the requested block.