Merge pull request #7052 from BitGo/WP-5415-express-migrate-api-v2-coin-wallet-generate-to-typed-routes

refactor: migrated generateWallet to typed routes

Author: danielzhao122

modules/express/package.json

@@ -50,6 +50,7 @@
     "debug": "^3.1.0",
     "dotenv": "^16.0.0",
     "express": "4.21.2",
+    "io-ts-types": "^0.5.16",
     "io-ts": "npm:@bitgo-forks/[email protected]",
     "io-ts-types": "^0.5.19",
     "lodash": "^4.17.20",

modules/express/src/clientRoutes.ts

@@ -636,11 +636,11 @@ export async function handleV2OFCSignPayload(
  * handle new wallet creation
  * @param req
  */
-export async function handleV2GenerateWallet(req: express.Request) {
+export async function handleV2GenerateWallet(req: ExpressApiRouteRequest<'express.wallet.generate', 'post'>) {
   const bitgo = req.bitgo;
-  const coin = bitgo.coin(req.params.coin);
-  const result = await coin.wallets().generateWallet(req.body);
-  if (req.query.includeKeychains === 'false') {
+  const coin = bitgo.coin(req.decoded.coin);
+  const result = await coin.wallets().generateWallet(req.decoded);
+  if ((req.decoded.includeKeychains as any) === false) {
     return result.wallet.toJSON();
   }
   return { ...result, wallet: result.wallet.toJSON() };
@@ -1608,7 +1608,7 @@ export function setupAPIRoutes(app: express.Application, config: Config): void {
   router.post('express.keychain.local', [prepareBitGo(config), typedPromiseWrapper(handleV2CreateLocalKeyChain)]);
 
   // generate wallet
-  app.post('/api/v2/:coin/wallet/generate', parseBody, prepareBitGo(config), promiseWrapper(handleV2GenerateWallet));
+  router.post('express.wallet.generate', [prepareBitGo(config), typedPromiseWrapper(handleV2GenerateWallet)]);
 
   router.put('express.wallet.update', [prepareBitGo(config), typedPromiseWrapper(handleWalletUpdate)]);
 

modules/express/src/typedRoutes/api/index.ts

@@ -27,6 +27,7 @@ import { PostCreateAddress } from './v2/createAddress';
 import { PutFanoutUnspents } from './v1/fanoutUnspents';
 import { PostOfcSignPayload } from './v2/ofcSignPayload';
 import { PostWalletRecoverToken } from './v2/walletRecoverToken';
+import { PostGenerateWallet } from './v2/generateWallet';
 import { PostCoinSignTx } from './v2/coinSignTx';
 import { PostWalletSignTx } from './v2/walletSignTx';
 import { PostWalletTxSignTSS } from './v2/walletTxSignTSS';
@@ -207,6 +208,9 @@ export const ExpressOfcSignPayloadApiSpec = apiSpec({
   'express.wallet.update': {
     put: PutExpressWalletUpdate,
   },
+  'express.wallet.generate': {
+    post: PostGenerateWallet,
+  },
 });
 
 export type ExpressApi = typeof ExpressPingApiSpec &

modules/express/src/typedRoutes/api/v2/generateWallet.ts

@@ -0,0 +1,115 @@
+import * as t from 'io-ts';
+import { BooleanFromString } from 'io-ts-types';
+import { httpRoute, httpRequest, optional } from '@api-ts/io-ts-http';
+import { BitgoExpressError } from '../../schemas/error';
+import { UserKeychainCodec, BackupKeychainCodec, BitgoKeychainCodec } from '../../schemas/keychain';
+import { multisigType, walletType } from '../../schemas/wallet';
+
+/**
+ * Request body for wallet generation.
+ */
+export const GenerateWalletBody = {
+  /** Wallet label */
+  label: t.string,
+  /** Enterprise id. Required for Ethereum wallets since they can only be created as part of an enterprise. Optional for other coins. */
+  enterprise: optional(t.string),
+  /** If absent, BitGo uses the default wallet type for the asset */
+  multisigType: optional(multisigType),
+  /** The type of wallet, defined by key management and signing protocols. 'hot' and 'cold' are both self-managed wallets. If absent, defaults to 'hot' */
+  type: optional(walletType),
+  /** Passphrase to be used to encrypt the user key on the wallet */
+  passphrase: optional(t.string),
+  /** User provided public key */
+  userKey: optional(t.string),
+  /** Backup extended public key */
+  backupXpub: optional(t.string),
+  /** Optional key recovery service to provide and store the backup key */
+  backupXpubProvider: optional(t.literal('dai')),
+  /** Flag for disabling wallet transaction notifications */
+  disableTransactionNotifications: optional(t.boolean),
+  /** The passphrase used for decrypting the encrypted wallet passphrase during wallet recovery */
+  passcodeEncryptionCode: optional(t.string),
+  /** Seed that derives an extended user key or common keychain for a cold wallet */
+  coldDerivationSeed: optional(t.string),
+  /** Gas price to use when deploying an Ethereum wallet */
+  gasPrice: optional(t.number),
+  /** Flag for preventing KRS from sending email after creating backup key */
+  disableKRSEmail: optional(t.boolean),
+  /** (ETH only) Specify the wallet creation contract version used when creating a wallet contract */
+  walletVersion: optional(t.number),
+  /** True, if the wallet type is a distributed-custodial. If passed, you must also pass the 'enterprise' parameter */
+  isDistributedCustody: optional(t.boolean),
+  /** BitGo key ID for self-managed cold MPC wallets */
+  bitgoKeyId: optional(t.string),
+  /** Common keychain for self-managed cold MPC wallets */
+  commonKeychain: optional(t.string),
+} as const;
+
+export const GenerateWalletResponse200 = t.union([
+  t.UnknownRecord,
+  t.type({
+    wallet: t.UnknownRecord,
+    encryptedWalletPassphrase: optional(t.string),
+    userKeychain: optional(UserKeychainCodec),
+    backupKeychain: optional(BackupKeychainCodec),
+    bitgoKeychain: optional(BitgoKeychainCodec),
+    warning: optional(t.string),
+  }),
+]);
+
+/**
+ * Response body for wallet generation.
+ */
+export const GenerateWalletResponse = {
+  /** The newly created wallet */
+  200: GenerateWalletResponse200,
+  /** Bad request */
+  400: BitgoExpressError,
+} as const;
+
+/**
+ * Path parameters for wallet generation.
+ */
+export const GenerateWalletV2Params = {
+  /** Coin ticker / chain identifier */
+  coin: t.string,
+};
+
+/**
+ * Query parameters for wallet generation.
+ * @property includeKeychains - Include user, backup and bitgo keychains along with generated wallet
+ */
+export const GenerateWalletV2Query = {
+  /** Include user, backup and bitgo keychains along with generated wallet */
+  includeKeychains: optional(BooleanFromString),
+};
+
+/**
+ * Generate Wallet
+ *
+ * This API call creates a new wallet. Under the hood, the SDK (or BitGo Express) does the following:
+ *
+ * 1. Creates the user keychain locally on the machine, and encrypts it with the provided passphrase (skipped if userKey is provided).
+ * 2. Creates the backup keychain locally on the machine.
+ * 3. Uploads the encrypted user keychain and public backup keychain.
+ * 4. Creates the BitGo key (and the backup key if backupXpubProvider is set) on the service.
+ * 5. Creates the wallet on BitGo with the 3 public keys above.
+ *
+ * ⓘ Ethereum wallets can only be created under an enterprise. Pass in the id of the enterprise to associate the wallet with. Your enterprise id can be seen by clicking on the "Manage Organization" link on the enterprise dropdown. Each enterprise has a fee address which will be used to pay for transaction fees on all Ethereum wallets in that enterprise. The fee address is displayed in the dashboard of the website, please fund it before creating a wallet.
+ *
+ * ⓘ You cannot generate a wallet by passing in a subtoken as the coin. Subtokens share wallets with their parent coin and it is not possible to create a wallet specific to one token.
+ *
+ * ⓘ This endpoint should be called through BitGo Express if used without the SDK, such as when using cURL.
+ *
+ * @operationId express.wallet.generate
+ */
+export const PostGenerateWallet = httpRoute({
+  path: '/api/v2/:coin/wallet/generate',
+  method: 'POST',
+  request: httpRequest({
+    params: GenerateWalletV2Params,
+    query: GenerateWalletV2Query,
+    body: GenerateWalletBody,
+  }),
+  response: GenerateWalletResponse,
+});

modules/express/src/typedRoutes/schemas/keychain.ts

@@ -0,0 +1,41 @@
+import * as t from 'io-ts';
+
+// Base keychain fields
+const BaseKeychainCodec = t.type({
+  id: t.string,
+  pub: t.string,
+  source: t.string,
+});
+
+// User keychain: can have encryptedPrv and prv
+export const UserKeychainCodec = t.intersection([
+  BaseKeychainCodec,
+  t.partial({
+    ethAddress: t.string,
+    coinSpecific: t.UnknownRecord,
+    encryptedPrv: t.string,
+    prv: t.string,
+  }),
+]);
+
+// Backup keychain: can have prv
+export const BackupKeychainCodec = t.intersection([
+  BaseKeychainCodec,
+  t.partial({
+    ethAddress: t.string,
+    coinSpecific: t.UnknownRecord,
+    prv: t.string,
+  }),
+]);
+
+// BitGo keychain: must have isBitGo
+export const BitgoKeychainCodec = t.intersection([
+  BaseKeychainCodec,
+  t.type({
+    isBitGo: t.boolean,
+  }),
+  t.partial({
+    ethAddress: t.string,
+    coinSpecific: t.UnknownRecord,
+  }),
+]);

modules/express/src/typedRoutes/schemas/wallet.ts

@@ -138,6 +138,10 @@ export const CustomChangeKeySignatures = t.partial({
   bitgo: t.string,
 });
 
+export const multisigType = t.union([t.literal('onchain'), t.literal('tss')]);
+
+export const walletType = t.union([t.literal('cold'), t.literal('custodial'), t.literal('hot'), t.literal('trading')]);
+
 /**
  * Wallet response data
  * Comprehensive wallet information returned from wallet operations
@@ -175,11 +179,11 @@ export const WalletResponse = t.partial({
   /** Enterprise ID this wallet belongs to */
   enterprise: t.string,
   /** Wallet type (e.g., 'hot', 'cold', 'custodial') */
-  type: t.string,
+  type: walletType,
   /** Wallet subtype (e.g., 'lightningSelfCustody') */
   subType: t.string,
   /** Multisig type ('onchain' or 'tss') */
-  multisigType: t.union([t.literal('onchain'), t.literal('tss')]),
+  multisigType: multisigType,
   /** Multisig type version (e.g., 'MPCv2') */
   multisigTypeVersion: t.string,
   /** Coin-specific wallet data */