@bitpay-labs/bitcore-wallet-service 11.11.1 → 11.11.3

package/src/lib/routes/tss.ts

@@ -1,7 +1,6 @@
 import express from 'express';
 import * as Types from '../../types/expressapp';
 import { TssKeyGen, TssSign } from '../tss';
-import { authRequest } from './middleware/authRequest';
 import { authTssKeyGenRequest, authTssSignRequest } from './middleware/authTssRequest';
 import { createWalletLimiter } from './middleware/createWalletLimiter';
 import { verifyTssMessage } from './middleware/verifyTssMessage';
@@ -49,6 +48,36 @@ export class TssRouter {
       }
     });
 
+    // Must be before /keygen/:id/:round so "secret" doesn't get interpreted as a round number
+    router.get('/v1/tss/keygen/:id/secret', authTssKeyGenRequest({ bypassExpired: true }), async function(req, res) {
+      try {
+        const id = req.params.id;
+        const copayerId = req.headers['x-identity'];
+        const { chain, network } = req.query as { [key: string]: string };
+        const secret = await TssKeyGen.getBwsJoinSecret({ id, chain, network, copayerId });
+        return res.json({ secret });
+      } catch (err) {
+        return returnError(err ?? 'unknown', res, req);
+      }
+    });
+
+    router.post('/v1/tss/keygen/:id/secret', authTssKeyGenRequest({ bypassExpired: true }), async function(req, res) {
+      try {
+        const id = req.params.id;
+        const { chain, network, secrets, secret } = req.body;
+        const copayerId = req.headers['x-identity'];
+        if (secrets == null && secret != null) {
+          // Legacy (< v1.3) clients send a single unencrypted secret
+          await TssKeyGen.storeBwsJoinSecret({ id, secret, copayerId });
+        } else {
+          await TssKeyGen.storeBwsJoinSecrets({ id, chain, network, secrets, copayerId });
+        }
+        return res.send();
+      } catch (err) {
+        return returnError(err ?? 'unknown', res, req);
+      }
+    });
+
     router.get('/v1/tss/keygen/:id/:round', authTssKeyGenRequest(), async function(req, res) {
       let interval: NodeJS.Timeout;
       try {
@@ -58,10 +87,6 @@ export class TssRouter {
         const { id, round } = req.params as { [key: string]: string };
         const { maxWaitTime } = req.query as { [key: string]: string };
         const copayerId = req.headers['x-identity'];
-        if (round === 'secret') {
-          const secret = await TssKeyGen.getBwsJoinSecret({ id, copayerId });
-          return res.json({ secret });
-        }
 
         // Validate access and fetch session before committing to a streaming response, so that errors like
         //   "session not found" or "not a participant" can still be returned with a proper
@@ -100,33 +125,10 @@ export class TssRouter {
       }
     });
 
-    router.post('/v1/tss/keygen/:id/secret', authTssKeyGenRequest(), async function(req, res) {
-      try {
-        const id = req.params.id;
-        const { secret } = req.body;
-        const copayerId = req.headers['x-identity'];
-        await TssKeyGen.storeBwsJoinSecret({ id, secret, copayerId });
-        return res.send();
-      } catch (err) {
-        return returnError(err ?? 'unknown', res, req);
-      }
-    });
-
-    router.get('/v1/tss/keygen/:id/secret', authTssKeyGenRequest(), async function(req, res) {
-      try {
-        const id = req.params.id;
-        const copayerId = req.headers['x-identity'];
-        const secret = await TssKeyGen.getBwsJoinSecret({ id, copayerId });
-        return res.json({ secret });
-      } catch (err) {
-        return returnError(err ?? 'unknown', res, req);
-      }
-    });
-
 
     /** Signature Methods */
 
-    router.post('/v1/tss/sign/:id', authRequest(), verifyTssMessage, async function(req, res) {
+    router.post('/v1/tss/sign/:id', authTssSignRequest({ joinable: true }), verifyTssMessage, async function(req, res) {
       try {
         const id = req.params.id;
         // version was not given by client until 1.1, so fallback to 1.0
@@ -178,7 +180,8 @@ export class TssRouter {
       try {
         const id = req.params.id;
         const { signature } = req.body;
-        await TssSign.storeSignature({ id, signature });
+        const copayerId = req.headers['x-identity'];
+        await TssSign.storeSignature({ id, signature, copayerId });
         return res.send();
       } catch (err) {
         return returnError(err ?? 'unknown', res, req);

package/src/lib/routes/wallets.ts

@@ -228,8 +228,10 @@ export function registerWalletRoutes(router: express.Router, context: RouteConte
         return res.json([]);
       }
 
+      // a copayer that isn't an object with a string id can't exist, so it isn't looked up
+      const wellFormed = copayers.filter(c => typeof c?.copayerId === 'string');
       const storage = WalletService.getStorage();
-      const existing = await Promise.all<{ copayerId: string; verified: boolean }>(copayers.map(async c => {
+      const existing = await Promise.all<{ copayerId: string; verified: boolean }>(wellFormed.map(async c => {
         const copayer = await storage.fetchCopayerLookup(c.copayerId).catch(() => null);
         if (!copayer) {
           return { copayerId: c.copayerId, verified: false };

package/src/lib/server.ts

@@ -604,6 +604,7 @@ export class WalletService implements IWalletService {
    * @param {number} [opts.tssVersion] TSS version to use. Supplying this with n > 1 and a multisig chain (e.g. btc) will tell the wallet to use
    *                                   threshold insead of on-chain multisig. Otherwise, n > 1 and a non-multisig chain will default to TSS_KEYGEN_SCHEME_VERSION
    * @param {string} [opts.tssKeyId] TSS key session id. This is the id of the TSS key generation session that will be used to create the wallet.
+   * @param {string} [opts.tssKeygenCopayerId] The ID of the copayer creating the wallet. Required for TSS version >= 1.3.
    */
   async createWallet(opts, cb) {
     let pubKey;
@@ -674,6 +675,17 @@ export class WalletService implements IWalletService {
         return cb(new ClientError('Invalid TSS version'));
       }
 
+      if (opts.tssVersion >= 1.3) {
+        if (!opts.tssKeygenCopayerId) {
+          return cb(new ClientError('Copayer ID is required for TSS version >= 1.3'));
+        }
+        // This is only a sanity check to prevent problems down the line. If this is somehow
+        // spoofed, there are more strict authorization checks later in the wallet creation flow.
+        if (keySession.participants.indexOf(opts.tssKeygenCopayerId) !== 0) {
+          return cb(new ClientError('Only the TSS session leader can create a wallet'));
+        }
+      }
+
       // TSS wallets behave like a single-sig
       opts.m = 1;
       opts.n = 1;
@@ -873,26 +885,29 @@ export class WalletService implements IWalletService {
       pendingTxps?: ITxProposal[];
       preferences?: boolean;
     } = {};
-    async.parallel(
-      [
-        next => {
-          this.getWallet({}, (err, wallet: Partial<Wallet>) => {
-            if (err) return next(err);
-            if (this._upgradeNeeded(UPGRADES.SOL_bwc_$lt_10_10_12, wallet)) {
-              return next(Errors.UPGRADE_NEEDED);
-            }
+    this.getWallet({}, (err, fetchedWallet: Wallet) => {
+      if (err) return cb(err);
 
+      // Read the wallet once, and give each step its own copy, the same as reading it again: the steps change their
+      // wallet in place (this one strips copayer data, the balance code sets tokenAddress on it), and the balance step
+      // can store its copy whole.
+      const copyOfWallet = () => Wallet.fromObj(fetchedWallet.toObject());
+      const omit = (obj, keys: string[]): any => Object.fromEntries(Object.entries(obj).filter(([key]) => !keys.includes(key)));
+      async.parallel(
+        [
+          next => {
+            let wallet: Partial<Wallet> = copyOfWallet();
             const walletExtendedKeys = ['publicKeyRing', 'pubKey', 'addressManager'];
             const copayerExtendedKeys = ['xPubKey', 'requestPubKey', 'signature', 'addressManager', 'customData'];
 
             wallet.copayers = (wallet.copayers || []).map(copayer => {
               if (copayer.id == this.copayerId) return copayer;
-              return _.omit(copayer, 'customData');
+              return omit(copayer, ['customData']);
             });
             if (!opts.includeExtendedInfo) {
-              wallet = _.omit(wallet, walletExtendedKeys);
+              wallet = omit(wallet, walletExtendedKeys);
               wallet.copayers = (wallet.copayers || []).map(copayer => {
-                return _.omit(copayer, copayerExtendedKeys);
+                return omit(copayer, copayerExtendedKeys);
               }) as Copayer[];
             }
             status.wallet = wallet;
@@ -903,46 +918,45 @@ export class WalletService implements IWalletService {
               status.serverMessage = deprecatedServerMessage(wallet, this.appName, this.appVersion);
             }
             next();
-          });
-        },
-        next => {
-          opts.wallet = status.wallet;
-          this.getBalance(opts, (err, balance) => {
-            // ignore WALLET_NEED_SCAN err is includeExtendedInfo is given
-            // (to allow `importWallet` to import a wallet, while scan has
-            // failed)
-            if (opts.includeExtendedInfo) {
-              if (err && err.code != 'WALLET_NEED_SCAN') {
+          },
+          next => {
+            this.getBalance({ ...opts, wallet: copyOfWallet() }, (err, balance) => {
+              // ignore WALLET_NEED_SCAN err is includeExtendedInfo is given
+              // (to allow `importWallet` to import a wallet, while scan has
+              // failed)
+              if (opts.includeExtendedInfo) {
+                if (err && err.code != 'WALLET_NEED_SCAN') {
+                  return next(err);
+                }
+              } else if (err) {
                 return next(err);
               }
-            } else if (err) {
-              return next(err);
-            }
 
-            status.balance = balance;
-            next();
-          });
-        },
-        next => {
-          this.getPendingTxs(opts, (err, pendingTxps) => {
-            if (err) return next(err);
-            status.pendingTxps = pendingTxps;
-            next();
-          });
-        },
-        next => {
-          this.getPreferences({}, (err, preferences) => {
-            if (err) return next(err);
-            status.preferences = preferences;
-            next();
-          });
+              status.balance = balance;
+              next();
+            });
+          },
+          next => {
+            this.getPendingTxs({ ...opts, wallet: copyOfWallet() }, (err, pendingTxps) => {
+              if (err) return next(err);
+              status.pendingTxps = pendingTxps;
+              next();
+            });
+          },
+          next => {
+            this.getPreferences({}, (err, preferences) => {
+              if (err) return next(err);
+              status.preferences = preferences;
+              next();
+            });
+          }
+        ],
+        err => {
+          if (err) return cb(err);
+          return cb(null, status);
         }
-      ],
-      err => {
-        if (err) return cb(err);
-        return cb(null, status);
-      }
-    );
+      );
+    });
   }
 
   /**
@@ -1036,7 +1050,11 @@ export class WalletService implements IWalletService {
     this._notify(type, data, {}, cb);
   }
 
-  _addCopayerToWallet(wallet: Wallet, opts, cb) {
+  _addCopayerToWallet(
+    wallet: Wallet,
+    opts: JoinWalletOpts,
+    cb: (err: ClientError | null, result?: { copayerId: string | null; wallet: Wallet }) => void
+  ) {
     const copayer = Copayer.create({
       coin: wallet.coin,
       chain: wallet.chain, // chain === coin for stored clients
@@ -1192,20 +1210,11 @@ export class WalletService implements IWalletService {
 
   /**
    * Joins a wallet in creation.
-   * @param {Object} opts
-   * @param {string} opts.walletId The wallet id.
-   * @param {string} opts.coin The expected coin for this wallet (btc, bch, eth, doge, ltc). Default: btc
-   * @param {string} opts.chain The expected chain for this wallet (btc, bch, eth, doge, ltc). Default: btc
-   * @param {string} opts.name The copayer name.
-   * @param {string} opts.xPubKey Extended Public Key for this copayer
-   * @param {string} opts.hardwareSourcePublicKey Public key from a hardware device for this copayer
-   * @param {string} opts.clientDerivedPublicKey Public key from the client for this wallet
-   * @param {string} opts.requestPubKey Public Key used to check requests from this copayer.
-   * @param {string} opts.copayerSignature S(name|xPubKey|requestPubKey). Used by other copayers to verify that the copayer joining knows the wallet secret.
-   * @param {string} [opts.customData] Custom data for this copayer.
-   * @param {boolean} [opts.dryRun] Simulate the action but do not change server state.
    */
-  joinWallet(opts, cb) {
+  joinWallet(
+    opts: JoinWalletOpts,
+    cb: (err: ClientError | null, result?: { copayerId: string | null; wallet: Wallet }) => void
+  ) {
     // xPubKey is the canonical copayer identity in the current protocol. Alternate public-key
     // fields are ancillary metadata; supporting an xPubKey-less copayer requires a versioned
     // end-to-end identity protocol rather than a local identity fallback.
@@ -1224,6 +1233,9 @@ export class WalletService implements IWalletService {
       opts.chain = opts.coin; // chain === coin for stored clients
     }
     if (!Utils.checkValueInCollection(opts.chain, Constants.CHAINS)) return cb(new ClientError('Invalid coin'));
+    if (opts.tssKeygenChain != null && !Utils.checkValueInCollection(opts.tssKeygenChain, Constants.CHAINS)) {
+      return cb(new ClientError('Invalid TSS keygen chain'));
+    }
 
     // xPubKey is parsed and validated for every join; ancillary fields never suppress it.
     // A future update will re-add conditional logic which allows opts.hardwareSourcePublicKey
@@ -1284,8 +1296,16 @@ export class WalletService implements IWalletService {
 
         if (wallet.tssKeyId) {
           const keySession = await storage.fetchTssKeyGenSession({ id: wallet.tssKeyId });
-          const copayerId = Copayer.xPubToCopayerId(opts.chain, opts.xPubKey);
-          if (!keySession.participants.includes(copayerId)) {
+          // A sibling wallet on another network (e.g. livenet -> testnet) has an xPubKey serialized for that network,
+          // but the keygen session's copayer IDs were derived from the xPubKey serialized for the session's network.
+          const idChain = opts.tssKeygenChain || opts.chain;
+          const copayerIds = new Set([
+            Copayer.xPubToCopayerId(idChain, opts.xPubKey), // this is probably a duplicate of one of the next two entries, but just in case.
+            Copayer.xPubToCopayerId(idChain, Utils.convertXPubKeyForNetwork(opts.xPubKey, idChain, 'livenet')),
+            Copayer.xPubToCopayerId(idChain, Utils.convertXPubKeyForNetwork(opts.xPubKey, idChain, 'testnet'))
+          ]);
+
+          if (!keySession?.participants.some(id => copayerIds.has(id))) {
             return cb(Errors.TSS_NON_PARTICIPANT);
           }
           return this._addCopayerToWallet(wallet, opts, cb);
@@ -1535,9 +1555,10 @@ export class WalletService implements IWalletService {
   _canCreateAddress(ignoreMaxGap, cb) {
     if (ignoreMaxGap) return cb(null, true);
 
-    this.storage.fetchAddresses(this.walletId, (err, addresses: IAddress[]) => {
+    const newest = { noChange: true, reverse: true, limit: Defaults.MAX_MAIN_ADDRESS_GAP };
+    this.storage.fetchAddressesPage(this.walletId, newest, (err, addresses: IAddress[]) => {
       if (err) return cb(err);
-      const latestAddresses = addresses.filter(x => !x.isChange).slice(-Defaults.MAX_MAIN_ADDRESS_GAP) as IAddress[];
+      const latestAddresses = addresses.reverse();
       if (
         latestAddresses.length < Defaults.MAX_MAIN_ADDRESS_GAP ||
         latestAddresses.some(a => a.hasActivity)
@@ -1638,7 +1659,7 @@ export class WalletService implements IWalletService {
     };
 
     const getFirstAddress = (wallet, cb) => {
-      this.storage.fetchAddresses(this.walletId, (err, addresses) => {
+      this.storage.fetchAddressesPage(this.walletId, { limit: 1 }, (err, addresses) => {
         if (err) return cb(err);
         if (addresses?.length) {
           const x = addresses[0];
@@ -1691,17 +1712,9 @@ export class WalletService implements IWalletService {
 
   getAddresses(opts: GetAddressesOpts, cb) {
     opts = opts || {};
-    this.storage.fetchAddresses(this.walletId, (err, addresses) => {
+    const { noChange, addresses: only, reverse, skip, limit } = opts;
+    this.storage.fetchAddressesPage(this.walletId, { noChange, addresses: only, reverse, skip, limit }, (err, addresses) => {
       if (err) return cb(err);
-      if (opts.noChange) {
-        addresses = addresses.filter(a => !a.isChange);
-      }
-      if (opts.addresses) {
-        addresses = addresses.filter(a => opts.addresses.includes(a.address));
-      }
-      if (opts.reverse) addresses.reverse();
-      if (opts.skip > 0) addresses = addresses.slice(opts.skip);
-      if (opts.limit > 0) addresses = addresses.slice(0, opts.limit);
 
       this.getWallet({}, (err, wallet) => {
         if (err) return cb(err);
@@ -1783,7 +1796,7 @@ export class WalletService implements IWalletService {
     async.series(
       [
         next => {
-          this.getWallet({}, (err, w) => {
+          const useWallet = (err, w) => {
             if (err) return next(err);
 
             wallet = w;
@@ -1793,7 +1806,10 @@ export class WalletService implements IWalletService {
             bc = this._getBlockchainExplorer(wallet.chain, wallet.network);
             if (!bc) return cb(new Error('Could not get blockchain explorer instance'));
             return next();
-          });
+          };
+          // the balance code passes the wallet it already has
+          if (opts.wallet) return useWallet(null, opts.wallet);
+          this.getWallet({}, useWallet);
         },
         next => {
           if (Array.isArray(opts.addresses)) {
@@ -1889,7 +1905,7 @@ export class WalletService implements IWalletService {
         next => {
           utxoIndex = _.keyBy(allUtxos, utxoKey);
 
-          this.getPendingTxs({ numberFormat: opts.numberFormat }, (err, txps) => {
+          this.getPendingTxs({ numberFormat: opts.numberFormat, wallet }, (err, txps) => {
             if (err) return next(err);
 
             const lockedInputs = txps.flatMap(t => t.inputs).map(utxoKey);
@@ -1933,7 +1949,8 @@ export class WalletService implements IWalletService {
               });
               logger.debug(`Got ${allUtxos.length} usable UTXOs`);
               return next();
-            }
+            },
+            wallet
           );
         },
         next => {
@@ -1946,6 +1963,7 @@ export class WalletService implements IWalletService {
             }
             utxo.path = addressToPath[utxo.address].path;
             utxo.publicKeys = addressToPath[utxo.address].publicKeys;
+            utxo.isChange = addressToPath[utxo.address].isChange;
           }
           return next();
         }
@@ -2399,6 +2417,37 @@ export class WalletService implements IWalletService {
   }
 
   _validateAndSanitizeTxOpts(wallet, opts, cb) {
+    const gasFeeFields = ['gasPrice', 'maxGasFee', 'priorityGasFee'];
+    const hasGasFeeOverride = gasFeeFields.some(key => opts[key] != null);
+    if (hasGasFeeOverride) {
+      if (!Constants.EVM_CHAINS[wallet.chain.toUpperCase()]) {
+        return cb(new ClientError('Gas fee overrides are only supported for EVM chains'));
+      }
+      for (const key of gasFeeFields) {
+        if (opts[key] != null && (!Number.isSafeInteger(opts[key]) || opts[key] <= 0)) {
+          return cb(new ClientError(`${key} must be a positive safe integer in wei`));
+        }
+      }
+      if (opts.gasPrice != null && Number(opts.txType || 0) !== 0) {
+        return cb(new ClientError('gasPrice requires a type 0 transaction'));
+      }
+      if ((opts.maxGasFee != null || opts.priorityGasFee != null) && Number(opts.txType) !== 2) {
+        return cb(new ClientError('maxGasFee and priorityGasFee require a type 2 transaction'));
+      }
+      if ((opts.maxGasFee != null) !== (opts.priorityGasFee != null)) {
+        return cb(new ClientError('maxGasFee and priorityGasFee must be supplied together'));
+      }
+      if (opts.priorityGasFee > opts.maxGasFee) {
+        return cb(new ClientError('priorityGasFee must not exceed maxGasFee'));
+      }
+      if (opts.feePerKb != null || opts.fee != null) {
+        return cb(new ClientError('Gas fee overrides cannot be combined with feePerKb or fee'));
+      }
+      // sendMax calculates its amount before getFee, using a separate fee estimate.
+      if (opts.sendMax) {
+        return cb(new ClientError('Gas fee overrides are not supported with sendMax'));
+      }
+    }
     async.series(
       [
         next => {
@@ -2406,7 +2455,7 @@ export class WalletService implements IWalletService {
             boolToNum(!!opts.feeLevel) + boolToNum(Utils.isNumber(opts.feePerKb)) + boolToNum(Utils.isNumber(opts.fee));
           if (feeArgs > 1) return next(new ClientError('Only one of feeLevel/feePerKb/fee can be specified'));
 
-          if (feeArgs == 0) {
+          if (feeArgs == 0 && !hasGasFeeOverride) {
             opts.feeLevel = 'normal';
           }
 
@@ -2418,6 +2467,11 @@ export class WalletService implements IWalletService {
               );
           }
 
+          // An explicit gas fee determines the price, not the named fee level.
+          if (hasGasFeeOverride) {
+            delete opts.feeLevel;
+          }
+
           const error = ChainService.checkUtxos(wallet.chain, opts);
           if (error) {
             return next(new ClientError('fee can only be set when inputs are specified'));
@@ -2779,6 +2833,9 @@ export class WalletService implements IWalletService {
    * @param {Boolean} opts.enableRBF - Optional. enable BTC Replace By Fee
    * @param {Boolean} opts.replaceTxByFee - Optional. Ignore locked utxos check ( used for replacing a transaction designated as RBF)
    * @param {number} opts.txType - Optional. Type of EVM transaction
+   * @param {number} opts.gasPrice - Optional. Type 0 gas price in wei. Overrides feeLevel; incompatible with fee/feePerKb/sendMax.
+   * @param {number} opts.maxGasFee - Optional. Type 2 maximum fee per gas in wei; requires priorityGasFee.
+   * @param {number} opts.priorityGasFee - Optional. Positive type 2 priority fee per gas in wei; requires maxGasFee and must not exceed it. Gas fee overrides cannot be used with fee/feePerKb/sendMax.
    * @param {number} opts.gasLimitBuffer - Optional. Percentage of buffer to add to the gasLimit
    * @param {number} opts.priorityFeePercentile - Optional. Percentile of targeted priority fee rate
    * @param {Boolean} opts.multiTx - Optional. Proposal will create multiple transactions
@@ -3169,19 +3226,23 @@ export class WalletService implements IWalletService {
    * @returns {Object} txProposal
    */
   getTx(opts, cb: (err: any, txp?: TxProposal) => void) {
-    this.storage.fetchTx(this.walletId, opts.txProposalId, (err, txp) => {
+    // the tx and its note are both completed from the wallet, so read it once
+    this.storage.fetchWallet(this.walletId, (err, wallet) => {
       if (err) return cb(err);
-      if (!txp) return cb(Errors.TX_NOT_FOUND);
+      this.storage.fetchTx(this.walletId, opts.txProposalId, (err, txp) => {
+        if (err) return cb(err);
+        if (!txp) return cb(Errors.TX_NOT_FOUND);
 
-      if (!txp.txid) return cb(null, txp);
+        if (!txp.txid) return cb(null, txp);
 
-      this.storage.fetchTxNote(this.walletId, txp.txid, (err, note) => {
-        if (err) {
-          this.logw(`Error fetching tx note for ${txp.txid}:`, err);
-        }
-        txp.note = note;
-        return cb(null, txp);
-      });
+        this.storage.fetchTxNote(this.walletId, txp.txid, (err, note) => {
+          if (err) {
+            this.logw(`Error fetching tx note for ${txp.txid}:`, err);
+          }
+          txp.note = note;
+          return cb(null, txp);
+        }, wallet);
+      }, wallet);
     });
   }
 
@@ -3199,19 +3260,22 @@ export class WalletService implements IWalletService {
     // foreign wallet's proposal data to any authenticated copayer. The
     // internal global consumers (BlockchainMonitor, getWalletFromIdentifier)
     // are unaffected; they keep calling storage.fetchTxByHash directly.
-    this.storage.fetchTxByHashForWallet(this.walletId, opts.txid, (err, txp) => {
+    this.storage.fetchWallet(this.walletId, (err, wallet) => {
       if (err) return cb(err);
-      if (!txp) return cb(Errors.TX_NOT_FOUND);
+      this.storage.fetchTxByHashForWallet(this.walletId, opts.txid, (err, txp) => {
+        if (err) return cb(err);
+        if (!txp) return cb(Errors.TX_NOT_FOUND);
 
-      if (!txp.txid) return cb(null, txp);
+        if (!txp.txid) return cb(null, txp);
 
-      this.storage.fetchTxNote(this.walletId, txp.txid, (err, note) => {
-        if (err) {
-          this.logw(`Error fetching tx note for ${txp.txid}:`, err);
-        }
-        txp.note = note;
-        return cb(null, txp);
-      });
+        this.storage.fetchTxNote(this.walletId, txp.txid, (err, note) => {
+          if (err) {
+            this.logw(`Error fetching tx note for ${txp.txid}:`, err);
+          }
+          txp.note = note;
+          return cb(null, txp);
+        }, wallet);
+      }, wallet);
     });
   }
 
@@ -3841,7 +3905,7 @@ export class WalletService implements IWalletService {
             return cb(err, txps);
           }
         );
-      });
+      }, opts.wallet);
     }
   }
 
@@ -4131,7 +4195,7 @@ export class WalletService implements IWalletService {
         return cb(err);
       }
       wallet.beRegistered = true;
-      return this.storage.storeWallet(wallet, err => cb(err, true));
+      return this.storage.storeWalletRegistration(wallet, err => cb(err, true));
     });
   }
 
@@ -4867,7 +4931,8 @@ export class WalletService implements IWalletService {
                       minTs,
                       maxTs
                     },
-                    done
+                    done,
+                    wallet
                   );
                 },
                 done => {
@@ -4876,7 +4941,8 @@ export class WalletService implements IWalletService {
                     {
                       minTs
                     },
-                    done
+                    done,
+                    wallet
                   );
                 }
               ],
@@ -5790,3 +5856,30 @@ export const UPGRADES = {
 } as const;
 
 type Upgrade = typeof UPGRADES[keyof typeof UPGRADES];
+
+export interface JoinWalletOpts {
+  /** The wallet id. */
+  walletId: string;
+  /** The expected coin for this wallet (btc, bch, eth, doge, ltc). Default: btc */
+  coin?: string;
+  /** The expected chain for this wallet (btc, bch, eth, doge, ltc). Default: btc */
+  chain?: string;
+  /** The copayer name. */
+  name: string;
+  /** Extended Public Key for this copayer */
+  xPubKey: string;
+  /** Public key from a hardware device for this copayer */
+  hardwareSourcePublicKey?: string;
+  /** Public key from the client for this wallet */
+  clientDerivedPublicKey?: string;
+  /** Public Key used to check requests from this copayer. */
+  requestPubKey: string;
+  /** Signature proving knowledge of the wallet secret for this copayer. */
+  copayerSignature: string;
+  /** Custom data for this copayer. */
+  customData?: string;
+  /** Simulate the action but do not change server state. */
+  dryRun?: boolean;
+  /** The chain used for TSS key generation. */
+  tssKeygenChain?: string;
+};