Description
openedon Mar 7, 2023
Summary
Define how to handle SIGN_MODE_TEXTUAL spec updates.
Problem Definition
We allow SIGN_MODE_TEXTUAL's spec to be updated, as state-machine-breaking changes. However, we need to define how to coordinate these updates between node and clients.
Take an example: imagine SDK v0.48 uses SIGN_MODE_TEXTUAL v1 (current spec), but v0.49 uses v2 (small value renderer formatting change). If a JS client uses v1 to generate to sign doc and the signature, and sends to a v2 node (or vice versa), then we'll get the usual hard-to-debug message:
signature verification failed; verify nonce, acct num and chain id.
Find a solution that:
- Allows coordination between clients and node on which spec version to use
- Allows easy debugging of failed signatures
Proposal
During yesterday's Textual sync, multiple solutions were discussed:
- Proposals 1a and 1b: put the version info in the Tx itself
- Proposals 2a and 2b: put the version info into the Textual SignDoc
➡️ Proposal 1a: Use SIGN_MODE_TEXTUAL_V{N}
Create a new sign mode with a version suffix each time there's a spec change. The first one can be SIGN_MODE_TEXTUAL
, but subsequent ones are _V2
etc.
- Pros:
- solves 1 & 2 in the easiest possible way
- Cons:
- multiple Textual sign modes, slight code duplication
In this case, we should also probably disallow one node being able to activate two different SIGN_MODE_TEXTUAL versions at the same time.
➡️ Proposal 1b: Add a new field in the Tx
struct
Similar to Proposal 1a, but put the version somewhere else in the Tx, e.g.
message Single {
// mode is the signing mode of the single signer
cosmos.tx.signing.v1beta1.SignMode mode = 1;
+ // Additional info for the sign mode
+ string additional_info = 2;
}
- Pros:
- solves 1 & 2
- we keep one single
SIGN_MODE_TEXTUAL
enum - backwards compatible
- Cons:
- modification of the Tx struct
➡️ Proposal 2a: Put the version in the Textual sign doc (not shown to user)
After #15282, Textual's sign doc is the CBOR encoding of:
type SignDoc struct {
screens []Screen
}
it would be easy to add a version uint64
field there.
- Pros:
- solves 2, debuggability is slightly worse than 1a and 1b, but still doable
- one SIGN_MODE_TEXTUAL enum
- Cons:
- problem 1 needs a separate solution, though should be easy to implement (e.g. a simple mapping SDK version <-> Textual spec Version should suffice for JS clients, or in the future, a gRPC endpoint).
➡️ Proposal 2b: Show the spec version as an expert screen
Same as 2b, but put the spec version in one of the Ledger screens (expert mode only).
- Pros:
- slight improvement over 2a's debuggability
- Cons:
- additional screen