Merge branch 'master' into WP-5416-express-migrate-api-v2-coin-wallet-id-to-typed-route

TICKET: WP-5416

Author: danielzhao122

commitlint.config.js

@@ -65,6 +65,7 @@ module.exports = {
         'COIN-',
         'FIAT-',
         'ME-',
+        'ANT-',
         '#', // Prefix used by GitHub issues
       ],
     },

examples/ts/create-go-account.ts

@@ -0,0 +1,67 @@
+/**
+ * Create a Go Account wallet at BitGo.
+ * This makes use of the convenience function generateWallet with type: 'trading'
+ *
+ * IMPORTANT: You must backup the encrypted private key and encrypted wallet passphrase!
+ *
+ * Copyright 2025, BitGo, Inc.  All Rights Reserved.
+ */
+
+import { BitGoAPI } from '@bitgo/sdk-api';
+import { coins } from 'bitgo';
+require('dotenv').config({ path: '../../.env' });
+
+const bitgo = new BitGoAPI({
+  accessToken: process.env.TESTNET_ACCESS_TOKEN,
+  env: 'test', // Change this to env: 'production' when you are ready for production
+});
+
+// Go Accounts use the 'ofc' (Off-Chain) coin
+const coin = 'ofc';
+bitgo.register(coin, coins.Ofc.createInstance);
+
+// TODO: set a label for your new Go Account here
+const label = 'Example Go Account Wallet';
+
+// TODO: set your passphrase for your new wallet here (encrypts the private key)
+const passphrase = 'go_account_wallet_passphrase';
+
+// TODO: set your passcode encryption code here (encrypts the passphrase itself)
+const passcodeEncryptionCode = 'encryption_code_for_passphrase';
+
+// TODO: set your enterprise ID for your new wallet here
+const enterprise = 'your_enterprise_id';
+
+async function main() {
+  const response = await bitgo.coin(coin).wallets().generateWallet({
+    label,
+    passphrase,
+    passcodeEncryptionCode,
+    enterprise,
+    type: 'trading', // Required for Go Accounts
+  });
+
+  // Type guard to ensure we got a Go Account response
+  if (!('userKeychain' in response)) {
+    throw new Error('Go account missing required user keychain');
+  }
+
+  const { wallet, userKeychain, encryptedWalletPassphrase } = response;
+
+  console.log(`Wallet ID: ${wallet.id()}`);
+
+  console.log('BACKUP THE FOLLOWING INFORMATION: ');
+  console.log('User Keychain:');
+  console.log(`Keychain ID: ${userKeychain.id}`);
+  console.log(`Public Key: ${userKeychain.pub}`);
+  console.log(`Encrypted Private Key: ${userKeychain.encryptedPrv}`);
+
+  console.log(`Encrypted Wallet Passphrase: ${encryptedWalletPassphrase}`);
+
+  // Create receive address for Go Account
+  const receiveAddress = await wallet.createAddress();
+  console.log('Go Account Receive Address:', receiveAddress.address);
+}
+
+main().catch((e) => console.error('Error creating Go Account:', e));
+

examples/ts/share-wallet.ts

@@ -22,14 +22,14 @@ bitgo.register(coin, Tbtc.createInstance);
 const walletId = '';
 
 // TODO: set BitGo account email of wallet share recipient
-const recipient = null;
+const recipient = "recipient_email";
 
 // TODO: set share permissions as a comma-separated list
 // Valid permissions to choose from are: view, spend, manage, admin
 const perms = 'view';
 
 // TODO: provide the passphrase for the wallet being shared
-const passphrase = null;
+const passphrase = "passhrase";
 
 async function main() {
   const wallet = await bitgo.coin(coin).wallets().get({ id: walletId });

modules/account-lib/src/index.ts

@@ -331,6 +331,10 @@ const coinMessageBuilderFactoryMap = {
   tada: Ada.MessageBuilderFactory,
   sol: Sol.MessageBuilderFactory,
   tsol: Sol.MessageBuilderFactory,
+  arbeth: Eth.MessageBuilderFactory,
+  tarbeth: Eth.MessageBuilderFactory,
+  opeth: Eth.MessageBuilderFactory,
+  topeth: Eth.MessageBuilderFactory,
 };
 
 coins

modules/bitgo/test/v2/unit/wallets.ts

@@ -515,6 +515,51 @@ describe('V2 Wallets:', function () {
         params.passphrase
       );
     });
+
+    it('should generate Go Account wallet', async () => {
+      const ofcWallets = bitgo.coin('ofc').wallets();
+
+      const params: GenerateWalletOptions = {
+        label: 'Go Account Wallet',
+        passphrase: 'go_account_password',
+        enterprise: 'enterprise-id',
+        passcodeEncryptionCode: 'originalPasscodeEncryptionCode',
+        type: 'trading',
+      };
+
+      const keychainId = 'user_keychain_id';
+
+      // Mock keychain creation and upload
+      nock(bgUrl)
+        .post('/api/v2/ofc/key', function (body) {
+          body.should.have.property('encryptedPrv');
+          body.should.have.property('originalPasscodeEncryptionCode');
+          body.keyType.should.equal('independent');
+          body.source.should.equal('user');
+          return true;
+        })
+        .reply(200, { id: keychainId, pub: 'userPub', encryptedPrv: 'encryptedPrivateKey' });
+
+      // Mock wallet creation
+      const walletNock = nock(bgUrl)
+        .post('/api/v2/ofc/wallet/add', function (body) {
+          body.type.should.equal('trading');
+          body.m.should.equal(1);
+          body.n.should.equal(1);
+          body.keys.should.have.length(1);
+          body.keys[0].should.equal(keychainId);
+          return true;
+        })
+        .reply(200, { id: 'wallet123', keys: [keychainId] });
+
+      const response = await ofcWallets.generateWallet(params);
+
+      walletNock.isDone().should.be.true();
+
+      assert.ok(response.encryptedWalletPassphrase);
+      assert.ok(response.wallet);
+      assert.ok('userKeychain' in response);
+    });
   });
 
   describe('Generate TSS wallet:', function () {

modules/express/src/clientRoutes.ts

@@ -687,11 +687,11 @@ export function handleV2CreateLocalKeyChain(req: ExpressApiRouteRequest<'express
  * handle wallet share
  * @param req
  */
-async function handleV2ShareWallet(req: express.Request) {
+export async function handleV2ShareWallet(req: ExpressApiRouteRequest<'express.v2.wallet.share', 'post'>) {
   const bitgo = req.bitgo;
-  const coin = bitgo.coin(req.params.coin);
-  const wallet = await coin.wallets().get({ id: req.params.id });
-  return wallet.shareWallet(req.body);
+  const coin = bitgo.coin(req.decoded.coin);
+  const wallet = await coin.wallets().get({ id: req.decoded.id });
+  return wallet.shareWallet(req.decoded);
 }
 
 /**
@@ -1621,8 +1621,7 @@ export function setupAPIRoutes(app: express.Application, config: Config): void {
 
   router.post('express.v2.wallet.createAddress', [prepareBitGo(config), typedPromiseWrapper(handleV2CreateAddress)]);
 
-  // share wallet
-  app.post('/api/v2/:coin/wallet/:id/share', parseBody, prepareBitGo(config), promiseWrapper(handleV2ShareWallet));
+  router.post('express.v2.wallet.share', [prepareBitGo(config), typedPromiseWrapper(handleV2ShareWallet)]);
   app.post(
     '/api/v2/:coin/walletshare/:id/acceptshare',
     parseBody,

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

@@ -29,6 +29,7 @@ import { PostWalletRecoverToken } from './v2/walletRecoverToken';
 import { PostCoinSignTx } from './v2/coinSignTx';
 import { PostWalletSignTx } from './v2/walletSignTx';
 import { PostWalletTxSignTSS } from './v2/walletTxSignTSS';
+import { PostShareWallet } from './v2/shareWallet';
 import { PutExpressWalletUpdate } from './v2/expressWalletUpdate';
 
 export const ExpressApi = apiSpec({
@@ -113,6 +114,9 @@ export const ExpressApi = apiSpec({
   'express.v2.wallet.signtxtss': {
     post: PostWalletTxSignTSS,
   },
+  'express.v2.wallet.share': {
+    post: PostShareWallet,
+  },
   'express.wallet.update': {
     put: PutExpressWalletUpdate,
   },

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

@@ -0,0 +1,88 @@
+import * as t from 'io-ts';
+import { httpRoute, httpRequest, optional } from '@api-ts/io-ts-http';
+import { BitgoExpressError } from '../../schemas/error';
+import { ShareState, ShareWalletKeychain } from '../../schemas/wallet';
+
+/**
+ * Path parameters for sharing a wallet
+ */
+export const ShareWalletParams = {
+  /** Coin ticker / chain identifier */
+  coin: t.string,
+  /** Wallet ID */
+  id: t.string,
+} as const;
+
+/**
+ * Request body for sharing a wallet
+ */
+export const ShareWalletBody = {
+  /** Recipient email address */
+  email: t.string,
+  /** Permissions string, e.g., "view,spend" */
+  permissions: t.string,
+  /** Wallet passphrase used to derive shared key when needed */
+  walletPassphrase: optional(t.string),
+  /** Optional message to include with the share */
+  message: optional(t.string),
+  /** If true, allows sharing without a keychain */
+  reshare: optional(t.boolean),
+  /** If true, skips sharing the wallet keychain with the recipient */
+  skipKeychain: optional(t.boolean),
+  /** If true, suppresses email notification to the recipient */
+  disableEmail: optional(t.boolean),
+} as const;
+
+/**
+ * Response for sharing a wallet
+ */
+export const ShareWalletResponse200 = t.intersection([
+  t.type({
+    /** Wallet share id */
+    id: t.string,
+    /** Coin of the wallet */
+    coin: t.string,
+    /** Wallet id */
+    wallet: t.string,
+    /** Id of the sharer */
+    fromUser: t.string,
+    /** Id of the recipient */
+    toUser: t.string,
+    /** Comma-separated list of privileges for wallet */
+    permissions: t.string,
+  }),
+  t.partial({
+    /** Wallet label */
+    walletLabel: t.string,
+    /** User-readable message */
+    message: t.string,
+    /** Share state */
+    state: ShareState,
+    /** Enterprise id, if applicable */
+    enterprise: t.string,
+    /** Pending approval id, if one was generated */
+    pendingApprovalId: t.string,
+    /** Included if shared with spend permission */
+    keychain: ShareWalletKeychain,
+  }),
+]);
+
+export const ShareWalletResponse = {
+  200: ShareWalletResponse200,
+  400: BitgoExpressError,
+} as const;
+
+/**
+ * Share this wallet with another BitGo user.
+ *
+ * @operationId express.v2.wallet.share
+ */
+export const PostShareWallet = httpRoute({
+  path: '/api/v2/{coin}/wallet/{id}/share',
+  method: 'POST',
+  request: httpRequest({
+    params: ShareWalletParams,
+    body: ShareWalletBody,
+  }),
+  response: ShareWalletResponse,
+});

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

@@ -1,5 +1,21 @@
 import * as t from 'io-ts';
 
+export const ShareState = t.union([
+  t.literal('pendingapproval'),
+  t.literal('active'),
+  t.literal('accepted'),
+  t.literal('canceled'),
+  t.literal('rejected'),
+]);
+
+export const ShareWalletKeychain = t.partial({
+  pub: t.string,
+  encryptedPrv: t.string,
+  fromPubKey: t.string,
+  toPubKey: t.string,
+  path: t.string,
+});
+
 /**
  * Wallet user with permissions
  */