# Sign Mode Textual

This HackMD serves as a living document to specify SIGN_MODE_TEXTUAL.

Related conversations:

- SIGN_MODE_TEXTUAL [Github issue](https://github.com/cosmos/cosmos-sdk/issues/6513), offers background & context.
- TX working group [Zenhub board](https://app.zenhub.com/workspaces/regen-network---blockchain-eng-60677630201cec0017c79548/board?epics=51193526_9557&filterLogic=any&repos=133723334,51193526,369126800&showPRs=false) and [Meeting notes](https://hackmd.io/G4mjmz7YRJ-5_rE12Y8uYQ), the SDK's group working on design & implementation.
- Slack private group (ask @amaurym)

## Specification (WIP)

We propose to have SIGN_MODE_TEXTUAL's signing payload `SignDocTextual` to be an array of strings. Each string would correspond to one "screen" on the Ledger device, with no (or little, TBD) additional formatting done by the Ledger app.

message SignDocTextual {
  repeated string screens = 1;
}

The string array MUST follow the specifications below.

### 1. Bijectivity with Protobuf transactions

The encoding and decoding operations between a Protobuf transaction (whose definition can be found [here](https://github.com/cosmos/cosmos-sdk/blob/master/proto/cosmos/tx/v1beta1/tx.proto#L13)) and the string array MUST be bijective.

We concede that bijectivity is not strictly needed. Avoiding transaction malleability only requires collision resistance on the encoding. Lossless encoding also does not require decodability. However, bijectivity assures both non-malleability and losslessness.

This also prevents users signing over hashed transaction metadata, which is a security concern for Ledger (the company).

We propose to maintain functional tests using bijectivity in the SDK to assure losslessness and the absence of malleability.

### 2. Only ASCII 32-127 characters allowed

Ledger devices have limited character display capabilities, so all strings MUST only contain ASCII characters in the 32-127 range.

In particular, the newline `"\n"` (ASCII: 10) character is forbidden.

### 3. All strings have the `<key>: <value>` format

All strings MUST match the following Regex: `TODO`.

This is helpful for UIs displaying SignDocTextual to users. This MAY be used in the Ledger app to perform custom on-screen formatting, for example to break long lines into multiple screens.

The `<value>` itself can contain the `": "` characters.

### 4. Values are encoded using Value Renderers

### 5. Strings starting with `*` are only shown in Expert mode

Ledger devices have the an Expert mode for advanced users. Strings starting with the `*` character will only be shown in Expert mode.

### 6. The string array format

Below is the general format of a TX with N msgs. Each new line corresponds to a new screen on the Ledger device. `//` denotes comments and are not shown on the Ledger device.

#### How does the envelope get rendered?

Chain ID: <string>
Account number: <uint64>
Sequence: <uint64>
This transaction has 2 messages:
Msg (1/2): bank send coins
// one or multiple lines for Msg1's content, see below for examples
Msg (2/2): governance submit proposal
// one or multiple lines for Msg2's content, see below for examples
End of messages
Fee: <coins>
*Fee payer: cosmos1abc...abc     // If fee_payer is set
*Fee granter: cosmos1abc...abc   // If fee_granter is set
Memo: some memo                 // If memo is set
*Gas Limit: 100,000                   // * means only in expert mode
*Timeout at block #5324         // If timeout_height is set
Tipper: cosmos1ghi...ghi        // If there's a tip
Tip: 1.0 atom
// If multiple signers:
*Signers:
*Signer (1/3):
*Public Key: // base64-encoded pk or hex
*Sign mode: DIRECT
*Signer (2/3):
// --snip--
End of signers

#### How does each Msg get rendered?

Msg (1/2): bank send coins
// one or multiple lines for Msg1's content, see below for examples

message MsgVote {
  uint64 proposal_id = 1;
  Vote vote = 2; 
}

Message (1/2): gov vote
Proposal Id: <uint64>
Vote: <string> // VOTE_OPTION_{ABSTAIN,YES}

### Support LEGACY_AMINO_JSON for backwards-compatbility

### Rejected ideas

- Idea: (Each string is less than `N` (TBD) characters, to avoid string streaming on the screen.)
- Hard, because Ledger chars are no monospace
- Maybe "key: value" formatting is better

## Wire Format

This string array is encoded as a single `\n`-delimited string.

## Value Renderers

These describe how values of different types should be automatically rendered.

### `number`

- Applies to `sdk.Dec`, `sdk.Int`, and other numeric types (`uint64`, etc.)
- Formatting with `,`s for every three integral digits
- Ex:
`1000` -> `1,000`
`1000000.00` -> `1,000,000.00`

TODO consider `'` as separator?

### `coin`

- Applies to `Coin`
- Denoms are converted to `display` denoms using `Metadata` (if available)
- Amounts are converted to `display` denom amounts and rendered as `number`s above
- One space between the denom and amount
- In the future, IBC denoms could maybe be converted to DID/IIDs, if we can find a robust way for doing this (ex. `cosmos:hub:atom`)
- Ex:
- `1000000000uatom` -> `1,000 atom`

### `type_url`

- all protobuf messages to be used with `SIGN_MODE_TEXTUAL` should have a short name associated with them that can be used in format strings whenever the type url is explicitly referenced (as in the `MsgRevoke` examples below).
- these could be options in a proto messages or config files

message MsgSend {
  option (cosmos.textual) {
    msg_name = "bank send coins"
  }
}

- they should be unique per message, per chain
- Ex:
- `cosmos.bank.v1beta1.MsgSend` -> `bank send coins`
- `cosmos.gov.v1beta1.MsgVote` -> `governance vote`

### Arrays

TODO

### Structs

TODO

### Enums

- String case convention: snake case to sentence case
- Allow optional annotation for textual name
- E.g `enum VoteOption`
- convert enum name (`VoteOption`) to snake_case (`VOTE_OPTION`)
- truncate that prefix + `_` from the enum name if it exists (`VOTE_OPTION_` gets stripped from `VOTE_OPTION_YES` -> `YES`)
- convert rest to sentence case: `YES` -> `Yes`
- in summary: `VOTE_OPTION_YES` -> `Yes`

### `google.protobuf.Timestamp` (TODO)

Rendered as either ISO8601 (`2021-01-01T12:00:00Z`) or a more standard English-language date format (`Jan. 1, 2021 12:00 UTC`)

### `google.protobuf.Duration` (TODO)

- rendered in terms of weeks, days, hours, minutes and seconds as these time units can be measured independently of any calendar and duration values are in seconds (so months and years can't be used precisely)
- total seconds values included at the end so users have both pieces of information
- Ex:
- `1483530 seconds` -> `2 weeks, 3 days, 4 hours, 5 minutes, 30 seconds (1483530 seconds total)`

### address bytes

We currently use `string` types in protobuf for addresses so this may not be needed, but if any address bytes are used in sign mode textual they should be rendered with bech32 formatting

## Examples

#### Example 1: Simple `MsgSend`

JSON:

{
  "body": {
    "messages": [
      {
        "@type": "/cosmos.bank.v1beta1.MsgSend",
        "from": "cosmos1...abc",
        "to": "cosmos1...def",
        "amount": [
          {
            "denom": "uatom",
            "amount": 10000000
          }
        ]
      }
    ]
  },
  "auth_info": {
    "signer_infos": [
      {
        "public_key": "iQ...==",
        "mode_info": { "single": { "mode": "SIGN_MODE_TEXTUAL" } },
        "sequence": 2
      }
    ],
    "fee": {
      "amount": [
        {
          "denom": "atom",
          "amount": 0.002
        }
      ],
      "gas_limit": 100000
    }
  },
  // Additional SignerData.
  "chain_id": "simapp-1",
  "account_number": 10
}

SIGN_MODE_TEXTUAL:

Chain ID: simapp-1
Account number: 10
*Public Key: iQ...==        // Base64 pubkey
Sequence: 2
This transaction has 1 message:
Message (1/1): bank v1beta1 send coins
From: cosmos1...abc
To: cosmos1...def
Amount: 10 atom            // Conversion from uatom to atom using value renderers
End of transaction messages
Fee: 0.002 atom
*Gas: 100'000

#### Example 2: Multi-Msg Transaction with 3 signers

#### Example 3: Legacy Multisig

#### Example 4: Fee Payer with Tips

{
  "body": {
    "messages": [
      {
        "@type": "/cosmos.bank.v1beta1.MsgSend",
        "from": "cosmos1...tipper",
        "to": "cosmos1...abc",
        "amount": [
          {
            "denom": "uatom",
            "amount": 10000000
          }
        ]
      }
    ]
  },
  "auth_info": {
    "signer_infos": [
      {
        "public_key": "iQ...==",
        "mode_info": { "single": { "mode": "SIGN_MODE_DIRECT_AUX" } },
        "sequence": 42
      },
      {
        "public_key": "iR...==",
        "mode_info": { "single": { "mode": "SIGN_MODE_TEXTUAL" } },
        "sequence": 2
      }
    ],
    "fee": {
      "amount": [
        {
          "denom": "atom",
          "amount": 0.002
        }
      ],
      "gas_limit": 100000,
      "payer": "cosmos1...feepayer"
    },
    "tip": {
      "amount": [
        {
          "denom": "ibc/CDC4587874B85BEA4FCEC3CEA5A1195139799A1FEE711A07D972537E18FDA39D",
          "amount": 200
        }
      ],
      "tipper": "cosmos1...tipper"
    }
  },
  // Additional SignerData.
  "chain_id": "simapp-1",
  "account_number": 10
}

SIGN_MODE_TEXTUAL for the feepayer:

Chain ID: simapp-1
Account number: 10
*Public Key: iR...==
Sequence: 2
This transaction has 1 message:
Message (1/1): bank v1beta1 send coins
From: cosmos1...abc
To: cosmos1...def
Amount: 10 atom
End of transaction messages
Fee: 0.002 atom
Fee Payer: cosmos1...feepayer
Tipper: cosmos1...tipper
Tip: 200 ibc/CDC4587874B85BEA4FCEC3CEA5A1195139799A1FEE711A07D972537E18FDA39D
*Gas: 100'000
*This transaction has 1 other signer:
*Signer (1/2):
*Public Key: iQ...==
*Sign mode: Direct Aux
*Sequence: 42
*End of other signers

# Aaron's Original Proposal

<details>
<summary>Click here to see original version of this hackmd</summary>

I propose using the https://mustache.github.io syntax (with `{` and `}` delimiters instead of
`{{` and `}}`) and with values pre-rendered based on their type using the value renderers below.

# Value Renderers

These describe how values of different types should be automatically rendered.

## `number`
* Applies to `sdk.Dec`, `sdk.Int`, and other numeric types (`uint64`, etc.)
* Formatting with `,`s for every three integral digits
* Ex:
`1000` -> `1,000`
`1000000.00` -> `1,000,000.00`

## `coin`
* Applies to `Coin`
* Denoms are converted to `display` denoms using `Metadata` (if available)
* Amounts are converted to `display` denom amounts and rendered as `number`s above
* One space between the denom and amount
* In the future, IBC denoms could maybe be converted to DID/IIDs, if we can find a robust way for doing this (ex. `cosmos:hub:atom`)
* Ex:
* `1000000000uatom` -> `1,000 atom`

## `google.protobuf.Timestamp`
Rendered as either ISO8601 (`2021-01-01T12:00:00Z`) or a more standard English-language date format (`Jan. 1, 2021 12:00 UTC`)

## `google.protobuf.Duration`
* rendered in terms of weeks, days, hours, minutes and seconds as these time units can be measured independently of any calendar and duration values are in seconds (so months and years can't be used precisely)
* total seconds values included at the end so users have both pieces of information
* Ex:
* `1483530 seconds` -> `2 weeks, 3 days, 4 hours, 5 minutes, 30 seconds (1483530 seconds total)`

## `type_url`
* all protobuf messages to be used with `SIGN_MODE_TEXTUAL` should have a short name associated with them that can be used in format strings whenever the type url is explicitly referenced (as in the `MsgRevoke` examples below).
* these could be options in a proto messages or config files

message MsgSend {
  option (cosmos.textual) {
    msg_name = "bank send"
  }
}

* they should be unique per message, per chain
* Ex:
* `cosmos.bank.v1beta1.MsgSend` -> `bank send`
* `cosmos.gov.v1beta1.MsgVote` -> `governance vote`

## address bytes
We currently use `string` types in protobuf for addresses so this may not be needed, but if any address bytes are used in sign mode textual they should be rendered with bech32 formatting

# Examples

These examples all use the mustache syntax with simple `{` and `}` delimiters.

## bank
### MsgSend

Send {amount} from {from} to {to}
Send 10 atom from cosmos123 to cosmos345

### MsgMultiSend

Send coins from multiple accounts:
{#inputs}
{coins} from {address}
{/inputs}
{#outputs}
{coins} from {address}
{/outputs}

## authz
### MsgGrant

On behalf of {granter}, grant {grantee} the authorization to:
{#grant}
{authorization}
{#expiration}
Expiring on {expiration}
{/expiration}
{/grant}

#### GenericAuthorization

Perform {msg} actions

#### SendAuthorization

Send up to {spend_limit}

#### StakeAuthorization

{authorization_type} up to {max_tokens} to/from one of the following validators:
{#validators}
{.}
{/validators}

### MsgExec

{grantee} performs the following delegated actions:
{msgs}

### MsgRevoke
`Revoke the authorization of {grantee} to perform {msg_type_url} operations on behalf of {granter}`

Examples:

Revoke the authorization of cosmos123 to perform any bank send actions on behalf of cosmos234
Revoke the authorization of cosmos123 to perform any governance vote actions on behalf of cosmos234

## Crisis
### MsgVerifyInvariant

{sender} verifies the {invariant_route} invariant in the {invariant_module_name} module

## Distribution
### MsgWithdrawDelegatorReward

Withdraw {delegator_address}'s delegator rewards from {validator_address}

### MsgSetWithdrawAddress

Set {delegator_address}'s delegator rewards withdraw address to {withdraw_address}

## gov
### MsgVote

{voter} votes {option} on gov proposal {proposal_id}

### MsgSubmitProposal

{proposer} proposes that on chain governance do the following {#initial_deposit}with an initial desposit of {initial_deposit}{/initial_deposit}:
{msgs}

## staking
### MsgDelegate
`Delegate {amount} from delegator {delegator_address} to {validator_address}`

## feegrant

### MsgGrantAllowance

#### BasicAllowance

Spend up to {spend_limit} on fees by {#expiration}{expiration}{/expiration}

#### PeriodicAllowance

{basic}
with the following rules:
can spend {period_spend_limit} per {duration}
with the next period starting on {period_reset}
and {period_can_spend} remaining to be spent in this period

Ex:

Spend up to 10 atom on fees by Aug. 15, 2021 12:00 UTC
with the following rules:
can spend 2 atom per 1 day
with the next period starting on Aug. 1, 2021 12:00 UTC
and 1 atom remaining to be spent in this period

</details>