From be9c985f7a21dce79b5bd1938a54ee4308455ef0 Mon Sep 17 00:00:00 2001 From: Lokesh Chandra Date: Thu, 20 Nov 2025 13:07:31 +0530 Subject: [PATCH] docs(express): createLocalKeyChainV1 API definition Ticket: WP-6950 --- .../typedRoutes/api/v1/createLocalKeyChain.ts | 29 ++++++++++--------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/modules/express/src/typedRoutes/api/v1/createLocalKeyChain.ts b/modules/express/src/typedRoutes/api/v1/createLocalKeyChain.ts index f897e306b5..d3c3cac1d5 100644 --- a/modules/express/src/typedRoutes/api/v1/createLocalKeyChain.ts +++ b/modules/express/src/typedRoutes/api/v1/createLocalKeyChain.ts @@ -7,9 +7,10 @@ import { BitgoExpressError } from '../../schemas/error'; */ export const CreateLocalKeyChainRequestBody = { /** - * Optional seed for key generation. If not provided, a random seed with 512 bits - * of entropy will be generated for maximum security. The seed is used to derive a BIP32 - * extended key pair. + * Optional seed for deterministic key generation. If not provided, a cryptographically + * secure random seed with 512 bits of entropy will be automatically generated. When providing + * a custom seed, ensure it has sufficient entropy and is generated using a cryptographically + * secure random number generator. */ seed: optional(t.string), }; @@ -18,26 +19,28 @@ export const CreateLocalKeyChainRequestBody = { * Response for creating a local keychain */ export const CreateLocalKeyChainResponse = t.type({ - /** The extended private key in BIP32 format (xprv...) */ + /** The extended private key in BIP32 format (xprv...). Keep this secure and never share it. */ xprv: t.string, - /** The extended public key in BIP32 format (xpub...) */ + /** The extended public key in BIP32 format (xpub...). Safe to share. */ xpub: t.string, - /** Ethereum address derived from the extended public key (only available when Ethereum utilities are accessible) */ + /** Ethereum address derived from the xpub (optional - only present when Ethereum utilities are available) */ ethAddress: optional(t.string), }); /** * Create a local keychain * - * Locally creates a new keychain using BIP32 HD (Hierarchical Deterministic) key derivation. - * This is a client-side operation that does not involve any server-side operations. + * Generates a new BIP32 HD (Hierarchical Deterministic) keychain locally on the Express server. + * This is a local key generation operation that does not communicate with the BitGo service. + * The operation is synchronous and completes immediately. * - * Returns an object containing the xprv and xpub keys in BIP32 extended key format. - * The created keychain is not known to the BitGo service. To use it with BitGo, - * you must add it using the 'Add Keychain' API call. + * Returns an object containing the xprv (private key) and xpub (public key) in BIP32 extended + * key format. The generated keychain is not registered with BitGo. To use it with BitGo wallets, + * you must add it using the 'Add Keychain' API call (note: only send the xpub, never the xprv). * - * For security reasons, it is highly recommended that you encrypt the private key - * immediately and securely destroy the unencrypted original to prevent theft. + * **Security:** The response contains the unencrypted private key (xprv). Ensure all + * communications with BitGo Express use TLS/SSL encryption. Encrypt the private key + * immediately upon receipt and securely destroy the unencrypted copy to prevent theft. * * @operationId express.v1.keychain.local * @tag express