github.com/cosmos/cosmos-sdk@v0.50.10/docs/architecture/adr-050-sign-mode-textual-annex2.md (about)

     1  # ADR 050: SIGN_MODE_TEXTUAL: Annex 2 XXX
     2  
     3  ## Changelog
     4  
     5  * Oct 3, 2022: Initial Draft
     6  
     7  ## Status
     8  
     9  DRAFT
    10  
    11  ## Abstract
    12  
    13  This annex provides normative guidance on how devices should render a
    14  `SIGN_MODE_TEXTUAL` document.
    15  
    16  ## Context
    17  
    18  `SIGN_MODE_TEXTUAL` allows a legible version of a transaction to be signed
    19  on a hardware security device, such as a Ledger. Early versions of the
    20  design rendered transactions directly to lines of ASCII text, but this
    21  proved awkward from its in-band signaling, and for the need to display
    22  Unicode text within the transaction.
    23  
    24  ## Decision
    25  
    26  `SIGN_MODE_TEXTUAL` renders to an abstract representation, leaving it
    27  up to device-specific software how to present this representation given the
    28  capabilities, limitations, and conventions of the deivce.
    29  
    30  We offer the following normative guidance:
    31  
    32  1. The presentation should be as legible as possible to the user, given
    33  the capabilities of the device. If legibility could be sacrificed for other
    34  properties, we would recommend just using some other signing mode.
    35  Legibility should focus on the common case - it is okay for unusual cases
    36  to be less legible.
    37  
    38  2. The presentation should be invertible if possible without substantial
    39  sacrifice of legibility.  Any change to the rendered data should result
    40  in a visible change to the presentation. This extends the integrity of the
    41  signing to user-visible presentation.
    42  
    43  3. The presentation should follow normal conventions of the device,
    44  without sacrificing legibility or invertibility.
    45  
    46  As an illustration of these principles, here is an example algorithm
    47  for presentation on a device which can display a single 80-character
    48  line of printable ASCII characters:
    49  
    50  * The presentation is broken into lines, and each line is presented in
    51  sequence, with user controls for going forward or backward a line.
    52  
    53  * Expert mode screens are only presented if the device is in expert mode.
    54  
    55  * Each line of the screen starts with a number of `>` characters equal
    56  to the screen's indentation level, followed by a `+` character if this
    57  isn't the first line of the screen, followed by a space if either a
    58  `>` or a `+` has been emitted,
    59  or if this header is followed by a `>`, `+`, or space.
    60  
    61  * If the line ends with whitespace or an `@` character, an additional `@`
    62  character is appended to the line.
    63  
    64  * The following ASCII control characters or backslash (`\`) are converted
    65  to a backslash followed by a letter code, in the manner of string literals
    66  in many languages:
    67  
    68      * a: U+0007 alert or bell
    69      * b: U+0008 backspace
    70      * f: U+000C form feed
    71      * n: U+000A line feed
    72      * r: U+000D carriage return
    73      * t: U+0009 horizontal tab
    74      * v: U+000B vertical tab
    75      * `\`: U+005C backslash
    76  
    77  * All other ASCII control characters, plus non-ASCII Unicode code points,
    78  are shown as either:
    79  
    80      * `\u` followed by 4 uppercase hex chacters for code points
    81      in the basic multilingual plane (BMP).
    82  
    83      * `\U` followed by 8 uppercase hex characters for other code points.
    84  
    85  * The screen will be broken into multiple lines to fit the 80-character
    86  limit, considering the above transformations in a way that attempts to
    87  minimize the number of lines generated. Expanded control or Unicode characters
    88  are never split across lines.
    89  
    90  Example output:
    91  
    92  ```
    93  An introductory line.
    94  key1: 123456
    95  key2: a string that ends in whitespace   @
    96  key3: a string that ends in  a single ampersand - @@
    97   >tricky key4<: note the leading space in the presentation
    98  introducing an aggregate
    99  > key5: false
   100  > key6: a very long line of text, please co\u00F6perate and break into
   101  >+  multiple lines.
   102  > Can we do further nesting?
   103  >> You bet we can!
   104  ```
   105  
   106  The inverse mapping gives us the only input which could have
   107  generated this output (JSON notation for string data):
   108  
   109  ```
   110  Indent  Text
   111  ------  ----
   112  0       "An introductory line."
   113  0       "key1: 123456"
   114  0       "key2: a string that ends in whitespace   "
   115  0       "key3: a string that ends in  a single ampersand - @"
   116  0       ">tricky key4<: note the leading space in the presentation"
   117  0       "introducing an aggregate"
   118  1       "key5: false"
   119  1       "key6: a very long line of text, please coöperate and break into multiple lines."
   120  1       "Can we do further nesting?"
   121  2       "You bet we can!"
   122  ```