Refactor signature generation and add ledger support

Author: Fabrice Bascoulergue

docs/README.md

@@ -12,7 +12,7 @@ A couple examples to help you get started.
 
 ```typescript
 import {
-    LumWallet,
+    LumWalletFactory,
     LumClient,
     LumTypes,
     LumUtils,
@@ -21,15 +21,15 @@ import {
 } from '@lum-network/sdk-javascript'
 ```
 
-### Create a wallet
+### Software wallets
 
 #### Mnemonic
 ```typescript
 // Create a new cryptographically secure random mnemonic 
 const mnemonic = LumUtils.generateMnemonic(12);
 
 // Create a wallet instance based on this fresh mnemonic
-const wallet = await LumWallet.fromMnemonic(mnemonic);
+const wallet = await LumWalletFactory.fromMnemonic(mnemonic);
 ```
 
 #### Private key
@@ -38,12 +38,12 @@ const wallet = await LumWallet.fromMnemonic(mnemonic);
 const privateKey = LumUtils.generatePrivateKey();
 
 // Create a wallet instance based on this fresh private key
-const wallet = await LumWallet.fromPrivateKey(mnemonic);
+const wallet = await LumWalletFactory.fromPrivateKey(mnemonic);
 console.log(`Wallet address: ${wallet.address}`);
 
 // Create a wallet instance based on an hexadecimal private key (ex: user input - 0x is optional)
 const hexPrivateKey = '0xb8e62c34928025cdd3aef6cbebc68694b5ad9209b2aff6d3891c8e61d22d3a3b';
-const existingWallet = await LumWallet.fromPrivateKey(LumUtils.keyFromHex(hexPrivateKey));
+const existingWallet = await LumWalletFactory.fromPrivateKey(LumUtils.keyFromHex(hexPrivateKey));
 console.log(`Existing wallet address: ${wallet.address}`);
 ```
 
@@ -53,10 +53,49 @@ console.log(`Existing wallet address: ${wallet.address}`);
 const privateKey = LumUtils.generatePrivateKey();
 // Create a keystore (or consume user input)
 const keystore = LumUtils.generateKeyStore(privateKey, 'some-password');
-const wallet = await LumWallet.fromKeyStore(keystore, 'some-password');
+const wallet = await LumWalletFactory.fromKeyStore(keystore, 'some-password');
 console.log(`Wallet address: ${wallet.address}`);
 ```
 
+### Hardware wallets
+
+**IMPORTANT NOTES:**
+- Transaction signature using Hardware devices is currently work in progress, therefore broadcasting a transaction is not possible at the moment.
+- Derivation path using the Cosmos Ledger application cannot be set to the default Lum Path for now `m/44'/118'/0'/*/*` and must remain on the Cosmos path `m/44'/'837/0'/*/*`
+
+#### Ledger
+
+The SDK only provides access to the Ledger API using a provided Transport.
+Ledger transport must be initialized and handled by the code using the SDK.
+
+See [LedgerHQ/ledgerjs documentation](https://github.com/LedgerHQ/ledgerjs) for more information.
+
+```typescript
+import TransportNodeHid from '@ledgerhq/hw-transport-node-hid';
+
+// Connect your ledger device
+// Unlock it
+// Open the Cosmos application
+
+// Create a Node HID transport
+const transport = await TransportNodeHid.create();
+
+// Create the ledger based wallet instance
+const wallet = await LumWalletFactory.fromLedgerTransport(transport, `m/44'/118'/0'/0/0`, 'lum');
+
+// Change account to 1 and wallet to 1 (optional)
+await wallet.useAccount(`m/44'/118'/0'/1/1`, 'lum');
+
+// Get account information
+const account = await testnetClient.getAccount(wallet.getAddress());
+if (account === null) {
+    console.log('Account: not found');
+} else {
+    console.log(`Account: ${account.address}, ${account.accountNumber}, ${account.sequence}`);
+}
+```
+
+
 ### Connect to the testnet
 
 ```typescript
@@ -78,7 +117,7 @@ if (account === null) {
 
 #### Get account balances
 ```typescript
-const balances = await testnetClient.getBalancesUnverified(wallet.address);
+const balances = await testnetClient.getAllBalancesUnverified(wallet.address);
 if (balances.length === 0) {
     console.log('Balances: empty account');
 } else {
@@ -115,8 +154,19 @@ const fee = {
     amount: [{ denom: LumConstants.LumDenom, amount: '1' }],
     gas: '100000',
 };
+// Fetch account number and sequence
+const account = await testnetClient.getAccount(wallet.address);
+// Create the transaction document
+const doc = {
+    accountNumber: account.accountNumber,
+    chainId,
+    fee: fee,
+    memo: 'my transaction memo',
+    messages: [sendMsg],
+    sequence: account.sequence,
+};
 // Sign and broadcast the transaction using the client
-const broadcastResult = await clt.signAndBroadcastTx(w1, [sendMsg], fee, 'hello memo!');
+const broadcastResult = await clt.signAndBroadcastTx(w1, doc);
 // Verify the transaction was succesfully broadcasted and made it into a block
 console.log(`Broadcast success: ${LumUtils.broadcastTxCommitSuccess(broadcastResult)}`);
 ```

jest.config.js

@@ -13,5 +13,5 @@ module.exports = {
             tsconfig: 'tsconfig.spec.json',
         },
     },
-    testTimeout: 10000,
+    testTimeout: 30000,
 };

src/client/LumClient.ts

@@ -243,21 +243,15 @@ export class LumClient {
      * Signs the messages using the provided wallet and builds the transaction
      *
      * @param wallet signing wallet
-     * @param messages messages to sign
-     * @param fee requested fee
-     * @param memo optional memo for the transaction
+     * @param doc document to sign
      */
-    signTx = async (wallet: LumWallet, messages: LumMessages.Message[], fee: LumTypes.Fee, memo?: string): Promise<Uint8Array> => {
+    signTx = async (wallet: LumWallet, doc: LumTypes.Doc): Promise<Uint8Array> => {
         const account = await this.getAccount(wallet.getAddress());
         if (!account) {
             throw new Error('Account not found');
         }
-        const { accountNumber, sequence } = account;
-        const chainId = await this.getChainId();
-
-        const authInfo = LumUtils.generateAuthInfo(wallet.getPublicKey(), fee, sequence);
-        const signDoc = LumUtils.generateSignDoc(messages, memo, authInfo, chainId, accountNumber);
-        const signature = await wallet.signTransaction(signDoc);
+        const signDoc = LumUtils.generateSignDoc(doc, wallet.getPublicKey());
+        const signature = await wallet.signTransaction(doc);
         return LumUtils.generateTxBytes(signDoc, signature);
     };
 
@@ -276,12 +270,10 @@ export class LumClient {
      * Signs and broadcast the transaction using the specified wallet and messages
      *
      * @param wallet signing wallet
-     * @param messages messages to sign
-     * @param fee requested fee
-     * @param memo optional memo for the transaction
+     * @param doc document to sign and broadcast as a transaction
      */
-    signAndBroadcastTx = async (wallet: LumWallet, messages: LumMessages.Message[], fee: LumTypes.Fee, memo?: string): Promise<LumTypes.BroadcastTxCommitResponse> => {
-        const signedTx = await this.signTx(wallet, messages, fee, memo);
+    signAndBroadcastTx = async (wallet: LumWallet, doc: LumTypes.Doc): Promise<LumTypes.BroadcastTxCommitResponse> => {
+        const signedTx = await this.signTx(wallet, doc);
         return this.broadcastTx(signedTx);
     };
 }

src/types/Doc.ts

@@ -0,0 +1,29 @@
+import { Message } from '../messages';
+import { Fee } from './Fee';
+
+export interface Doc {
+    /** account_number is the account number of the account in state */
+    accountNumber: number;
+    /**
+     * chain_id is the unique identifier of the chain this transaction targets.
+     * It prevents signed transactions from being used on another chain by an
+     * attacker
+     */
+    chainId: string;
+    /**
+     * Transaction requested Fee
+     */
+    fee: Fee;
+    /**
+     * Transaction memo
+     */
+    memo?: string;
+    /**
+     * Transactions messages
+     */
+    messages: Message[];
+    /**
+     * Transction sequence number
+     */
+    sequence: number;
+}

src/types/index.ts

@@ -6,5 +6,6 @@ export * from './Fee';
 export * from './Description';
 export * from './Commission';
 export * from './CommissionRates';
+export * from './Doc';
 export * from './SignDoc';
 export * from './Log';

src/utils/commons.ts

@@ -1 +1,26 @@
 export { isNonNullObject, isUint8Array } from '@cosmjs/utils';
+
+/**
+ * Sorts an object properties recursively.
+ *
+ * @param jsonObj object to sort
+ * @returns a new object with keys sorted alphabetically
+ */
+export const sortJSON = <T>(jsonObj: T): T => {
+    if (jsonObj instanceof Array) {
+        for (let i = 0; i < jsonObj.length; i++) {
+            jsonObj[i] = sortJSON(jsonObj[i]);
+        }
+        return jsonObj;
+    } else if (typeof jsonObj !== 'object') {
+        return jsonObj;
+    }
+
+    let keys = Object.keys(jsonObj) as Array<keyof T>;
+    keys = keys.sort();
+    const newObject: Partial<T> = {};
+    for (let i = 0; i < keys.length; i++) {
+        newObject[keys[i]] = sortJSON(jsonObj[keys[i]]);
+    }
+    return newObject as T;
+};

src/utils/transactions.ts

@@ -6,8 +6,7 @@ import { makeAuthInfoBytes, makeSignBytes } from '@cosmjs/proto-signing';
 import { TxRaw } from '../codec/cosmos/tx/v1beta1/tx';
 
 import { sha256 } from './encoding';
-import { Message } from '../messages';
-import { Fee, SignDoc } from '../types';
+import { Fee, Doc, SignDoc } from '../types';
 import { publicKeyToProto } from './keys';
 import { LumRegistry } from '../registry';
 
@@ -18,7 +17,7 @@ import { LumRegistry } from '../registry';
  * @param fee requested fee
  * @param sequence account sequence number
  */
-export const generateAuthInfo = (publicKey: Uint8Array, fee: Fee, sequence: number): Uint8Array => {
+export const generateAuthInfoBytes = (publicKey: Uint8Array, fee: Fee, sequence: number): Uint8Array => {
     const pubkeyAny = publicKeyToProto(publicKey);
     const gasLimit = Int53.fromString(fee.gas).toNumber();
     return makeAuthInfoBytes([pubkeyAny], fee.amount, gasLimit, sequence);
@@ -27,16 +26,13 @@ export const generateAuthInfo = (publicKey: Uint8Array, fee: Fee, sequence: numb
 /**
  * Generate transaction doc to be signed
  *
- * @param messages Transaction messages
- * @param memo optional memo for the transaction
- * @param authInfoBytes info bytes (as generated by the generateAuthInfo function)
- * @param chainId chain id
- * @param accountNumber account number
+ * @param doc document to create the sign version
+ * @param publicKey public key used for signature
  */
-export const generateSignDoc = (messages: Message[], memo: string | undefined, authInfoBytes: Uint8Array, chainId: string, accountNumber: number): SignDoc => {
+export const generateSignDoc = (doc: Doc, publicKey: Uint8Array): SignDoc => {
     const txBody = {
-        messages: messages,
-        memo: memo,
+        messages: doc.messages,
+        memo: doc.memo,
     };
     const bodyBytes = LumRegistry.encode({
         typeUrl: '/cosmos.tx.v1beta1.TxBody',
@@ -45,9 +41,9 @@ export const generateSignDoc = (messages: Message[], memo: string | undefined, a
 
     return {
         bodyBytes,
-        authInfoBytes,
-        chainId,
-        accountNumber: Long.fromNumber(accountNumber),
+        authInfoBytes: generateAuthInfoBytes(publicKey, doc.fee, doc.sequence),
+        chainId: doc.chainId,
+        accountNumber: Long.fromNumber(doc.accountNumber),
     };
 };
 

src/wallet/LumLedgerWallet.ts

@@ -25,16 +25,29 @@ export class LumLedgerWallet extends LumWallet {
         return true;
     };
 
-    signTransaction = async (doc: LumTypes.SignDoc): Promise<Uint8Array> => {
+    signTransaction = async (doc: LumTypes.Doc): Promise<Uint8Array> => {
         if (!this.hdPath) {
             throw new Error('No account selected.');
         }
-        // Implementation is delayed. We are not sure if we will be able to sign transactions using the new protobuf implementation
+        // TODO: does not work as intented - signature "works" but not valid for broadcast using the client
+        // Implementation not working. We are not sure if we will be able to sign transactions using the new protobuf implementation
         // with the current cosmos ledger application
         //
         // Useful doc & code:
         // sign call: https://github.com/LedgerHQ/ledgerjs/blob/master/packages/hw-app-cosmos/src/Cosmos.js
         // Expected tx format: https://github.com/cosmos/ledger-cosmos/blob/master/docs/TXSPEC.md
-        throw new Error('Not implemented.');
+        const msg = {
+            'account_number': doc.accountNumber,
+            'chain_id': doc.chainId,
+            'fee': doc.fee,
+            'memo': doc.memo,
+            'msgs': doc.messages,
+            'sequence': doc.sequence,
+        };
+        const { signature, return_code } = await this.cosmosApp.sign(this.hdPath, JSON.stringify(LumUtils.sortJSON(msg)));
+        if (!signature || return_code === 0) {
+            throw new Error(`Failed to sign message: error code ${return_code}`);
+        }
+        return new Uint8Array(signature);
     };
 }

src/wallet/LumPaperWallet.ts

@@ -1,4 +1,4 @@
-import { LumUtils, LumConstants, LumMessages, LumTypes } from '..';
+import { LumUtils, LumConstants, LumTypes } from '..';
 import { LumWallet } from '.';
 
 export class LumPaperWallet extends LumWallet {
@@ -39,11 +39,12 @@ export class LumPaperWallet extends LumWallet {
         throw new Error('No available mnemonic or private key.');
     };
 
-    signTransaction = async (doc: LumTypes.SignDoc): Promise<Uint8Array> => {
+    signTransaction = async (doc: LumTypes.Doc): Promise<Uint8Array> => {
         if (!this.privateKey || !this.publicKey) {
             throw new Error('No account selected.');
         }
-        const signBytes = LumUtils.generateSignDocBytes(doc);
+        const signDoc = LumUtils.generateSignDoc(doc, this.getPublicKey());
+        const signBytes = LumUtils.generateSignDocBytes(signDoc);
         const hashedMessage = LumUtils.sha256(signBytes);
         const signature = await LumUtils.generateSignature(hashedMessage, this.privateKey);
         return signature;

src/wallet/LumWallet.ts

@@ -46,9 +46,9 @@ export abstract class LumWallet {
     abstract useAccount(hdPath: string, addressPrefix: string): Promise<boolean>;
 
     /**
-     * Sign a transaction using a LumWallet
+     * Sign a transaction document using a LumWallet
      *
      * @param doc document to sign
      */
-    abstract signTransaction(doc: LumTypes.SignDoc): Promise<Uint8Array>;
+    abstract signTransaction(doc: LumTypes.Doc): Promise<Uint8Array>;
 }