/
Iroha Configuration

Iroha Configuration

Apr 13, 2021

Status

 In progress 

Stakeholders

@武宮誠 @Vadim Reutskiy @Andrei Lebedev @Iurii Vinogradov

Outcome

Due date

Sep 11, 2020 

Owner

@Nikita Puzankov

Background

Iroha has a lot of configuration options, such as `TORII_URL` for client and peer-side web addresses, `BLOCK_STORE_PATH` for path to the blockstore in the OS and `TRANSACTION_RECEIPT_TIME` for peer-to-peer messaging timeouts.

All this parameters should be configured and a lot of them should have an ability to be changed in runtime.

Problem

The problem is to define a concept for Iroha Configuration management. Because parameters differ in their aim, ability to be managed during runtime and other aspects, we may need to have different mechanism for their management which in turn will bring additional complexity to our solution. To keep it simple we need to have a minimum options and differences in it.

To find such a solution we need to make a list of possible configurations first:

  • Public and Private keys of Iroha Peer

  • Kura configuration:

    • Kura Mode (strict or fast)

    • Block Store Path

  • Sumeragi configuration:

    • Peer Id

    • Block Time

    • List of Trusted Peers

    • Maximum Amount of Faulty Peers

    • Commit Time

    • Transaction Receipt Time

  • Torii configuration

    • Client-side URL

    • Peer-side URL

    • Maintenance URL

  • Block synchronization configuration:

    • Gossip Period

    • Batch Size

  • Queue configuration:

    • Maximum transactions in block

    • Transactions time to live

  • Logger configuration:

    • Maximum Logging Level

    • Terminal Color Enabled

    • Date Time Format

  • Initial configuration is out-of-scope because will be solved in Genesis Block and Network Setup

Documentation for configuration can be found here.

Now we can analyze each parameter with several criterias:

Parameter

Possible Values

Default Value

Should it be synchronized between Peers

Should it pass consensus

Can it be applied without restart

Will it affect clients

block_sync.batch_size

unsigned 32 bit integer

4

Yes?

Yes

Yes

No

block_sync.gossip_period

unsigned 128 bit integer

10_000

Yes

Yes

Yes

No

kura.block_store_path

Valid Unix path

"./blocks"

No

No

With additional development

No

kura.init_mode

strict/fast

strict

No

No

With additional development

No

logger.max_log_level

TRACE/INFO/DEBUG/WARN/ERROR

DEBUG

No

No

Yes

No

key_pair

Valid Key Hash

 

No

No

Yes

Yes

queue.maximum_transactions_in_block

unsigned 32 bit integer

8192

Yes

Yes

Yes

No

queue.maximum_transactions_in_queue

unsigned 32 bit integer

65536

 

 

Yes

 

queue.transaction_time_to_live

unsigned 128 bit integer

86400000(ms)

Yes

Yes

Yes

No

sumeragi.block_time

unsigned 128 bit integer

1000(ms)

Yes

Yes

Yes

No

sumeragi.commit_time

unsigned 128 bit integer

1000(ms)

Yes

Yes

Yes

No

sumeragi.max_faulty_peers

unsigned 32 bit integer

0

Yes

Yes

Yes

No

sumeragi.max_instruction_number_per_tx

unsigned 32 bit integer

4096

Yes

 

Yes

 

sumeragi.n_topology_shifts_before_reshuffle

unsigned 32 bit integer

1

Yes

 

Yes

 

sumeragi.peer_id

Valid URL + Key Hash

 

Yes (Other Peers should update old Id to the new one)

No

With additional development

Yes

sumeragi.trusted_peers

Valid URL + Key Hash

[]

Yes

Yes

Yes

No

sumeragi.tx_receipt_time

unsigned 128 bit integer

200(ms)

Yes

Yes

Yes

No

torii.api_url

Valid URL

"127.0.0.1:8080"

No

No

 

Yes

torii.max_instruction_number

unsigned 32 bit integer

4096

 

 

Yes

 

torii.max_sumeragi_message_size

unsigned 32 bit integer

16384000

 

 

Yes

 

torii.max_transaction_size

unsigned 32 bit integer

32768

 

 

Yes

 

torii.p2p_url

Valid URL

"127.0.0.1:1337"

Yes

No

 

No

torii.Maintenance URL

Valid URL

 

No

No

 

Yes

wsv.account_metadata_limits

Byte size and UTF length

4096, 1048576

 

 

Yes

 

wsv.asset_metadata_limits

Byte size and UTF length

4096, 1048576

 

 

Yes

 

wsv.length_limits

Range

[1; 128]

 

 

Yes

 

Solution

So solution may be to use Iroha Special Instructions for management consensus dependent parameters like "Gossip Period", storing set of parameters under a Peer entity in World State View and propagating these parameters and their updates into subsystems via Iroha channels.

Parameters that can be managed without consensus can avoid usage of Iroha Special Instructions and implemented separately as API for system administrators.

Decisions

  • Split parameters into consensus dependent and maintenance related

    • Use Iroha Special Instructions for consensus related

    • Put management of other parameters under Maintenance Endpoint

  • Implement "hot reload" mechanisms in Iroha subsystems

Alternatives

  • Use Iroha Special Instructions for all parameters - brings additional set of instructions to maintain, increases load on blocks store and blocks synchronization, won't guarantee non-functional requirements from system administrators perspective (each update will take time needed to finalize block)

  • Use Maintenance Endpoint for all parameters - brings additional complexity in terms of parameters synchronization and open security related issues (who can change "Batch Size" on all Peers?)

  • Do not synchronize any parameters between Peers - may be a good option

Concerns

Lack of real use cases and strong opinions on topic from potential users gave no ability to make a really welcoming decision.

Assumptions

Maintenance Endpoint will be "unstable" during 2.0 release.

Risks

  • Solution will not cover all needs `[4;6]`

  • Requirements will be simpler than expected `[3;3]`

  • "Hot reload" mechanisms will require a lot of work `[6;7]`

Additional Information

Comments