mukan-sdk/docs/architecture/adr-050-sign-mode-textual-annex2.md

# 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 device, 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 indentation 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, an additional `@`
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!"
```