Status

DECIDED

Stakeholders

Salakhiev Kamil  Iurii Vinogradov Egor Ivkov   

Outcome

Unable to render Jira issues macro, execution error.

Due date
Owner

Nikita Puzankov

Background

Iroha Users need information about "system" aspects which are not available via Iroha Queries to World State View, for example:

  • Peer's Health Check (Naming of states inspired by Prometheus)

  • Peer's Management - start, stop

  • Resources Monitoring  - CPU, Memory and Disk consumption

  • Logging Configuration

  • Business Measurements of Iroha

    • Transactions per second amount

    • Blocks Storage size

    • Submitted transactions statuses changes
    • Blocks statuses changes

Problem

For some clients and for Iroha administrators it is important to have more information than can be provided by Iroha Data Model.

One of such a cases were described by the following requirements:

  • Client should receive status changes of all transactions submitted by this client.
  • Iroha Peer should guarantee that changes submitted to the client goes over synchronous protocol and messages received by client if peer and client are connected.
    • If peer, client or network goes down - Client should use another API to check current status of entities needed.
    • Iroha Peer will not store information about status changes and they may be lost.
    • iroha Peer will provide information available for this peer only.
  • The same functionality should be provided to monitor blocks statuses.

Because transactions states changes are not stored on the Blockchain and can't be presented in World State View `Maintenance Endpoint` is a good place to add this functionality to.

Solution

As a result we can create additional client-facing Iroha API which described in the table below:

APIURIProtocolComments
Configuration`/config`HTTP

REST API for managing Iroha Peer's configuration:

  • log level
Monitoring`/health`HTTPAligned with Prometheus Peer's Health Check information
`/metrics`HTTPMetrics ready to be scraped by Prometheus
Events`/event`

WebSocket

Human friendly WS API for Cloud Events consumers
TCP/IPLow-level API with binary messages for Cloud Events consumers

Each API responsible for subset of maintenance features. Events API available in two variants - WebSocket for mobile clients, web applications and other human oriented technologies, while TCP/IP option for those clients which resources are limited.

Decisions

  • Use HTTP for configuration and monitoring APIs (message format can be json or text based on Prometheus specification)
  • Events API implemented as WebSocket and proprietary TCP/IP variants
  • Additional port should be used by Maintenance Endpoint

Alternatives

  • We can stay with TCP approach but we will need to change DevOps processes and tools, Substrate Off-chain workers also will not be able to deal with TCP
  • We can use HTTP for Events API but it's not effective way to handle active sessions between Iroha Peers and Substrate Off-chain workers

Assumptions

Different system events will be aligned with CNCF CloudEvents Specification and may be used in non-maintenance endpoints later.

Concerns

To prevent secured information losses `subscribers` should receive only information they had permissions to have. The "CanAnything" permission will provide information about the entire system and most of maintenance endpoints will require accounts with it. If account has no "CanAnything" permission, it's signature should be presented in transactions to receive information about their states changes.

Risks

  • Substrate off-chain workers integration will require additional parties (no direct communication with Iroha) `[9;4]`
  • Support of two variants for Events API will require additional maintenance resources `[7;2]`

Additional Information

  • No labels

13 Comments

  1. Iurii Vinogradov

    1. Speaking about the security aspect:
      1. I think it is clear that if user is subscribed on own transactions statuses than here are no security breach.
      2. But when this user wants to get information of his transactions committed to the block he will get the whole block in the current vision. Here some security breach is possible if Iroha2 not expects that any one can get all block data.

    1. Nikita Puzankov

      Iurii Vinogradov yes - 1.b is exactly the main concern here. We have permissions model for both - Instructions and Queries so maybe Makoto Takemiya has an opinion on what we should provide for blocks API?

      1. Makoto Takemiya

        If someone doesn't have permission to view something, they shouldn't get it. For proving that their tx is in a block, you just need hashes of merkle subtree (not even tx hashes at the root, except maybe the sibling of your tx).

      2. Iurii Vinogradov

        According to Makoto's message we can filter block data returned to the User according to his permissions.

        1. Nikita Puzankov

          Yes, as I wrote in "Security aspect" we will filter transactions that were sent by another clients.

  2. Nikita Puzankov

    Draft - changes transmitted through Iroha to connected and alive listener. Each listeners keeps TcpStream connection with client and submits changes. Iroha Client's API converts TcpStream into Stream<Change>.

    Each change submitted via TcpStream should be confirmed by the client in a timely manner, if not - listener will be deleted. 

    1. Vladislav Markushin

      That's good IMO. I think we also need a protocol for packing this data.

    2. Nikita Puzankov

      Egor Ivkov made a comment about the receipt - should it contain some hash of the event?

  3. Egor Ivkov

    I have some security concerns about the endpoints that we have:

    1. If anyone can set the log level of the node, then it gives the possibility to slow down the node by setting the log level to maximum. This will significantly influence the performance as we have observed several times. The solution can be to have a list of keys in the config of the node, that belong to the node administrator.
    2. Sharing the RAM and disk usage can help attackers find the weakest nodes and target them in attempt to hinder the performance of the network.

    1. Nikita Puzankov

      Hi Egor Ivkov,

      1. Not anyone - only people with rights to do this.
      2. This API also should be protected.

      1. Egor Ivkov

        Yes, sure. That's what I am getting at. Should we have a special RFC for this? Or is this out of the scope of MVP?

        1. Nikita Puzankov

          You can add decision to protect endpoints to this RFC.

    2. Vadim Reutskiy

      Maintenance endpoint requires protection, for sure. You are absolutely correct in your warnings.

      We can take an existing approach for such protection.

      Bulat Saifullin Andrei Lebedev can you share your vision how it can be done to satisfy the protection and convenience?