Sign Mode Textual

This HackMD serves as a living document to specify SIGN_MODE_TEXTUAL.

Related conversations:

• SIGN_MODE_TEXTUAL Github issue, offers background & context.
• TX working group Zenhub board and Meeting notes, 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) 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 numbers 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

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

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

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

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

Perform {msg} actions

Send up to {spend_limit}

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

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

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

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

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

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

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

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

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

{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

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