LaconicNetwork/cosmos-sdk
7
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 2 Wiki Activity

docs(adr): Add Textual SpecVersion (#15270)

Browse Source
This commit is contained in:
Amaury 2023-03-20 16:56:26 +01:00 committed by GitHub
parent 897ef64712
commit a8dceddad9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 27 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
docs/architecture/adr-050-sign-mode-textual.md
View File

@ -12,13 +12,16 @@
* Dec 01, 2022: Link to examples in separate JSON file.
* Dec 06, 2022: Re-ordering of envelope screens.
* Dec 14, 2022: Mention exceptions for invertability.
* Jan 23, 2022: Switch Screen.Text to Title+Content.
* Jan 23, 2023: Switch Screen.Text to Title+Content.
* Mar 07, 2023: Change SignDoc from array to struct containing array.
* Mar 20, 2023: Introduce a spec version initialized to 0.
## Status
Accepted. Implementation started. Small value renderers details still need to be polished.
Spec version: 0.
## Abstract
This ADR specifies SIGN_MODE_TEXTUAL, a new string-based sign mode that is targetted at signing with hardware devices.
@ -300,6 +303,21 @@ By including this hash in the SIGN_MODE_TEXTUAL signing payload, we keep the sam
These bytes are only shown in expert mode, hence the leading `*`.
## Updates to the current specification
The current specification is not set in stone, and future iterations are to be expected. We distinguish two categories of updates to this specification:
1. Updates that require changes of the hardware device embedded application.
2. Updates that only modify the envelope and the value renderers.
Updates in the 1st category include changes of the `Screen` struct or its corresponding CBOR encoding. This type of updates require a modification of the hardware signer application, to be able to decode and parse the new types. Backwards-compatibility must also be guaranteed, so that the new hardware application works with existing versions of the SDK. These updates require the coordination of multiple parties: SDK developers, hardware application developers (currently: Zondax), and client-side developers (e.g. CosmJS). Furthermore, a new submission of the hardware device application may be necessary, which, dependending on the vendor, can take some time. As such, we recommend to avoid this type of updates as much as possible.
Updates in the 2nd category include changes to any of the value renderers or to the transaction envelope. For example, the ordering of fields in the envelope can be swapped, or the timestamp formatting can be modified. Since SIGN_MODE_TEXTUAL sends `Screen`s to the hardware device, this type of change do not need a hardware wallet application update. They are however state-machine-breaking, and must be documented as such. They require the coordination of SDK developers with client-side developers (e.g. CosmJS), so that the updates are released on both sides close to each other in time.
We define a spec version, which is an integer that must be incremented on each update of either category. This spec version will be exposed by the SDK's implementation, and can be communicated to clients. For example, SDK v0.48 might use the spec version 1, and SDK v0.49 might use 2; thanks to this versioning, clients can know how to craft SIGN_MODE_TEXTUAL transactions based on the target SDK version.
The current spec version is defined in the "Status" section, on the top of this document. It is initialized to `0` to allow flexibility in choosing how to define future versions, as it would allow adding a field either in the SignDoc Go struct or in Protobuf in a backwards-compatible way.
## Additional Formatting by the Hardware Device
See [annex 2](./adr-050-sign-mode-textual-annex2.md).

8
x/tx/signing/textual/handler.go
View File

@ -22,6 +22,8 @@ import (
"cosmossdk.io/x/tx/signing/textual/internal/textualpb"
)
const specVersion = 0
// CoinMetadataQueryFn defines a function that queries state for the coin denom
// metadata. It is meant to be passed as an argument into `NewSignModeHandler`.
type CoinMetadataQueryFn func(ctx context.Context, denom string) (*bankv1beta1.Metadata, error)
@ -85,6 +87,12 @@ func NewSignModeHandler(o SignModeOptions) (*SignModeHandler, error) {
return t, nil
}
// SpecVersion returns the spec version this SignModeHandler implementation
// is following.
func (r *SignModeHandler) SpecVersion() uint64 {
return specVersion
}
// GetFieldValueRenderer returns the value renderer for the given FieldDescriptor.
func (r *SignModeHandler) GetFieldValueRenderer(fd protoreflect.FieldDescriptor) (ValueRenderer, error) {
switch {