> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cosmos.network/llms.txt
> Use this file to discover all available pages before exploring further.

# ADR 050: SIGN_MODE_TEXTUAL: Annex 2 XXX

> Oct 3, 2022: Initial Draft

## 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!"
```