chore(connect): Add doc and more tests

vacuumlabs · Feb 5, 2024 · 55e4576 · 55e4576
1 parent 3685b2b
commit 55e4576
Show file tree

Hide file tree

Showing 3 changed files with 205 additions and 13 deletions.
diff --git a/docs/packages/connect/methods/cardanoSignMessage.md b/docs/packages/connect/methods/cardanoSignMessage.md
@@ -0,0 +1,100 @@
+## Cardano: Sign message
+
+Asks device to sign given message. User is presented with the first few bytes of the message and the hash of the whole message. User is asked to confirm details on Trezor.
+
+```javascript
+const result = await TrezorConnect.cardanoSignMessage(params);
+```
+
+### Params
+
+[Optional common params](commonParams.md)
+
+[CardanoSignMessage type](https://github.com/trezor/trezor-suite/blob/develop/packages/connect/src/types/api/cardano/index.ts)
+
+-   `signingPath` - _required_ `string | Array<number>` minimum length is `5`. [read more](../path.md)
+-   `payload` - _required_ `string` message bytes in hex.
+-   `hashPayload` - _required_ `boolean` if true, device will hash the payload before signing. Must be enabled if payload exceeds 1024 bytes.
+-   `displayAscii` - _required_ `boolean` if true, device will decode payload as ASCII.
+-   `networkId` - _optional_ `number` network identifier. Required if `addressParameters` are set.
+-   `protocolMagic` - _optional_ `number` protocol magic. Required if `addressParameters` are set.
+-   `addressParameters` - _optional_ `CardanoAddressParameters` object. [read more](./cardanoGetAddress.md#address-parameters) Used to derive address for message header. If not set then the key hash given by `signingPath` will be used instead.
+-   `derivationType` — _optional_ `CardanoDerivationType` enum. determines used derivation type. Default is set to ICARUS_TREZOR=2
+
+### Displaying payload
+
+If `hashPayload` is `true`, the device will display just the first 56 bytes of the payload. Otherwise 1024 bytes are displayed.
+
+The payload is decoded as a hex string if `displayAscii` is set to `false`. Otherwise it is decoded as an ASCII string, which succeeds only given the following conditions are met:
+
+-   The payload is a valid ASCII string.
+-   It must be clear to the user what the contents of the payload are, specifically there is:
+    -   At least one character
+    -   No control characters
+    -   No leading, trailing nor multiple consecutive spaces
+
+### Example
+
+Sign hash of "Hello Trezor!":
+
+```javascript
+TrezorConnect.cardanoSignMessage({
+    signingPath: "m/1852'/1815'/0'/0/0",
+    payload: '48656c6c6f205472657a6f7221', // "Hello Trezor!" in hex
+    hashPayload: true,
+    displayAscii: true,
+});
+```
+
+Sign hash of "Hello Trezor!" using address parameters for header:
+
+```javascript
+TrezorConnect.cardanoSignMessage({
+    signingPath: "m/1852'/1815'/0'/0/0",
+    payload: '48656c6c6f205472657a6f7221', // "Hello Trezor!" in hex
+    hashPayload: true,
+    displayAscii: true,
+    networkId: 1,
+    protocolMagic: 764824073,
+    addressParameters: {
+        addressType: 0,
+        path: "m/1852'/1815'/0'/0/0",
+        stakingPath: "m/1852'/1815'/0'/2/0",
+    },
+});
+```
+
+### Result
+
+[CardanoSignedMessage type](https://github.com/trezor/trezor-suite/blob/develop/packages/connect/src/types/api/cardano/index.ts)
+
+```javascript
+{
+    success: true,
+    payload: {
+      signature: string,
+      payload: string,
+      headers: {
+        protected: {
+          1: -8, // EdDSA algorithm
+          address: string,
+        },
+        unprotected: {
+          hashed: boolean,
+          version: number,
+        }
+      }
+    }
+}
+```
+
+Error
+
+```javascript
+{
+    success: false,
+    payload: {
+        error: string // error message
+    }
+}
+```
diff --git a/packages/connect/e2e/__fixtures__/cardanoSignMessage.ts b/packages/connect/e2e/__fixtures__/cardanoSignMessage.ts
@@ -7,35 +7,126 @@ const legacyResults = {
     },
 };
 
+const headerUnhashed = (address: string) => ({
+    protected: {
+        1: ALGORITHM_IDS.EdDSA,
+        address,
+    },
+    unprotected: {
+        hashed: false,
+        version: 1,
+    },
+});
+
+const headerHashed = (address: string) => {
+    const header = headerUnhashed(address);
+    header.unprotected.hashed = true;
+    return header;
+};
+
+/** "HelloTrezor!" repeated 86 times (=1032 bytes) in hex */
+const HELLO_TREZOR_86 =
+    '48656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f722148656c6c6f5472657a6f7221';
+
 export default {
     method: 'cardanoSignMessage',
     setup: {
         mnemonic: 'mnemonic_all',
     },
     tests: [
         {
-            description: 'Sign short ASCII payload hash',
+            description: 'Sign short ASCII payload',
             params: {
                 signingPath: "m/1852'/1815'/0'/0/0",
-                payload: '54657374',
-                hashPayload: true,
+                payload: '54657374', // "Test" hex
+                hashPayload: false,
                 displayAscii: true,
             },
             result: {
                 payload: '54657374',
                 signature:
-                    'cde9451e081f325ed9991b5c20f22c7220526f97e646abee71b8fe232e475b8b06a98df28fdec911e81a050d47c0fcbe3b629d38fc12730fb74ab0a5f56f7f05',
-                headers: {
-                    protected: {
-                        1: ALGORITHM_IDS.EdDSA,
-                        address: '80f9e2c88e6c817008f3a812ed889b4a4da8e0bd103f86e7335422aa',
-                    },
-                    unprotected: {
-                        hashed: true,
-                        version: 1,
-                    },
+                    '1c2c7612840654a56d61b58df36f41a4b47ad4034140ea369269c143f2732b2702c42fa753a8c52a9b662ba02944e43ec95c59cb892bf01cdd4a7f1c9397490c',
+                headers: headerUnhashed('80f9e2c88e6c817008f3a812ed889b4a4da8e0bd103f86e7335422aa'),
+            },
+            legacyResults: [legacyResults.beforeMessageSigning],
+        },
+        {
+            description: 'Sign short ASCII payload with address parameters',
+            params: {
+                signingPath: "m/1852'/1815'/0'/0/0",
+                payload: '54657374', // "Test" hex
+                hashPayload: false,
+                displayAscii: true,
+                networkId: 1,
+                protocolMagic: 764824073,
+                addressParameters: {
+                    addressType: 0,
+                    path: "m/1852'/1815'/0'/0/0",
+                    stakingPath: "m/1852'/1815'/0'/2/0",
                 },
             },
+            result: {
+                payload: '54657374',
+                signature:
+                    '31ddc8531e70f9be45af9812ab466749e2ed63d5be626956f3341867f518c29ad669380766a9e5ceefe9f099211809831892cbd3161ca4c935e1b574f59fb406',
+                headers: headerUnhashed(
+                    '0180f9e2c88e6c817008f3a812ed889b4a4da8e0bd103f86e7335422aa122a946b9ad3d2ddf029d3a828f0468aece76895f15c9efbd69b4277',
+                ),
+            },
+            legacyResults: [legacyResults.beforeMessageSigning],
+        },
+        {
+            description: 'Sign short non-ASCII payload',
+            params: {
+                signingPath: "m/1852'/1815'/0'/0/0",
+                payload: 'ff',
+                hashPayload: false,
+                displayAscii: false,
+            },
+            result: {
+                payload: 'ff',
+                signature:
+                    '003a3631d6c7509c2ebfbeb955c7f6a6b214c4283c2cbc10fc7eda6f2237881c7b219e4b28f3004d50cf528ad325b2d4f10425003096f80db58fc160365d920d',
+                headers: headerUnhashed('80f9e2c88e6c817008f3a812ed889b4a4da8e0bd103f86e7335422aa'),
+            },
+            legacyResults: [legacyResults.beforeMessageSigning],
+        },
+        {
+            description: 'Sign long ASCII payload hash',
+            params: {
+                signingPath: "m/1852'/1815'/0'/0/0",
+                payload: HELLO_TREZOR_86,
+                hashPayload: true,
+                displayAscii: true,
+            },
+            result: {
+                payload: HELLO_TREZOR_86,
+                signature:
+                    '39dba8107fb840b0aeff3f45eaddf9612cd4fd640a18cbe28ea2448b8ba2fea99b67cd9662a46cc7a70e1ad0d6399008d5fad9d67ddb437a623b594bf93b8e0f',
+                headers: headerHashed('80f9e2c88e6c817008f3a812ed889b4a4da8e0bd103f86e7335422aa'),
+            },
+            legacyResults: [legacyResults.beforeMessageSigning],
+        },
+        {
+            description: 'Sign long ASCII payload without hashing',
+            params: {
+                signingPath: "m/1852'/1815'/0'/0/0",
+                payload: HELLO_TREZOR_86,
+                hashPayload: false,
+                displayAscii: true,
+            },
+            result: false,
+            legacyResults: [legacyResults.beforeMessageSigning],
+        },
+        {
+            description: 'Display ambigous-looking " " ASCII payload',
+            params: {
+                signingPath: "m/1852'/1815'/0'/0/0",
+                payload: '20', // " " (single space) hex
+                hashPayload: false,
+                displayAscii: true,
+            },
+            result: false,
             legacyResults: [legacyResults.beforeMessageSigning],
         },
     ],

diff --git a/packages/connect/src/types/api/index.ts b/packages/connect/src/types/api/index.ts
@@ -167,6 +167,7 @@ export interface TrezorConnect {
 
     cardanoComposeTransaction: typeof cardanoComposeTransaction;
 
+    // https://github.com/trezor/trezor-suite/blob/develop/docs/packages/connect/methods/cardanoSignMessage.md
     cardanoSignMessage: typeof cardanoSignMessage;
 
     // https://github.com/trezor/trezor-suite/blob/develop/docs/packages/connect/methods/changePin.md