Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Page Properties


Target releaseIroha 2.0 MVP
Document status
Status
titleDRAFT
Document owner
Tech lead
Developers
Blockchain advisorsKamil Salakhiev Andrei Lebedev
QAStephan Lavrentev


Goals

Background and strategic fit

Table of Contents


Expand
titleHistory of changes
Change History


Assumptions

Requirements

Functional requirements

For the functional requirements, we should follow the default use case template by example:

Use case title
[FR0000] Example use-case; ID should be unique
Status

Status
colourYellow
titlediscuss

Status
colourGreen
titledecided

Status
colourRed
titlepostpone

Preconditions
  • List of preconditions which must be satisfied before the use case can be applied
  • Each precondition should be defined as the point in the list

Use case flow

  1. The enumerated list of actions, which describes the interaction between actors step by step
  2. Each step should involve a single actor as an object of the action
  3. Each step can involve one or more actors as a subject of the action
  4. Each use case can involve other use cases as dependencies by include or extend relationships
Postconditions
  • One or more results of successfully finished use case
Alternative flow
  • List of alternative flows that can happen with the use case.
  • Each entry should have the link to the step of the main use case flow when the alternative can occur
    • If needed, each entry can contain sub-entries
  • Each entry should describe the consequences of the alternative flow
Exception flow
  • List of exceptions that can happen during the use case flow, which can prevent it to be successfully finished
  • Each entry should have the link to the step of the main use case flow when the exception can occur
    • If needed, each entry can contain sub-entries
  • Each entry should describe the consequences of the exception


Iroha network operations

Use case title
[FR0001] Starting the Iroha network
Status

Status
colourYellow
titlediscuss

Preconditions
  • The administrator has configured environment for running Iroha executables
  • The administrator has prepared the genesis block

Use case flow

  1. The administrator launches the command to run Iroha peer and providing the path to the genesis block description
  2. The Iroha peer read and validates the genesis block configuration
  3. The Iroha peer starts the Iroha network according to the configuration in the genesis block
  4. The Iroha peer provides "successfully started" report to the administrator
Postconditions
  • The Iroha network is running
  • The administrator has access to the root account of the network
Alternative flow


Exception flow
  • At step 2, in case of the invalid genesis block, the Iroha peer shows corresponding error messages to the administrator and halts the network creation process


Use case title
[FR0002] Adding peer to the Iroha network
Status

Status
colourYellow
titlediscuss

Preconditions

Use case flow


Postconditions
Alternative flow
Exception flow


Use case title
[FR0003] Removing peer from the Iroha network
Status

Status
colourYellow
titlediscuss

Preconditions

Use case flow


Postconditions
Alternative flow
Exception flow


Use case title
[FR0004] Configuring initial state of the Iroha network
Status

Status
colourYellow
titlediscuss

Preconditions

Use case flow


Postconditions
Alternative flow
Exception flow


Making changes in Iroha network data by Iroha special instructions

Use case title
[FR0100] Sending the transaction to the Iroha network
Status

Status
colourYellow
titlediscuss

Preconditions
  • The user has an account in the Iroha network
  • The user has prepared the transaction for sending; transactions can consist of several instructions
  • The user has permissions to execute all instruction included in the transaction
  • The Iroha network is working in normal condition

Use case flow

  1. The user sends the transaction to the Iroha peer through the API
  2. The Iroha peer receives the transaction and validates its contents
  3. The Iroha peer checks that the user's account have enough permissions to run all instructions included in the transaction
  4. The Iroha peer executes the transaction by applying it to the current block
  5. The Iroha peer returns the result of the operation to the user
Postconditions
  • The transaction is successfully executed and applied to the network state
Alternative flow
  • On step 4, if the current user's account is multi-signature, the result of the transaction will be applied to the block-store only when the number of signatures will reach the current quorum value. In other cases, the Iroha peer will return "pending" status as a response on step 5.
Exception flow
  • On step 2, one of the instructions has invalid structure, the Iroha peer returns an error message with description to the user and stops the flow
  • On step 3, if the user's account does not have required permissions to execute one of the instructions, the Iroha peer returns information about that error and stops the flow
  • On step 3, in case of a multi-signature transaction, if the instruction signed using the key pair, which was already used for signing that instruction, the Iroha peer will return "already signed" error status and stop the flow


Use case title
[FR0101] Creation of the user in the Iroha network
Status

Status
colourYellow
titlediscuss

Preconditions
  • The user has permission to create other users

Use case flow

  1. The user prepares information about the account that should be created, which includes name, domain, the public key and permissions list
  2. The user prepares instruction to send to the Iroha network according to the prepared information
  3. The user sends the transaction with the instruction to the Iroha peer (<<include>> FR0100)
  4. Tha Iroha peer returns the result of the instruction execution to the user
Postconditions
  • The new account in the Iroha network is created
Alternative flowN/A
Exception flow
  • On step 3, if the account with the provided name or public key already exists in the network, the Iroha peer will return "already exists" error status; user case flow will stop.


Use case title
[FR0102] Configuring permissions for the account in the Iroha network
Status

Status
colourYellow
titlediscuss

Preconditions

Use case flow


Postconditions
Alternative flow
Exception flow


Use case title
[FR0102] Granting permissions for the account in the Iroha network
Status

Status
colourYellow
titlediscuss

Preconditions
  • The user has access to his/her account in the Iroha network
  • The user's account has permissions to provide grantable permissions

Use case flow

  1. The user prepares the instruction to grant one or more permissions to another account
  2. The user sends the transaction with the prepared instruction to the Iroha peer (<<includes>> FR0100)
  3. The Iroha peer returns the result of the instruction to the user
Postconditions
  • The permission was granted to another account
Alternative flow
Exception flow


Use case title
[FR0104] Sending complex instruction using ISI DSL
Status

Status
colourYellow
titlediscuss

Preconditions

Use case flow


Postconditions
Alternative flow
Exception flow


Use case title
[FR0105] Sending instruction and subscribing to the status of finalization
Status

Status
colourYellow
titlediscuss

Preconditions
  • The user has permissions to execute requested instruction

Use case flow

  1. The user prepares the instruction parameters according to his/her needs
  2. The user sends the transaction with the instruction into the Iroha peer (<<includes>> FR0100)
  3. The user uses the same connection for obtaining the status of the instruction finalization
  4. The Iroha peer sends updates about the instruction finalization status to the user
  5. The user receives the "successfully finalized" status about the instruction
Postconditions
  • The instruction is accepted and finalized in the block-storage
  • The user did not spend additional resources for redundant network connections and requests
Alternative flow
Exception flow
  • At step 4 if the instruction cannot pass the validation, the user would not get the "successfully finalized" status; instead, he/she will get the "invalid instruction" status.
  • At step 4 if the network is in "bad" condition, the user would get the "successfully finalized" status eventually, when the network will return in a "good" state.


Use case title
[FR0106] Creation of the multi-signature account in the Iroha network
Status

Status
colourYellow
titlediscuss

Preconditions

Use case flow


Postconditions
Alternative flow
Exception flow


Use case title
[FR0107] Changing quorum for the multi-signature account
Status

Status
colourYellow
titlediscuss

Preconditions

Use case flow


Postconditions
Alternative flow
Exception flow


Use case title
[FR0108] Changing list of signatories for the multi-signature account
Status

Status
colourYellow
titlediscuss

Preconditions
  • The user has permissions to change the list of signatories to the required account
  • The user has key pair for adding/deleting a signatory to/from the selected account

Use case flow

  1. The user prepares the instruction of adding/deleting signatories for sending
  2. The user sends the transaction with the instruction to the Iroha peer (<<include>> FR0100)
  3. The user receives the response from the Iroha peer
Postconditions
  • List of signatories for the selected account was changed correspondingly
Alternative flowN/A
Exception flow
  • On step 2, if the signatory with the current key pair exists in the list of signatories in the target account, the Iroha peer will return "already added" error status; use case flow stops.


Use case title
[FR0109] Signing multi-signature transaction
Status

Status
colourYellow
titlediscuss

Preconditions
  • There is a multi-signature account in the Iroha network
  • The user has access to the one or many key pairs for the multi-signature account
  • The current amount of signatures to the multi-signature transaction is lower than a current quorum value

Use case flow

  1. The user obtains the current list of pending transactions (<<include>> FR0203)
  2. The user finds the required transaction that can be signed by his/her signatures
  3. The user signs required transaction using the available key pair by calling the corresponding method from CLI or client SDK
  4. The user sends signed transaction to the Iroha peer (<<include>> FR0100)
Postconditions
  • Amount of signatures in the signed instruction increased by 1 signature
  • Signed instruction disappears from the list of pending instructions for the current user's account
Alternative flow
  • On step 2 the user can select more than one transactions, all of them can be sent on step 4 as a separate requests
  • On step 3 the user can sign the transaction by more than one signature, and all of them can be sent as a single request per single transaction on step 42 ideology of Iroha1 when creation of same transaction which already exists will result in addition of signature to this transation in pending state. This reduces need to perform queries and search for transactions needed to be signed. For bridge functionality that is a prefered flow, because all bridge instances will already know about how to form a transaction from the bridge consensus. And only malicious bridge peers will send wrongly formed transaction what is expected.
  • On step 3 the user can sign the transaction by more than one signature, and all of them can be sent as a single request per single transaction on step 4. In bridge implementation scenario is: 1. Selected bridge get all bridge instances signatures from the block and calls an Iroha2 ISI with the transfer information, attaching all bridge nodes signatures. It can be implemented as in Iroha1 by sending multple ISI calls in one transaction or batch, or it can be implemented as One ISI call with multiple signatures.
Exception flow
  • On step 1, in case of the empty list of pending transactions, the Iroha peer will return corresponding status and the use case flow stops
  • On step 3, if the user uses key pair, which was already used for signing the transaction, the CLI/SDK will return corresponding error status; use case flow stops if there are no more available key pairs. 
    Status
    colourYellow
    titleTBD
     (define, will it be available to do on the client-side?)


Use case title
[FR0110] Changing the conditions for the multi-signature account
Status

Status
colourYellow
titlediscuss

Preconditions
  • The user has permissions to change the conditions for the target multi-signature account

Use case flow

  1. The user requests the list of currently configured conditions for the target multi-signature account
  2. The user prepared the instruction with the list of conditions to be added/removed
  3. The user sends the transaction with the instruction to the Iroha peer (<<include>> FR0100)
  4. The Iroha peer sends the response to the user
Postconditions
  • The list of conditions for the target multi-signature account was changed correspondingly
Alternative flow
Exception flow


Acquiring data from the Iroha network by queries

Use case title
[FR0200] Acquiring data from the Iroha network by query
Status

Status
colourYellow
titlediscuss

Preconditions

Use case flow


Postconditions
Alternative flow
Exception flow


Use case title
[FR0201] Acquiring the information about the selected account
Status

Status
colourYellow
titlediscuss

Preconditions

Use case flow


Postconditions
Alternative flow
Exception flow


Use case title
[FR0202] Acquiring of the current permissions for the selected account
Status

Status
colourYellow
titlediscuss

Preconditions

Use case flow


Postconditions
Alternative flow
Exception flow


Use case title
[FR0203] Acquiring a list of pending multi-signature instructions
Status

Status
colourYellow
titlediscuss

Preconditions
  • The user has permissions to request the list of pending transactions

Use case flow

  1. The user prepares query for requesting the list of the pending transaction
  2. The user sends the query to the Iroha peer (<<include>> FR0200)
  3. The user receives the list of currently pending multi-signature transaction  
    Status
    colourYellow
    titleTBD
     (should the Iroha expose all pending transactions, or we need to add the account ID / public key to filter the request?)
Postconditions
  • The user has the list of currently pending instructions
Alternative flowN/A
Exception flow
  • On step 3, if there are no currently pending transactions, the Iroha peer will return "empty response" status


Use case title
[FR0204] Acquiring a list of current conditions for a multi-signature account
Status

Status
colourYellow
titlediscuss

Preconditions
  • The user has permissions to request a list of conditions to the target multi-signature account

Use case flow

  1. The user prepares query for requesting a list of currently configured conditions of signing for the target multi-signature account
  2. The user sends the query to the Iroha peer (<<include>> FR0200)
  3. The user receives the list of currently configured conditions of signing for the target multi-signature account
Postconditions
  • The user received the list of conditions for the target account
Alternative flowN/A
Exception flow
  • On step 3, if there are no currently configured conditions, the Iroha peer will return "empty response" status
  • On step 3, if the account is not multi-signature, the Iroha peer will return "not applicable" status


Use case title
[FR0205] Acquiring a block by its number
Status

Status
colourYellow
titlediscuss

Preconditions
  • The user has permissions to request the block by its number

Use case flow

  1. The user prepares query for requesting the i-th block
  2. The user sends the query to the Iroha peer (<<include>> FR0200)
  3. The user receives the block description with all its' transactions etc
Postconditions
  • The user has the i-th block
Alternative flowN/A
Exception flow
  • On step 3, if there are no block specified, the Iroha peer will return "error/no such block" response


Use case title
[FR0206] Acquiring blocks subscription (can be extended with a start block number index)
Status

Status
colourYellow
titlediscuss

Preconditions
  • The user has permissions to request blocks (subscription, can be separate permission or from <<include>> FR0205)

Use case flow

  1. The user prepares query for subscription for blocks
  2. The user sends the query to the Iroha peer (<<include>> FR0200)
  3. The user gets the connection to receive blocks within initialized 
Postconditions
  • The user has got stable blocks perception channel and newly arriving blocks
Alternative flowN/A
Exception flowN/A


Use case title
[FR0207] Acquiring pending transactions subscription
Status

Status
colourYellow
titlediscuss

Preconditions
  • The user has permissions to request the list of pending transactions (subscription, can be separate permission or from <<include>> FR0203)

Use case flow

  1. The user prepares query for subscription for pending transactions
  2. The user sends the query to the Iroha peer (<<include>> FR0200)
  3. The user gets the connection to receive pending transactions within initialized 
Postconditions
  • The user has got stable pending transactions perception channel and newly arriving pending transactions
Alternative flowN/A
Exception flowN/A


Use case title
[FR0208] Subscribing on the query results
Status

Status
colourYellow
titlediscuss

Preconditions
  • The user has permissions to get results of the target query

Use case flow

  1. The user prepares request data for the target query
  2. The user establishes permanent connection to the Iroha peer and provides the query request
  3. The Iroha peer confirms the connection and start sending updates on the query results until user closes the connection
  4. The user receives the results and performs continuous analysis of the payload
Postconditions
  • The user has continuous results of query execution
Alternative flow
Exception flow
  • On step 3, if the Iroha peer experiences issues with the network connection to other peers, the flow of results may be unplugged 
    Status
    colourYellow
    titleTBD
  • On step 3, if the user experiences issues with the network connection to the Iroha peer, the flow of results will be interrupted
  • On step 3, if the user experiences issues with the network connection to the Iroha peer, the flow of results will be interrupted


Use case title
[FR0209] Validate result of the query
Status

Status
colourYellow
titlediscuss

Preconditions
  • The user has permissions to get results of the target query

Use case flow

  1. The user prepares request data for the target query
  2. The user establishes permanent connection to the Iroha peer and provides the query request
  3. Iroha peer returns response containing result of the query as well as the merkle proof of its inclusion to the latest WSV
Postconditions
  • The user has result of the query request with merkle proof of its validity
Alternative flow
Exception flow



Use case title
[FR0210] Query old Iroha state (i.e. query balance month ago)
Status

Status
colourYellow
titlediscuss

Preconditions
  • The user has permissions to get results of the target query

Use case flow

  1. The user prepares request data for the target query
  2. The user establishes permanent connection to the Iroha peer and provides the query request
  3. Besides query params user provides date or block number corresponding to the state being queried
  4. Iroha peer reconstructs state for provided date or block
  5. Iroha peer returns response containing result of the query
Postconditions
  • The user has result of the query
Alternative flow
Exception flow


Non-functional requirements


Questions

Below is a list of questions to be addressed as a result of this requirements document:

QuestionOutcome

Not Doing