diff --git a/.changelog/unreleased/breaking-changes/ibc-relayer-cli/594-unify-cli.md b/.changelog/unreleased/breaking-changes/ibc-relayer-cli/594-unify-cli.md new file mode 100644 index 0000000000..6cc56fec6b --- /dev/null +++ b/.changelog/unreleased/breaking-changes/ibc-relayer-cli/594-unify-cli.md @@ -0,0 +1,2 @@ +- New ADR to describe unifying CLI flags + ([#594](https://github.com/informalsystems/ibc-rs/issues/594)) \ No newline at end of file diff --git a/docs/architecture/README.md b/docs/architecture/README.md index b50a2fd3d0..d5c096abb8 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -36,3 +36,4 @@ To suggest an ADR, please make use of the [ADR template](./adr-template.md) prov | [007](./adr-007-error.md) | Error Management | Accepted | | [008](./adr-008-ics20-implementation.md) | ICS20 implementation | Accepted | | [009](./adr-009-chain-endpoint-handle-standardization.md) | ChainEndpoint and ChainHandle methods standardization | Accepted | +| [010](./adr-010-unified-cli-arguments-hermes.md) | Unified approach for CLI arguments for Hermes v1.0.0 | Proposed | diff --git a/docs/architecture/adr-010-unified-cli-arguments-hermes.md b/docs/architecture/adr-010-unified-cli-arguments-hermes.md new file mode 100644 index 0000000000..f39aea60b5 --- /dev/null +++ b/docs/architecture/adr-010-unified-cli-arguments-hermes.md @@ -0,0 +1,194 @@ +# ADR 010: Unified approach for CLI arguments for Hermes v1.0.0 + +## Changelog +* 15.06.2022: Proposed. + +## Context + +In this ADR we provide recommendations and intuitions to using flags for all the arguments of the Hermes commands. + +The problem we are trying to solve is a unified approach to CLI arguments for Hermes v1.0.0. + +## Decision + +To avoid confusion, all the parameters should take long flags. The following approach should be applied: + +* Only long flags are used in order to avoid having nonintuitive flags or conflicting flags. +* Any parameter ending with `_id` should have the `_id` removed from the flag to shorten it. For example the flag for `chain_id` should only be `chain`. +* Flags which can be shortened and still be meaningful should be shortened. This is done for `connection`, `channel` and `sequence`, which become respectively `conn`, `chan` and `seq`. +* For the channel and connection creation CLIs, the objects at the two ends are prefixed by `--a-` and `--b-`. Example `--a-chain` and `--b-chain`. +* Whenever `chain`, `conn`, `chan` and `port` flags have to be disambiguated with a specifier, the specifier will be a prefix. Example of specifiers we currently use are `host`, `reference`, `a`, `b` and `counterparty`. + +The following commands are implemented, with the binary name `hermes` often omitted: + +### Hermes global flags + +* `hermes --config ` + +* `hermes --json ` + +### Commands for clients + +* `create client --host-chain --reference-chain ` + * Optional: `[--clock-drift ] [--trust-threshold ] [--trusting-period ]` + +* `update client --host-chain --client ` + * Optional: `[--height ] [--trusted-height ]` + +* `upgrade client --host-chain --client ` + +* `upgrade clients --reference-chain ` + * Optional: `[--host-chain ]` + +### Create a connection + +* `create connection --a-chain --b-chain ` + * Optional: `[--delay ]` + +* `create connection --a-chain --a-client --b-client ` + * Optional: `[--delay ]` + +### Create a channel + +* `create channel --a-chain --a-conn --a-port --b-port ` + * Optional: `[--chan-version ] [--order ]` + +* `create channel --a-chain --b-chain --a-port --b-port --new-client-conn` + * Optional: `[--chan-version ] [--order ]` + +### Commands for keys + +* `keys add --chain --key-file --mnemonic-file ` + * Optional: `[--hd-path ] [--key-name ]` + +* `keys balance --chain ` + * Optional: `[--key-name ]` + +* `keys delete --chain --all` + +* `keys delete --chain --key-name ` + +* `keys list --chain ` + +### Listen + +* `listen --chain ` + * Optional: `[--event ]` + +### Misbehaviour + +* `misbehaviour --chain --client ` + +### Start the relayer in multi-chain mode + +* `start` + * Optional: `[--full-scan]` + +### Clear packets + +* `clear packets --chain --port --chan ` + +### Queries + +__Client__ + +* `query client connections --chain --client ` + * Optional: `[--height ]` + +* `query client consensus --chain --client ` + * Optional: `[--consensus-height ] [--height ] [--heights-only]` + +* `query client header --chain --client --consensus-height ` + * Optional: `[--height ]` + +* `query client state --chain --client ` + * Optional: `[--height ]` + +* `query clients --host-chain ` + * Optional: `[--omit-chain-ids] [--reference-chain ]` + +__Connection__ + +* `query connection channels --chain --conn ` + +* `query connection end --chain --conn ` + * Optional: `[--height ]` + +* `query connections --chain ` + * Optional: `[--chain-counterparty ] [--verbose]` + +__Channel__ + +* `query channel client --chain --port --chan ` + +* `query channel end --chain --port --chan ` + * Optional: `[--height ]` + +* `query channel full --chain --port --chan ` + * Optional: `[--height ] [--verbose]` + +* `query channels --chain ` + * Optional: `[--counterparty-chain ] [--verbose]` + +__Packet__ + +* `query packet ack --chain --port --chan --seq ` + * Optional: `[--height ]` + +* `query packet acks --chain --port --chan ` + +* `query packet commitment --chain --port --chan --seq ` + * Optional: `[--height ]` + +* `query packet commitments --chain --port --chan ` + +* `query packet pending --chain --port --chan ` + +* `query packet unreceived-acks --chain --port --chan ` + +* `query packet unreceived-packets --chain --port --chan ` + +__Tx__ + +* `query tx events --chain --hash ` + +### Shell completion + +* `completions --shell ` + +### Validate configuration file + +* `config validate` + +### Health check + +* `health-check` + +## Status + +Proposed. + +__17.06.22__ + +The following are not yet implemented: +* Optional flags for `upgrade clients`, issue [#2311](https://github.com/informalsystems/ibc-rs/issues/2311) +* Optional flags for `query connections`, issue [#2310](https://github.com/informalsystems/ibc-rs/issues/2310) +* Updating `query channel ends` to `query channel full` + +The PR which updates the flags for all the commands as described in this ADR: [#2275](https://github.com/informalsystems/ibc-rs/pull/2275) + +## Consequences + +### Positive + +* Clear parameters for Hermes commands + +### Negative + +* Breaking changes which will require updating anything using Hermes + +### Neutral + +## References + +* Proposal in issue: [#2239](https://github.com/informalsystems/ibc-rs/issues/2239) \ No newline at end of file