forked from cosmos/cosmos-sdk
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: structured screens for SIGN_MODE_TEXTUAL (cosmos#13434)
## Description Refs: cosmos#11970 Changes target of `SIGN_MODE_TEXTUAL` rendering to be a structured datatype instead of lines of ASCII text. This avoids the complexities of in-band, signaling and allows more capable signing devices not to be hindered by the limitations of those less capable. --- ### Author Checklist *All items are required. Please add a note to the item if the item is not applicable and please add links to any relevant follow up issues.* I have... - [X] included the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title - [X] added `!` to the type prefix if API or client breaking change - [X] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/main/CONTRIBUTING.md#pr-targeting)) - [X] provided a link to the relevant issue or specification - [X] followed the guidelines for [building modules](https://github.com/cosmos/cosmos-sdk/blob/main/docs/building-modules) - [X] included the necessary unit and integration [tests](https://github.com/cosmos/cosmos-sdk/blob/main/CONTRIBUTING.md#testing) - [ ] added a changelog entry to `CHANGELOG.md` - [X] included comments for [documenting Go code](https://blog.golang.org/godoc) - [X] updated the relevant documentation or specification - [X] reviewed "Files changed" and left comments if necessary - [x] confirmed all CI checks have passed NOTE: changelog intentionally omitted - we'll add an entry when cosmos#11970 is complete. ### Reviewers Checklist *All items are required. Please add a note if the item is not applicable and please add your handle next to the items reviewed if you only reviewed selected items.* I have... - [ ] confirmed the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title - [ ] confirmed `!` in the type prefix if API or client breaking change - [ ] confirmed all author checklist items have been addressed - [ ] reviewed state machine logic - [ ] reviewed API design and naming - [ ] reviewed documentation is accurate - [ ] reviewed tests and test coverage - [ ] manually tested (if applicable)
- Loading branch information
Showing
16 changed files
with
312 additions
and
199 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,122 @@ | ||
# ADR 050: SIGN_MODE_TEXTUAL: Annex 2 XXX | ||
|
||
## Changelog | ||
|
||
- Oct 3, 2022: Initial Draft | ||
|
||
## Status | ||
|
||
DRAFT | ||
|
||
## Abstract | ||
|
||
This annex provides normative guidance on how devices should render a | ||
`SIGN_MODE_TEXTUAL` document. | ||
|
||
## Context | ||
|
||
`SIGN_MODE_TEXTUAL` allows a legible version of a transaction to be signed | ||
on a hardware security devices, such as a Ledger. Early versions of the | ||
design rendered transactions directly to lines of ASCII text, but this | ||
proved awkward from its in-band signaling, and for the need to display | ||
Unicode text within the transaction. | ||
|
||
## Decision | ||
|
||
`SIGN_MODE_TEXTUAL` renders to an abstract representation, leaving it | ||
up to device-specific software how to present this representation given the | ||
capabilities, limitations, and conventions of the deivce. | ||
|
||
We offer the following normative guidance: | ||
|
||
1. The presentation should be as legible as possible to the user, given | ||
the capabilities of the device. If legibility could be sacrificed for other | ||
properties, we would recommend just using some other signing mode. | ||
Legibility should focus on the common case - it is okay for unusual cases | ||
to be less legible. | ||
|
||
2. The presentation should be invertible if possible without substantial | ||
sacrifice of legibility. Any change to the rendered data should result | ||
in a visible change to the presentation. This extends the integrity of the | ||
signing to user-visible presentation. | ||
|
||
3. The presentation should follow normal conventions of the device, | ||
without sacrificing legibility or invertibility. | ||
|
||
As an illustration of these principles, here is an example algorithm | ||
for presentation on a device which can display a single 80-character | ||
line of printable ASCII characters: | ||
|
||
- The presentation is broken into lines, and each line is presented in | ||
sequence, with user controls for going forward or backward a line. | ||
|
||
- Expert mode screens are only presented if the device is in expert mode. | ||
|
||
- Each line of the screen starts with a number of `>` characters equal | ||
to the screen's indetation level, followed by a `+` character if this | ||
isn't the first line of the screen, followed by a space if either a | ||
`>` or a `+` has been emitted, | ||
or if this header is followed by a `>`, `+`, or space. | ||
|
||
- If the line ends with whitespace or an `@` character, and `@` character | ||
is appended to the line. | ||
|
||
- The following ASCII control characters or backslash (`\`) are converted | ||
to a backslash followed by a letter code, in the manner of string literals | ||
in many languages: | ||
|
||
- a: U+0007 alert or bell | ||
- b: U+0008 backspace | ||
- f: U+000C form feed | ||
- n: U+000A line feed | ||
- r: U+000D carriage return | ||
- t: U+0009 horizontal tab | ||
- v: U+000B vertical tab | ||
- `\`: U+005C backslash | ||
|
||
- All other ASCII control characters, plus non-ASCII Unicode code points, | ||
are shown as either: | ||
|
||
- `\u` followed by 4 uppercase hex chacters for code points | ||
in the basic multilingual plane (BMP). | ||
|
||
- `\U` followed by 8 uppercase hex characters for other code points. | ||
|
||
- The screen will be broken into multiple lines to fit the 80-character | ||
limit, considering the above transformations in a way that attempts to | ||
minimize the number of lines generated. Expanded control or Unicode characters | ||
are never split across lines. | ||
|
||
Example output: | ||
|
||
``` | ||
An introductory line. | ||
key1: 123456 | ||
key2: a string that ends in whitespace @ | ||
key3: a string that ends in a single ampersand - @@ | ||
>tricky key4<: note the leading space in the presentation | ||
introducing an aggregate | ||
> key5: false | ||
> key6: a very long line of text, please co\u00F6perate and break into | ||
>+ multiple lines. | ||
> Can we do further nesting? | ||
>> You bet we can! | ||
``` | ||
|
||
The inverse mapping gives us the only input which could have | ||
generated this output (JSON notation for string data): | ||
|
||
``` | ||
Indent Text | ||
------ ---- | ||
0 "An introductory line." | ||
0 "key1: 123456" | ||
0 "key2: a string that ends in whitespace " | ||
0 "key3: a string that ends in a single ampersand - @" | ||
0 ">tricky key4<: note the leading space in the presentation" | ||
0 "introducing an aggregate" | ||
1 "key5: false" | ||
1 "key6: a very long line of text, please coöperate and break into multiple lines." | ||
1 "Can we do further nesting?" | ||
2 "You bet we can!" | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.