Deprecate available commands at root of cardano-cli

[rdlrt]

Description

The current state of cardano-cli top-level sub-commands is quite chaotic and a bit too unpredictable. While I appreciate deprecation of specific commands, what we have currently is far from desirable.

1. There are cases where for instance we have cardano-cli address available at top level. We also have cardano-cli <era> address which is deprecated, and then we have cardano-cli latest address. It seems redundant to have cardano-cli address as well as cardano-cli latest address. To make it worse, if we go and check stake address - we do NOT have cardano-cli stake-address, but cardano-cli latest stake-address works. This requires us to check for each and every object individually rather than being able to count on some consistency.
2. My first assumption given the above was atleast when we have something at root as well as latest, their sub commands will be similar, nope! Let's have a look at cardano-cli query vs cardano-cli latest query. Latter gives us a lot more options (eg: treasury, ref-script-size, conway-specific queries).
   It sounds like the options presented at root should be atleast marked as deprecated, if not - have some consistency between root and latest.

Possible Solution

Retire all duplicates and only leave available commands under latest (or at root) and move anything from previous era to compatible

[CarlosLopezDeLara]

@rdlrt Let me try to explain where we are heading:

1. CLI is in the process of dropping support of pre-conway eras. 10.2.0.0 includes a deprecation message on all pre-conway eras.
2. latest == latest era. Currently conway.
3. Top level commands are commands that do not depend on era. Therefore, these commands do not include anything that depends on conway, this explains the different options between cardano-cli query and cardano-cli latest. Also cardano-cli latest is (currently) equivalent to cardano-cli conway
4. The intuition is to make conway the default at top level, and hide the era ; we have been there, at some point we made shelley the default, but that became a problem when integrating other eras.
5. compatible is only designed to preserve the minimal compatibility necessary to deploy networks in eras earlier than conway and being able to hardfork all the way up-to conway.
6. In the near future CLI will need to support the era after conway. At that time we will have cardano-cli upcoming, at that point cardano-cli latest == cardano-cli upcomming
7. Most things at top-level have the equivalent under era, just to make it easier for muscle memory.
8. The case of cardano-cli conway stake-address is a a tricky one, one may think that should be top-level, but CDDL for stake-address changed in Conway (making it era dependent) therefore can no longer be top-level.

In conclusion, top-level is era independent, anything else that depend on era goes under era. latest == the latest era supported, this may be a future era.

[rdlrt]

Thanks for your reply.

3. Top level commands are commands that do not depend on era. Therefore, these commands do not include anything that depends on conway, this explains the different options between cardano-cli query and cardano-cli latest. Also cardano-cli latest is (currently) equivalent to cardano-cli conway

That does not fully make sense - when you're using query commands, you're already talking to node - you should not require an input from user regarding which era is to be queried (as a query from node should not return any different output).

8. The case of cardano-cli conway stake-address is a a tricky one, one may think that should be top-level, but CDDL for stake-address changed in Conway (making it era dependent) therefore can no longer be top-level.

Sure, but then perhaps address/stake-address could also move to latest|upcoming then? There is literally 0 guarantee that a future era will not introduce a change to specs for any of the existing objects - at that point, all those who need CLI will then have to make adjustments again

A. I am still not getting a clear reason as to why top-level commands are desirable (especially key, address , stake-address , governance ), the ones that involve creation of keys/address/stake-address can be changed if there is a future change in CDDL, while genesis is different for byron vs later eras.

B. Presence of query into era-specific commands does not make sense either -- could stay at root, as the query is to be made against node - which is era-aware, whether it returns response against a specific sub-command (eg: cardano-cli query gov-state) or not should be handled from root query command itself determining state from node.

Splitting these in the way they currently are (especially under top-level Legacy commands - which in itself feels like it would at some point be retired) seems very ambiguous.

[CarlosLopezDeLara]

@rdlrt

That does not fully make sense - when you're using query commands, you're already talking to node - you should not require an input from user regarding which era is to be queried (as a query from node should not return any different output).

The queries are defined in the Ledger and they depend depend on era. Those at the top level just happen to behave the same in all eras from Shelley to Conway, thus can exist at top level. There is a subset of queries that do not exist in pre-conway: the governance related queries. Those must be place under conway query

The CLI uses the Node-to-Client miniprotocol to communicate with the node, of course. The thing is, the CLI cannot make assumptions about the era on the node it is talking to. Sometimes, it may be communicating with a local cluster running in the Alonzo, or Babbage era, while other times, it might interact with a node on a network operating in the Conway era. It is the user who needs to be aware of this piece of information.

That said, you have a valid point. Perhaps we could modify the CLI so that every query first determines the era of the node it is communicating with and then performs the corresponding query parameterized by the node's reported era. I'll discuss this with the engineers to assess its feasibility...

Sure, but then perhaps address/stake-address could also move to latest|upcoming then?

These already exist under conway, i.e., conway address and conway stake-address. latest is just a synonym for whatever the most recent era we support—currently, Conway.

If a new era introduces changes to the CDDL that affect any of these commands (e.g., if the upcoming era supports a new keyType), then the behavior would differ between conway address key-gen and upcoming address key-gen. In that case, latest address key-gen would behave the same as upcoming address key-gen.

However, if the keyType does not change, the commands would remain era-independent (or preserving its behavior across all eras). In such cases, there’s no need to distinguish them by an era sub-command.

Placing address under conway (e.g., cardano-cli conway address ...) was an attempt to make it easier for users. Perhaps we're falling short in achieving that goal?

A. I am still not getting a clear reason as to why top-level commands are desirable (especially key, address , stake-address , governance):

I agree that some of these commands are not necessary at the top level. Many of these will indeed be removed or reorganized. We are in the middle of this process—pre-Conway era commands are deprecated and will soon be removed. I'm open to discussing further reorganization.

Some of them, however, are being preserved to provide backwards compatibility (i.e. node ,address) mostly for testing purposes. For example so that Test Engineering team can run tests in clusters that start all the way back in Byron or Shelley and hard-fork all the way up to Conway or later eras... If Testing decides they don't need those tests anymore then we could remove these top-level commands or perhaps move them to compatible.

B. Presence of query into era-specific commands does not make sense either -- could stay at root, as the query is to be made

Top-level commands indicate that they are "era-independent" or behave the same way across all eras. That's why there is a query command at top level, with sub-commands and options slightly different to the ones under conway query which contains queries that are specific to conway era and did not exist before, for instance, all the governance related queries, or the upcoming query ledger-peers, and so on.

We must also consider that queries and node responses require serialization and deserialization, which itself is era-dependent. Consequently, we cannot make all queries top-level.

That said, an alternative could be removing top-level queries entirely, placing them only under specific eras (i.e. compatible query, conway query) This might provide a cleaner and less confusing user experience. Along these lines, perhaps a structure like the one below would be more user-friendly, less confusing, and offer a more pleasant experience? No promises at this point—just exploring the possibilities:

Available options:
  --version                Show the cardano-cli version
  -h,--help                Show this help text

Available commands:

  hash                     Compute the hash to pass to the various --*-hash
                           arguments of commands.
  query-tip                Get the node's current tip (slot no, hash, block no, era)
  key                      Key utility commands.
  ping                     Ping a cardano node either using node-to-node or node-to-client protocol. It negotiates a handshake and keeps sending keep alive messages.
  debug                    Debug commands
  help                     Show all help
  version                  Show the cardano-cli version
  

Era commands: 
  conway                   Conway era commands
  latest                   Latest era commands (Conway)
  compatible               Limited backward compatible commands for testing
                           only.

All of this to say, that YES, we recognize you have a valid point and we are trying to improve the UI/UX, we are in the process, we just need to balance things out and consider needs from different types of users.