From 1db283284d14c8288e8a09fbe06603c84142ad9e Mon Sep 17 00:00:00 2001 From: Lokesh Chandra Date: Thu, 20 Nov 2025 13:40:03 +0530 Subject: [PATCH] docs(express): simpleCreateV1 API definition Ticket: WP-6950 --- .../src/typedRoutes/api/v1/simpleCreate.ts | 61 +++++++++++++------ 1 file changed, 42 insertions(+), 19 deletions(-) diff --git a/modules/express/src/typedRoutes/api/v1/simpleCreate.ts b/modules/express/src/typedRoutes/api/v1/simpleCreate.ts index c7b837225b..b062e22e29 100644 --- a/modules/express/src/typedRoutes/api/v1/simpleCreate.ts +++ b/modules/express/src/typedRoutes/api/v1/simpleCreate.ts @@ -3,50 +3,73 @@ import { httpRoute, httpRequest, optional } from '@api-ts/io-ts-http'; import { BitgoExpressError } from '../../schemas/error'; export const SimpleCreateRequestBody = { - /** wallet passphrase to encrypt user and backup keys with */ + /** Wallet passphrase to encrypt user and backup keys with (required) */ passphrase: t.string, - /** wallet label, is shown in BitGo UI */ + /** Wallet label shown in BitGo UI */ label: optional(t.string), - /** backup keychain xpub, it is HIGHLY RECOMMENDED you generate this on a separate machine! - * BITGO DOES NOT GUARANTEE SAFETY OF WALLETS WITH MULTIPLE KEYS CREATED ON THE SAME MACHINE */ + /** Backup keychain xpub generated on a separate machine (HIGHLY RECOMMENDED for security - cannot be used with backupXpubProvider) */ backupXpub: optional(t.string), - /* Provision backup key from this provider (KRS), e.g. "keyternal". Setting this value will create an instant-capable wallet. */ + /** Key Recovery Service provider for backup key, e.g. "keyternal" (creates instant-capable wallet - cannot be used with backupXpub) */ backupXpubProvider: optional(t.string), + /** Enterprise ID to create wallet under */ enterprise: optional(t.string), - /** the code used to encrypt the wallet passcode used in the recovery process */ + /** Code used to encrypt the wallet passcode for the recovery process */ passcodeEncryptionCode: optional(t.string), + /** Disable transaction notifications for this wallet */ disableTransactionNotifications: optional(t.boolean), + /** Disable KRS email notifications (only applicable when using backupXpubProvider) */ disableKRSEmail: optional(t.boolean), }; export const SimpleCreateResponse = t.intersection([ t.type({ - /** newly created wallet model object */ + /** Newly created wallet model object with balance, label, keychains array, and other wallet properties */ wallet: t.UnknownRecord, - /** the newly created user keychain, which has an encrypted xprv stored on BitGo */ + /** User keychain with xpub and encryptedXprv (encrypted with passphrase, stored on BitGo) */ userKeychain: t.UnknownRecord, - /** the newly created backup keychain */ + /** Backup keychain with xpub (and xprv if created locally - must be backed up immediately) */ backupKeychain: t.UnknownRecord, - /** the BitGo-managed keychain */ + /** BitGo-managed keychain with xpub (BitGo holds this key) */ bitgoKeychain: t.UnknownRecord, }), t.partial({ - /** warning message when backup keychain has xprv */ + /** Warning message present only when backup keychain was created locally (has xprv) - reminds you to back it up */ warning: t.string, }), ]); /** - * Create Wallet with Keychain - * Create a new 2-of-3 wallet and it's associated keychains. - * Returns the locally created keys with their encrypted xprvs. + * Create Wallet with Keychains + * + * Creates a new 2-of-3 multisignature wallet along with all three required keychains in a single + * operation. This is a convenience method that handles the entire wallet setup process. + * * **WARNING: BE SURE TO BACKUP! NOT DOING SO CAN RESULT IN LOSS OF FUNDS!** * - * 1. Creates the user keychain locally on the client, and encrypts it with the provided passphrase - * 2. If no xpub was provided, creates the backup keychain locally on the client, and encrypts it with the provided passphrase - * 3. Uploads the encrypted user and backup keychains to BitGo - * 4. Creates the BitGo key on the service - * 5. Creates the wallet on BitGo with the 3 public keys above + * **Workflow:** + * 1. Creates the user keychain locally and encrypts it with the provided passphrase + * 2. Handles backup keychain based on parameters (see Backup Keychain Strategies below) + * 3. Uploads the encrypted user keychain and backup keychain xpub to BitGo + * 4. Creates the BitGo-managed keychain on the service + * 5. Creates the 2-of-3 multisig wallet on BitGo with all three public keys + * + * **Backup Keychain Strategies:** + * - **KRS Provider (Recommended)**: Set backupXpubProvider to use a Key Recovery Service (e.g., "keyternal") + * - Creates instant-capable wallets + * - Professional key management + * - Cannot be combined with backupXpub + * - **External Xpub (Recommended)**: Provide backupXpub generated on a separate, secure machine + * - Maximum security (keys never on same machine) + * - You control the backup key + * - Cannot be combined with backupXpubProvider + * - **Local Generation (NOT RECOMMENDED)**: If neither backupXpub nor backupXpubProvider provided + * - Creates backup key on same machine as user key (security risk) + * - Response includes warning message and unencrypted backup xprv + * - You MUST back up the backup keychain yourself + * + * **Response:** Returns wallet object and all three keychains. If backup keychain was created + * locally, response includes warning message and the backup keychain will contain xprv (which + * you must securely back up). Otherwise, backup keychain only contains xpub. * * @operationId express.v1.wallet.simplecreate * @tag express