Umbrella `iroha` CLI

[nxsaken]

Would it be better for UX to have a single iroha binary that contains all needed functionality, each gated behind features? Right now we have iroha and irohad as the main binaries, but also iroha_swarm, kagami, kura_inspector, iroha_wasm_builder, iroha_wasm_test_runner, parity_scale_cli. As a user, this feels clunky, I'd rather have everything accessible through the iroha binary.

# spawns irohad (features = ["peer"])
iroha serve ...

# kagami (features = ["kagami"])
iroha keygen ...
iroha schema
iroha genesis generate ...
iroha genesis sign ...

# client commands (features = ["client"])
iroha register domain ...
iroha register account ...
iroha transfer domain ...

# kura inspector (features = ["inspector"])
iroha inspect ...

# wasm stuff (features = ["wasm"])
iroha wasm check ...
iroha wasm build ...
iroha wasm test ...

# swarm (features = ["swarm"])
iroha swarm ...

# parity scale codec (features = ["codec"])
iroha codec types
iroha codec json-to-scale ...
iroha codec scale-to-json ...
iroha codec scale-to-rust ...

[mversic]

I don't think iroha should be mixed with irohad. It's very common to keep this separate if nothing then because irohad would bloat iroha client which should be lightweight

[nxsaken]

We could keep them separate and spawn irohad from the CLI.

[mversic]

as for the others that you've listed I'm not sure. They are helper tools. Most of them are not for end users but for devs. Many of them shouldn't even be published as crates. We need to consider each separately:

1. iroha_wasm_test_runner/iroha_swarm/kura_inspector should most certainly not be part of iroha cli or published. These are tools exclusively for internal development of iroha
2. parity_scale_cli (if we rename it) can be considered only because it helps one to translate between scale and json encodings of iroha data model structs. Could help 3rd parties to integrate with iroha. This is for developers but not internal
3. kagami and iroha_wasm_builder are helper tools for users of iroha and as such we can consider to integrate with iroha cli

[mversic]

We could keep them separate and spawn irohad from the CLI.

you mean to keep it as it is right now?

[nxsaken]

I think it’s simpler to treat all tools as first-class citizens rather than special-casing them. Since everything can be feature-gated anyway, why not provide this flexibility to users (who are likely to double as developers)? This approach makes it easier to use, avoids polluting the system with multiple binaries that need to be tracked, and ensures consistency across Iroha development-wise by maintaining a single CLI.

There are strong precedents for this, such as Git and Cargo, which orchestrate multiple binaries under the same umbrella CLI.

you mean to keep it as it is right now?

Right now, users have to install irohad separately and launch it directly. We can have irohad as a separate binary, while also allowing iroha to launch it if it’s installed/feature-gate-enabled. It’s worth researching how e.g. cargo subcommands handle this, but I believe this approach would provide a more streamlined user experience.

[mversic]

we are in a disagreement. I'm very much against unifying iroha and irohad. I'm also against integrating dev tools into iroha cli and polluting feature space. On others I'm willing to explore compromise

This approach makes it easier to use, avoids polluting the system with multiple binaries that need to be tracked, and ensures consistency across Iroha development-wise by maintaining a single CLI.

I can't say I understand this argument, but you can make all dev tools into a single binary

There are strong precedents for this, such as Git and Cargo, which orchestrate multiple binaries under the same umbrella CLI.

there are strong precedents for the other case like mysql vs mysqld or psql vs postgres

[mversic]

also having features is nice for libraries, but not so nice for making binaries. Laymen end users don't appreciate having to recompile code, they just want to download binaries and run with it

[0x009922]

I very much like the idea of unification! Maybe just slightly differently.

My idea is to make iroha the main server, and kagami - its universal client-side tool. You know, kagami means a mirror, and it makes sense to be a tool that encompasses a wide range of interactions with Iroha from client-side, to be a single Iroha reflecting surface. So, I would like to move everything listed (+ the squash tool?) into kagami.

I believe it is going to be a better UX not only because everything is in a single place, but also because the CLI structure/inputs/outputs will be consistent among all its subcommands.

As for the CLI structure, I would like to combine schema and codec in a single subcommand. I am also not sure how to deal with that "client" subcommands needs extra configuration, maybe even via a file - unlike the other subcommands. Though structure, naming etc is for later consideration.

As for feature gates, seems simple to implement and useful in some cases. E.g. in JS SDK I need only schema/encoding/genesis, and compiling the binary in CI only with these features will work faster.

[nxsaken]

My vision was to have a single command users would need to keep in mind. Having iroha and kagami sounds better than having multiple commands, but I think an experience similar to Docker or Cargo would be even better. Docker allows you to launch and connect to containers, and do Compose stuff using the same command, but different subcommands. In my mind smth like this would make Iroha a more polished, less frictional experience.

I'm sure there is a way to keep binaries separate, while also providing a singular interface to them – Cargo does that already. Maybe it's not via features, but with some sort of launcher pattern (as an option, checking at runtime if the binary that the user is trying to launch is installed, warning them, and maybe installing it for them). Research would be needed here, I don't think focusing on implementation details is very useful at this ideation stage.

[0x009922]

I think an experience similar to Docker or Cargo would be even better. Docker allows you to launch and connect to containers, and do Compose stuff using the same command, but different subcommands.

docker binary is only a client and does not control the state of the Docker daemon - it only interacts with it. Docker daemon is a separate entity, ran as a system service. Thus, I would agree with Marin that the daemon of Iroha and it's client should rather be separate binaries.

Apart from that, I share your opinion.

[nxsaken]

Yes, I agree with both of you on that. I didn't intend to argue that iroha and irohad be the same binary – I only want to let users launch irohad via iroha, which is not unheard of.

[mversic]

Yes, I agree with both of you on that. I didn't intend to argue that iroha and irohad be the same binary – I only want to let users launch irohad via iroha, which is not unheard of.

but it's unnecessary. It makes sense for docker because the user starts the deamon. With iroha only node admins will start the deamon. There is no reason to mix them into the same binary

[0x009922]

But please let's make a single binary for clients. It will simplify documentation and UX sooo much.

[mversic]

iroha and irohad are to remain separate

But please let's make a single binary for clients

can you explain what goes into it? what clients use that is not already in the client library? maybe kagami? everything else that we have are dev tools (which we can also put into client, but I personally wouldn't)

[0x009922]

can you explain what goes into it? what clients use that is not already in the client library? maybe kagami? everything else that we have are dev tools (which we can also put into client, but I personally wouldn't)

Mostly as outlined by @nxsaken: client interactions + all kagami + schema & conversions (useful for scripting) + swarm. I am not sure about wasm_builder and kura_inspector, though they are lightweight and having a single tool is convenient - it unifies developer experience.

[mversic]

Analysis

iroha_swarm

• shouldn't be unified with iroha since it's only used by the CI. Nobody will ever use this tool otherwise

kura_inspector

• IMO also shouldn't be unified. Also why is it not name iroha_kura_inspector?

iroha_wasm_builder

• not sure, but could be unified with iroha IMO. It could be a convenient tool for Iroha users

iroha_kagami

• crypto and genesis should be unified with iroha because they are used relatively often when setting up Iroha
• schema must not be unified under any circumstance because it depends on iroha_schema_gen which activates transparent_api feature. This will pollute iroha for all clients

iroha_codec

• cannot be unified with iroha for the same reason as iroha_kagami --schema can't

Recommendation

1. unify with iroha (things used for setting up and running iroha)

• iroha_kagami --crypto
• iroha_kagami --genesis

2. unify with iroha_kagami (things only used for development)

• kura_inspector
• iroha_swarm
• iroha_codec

3. unify iroha_wasm_builder with iroha or iroha_kagami

[0x009922]

• schema must not be unified under any circumstance because it depends on iroha_schema_gen which activates transparent_api feature. This will pollute iroha for all clients

This argument comes from implementation details and not from the users convenience perspective.

Schema and codec give a way to interact with Iroha from environment where SDK isn't supported. For example, one would be able to use crypto and codec tools to create and sign transactions and queries by using JSON format.

There must be ways to avoid enabling of transparent_api feature, e.g. generate schema as a build artifact of build.rs.

iroha_swarm

* shouldn't be unified with `iroha` since it's only used by the CI. Nobody will ever use this tool otherwise

It was intended as a tool for end-users as well, to generate compose files with various parameters.

[nxsaken]

iroha_kura_inspector

How about iroha_inspector?

[dmitrivenger]

@mversic someone should be assigned here

[mversic]

• schema must not be unified under any circumstance because it depends on iroha_schema_gen which activates transparent_api feature. This will pollute iroha for all clients

This argument comes from implementation details and not from the users convenience perspective.

Wherever the argument comes from it still needs to be accounted for. However, my argument was not correct, by unifying some crates transparent_api will get enabled iroha cli and not in iroha client. So long as we keep dependencies of the 2 crates separate it's fine to unify anything into iroha cli

Schema and codec give a way to interact with Iroha from environment where SDK isn't supported. For example, one would be able to use crypto and codec tools to create and sign transactions and queries by using JSON format.

true, that was the reason we introduced json api into iroha codec. However, this would be an advanced use case. That being said, I don't really see a case for unifying iroha schema

It was intended as a tool for end-users as well, to generate compose files with various parameters.

yeah, nobody will do that. I'd bet people would prefer to edit compose files manually. This seems niche and only of use for people who repeatedly make deployments. End users will deploy once and forget about this stuff. Only our CI and test infra deploy iroha repeatedly. If there are real examples of users using this only then would I consider unifying it

[aoyako]

Some notes from a fresh perspective:

1. For iroha: The documentation clearly defines its function:

"Iroha Client CLI is a 'thin' wrapper around functionality exposed in the iroha crate."

Additionally, as mentioned:

'client' subcommands need extra configuration.

If kagami functionality is merged, it would mean that a configuration file must be provided to a tool that is supposed to generate this configuration (or its parts). Leaving the configuration mandatory for a subset of commands will only make things more confusing, in my opinion.

2. For kagami:

• kagami should be renamed to iroha_kagami and reorganized.
• Combine iroha_kagami --schema and iroha_codec under a subcommand (e.g., codec).
• Add the following as new subcommand:
  • iroha_kura_inspector
  • iroha_wasm_builder
  • iroha_swarm

As a result: irohad and iroha will remain focused as a simple daemon/client. iroha_kagami will act as a Swiss Army knife for all other purposes. The last three subcommands in iroha_kagami will be first-level subcommands, so most users can safely ignore them unless needed. While the binary size will be large, users with everything set up from a previous version will not need to recompile iroha_kagami every time.

I would appreciate some feedback on this.

[0x009922]

After re-reading this thread, I would suggest the following structure:

# peer daemon
irohad

# dev tools
iroha codec 〈types|json-to-scale|scale-to-json|scale-to-rust〉
iroha wasm 〈check|build|test〉
iroha kura 〈print〉
iroha keygen
iroha genesis 〈sign|generate〉

# client: either nest the existing ones
iroha client 〈domain|account|asset|peer|events|wasm|blocks|json|multisig〉

# or (better IMO): rearrange them by actions
iroha submit -c client.toml〈json|wasm|register|mint|...other isi〉
iroha query -c client.toml〈json|domains|accounts|...other queries〉
iroha stream -c client.toml 〈events|blocks〉

# Separate binaries:

iroha_swarm

I see the concern with confusing configuration when client/dev tools are mixed in the same binary. Maybe it wouldn't be problematic if we require --config (-c) only for the client-specific subcommands. IMO, it would be significantly more problematic to have more than 1 binary for users/devs needs. It's worth to have just iroha that does all necessary stuff.

While the binary size will be large, users with everything set up from a previous version will not need to recompile iroha_kagami every time.

Binary size is not a concern at this point + we don't have data to support whether it's really that large or not.

[s8sato]

I'd personally stand for this and this design. What if we imagine users for each binary like this:

• irohad for node operators
• iroha for account owners, assuming equivalent functionality is provided for mobile clients
• kagami (?) for developers, including users who develop wasm executables