Maintenance Endpoint

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:

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

• https://github.com/cloudevents/spec/blob/v1.0/spec.md
• https://prometheus.io/docs/instrumenting/exposition_formats/
• https://substrate.dev/docs/en/knowledgebase/runtime/off-chain-workers#fetching-external-data