feat: add sdk-core vault module interfaces and scaffolding

Net-new sdk-core/src/bitgo/vault module mirroring the EnterpriseData/
Enterprise and WalletData/Wallet conventions: iVault/iVaults interfaces
(per API Changes v1 §3), the Vault and Vaults classes, and the barrel.
Vault implements getters, url(), toJSON(), and freeze/archive REST
plumbing; createWallet, member, and share methods are stubbed for
WCN-1203/WCN-1204. Vaults lifecycle methods (createVault, initialize,
finalize, list, get) are stubbed pending Phase 2/3 (WCN-1175/1177).
Wires an Enterprise.vaults() accessor and the bitgo barrel export.

WCN-1192

TICKET: WCN-1192

Author: davidkaplanbitgo

modules/sdk-core/src/bitgo/enterprise/enterprise.ts

@@ -7,6 +7,7 @@ import { BitGoBase } from '../bitgoBase';
 import { EnterpriseData, EnterpriseFeatureFlag, IEnterprise } from '../enterprise';
 import { getFirstPendingTransaction } from '../internal';
 import { ListWalletOptions, Wallet } from '../wallet';
+import { Vaults } from '../vault';
 import { BitGoProofSignatures, EcdsaUtils, SerializedNtildeWithVerifiers } from '../utils/tss/ecdsa';
 import { EcdsaTypes } from '@bitgo/sdk-lib-mpc';
 import { verifyEcdhSignature } from '../ecdh';
@@ -249,4 +250,11 @@ export class Enterprise implements IEnterprise {
   hasFeatureFlags(flags: EnterpriseFeatureFlag[]): boolean {
     return flags.every((targetFlag) => this._enterprise.featureFlags?.includes(targetFlag));
   }
+
+  /**
+   * Get the vaults collection accessor scoped to this Enterprise
+   */
+  vaults(): Vaults {
+    return new Vaults(this.bitgo, this.baseCoin, this.id);
+  }
 }

modules/sdk-core/src/bitgo/enterprise/iEnterprise.ts

@@ -3,6 +3,7 @@ import { IWallet } from '../wallet';
 import { Buffer } from 'buffer';
 import { BitGoProofSignatures, SerializedNtildeWithVerifiers } from '../utils/tss/ecdsa';
 import { EcdhDerivedKeypair } from '../keychain';
+import { IVaults } from '../vault';
 
 // useEnterpriseEcdsaTssChallenge is deprecated
 export type EnterpriseFeatureFlag = 'useEnterpriseEcdsaTssChallenge';
@@ -39,4 +40,5 @@ export interface IEnterprise {
     bitgoNitroChallenge: SerializedNtildeWithVerifiers
   ): Promise<void>;
   hasFeatureFlags(flags: EnterpriseFeatureFlag[]): boolean;
+  vaults(): IVaults;
 }

modules/sdk-core/src/bitgo/index.ts

@@ -27,6 +27,7 @@ export * from './tss';
 export { sendSignatureShare } from './tss';
 export * from './types';
 export * from './utils';
+export * from './vault';
 export * from './wallet';
 export * from './webhook';
 export { bitcoinUtil };

modules/sdk-core/src/bitgo/vault/iVault.ts

@@ -0,0 +1,154 @@
+/**
+ * @prettier
+ */
+import type { FreezeOptions, Wallet, WalletShare } from '../wallet';
+
+/**
+ * The four static root-key slots of a vault, keyed by (curve, scheme):
+ * - secp256k1Multisig ① — UTXO/XRP/XTZ/TRX/EOS
+ * - ecdsaMpc          ② — EVM/Cosmos (DKLS)
+ * - eddsaMpc          ③ — SOL/SUI/NEAR/TON/APT/DOT
+ * - ed25519Multisig   ④ — ALGO/XLM/HBAR
+ */
+export type RootKeyType = 'secp256k1Multisig' | 'ecdsaMpc' | 'eddsaMpc' | 'ed25519Multisig';
+
+export type VaultPermission = 'view' | 'spend' | 'admin' | 'dapp';
+
+/**
+ * The 12 static root key ids, by (curve, scheme). Each entry is an ordered
+ * [userKeyId, backupKeyId, bitgoKeyId] triplet — same shape and order as wallet.keys[].
+ */
+export type VaultRootKeys = Record<RootKeyType, [userKeyId: string, backupKeyId: string, bitgoKeyId: string]>;
+
+export interface VaultMembershipData {
+  userId: string; // new-model naming convention
+  permissions: VaultPermission[];
+  needsRecovery?: boolean;
+}
+
+/**
+ * A pending UMS spend grant awaiting a key share — mirror of the wallet's walletShareRequests[].
+ * Returned to spenders/admins and serviced via addMember.
+ */
+export interface VaultShareRequest {
+  userId: string;
+  permissions: VaultPermission[];
+  createdAt: string;
+}
+
+export interface VaultData {
+  id: string;
+  enterpriseId: string;
+  label: string;
+  // freeze is NOT a status — a frozen vault stays 'active' with the freeze field set (wallet precedent)
+  status: 'initializing' | 'active' | 'archived';
+  creator: string;
+  users: VaultMembershipData[];
+  vaultShareRequests?: VaultShareRequest[];
+  freeze?: { time?: string; expires?: string; reason?: string };
+  rootKeys?: VaultRootKeys; // ordered, like wallet.keys
+  archivedAt?: string;
+  createdAt: string;
+}
+
+export interface InitializeVaultOptions {
+  label: string; // Phase 1 carries no key material — key generation happens in Phase 2 via the existing keychain APIs
+}
+
+// Phase 3 — the client hands back the 12 key ids it created in Phase 2:
+export interface FinalizeVaultOptions {
+  rootKeys: VaultRootKeys;
+}
+
+/** Vault key-share states — identical to WalletShare states, no new states. */
+export type VaultShareState = 'pendingapproval' | 'active' | 'accepted' | 'canceled' | 'rejected';
+
+/**
+ * One of the 4 root USER keyshares carried on a VaultShare, ECDH-re-encrypted to the recipient.
+ * Body semantics land in the Part VI SDK ticket (WCN-1204).
+ */
+export interface VaultShareKeychain {
+  rootKeyType: RootKeyType;
+  rootKeyId: string;
+  encryptedPrv: string;
+  publicIdentifier: string;
+  fromPubKey: string;
+  toPubKey: string;
+  path: string;
+}
+
+export interface VaultShareData {
+  id: string;
+  enterpriseId: string;
+  vaultId: string;
+  vaultLabel?: string;
+  fromUser: string;
+  toUser: string;
+  permissions: VaultPermission[];
+  state: VaultShareState;
+  message?: string;
+  pendingApprovalId?: string;
+  isUMSInitiated?: boolean;
+  keychains?: VaultShareKeychain[];
+  createdAt: string;
+  updatedAt?: string;
+}
+
+/**
+ * Sharing ONE vault wallet with a non-member rides the existing wallet-share handshake (FR-13),
+ * so the result is the existing WalletShare shape.
+ */
+export type WalletShareData = WalletShare;
+
+// ---- per-vault operation options (bodies land in WCN-1203 / WCN-1204) ----
+
+export interface CreateVaultWalletOptions {
+  coin: string;
+  label: string;
+  type?: string;
+  multisigType?: string;
+  multisigTypeVersion?: string;
+}
+
+export interface AddVaultMemberOptions {
+  userId?: string;
+  email?: string;
+  permissions: VaultPermission[];
+  // required when 'spend' is included — the 4 root user keys ECDH-re-encrypted to the invitee
+  keychains?: VaultShareKeychain[];
+  message?: string;
+  disableEmail?: boolean;
+}
+
+export interface AddVaultWalletMemberOptions {
+  walletId: string;
+  email?: string;
+  permissions?: string[];
+  message?: string;
+}
+
+export interface AcceptVaultShareOptions {
+  vaultShareId: string;
+  userPassword?: string;
+  newWalletPassphrase?: string;
+  overrideEncryptedPrv?: string;
+}
+
+export interface IVault {
+  id(): string;
+  enterpriseId(): string;
+  label(): string;
+  status(): VaultData['status'];
+  url(extra?: string): string;
+  createWallet(params: CreateVaultWalletOptions): Promise<Wallet>;
+  // whole-vault: view/admin/spend; spend opens a key share (also how a spender services a
+  // vaultShareRequests entry in UMS orgs)
+  addMember(params: AddVaultMemberOptions): Promise<VaultData>;
+  // share ONE vault wallet (FR-13), not the whole vault
+  addMemberToWallet(params: AddVaultWalletMemberOptions): Promise<WalletShareData>;
+  listShares(params?: { state?: VaultShareState }): Promise<VaultShareData[]>;
+  acceptShare(params: AcceptVaultShareOptions): Promise<VaultShareData>;
+  freeze(params?: FreezeOptions): Promise<VaultData>;
+  archive(): Promise<VaultData>;
+  toJSON(): VaultData;
+}

modules/sdk-core/src/bitgo/vault/iVaults.ts

@@ -0,0 +1,36 @@
+/**
+ * @prettier
+ */
+import { InitializeVaultOptions, FinalizeVaultOptions } from './iVault';
+import { Vault } from './vault';
+
+/**
+ * Options for the createVault orchestrator.
+ *
+ * v1 targets the HOT custody model only: the multisig root user/backup keys are generated locally
+ * by the SDK, encrypted with `passphrase`, and registered on BitGo; the MPC roots run the standard
+ * hot ceremonies with the same passphrase. Self-managed cold keys and custodial vaults are out of
+ * scope for v1.
+ */
+export interface CreateVaultOptions {
+  label: string;
+  passphrase: string; // encrypts the locally-generated multisig user/backup prvs; shared with the MPC ceremonies
+}
+
+export interface ListVaultsOptions {
+  cursor?: string; // opaque cursor from a previous response's nextCursor
+  limit?: number;
+}
+
+export interface GetVaultOptions {
+  id: string;
+}
+
+export interface IVaults {
+  // orchestrates: initialize → 4 root key flows (vaultId-tagged) → finalize → keycard
+  createVault(params: CreateVaultOptions): Promise<Vault>;
+  initializeVault(params: InitializeVaultOptions): Promise<Vault>;
+  finalizeVault(vaultId: string, params: FinalizeVaultOptions): Promise<Vault>;
+  list(params?: ListVaultsOptions): Promise<{ vaults: Vault[]; nextCursor?: string }>;
+  get(params: GetVaultOptions): Promise<Vault>;
+}

modules/sdk-core/src/bitgo/vault/index.ts

@@ -0,0 +1,4 @@
+export * from './iVault';
+export * from './iVaults';
+export * from './vault';
+export * from './vaults';

modules/sdk-core/src/bitgo/vault/vault.ts

@@ -0,0 +1,123 @@
+/**
+ * @prettier
+ */
+import * as _ from 'lodash';
+import { IBaseCoin } from '../baseCoin';
+import { BitGoBase } from '../bitgoBase';
+import { FreezeOptions, Wallet } from '../wallet';
+import {
+  AcceptVaultShareOptions,
+  AddVaultMemberOptions,
+  AddVaultWalletMemberOptions,
+  CreateVaultWalletOptions,
+  IVault,
+  VaultData,
+  VaultShareData,
+  VaultShareState,
+  WalletShareData,
+} from './iVault';
+
+export class Vault implements IVault {
+  private readonly bitgo: BitGoBase;
+  private readonly baseCoin: IBaseCoin;
+  public readonly _vault: VaultData;
+
+  constructor(bitgo: BitGoBase, baseCoin: IBaseCoin, vaultData: VaultData) {
+    this.bitgo = bitgo;
+    this.baseCoin = baseCoin;
+    if (!_.isObject(vaultData)) {
+      throw new Error('vaultData has to be an object');
+    }
+    if (!_.isString(vaultData.id)) {
+      throw new Error('vault id has to be a string');
+    }
+    if (!_.isString(vaultData.enterpriseId)) {
+      throw new Error('vault enterpriseId has to be a string');
+    }
+    this._vault = vaultData;
+  }
+
+  id(): string {
+    return this._vault.id;
+  }
+
+  enterpriseId(): string {
+    return this._vault.enterpriseId;
+  }
+
+  label(): string {
+    return this._vault.label;
+  }
+
+  status(): VaultData['status'] {
+    return this._vault.status;
+  }
+
+  /**
+   * Enterprise-scoped v2 URL for this vault, e.g. /api/v2/enterprise/:eId/vaults/:vId
+   * @param extra
+   */
+  url(extra = ''): string {
+    return this.bitgo.url(`/enterprise/${this.enterpriseId()}/vaults/${this.id()}${extra}`, 2);
+  }
+
+  /**
+   * Mint a child wallet in this vault (server-side public derivation — no ceremony).
+   * Body lands in WCN-1203.
+   */
+  async createWallet(params: CreateVaultWalletOptions): Promise<Wallet> {
+    throw new Error('Vault.createWallet is not yet implemented (WCN-1203)');
+  }
+
+  /**
+   * Add a member to the whole vault (view/admin/spend). Spend opens a key share.
+   * Body lands in WCN-1204.
+   */
+  async addMember(params: AddVaultMemberOptions): Promise<VaultData> {
+    throw new Error('Vault.addMember is not yet implemented (WCN-1204)');
+  }
+
+  /**
+   * Share ONE vault wallet with a non-member via the existing wallet-share handshake (FR-13).
+   * Body lands in WCN-1204.
+   */
+  async addMemberToWallet(params: AddVaultWalletMemberOptions): Promise<WalletShareData> {
+    throw new Error('Vault.addMemberToWallet is not yet implemented (WCN-1204)');
+  }
+
+  /**
+   * List the vault key shares visible to the caller.
+   * Body lands in WCN-1204.
+   */
+  async listShares(params: { state?: VaultShareState } = {}): Promise<VaultShareData[]> {
+    throw new Error('Vault.listShares is not yet implemented (WCN-1204)');
+  }
+
+  /**
+   * Accept a vault key share addressed to the caller.
+   * Body lands in WCN-1204.
+   */
+  async acceptShare(params: AcceptVaultShareOptions): Promise<VaultShareData> {
+    throw new Error('Vault.acceptShare is not yet implemented (WCN-1204)');
+  }
+
+  /**
+   * Freeze the vault — blocks withdrawals on all vault wallets. Vault stays 'active'.
+   * @param params
+   */
+  async freeze(params: FreezeOptions = {}): Promise<VaultData> {
+    return (await this.bitgo.post(this.url('/freeze')).send(params).result()) as VaultData;
+  }
+
+  /**
+   * Archive the vault. Requires every vault wallet to already be archived; also the abandonment
+   * path for a stuck 'initializing' vault.
+   */
+  async archive(): Promise<VaultData> {
+    return (await this.bitgo.post(this.url('/archive')).send().result()) as VaultData;
+  }
+
+  toJSON(): VaultData {
+    return this._vault;
+  }
+}