Merge pull request #8405 from BitGo/wal-439-document-reducedencryptedprv-private-key-material

docs(mpc): document that reducedEncryptedPrv contains private key material

Author: aali-1

modules/sdk-core/src/bitgo/keychain/iKeychains.ts

@@ -32,7 +32,9 @@ export interface Keychain {
   provider?: string;
   encryptedPrv?: string;
   // Required for MPCV2 keys where we reduce the amount of data needed for the keycard.
-  // This is only generated client side and is not sent to WP
+  // Contains the party's private scalar (s_i) as private key material, CBOR-encoded
+  // and encrypted with the wallet passphrase. This is only generated client side and
+  // is not sent to WP.
   reducedEncryptedPrv?: string;
   derivationPath?: string;
   derivedFromParentWithSeed?: string;

modules/sdk-core/src/bitgo/utils/tss/ecdsa/ecdsaMPCv2.ts

@@ -365,6 +365,10 @@ export class EcdsaMPCv2Utils extends BaseEcdsaUtils {
           input: privateMaterial.toString('base64'),
           password: passphrase,
         });
+        // Encrypts the CBOR-encoded ReducedKeyShare (which contains the party's private
+        // scalar s_i) with the wallet passphrase. The result is stored as reducedEncryptedPrv
+        // on the key card QR code and represents a second copy of private key material
+        // beyond the server-stored encryptedPrv.
         reducedEncryptedPrv = this.bitgo.encrypt({
           // Buffer.toString('base64') can not be used here as it does not work on the browser.
           // The browser deals with a Buffer as Uint8Array, therefore in the browser .toString('base64') just creates a comma seperated string of the array values.

modules/sdk-lib-mpc/src/tss/ecdsa-dkls/dkg.ts

@@ -184,6 +184,11 @@ export class Dkg {
     return this.keyShareBuff;
   }
 
+  /**
+   * Returns a CBOR-encoded ReducedKeyShare buffer containing the party's private
+   * scalar (s_i) in the `prv` field. This buffer is private key material.
+   * The caller encrypts it and stores it as `reducedEncryptedPrv` on the key card QR code.
+   */
   getReducedKeyShare(): Buffer {
     if (!this.keyShareBuff) {
       throw Error('Can not get key share, DKG is not complete yet.');

modules/sdk-lib-mpc/src/tss/ecdsa-dkls/types.ts

@@ -60,6 +60,16 @@ export type RetrofitData = {
   xiList?: number[][];
 };
 
+/**
+ * A CBOR-encoded subset of an MPCv2 (DKLS) key share stored on the key card.
+ *
+ * @property bigSList - Public commitments S_i = s_i * G for each party.
+ * @property xList - Evaluation points (x-coordinates for Lagrange interpolation).
+ * @property rootChainCode - Root chain code for HD derivation.
+ * @property prv - The party's private scalar s_i. This is private key material;
+ *   possession of this value allows the holder to act as this party in signing.
+ * @property pub - The party's public key.
+ */
 export const ReducedKeyShareType = t.type({
   bigSList: t.array(t.array(t.number)),
   xList: t.array(t.array(t.number)),