@bsv/wallet-toolbox 2.9.0 → 2.10.0

package/out/src/CWIStyleWalletManager.js

@@ -4,6 +4,7 @@ exports.CWIStyleWalletManager = exports.OverlayUMPTokenInteractor = exports.UMPT
 const sdk_1 = require("@bsv/sdk");
 const PrivilegedKeyManager_1 = require("./sdk/PrivilegedKeyManager");
 const hashWasm_1 = require("./utility/hashWasm");
+const CWI_COMPONENT = 'wallet-toolbox.cwi-manager';
 /**
  * Number of rounds used in PBKDF2 for deriving password keys.
  */
@@ -40,14 +41,10 @@ function isValidKdfConfig(kdf) {
         isPositiveIntegerInRange(kdf.hashLength, exports.KDF_MAX_HASH_LENGTH));
 }
 function findKdfVersionFieldIndex(protocolFields) {
-    const hasMetadataWithProfiles = protocolFields.length >= 15 &&
-        protocolFields[12]?.length === 1 &&
-        protocolFields[12][0] === 3;
+    const hasMetadataWithProfiles = protocolFields.length >= 15 && protocolFields[12]?.length === 1 && protocolFields[12][0] === 3;
     if (hasMetadataWithProfiles)
         return 12;
-    const hasMetadataWithoutProfiles = protocolFields.length >= 14 &&
-        protocolFields[11]?.length === 1 &&
-        protocolFields[11][0] === 3;
+    const hasMetadataWithoutProfiles = protocolFields.length >= 14 && protocolFields[11]?.length === 1 && protocolFields[11][0] === 3;
     return hasMetadataWithoutProfiles ? 11 : -1;
 }
 function addProfilesField(token, protocolFields, kdfVersionFieldIndex) {
@@ -284,11 +281,11 @@ class OverlayUMPTokenInteractor {
      * @param hash The 32-byte SHA-256 hash of the presentation key.
      * @returns A UMPToken object (including currentOutpoint) if found, otherwise undefined.
      */
-    async findByPresentationKeyHash(hash) {
-        return await this.findToken({
+    async findByPresentationKeyHash(hash, options) {
+        return this.findToken({
             service: 'ls_users',
             query: { presentationHash: sdk_1.Utils.toHex(hash) }
-        }, 'presentation');
+        }, 'presentation', options);
     }
     /**
      * Finds a UMP token on-chain by the given recovery key hash, if it exists.
@@ -297,13 +294,13 @@ class OverlayUMPTokenInteractor {
      * @param hash The 32-byte SHA-256 hash of the recovery key.
      * @returns A UMPToken object (including currentOutpoint) if found, otherwise undefined.
      */
-    async findByRecoveryKeyHash(hash) {
-        return await this.findToken({
+    async findByRecoveryKeyHash(hash, options) {
+        return this.findToken({
             service: 'ls_users',
             query: { recoveryHash: sdk_1.Utils.toHex(hash) }
-        }, 'recovery');
+        }, 'recovery', options);
     }
-    async findToken(question, lookupKind) {
+    async findToken(question, lookupKind, options) {
         const correlationId = this.telemetry.enabled === true ? this.telemetry.createCorrelationId() : undefined;
         const startedAt = Date.now();
         this.telemetry.capture({
@@ -321,11 +318,11 @@ class OverlayUMPTokenInteractor {
             });
         }
         catch (error) {
-            const diagnostics = this.emptyLookupDiagnostics(correlationId);
-            this.captureLookupFailure(lookupKind, 'lookup-unavailable', diagnostics, startedAt, error);
+            const diagnostics = this.emptyStats(correlationId);
+            this.lookupFailed(lookupKind, 'lookup-unavailable', diagnostics, startedAt, error);
             throw new UMPTokenLookupError('lookup-unavailable', diagnostics, { cause: error });
         }
-        const diagnostics = this.toLookupDiagnostics(resolution);
+        const diagnostics = this.diagnosticsFor(resolution);
         const tokens = this.parseLookupAnswers(resolution.answer);
         const expectedHash = question.query[lookupKind === 'presentation' ? 'presentationHash' : 'recoveryHash'].toLowerCase();
         const matchingTokens = tokens.filter(token => sdk_1.Utils.toHex(lookupKind === 'presentation' ? token.presentationHash : token.recoveryHash).toLowerCase() ===
@@ -340,28 +337,35 @@ class OverlayUMPTokenInteractor {
         if (matchingTokens.length > 1) {
             const newest = this.resolveNewestToken(matchingTokens, resolution.answer.outputs);
             if (newest != null) {
-                this.captureLookupCompleted(lookupKind, 'found', diagnostics, startedAt, {
+                this.lookupDone(lookupKind, 'found', diagnostics, startedAt, {
                     supersededTokens: matchingTokens.length - 1
                 });
                 return newest;
             }
+            const pinned = options?.pinnedOutpoint
+                ? matchingTokens.find(token => token.currentOutpoint === options.pinnedOutpoint)
+                : undefined;
+            if (pinned != null) {
+                this.lookupDone(lookupKind, 'found', diagnostics, startedAt);
+                return pinned;
+            }
             const reason = 'token-ambiguous';
-            this.captureLookupFailure(lookupKind, reason, diagnostics, startedAt);
+            this.lookupFailed(lookupKind, reason, diagnostics, startedAt);
             throw new UMPTokenLookupError(reason, diagnostics);
         }
         if (matchingTokens.length === 1) {
-            this.captureLookupCompleted(lookupKind, 'found', diagnostics, startedAt);
+            this.lookupDone(lookupKind, 'found', diagnostics, startedAt);
             return matchingTokens[0];
         }
         // A clean empty response is sufficient negative evidence once no verified
         // token exists. Malformed outputs and failed peers are ignored so they cannot
         // deny onboarding by advertising corrupt data or remaining unavailable.
         if (resolution.progress.emptyHosts > 0) {
-            this.captureLookupCompleted(lookupKind, 'not-found', diagnostics, startedAt);
+            this.lookupDone(lookupKind, 'not-found', diagnostics, startedAt);
             return undefined;
         }
         const reason = resolution.answer.outputs.length > 0 ? 'token-malformed' : 'lookup-incomplete';
-        this.captureLookupFailure(lookupKind, reason, diagnostics, startedAt);
+        this.lookupFailed(lookupKind, reason, diagnostics, startedAt);
         throw new UMPTokenLookupError(reason, diagnostics);
     }
     /**
@@ -395,7 +399,7 @@ class OverlayUMPTokenInteractor {
                     continue;
                 const evidence = evidenceByCandidate.get(outpoint) ?? { txs: [], spent: new Set() };
                 evidence.txs.push(tx);
-                this.collectSpentOutpoints(tx, evidence.spent, new Set());
+                this.collectSpends(tx, evidence.spent, new Set());
                 evidenceByCandidate.set(outpoint, evidence);
             }
             catch {
@@ -418,7 +422,7 @@ class OverlayUMPTokenInteractor {
         const provenContinuations = survivors.filter(outpoint => {
             const evidence = evidenceByCandidate.get(outpoint);
             const token = candidates.get(outpoint);
-            return (evidence != null && token != null && evidence.txs.some(tx => this.consumesSameIdentityToken(tx, token)));
+            return evidence != null && token != null && evidence.txs.some(tx => this.consumesIdentity(tx, token));
         });
         if (provenContinuations.length !== 1)
             return undefined;
@@ -430,7 +434,7 @@ class OverlayUMPTokenInteractor {
      * hash — on-chain proof that the candidate is an update of a same-identity
      * predecessor rather than an independently minted token.
      */
-    consumesSameIdentityToken(tx, token) {
+    consumesIdentity(tx, token) {
         const presentationHash = sdk_1.Utils.toHex(token.presentationHash);
         const recoveryHash = sdk_1.Utils.toHex(token.recoveryHash);
         for (const input of tx.inputs) {
@@ -463,7 +467,7 @@ class OverlayUMPTokenInteractor {
      * renditions are absent from the lookup answer. Iterative so arbitrarily
      * long update chains cannot exhaust the call stack.
      */
-    collectSpentOutpoints(tx, spent, visited) {
+    collectSpends(tx, spent, visited) {
         const pending = [tx];
         while (pending.length > 0) {
             const current = pending.pop();
@@ -482,7 +486,7 @@ class OverlayUMPTokenInteractor {
             }
         }
     }
-    emptyLookupDiagnostics(correlationId) {
+    emptyStats(correlationId) {
         return {
             hostCount: 0,
             completedHosts: 0,
@@ -495,7 +499,7 @@ class OverlayUMPTokenInteractor {
             ...(correlationId !== undefined ? { correlationId } : {})
         };
     }
-    toLookupDiagnostics(resolution) {
+    diagnosticsFor(resolution) {
         const progress = resolution.progress;
         return {
             hostCount: progress.hostCount,
@@ -509,7 +513,7 @@ class OverlayUMPTokenInteractor {
             ...(progress.correlationId !== undefined ? { correlationId: progress.correlationId } : {})
         };
     }
-    lookupDiagnosticAttributes(diagnostics) {
+    lookupAttrs(diagnostics) {
         return {
             hostCount: diagnostics.hostCount,
             completedHosts: diagnostics.completedHosts,
@@ -521,7 +525,7 @@ class OverlayUMPTokenInteractor {
             outputCount: diagnostics.outputCount
         };
     }
-    captureLookupCompleted(lookupKind, result, diagnostics, startedAt, extraAttributes = {}) {
+    lookupDone(lookupKind, result, diagnostics, startedAt, extraAttributes = {}) {
         this.telemetry.capture({
             name: 'wallet-toolbox.ump.lookup.completed',
             component: 'wallet-toolbox.ump',
@@ -531,12 +535,12 @@ class OverlayUMPTokenInteractor {
                 lookupKind,
                 result,
                 durationMs: Date.now() - startedAt,
-                ...this.lookupDiagnosticAttributes(diagnostics),
+                ...this.lookupAttrs(diagnostics),
                 ...extraAttributes
             }
         });
     }
-    captureLookupFailure(lookupKind, reason, diagnostics, startedAt, error) {
+    lookupFailed(lookupKind, reason, diagnostics, startedAt, error) {
         this.telemetry.capture({
             name: 'wallet-toolbox.ump.lookup.indeterminate',
             component: 'wallet-toolbox.ump',
@@ -546,7 +550,7 @@ class OverlayUMPTokenInteractor {
                 lookupKind,
                 reason,
                 durationMs: Date.now() - startedAt,
-                ...this.lookupDiagnosticAttributes(diagnostics)
+                ...this.lookupAttrs(diagnostics)
             },
             error
         });
@@ -566,13 +570,13 @@ class OverlayUMPTokenInteractor {
     async buildAndSend(wallet, // This wallet MUST be the one built for the default profile
     adminOriginator, token, oldTokenToConsume) {
         // 1) Construct the data fields and PushDrop locking script for the new UMP token.
-        const fields = this.buildUMPTokenFields(token);
+        const fields = this.tokenFields(token);
         const script = await new sdk_1.PushDrop(wallet, adminOriginator).lock(fields, [2, 'admin user management token'], '1', 'self', 
         /* forSelf= */ true, 
         /* includeSignature= */ true);
         const tokenOutput = [{ lockingScript: script.toHex(), satoshis: 1, outputDescription: 'New UMP token output' }];
         // 2) Resolve the old-token input (if provided) and create the action.
-        const { resolvedOldToken, inputToken } = await this.resolveOldTokenInput(oldTokenToConsume);
+        const { resolvedOldToken, inputToken } = await this.resolveOldInput(oldTokenToConsume);
         const inputs = resolvedOldToken?.currentOutpoint
             ? [
                 {
@@ -582,21 +586,21 @@ class OverlayUMPTokenInteractor {
                 }
             ]
             : [];
-        const createResult = await this.createUMPAction(wallet, adminOriginator, inputs, tokenOutput, inputToken, resolvedOldToken);
+        const createResult = await this.createAction(wallet, adminOriginator, inputs, tokenOutput, inputToken, resolvedOldToken);
         // 3) If the wallet fully processed it (no signable tx), broadcast and return.
         if (!createResult.signableTransaction) {
-            return await this.broadcastFinishedUMPAction(createResult);
+            return this.broadcastFinal(createResult);
         }
         // 4) Sign and broadcast: with old token input or without.
         const reference = createResult.signableTransaction.reference;
         const partialTx = sdk_1.Transaction.fromBEEF(createResult.signableTransaction.tx);
         if (resolvedOldToken?.currentOutpoint) {
-            return await this.signAndBroadcastWithOldToken(wallet, adminOriginator, reference, partialTx);
+            return this.renewToken(wallet, adminOriginator, reference, partialTx);
         }
-        return await this.signAndBroadcastNewToken(wallet, adminOriginator, reference);
+        return this.broadcastNew(wallet, adminOriginator, reference);
     }
     /** Assembles the ordered number[][] fields array from a UMPToken. */
-    buildUMPTokenFields(token) {
+    tokenFields(token) {
         const fields = [];
         fields[0] = token.passwordSalt;
         fields[1] = token.passwordPresentationPrimary;
@@ -627,17 +631,17 @@ class OverlayUMPTokenInteractor {
         return fields;
     }
     /** Looks up the old token on the overlay; returns undefined resolved token if not found. */
-    async resolveOldTokenInput(oldTokenToConsume) {
+    async resolveOldInput(oldTokenToConsume) {
         if (!oldTokenToConsume?.currentOutpoint)
             return { resolvedOldToken: undefined, inputToken: undefined };
         const inputToken = await this.findByOutpoint(oldTokenToConsume.currentOutpoint);
         if (inputToken == null) {
-            throw new Error('The previous UMP token could not be resolved; refusing to publish a duplicate token.');
+            throw new Error('Previous UMP token unavailable; update refused.');
         }
         return { resolvedOldToken: oldTokenToConsume, inputToken };
     }
     /** Creates the UMP action without dropping a required old-token input on failure. */
-    async createUMPAction(wallet, adminOriginator, inputs, outputs, inputToken, resolvedOldToken) {
+    async createAction(wallet, adminOriginator, inputs, outputs, inputToken, resolvedOldToken) {
         try {
             return await wallet.createAction({
                 description: resolvedOldToken == null ? 'Create new UMP token' : 'Renew UMP token (consume old, create new)',
@@ -662,44 +666,44 @@ class OverlayUMPTokenInteractor {
         }
     }
     /** Handles a fully-finalized (no signable tx) createAction result — broadcasts and returns outpoint. */
-    async broadcastFinishedUMPAction(createResult) {
+    async broadcastFinal(createResult) {
         const finalTxid = createResult.txid || (createResult.tx != null ? sdk_1.Transaction.fromAtomicBEEF(createResult.tx).id('hex') : undefined);
         if (!finalTxid)
-            throw new Error('No signableTransaction and no final TX found.');
+            throw new Error('UMP transaction was not finalized.');
         if (createResult.tx == null)
-            throw new Error('No final TX data to broadcast.');
+            throw new Error('UMP transaction data missing.');
         const broadcastTx = sdk_1.Transaction.fromAtomicBEEF(createResult.tx);
         const result = await this.broadcaster.broadcast(broadcastTx);
-        this.assertSuccessfulBroadcast(result, 'create-finalized');
+        this.assertBroadcast(result, 'create-finalized');
         return `${finalTxid}.0`;
     }
     /** Signs the old-token input and broadcasts — used during UMP token renewal. */
-    async signAndBroadcastWithOldToken(wallet, adminOriginator, reference, partialTx) {
+    async renewToken(wallet, adminOriginator, reference, partialTx) {
         const unlocker = new sdk_1.PushDrop(wallet, adminOriginator).unlock([2, 'admin user management token'], '1', 'self');
         const unlockingScript = await unlocker.sign(partialTx, 0);
         const signResult = await wallet.signAction({ reference, spends: { 0: { unlockingScript: unlockingScript.toHex() } } }, adminOriginator);
         const finalTxid = signResult.txid || (signResult.tx == null ? '' : sdk_1.Transaction.fromAtomicBEEF(signResult.tx).id('hex'));
         if (!finalTxid)
-            throw new Error('Could not finalize transaction for renewed UMP token.');
+            throw new Error('Could not finalize renewed UMP token.');
         if (signResult.tx == null)
-            throw new Error('Final transaction data missing after signing renewed UMP token.');
+            throw new Error('Renewed UMP token transaction data missing.');
         const result = await this.broadcaster.broadcast(sdk_1.Transaction.fromAtomicBEEF(signResult.tx));
-        this.assertSuccessfulBroadcast(result, 'renew');
+        this.assertBroadcast(result, 'renew');
         return `${finalTxid}.0`;
     }
     /** Signs without input spending and broadcasts — used when creating a brand-new UMP token. */
-    async signAndBroadcastNewToken(wallet, adminOriginator, reference) {
+    async broadcastNew(wallet, adminOriginator, reference) {
         const signResult = await wallet.signAction({ reference, spends: {} }, adminOriginator);
         const finalTxid = signResult.txid || (signResult.tx == null ? '' : sdk_1.Transaction.fromAtomicBEEF(signResult.tx).id('hex'));
         if (!finalTxid)
-            throw new Error('Failed to finalize new UMP token transaction.');
+            throw new Error('Could not finalize new UMP token.');
         if (signResult.tx == null)
-            throw new Error('Final transaction data missing after signing new UMP token.');
+            throw new Error('New UMP token transaction data missing.');
         const result = await this.broadcaster.broadcast(sdk_1.Transaction.fromAtomicBEEF(signResult.tx));
-        this.assertSuccessfulBroadcast(result, 'create');
+        this.assertBroadcast(result, 'create');
         return `${finalTxid}.0`;
     }
-    assertSuccessfulBroadcast(result, operation) {
+    assertBroadcast(result, operation) {
         const succeeded = result.status === 'success';
         this.telemetry.capture({
             name: succeeded ? 'wallet-toolbox.ump.broadcast.completed' : 'wallet-toolbox.ump.broadcast.failed',
@@ -731,13 +735,13 @@ class OverlayUMPTokenInteractor {
             return [];
         const tokens = [];
         for (const output of answer.outputs) {
-            const token = this.parseLookupOutput(output);
+            const token = this.parseOutput(output);
             if (token != null)
                 tokens.push(token);
         }
         return tokens;
     }
-    parseLookupOutput(output) {
+    parseOutput(output) {
         try {
             const tx = sdk_1.Transaction.fromBEEF(output.beef);
             const txOutput = tx.outputs[output.outputIndex];
@@ -800,15 +804,15 @@ class OverlayUMPTokenInteractor {
             });
         }
         catch (error) {
-            const diagnostics = this.emptyLookupDiagnostics(correlationId);
-            this.captureLookupFailure('outpoint', 'lookup-unavailable', diagnostics, startedAt, error);
+            const diagnostics = this.emptyStats(correlationId);
+            this.lookupFailed('outpoint', 'lookup-unavailable', diagnostics, startedAt, error);
             throw new UMPTokenLookupError('lookup-unavailable', diagnostics, { cause: error });
         }
         if (resolution.answer.outputs.length === 0) {
             const p = resolution.progress;
             if (p.emptyHosts === 0) {
-                const diagnostics = this.toLookupDiagnostics(resolution);
-                this.captureLookupFailure('outpoint', 'lookup-incomplete', diagnostics, startedAt);
+                const diagnostics = this.diagnosticsFor(resolution);
+                this.lookupFailed('outpoint', 'lookup-incomplete', diagnostics, startedAt);
                 throw new UMPTokenLookupError('lookup-incomplete', diagnostics);
             }
             return undefined;
@@ -955,21 +959,21 @@ class CWIStyleWalletManager {
         if (this._initSnapshot !== undefined) {
             this.telemetry.capture({
                 name: 'wallet-toolbox.snapshot.initialization.started',
-                component: 'wallet-toolbox.cwi-manager',
+                component: CWI_COMPONENT,
                 severity: 'debug'
             });
             try {
                 await this.loadSnapshot(this._initSnapshot);
                 this.telemetry.capture({
                     name: 'wallet-toolbox.snapshot.initialization.completed',
-                    component: 'wallet-toolbox.cwi-manager',
+                    component: CWI_COMPONENT,
                     severity: 'info'
                 });
             }
             catch (error) {
                 this.telemetry.capture({
                     name: 'wallet-toolbox.snapshot.initialization.failed',
-                    component: 'wallet-toolbox.cwi-manager',
+                    component: CWI_COMPONENT,
                     severity: 'error',
                     error
                 });
@@ -979,9 +983,11 @@ class CWIStyleWalletManager {
     }
     // --- Authentication Methods ---
     /**
-     * Provides the presentation key.
+     * Provides the presentation key. A WAB operator pin may be supplied by the
+     * authentication manager; normal lookup and lineage resolution always run
+     * before this ambiguity-only fallback.
      */
-    async providePresentationKey(key) {
+    async providePresentationKey(key, lookupOptions) {
         if (this.authenticated) {
             throw new Error('User is already authenticated');
         }
@@ -996,18 +1002,18 @@ class CWIStyleWalletManager {
         const startedAt = Date.now();
         this.telemetry.capture({
             name: 'wallet-toolbox.authentication.account-lookup.started',
-            component: 'wallet-toolbox.cwi-manager',
+            component: CWI_COMPONENT,
             severity: 'debug',
             attributes: { lookupKind: 'presentation' }
         });
         let token;
         try {
-            token = await this.UMPTokenInteractor.findByPresentationKeyHash(hash);
+            token = await this.UMPTokenInteractor.findByPresentationKeyHash(hash, lookupOptions);
         }
         catch (error) {
             this.telemetry.capture({
                 name: 'wallet-toolbox.authentication.account-lookup.failed',
-                component: 'wallet-toolbox.cwi-manager',
+                component: CWI_COMPONENT,
                 severity: 'warn',
                 attributes: {
                     lookupKind: 'presentation',
@@ -1030,7 +1036,7 @@ class CWIStyleWalletManager {
         }
         this.telemetry.capture({
             name: 'wallet-toolbox.authentication.account-lookup.completed',
-            component: 'wallet-toolbox.cwi-manager',
+            component: CWI_COMPONENT,
             severity: 'info',
             attributes: {
                 lookupKind: 'presentation',
@@ -1052,14 +1058,14 @@ class CWIStyleWalletManager {
             throw new Error('Determine account status with a presentation or recovery key before providing a password.');
         }
         if (this.authenticationFlow === 'existing-user') {
-            await this.handleExistingUserPassword(password);
+            await this.unlockExisting(password);
         }
         else {
-            await this.handleNewUserPassword(password);
+            await this.createNewUser(password);
         }
     }
     /** Handles the password step for an existing user — derives keys, sets up infrastructure. */
-    async handleExistingUserPassword(password) {
+    async unlockExisting(password) {
         if (this.currentUMPToken == null)
             throw new Error('Provide presentation or recovery key first.');
         const derivedPasswordKey = await derivePasswordKey(this.currentUMPToken, sdk_1.Utils.toArray(password, 'utf8'));
@@ -1078,11 +1084,11 @@ class CWIStyleWalletManager {
             rootPrimaryKey = new sdk_1.SymmetricKey(primaryDecryptionKey).decrypt(this.currentUMPToken.passwordRecoveryPrimary);
             rootPrivilegedKey = new sdk_1.SymmetricKey(this.XOR(rootPrimaryKey, derivedPasswordKey)).decrypt(this.currentUMPToken.passwordPrimaryPrivileged);
         }
-        await this.setupRootInfrastructure(rootPrimaryKey, rootPrivilegedKey);
+        await this.setupRoot(rootPrimaryKey, rootPrivilegedKey);
         await this.switchProfile(this.activeProfileId);
     }
     /** Handles the password step for a new user — generates keys, builds UMP token, publishes on-chain. */
-    async handleNewUserPassword(password) {
+    async createNewUser(password) {
         if (this.authenticationMode !== 'presentation-key-and-password') {
             throw new Error('New-user flow requires presentation key and password mode.');
         }
@@ -1121,7 +1127,7 @@ class CWIStyleWalletManager {
             passwordKdf: this.kdfConfig
         };
         this.currentUMPToken = newToken;
-        await this.setupRootInfrastructure(rootPrimaryKey);
+        await this.setupRoot(rootPrimaryKey);
         await this.switchProfile(exports.DEFAULT_PROFILE_ID);
         // Fund the *default* wallet if funder provided
         if (this.newWalletFunder != null && this.underlying != null) {
@@ -1131,7 +1137,7 @@ class CWIStyleWalletManager {
             catch (error) {
                 this.telemetry.capture({
                     name: 'wallet-toolbox.authentication.new-wallet-funding.failed',
-                    component: 'wallet-toolbox.cwi-manager',
+                    component: CWI_COMPONENT,
                     severity: 'error',
                     error: new Error('New wallet funding failed.')
                 });
@@ -1179,7 +1185,7 @@ class CWIStyleWalletManager {
             const rootPrimaryKey = new sdk_1.SymmetricKey(xorKey).decrypt(this.currentUMPToken.presentationRecoveryPrimary);
             const rootPrivilegedKey = new sdk_1.SymmetricKey(xorKey).decrypt(this.currentUMPToken.presentationRecoveryPrivileged);
             // Build root infrastructure, load profiles, switch to default
-            await this.setupRootInfrastructure(rootPrimaryKey, rootPrivilegedKey);
+            await this.setupRoot(rootPrimaryKey, rootPrivilegedKey);
             await this.switchProfile(this.activeProfileId);
         }
     }
@@ -1221,7 +1227,7 @@ class CWIStyleWalletManager {
         }
         this.telemetry.capture({
             name: 'wallet-toolbox.snapshot.saved',
-            component: 'wallet-toolbox.cwi-manager',
+            component: CWI_COMPONENT,
             severity: 'info',
             attributes: {
                 formatVersion: 2,
@@ -1272,12 +1278,12 @@ class CWIStyleWalletManager {
             // Assign loaded data
             this.currentUMPToken = token;
             // Setup root infrastructure, load profiles, and switch to the loaded active profile
-            await this.setupRootInfrastructure(rootPrimaryKey); // Will automatically load profiles
+            await this.setupRoot(rootPrimaryKey); // Will automatically load profiles
             await this.switchProfile(activeProfileId); // Switch to the profile saved in the snapshot
             this.authenticationFlow = 'existing-user'; // Loading implies existing user
             this.telemetry.capture({
                 name: 'wallet-toolbox.snapshot.loaded',
-                component: 'wallet-toolbox.cwi-manager',
+                component: CWI_COMPONENT,
                 severity: 'info',
                 attributes: {
                     formatVersion: version,
@@ -1289,7 +1295,7 @@ class CWIStyleWalletManager {
             this.destroy(); // Clear state on error
             this.telemetry.capture({
                 name: 'wallet-toolbox.snapshot.load-failed',
-                component: 'wallet-toolbox.cwi-manager',
+                component: CWI_COMPONENT,
                 severity: 'error',
                 error
             });
@@ -1318,7 +1324,7 @@ class CWIStyleWalletManager {
             return false;
         }
         this.currentUMPToken = refreshed;
-        await this.setupRootInfrastructure(this.rootPrimaryKey);
+        await this.setupRoot(this.rootPrimaryKey);
         this.saveSnapshot();
         return true;
     }
@@ -1395,7 +1401,7 @@ class CWIStyleWalletManager {
         };
         this.profiles.push(newProfile);
         // Update the UMP token with the new profile list
-        await this.updateAuthFactors(this.currentUMPToken.passwordSalt, 
+        await this.updateFactors(this.currentUMPToken.passwordSalt, 
         // Need to re-derive/decrypt factors needed for re-encryption
         await this.getFactor('passwordKey'), await this.getFactor('presentationKey'), await this.getFactor('recoveryKey'), this.rootPrimaryKey, await this.getFactor('privilegedKey'), // Get ROOT privileged key
         this.profiles // Pass the updated profile list
@@ -1430,7 +1436,7 @@ class CWIStyleWalletManager {
             await this.switchProfile(exports.DEFAULT_PROFILE_ID); // This rebuilds the wallet
         }
         // Update the UMP token
-        await this.updateAuthFactors(this.currentUMPToken.passwordSalt, await this.getFactor('passwordKey'), await this.getFactor('presentationKey'), await this.getFactor('recoveryKey'), this.rootPrimaryKey, await this.getFactor('privilegedKey'), // Get ROOT privileged key
+        await this.updateFactors(this.currentUMPToken.passwordSalt, await this.getFactor('passwordKey'), await this.getFactor('presentationKey'), await this.getFactor('recoveryKey'), this.rootPrimaryKey, await this.getFactor('privilegedKey'), // Get ROOT privileged key
         this.profiles // Pass updated list
         );
     }
@@ -1499,7 +1505,7 @@ class CWIStyleWalletManager {
         const recoveryKey = await this.getFactor('recoveryKey');
         const presentationKey = await this.getFactor('presentationKey');
         const rootPrivilegedKey = await this.getFactor('privilegedKey'); // Get ROOT privileged key
-        await this.updateAuthFactors(passwordSalt, newPasswordKey, presentationKey, recoveryKey, this.rootPrimaryKey, rootPrivilegedKey, // Pass the explicitly fetched root key
+        await this.updateFactors(passwordSalt, newPasswordKey, presentationKey, recoveryKey, this.rootPrimaryKey, rootPrivilegedKey, // Pass the explicitly fetched root key
         this.profiles // Preserve existing profiles
         );
     }
@@ -1510,7 +1516,7 @@ class CWIStyleWalletManager {
         if (!this.authenticated || this.currentUMPToken == null || this.rootPrivilegedKeyManager == null) {
             throw new Error('Not authenticated or missing required data.');
         }
-        return await this.getFactor('recoveryKey');
+        return this.getFactor('recoveryKey');
     }
     /**
      * Changes the user's recovery key. Prompts user to save the new key.
@@ -1529,7 +1535,7 @@ class CWIStyleWalletManager {
         // Generate and save new recovery key
         const newRecoveryKey = (0, sdk_1.Random)(32);
         await this.recoveryKeySaver(newRecoveryKey);
-        await this.updateAuthFactors(this.currentUMPToken.passwordSalt, passwordKey, presentationKey, newRecoveryKey, // Use the new key
+        await this.updateFactors(this.currentUMPToken.passwordSalt, passwordKey, presentationKey, newRecoveryKey, // Use the new key
         this.rootPrimaryKey, rootPrivilegedKey, this.profiles // Preserve profiles
         );
     }
@@ -1550,7 +1556,7 @@ class CWIStyleWalletManager {
         const recoveryKey = await this.getFactor('recoveryKey');
         const passwordKey = await this.getFactor('passwordKey');
         const rootPrivilegedKey = await this.getFactor('privilegedKey'); // Get ROOT privileged key
-        await this.updateAuthFactors(this.currentUMPToken.passwordSalt, passwordKey, newPresentationKey, // Use the new key
+        await this.updateFactors(this.currentUMPToken.passwordSalt, passwordKey, newPresentationKey, // Use the new key
         recoveryKey, this.rootPrimaryKey, rootPrivilegedKey, this.profiles // Preserve profiles
         );
         // Update the temporarily stored key if it was set
@@ -1620,7 +1626,7 @@ class CWIStyleWalletManager {
         catch (error) {
             this.telemetry.capture({
                 name: 'wallet-toolbox.authentication.factor-decryption.failed',
-                component: 'wallet-toolbox.cwi-manager',
+                component: CWI_COMPONENT,
                 severity: 'error',
                 attributes: { factor: factorName },
                 error
@@ -1633,7 +1639,7 @@ class CWIStyleWalletManager {
      * Recomputes UMP token fields with updated factors and profiles, then publishes the update.
      * This operation requires the *root* privileged key and the *default* profile wallet.
      */
-    async updateAuthFactors(passwordSalt, passwordKey, presentationKey, recoveryKey, rootPrimaryKey, rootPrivilegedKey, // Explicitly pass the root key bytes
+    async updateFactors(passwordSalt, passwordKey, presentationKey, recoveryKey, rootPrimaryKey, rootPrivilegedKey, // Explicitly pass the root key bytes
     profiles // Pass current/new profiles list
     ) {
         if (!this.authenticated || this.rootPrimaryKey == null || this.currentUMPToken == null) {
@@ -1703,7 +1709,7 @@ class CWIStyleWalletManager {
         if (!currentActiveId.every(x => x === 0)) {
             this.telemetry.capture({
                 name: 'wallet-toolbox.ump.profile-switch.started',
-                component: 'wallet-toolbox.cwi-manager',
+                component: CWI_COMPONENT,
                 severity: 'debug',
                 attributes: { reason: 'token-update' }
             });
@@ -1727,7 +1733,7 @@ class CWIStyleWalletManager {
                 await this.switchProfile(currentActiveId);
                 this.telemetry.capture({
                     name: 'wallet-toolbox.ump.profile-switch.completed',
-                    component: 'wallet-toolbox.cwi-manager',
+                    component: CWI_COMPONENT,
                     severity: 'debug',
                     attributes: { reason: 'token-update' }
                 });
@@ -1895,11 +1901,11 @@ class CWIStyleWalletManager {
      * @param rootPrimaryKey      The user's root primary key (32 bytes).
      * @param ephemeralRootPrivilegedKey Optional root privileged key (e.g., during recovery flows).
      */
-    async setupRootInfrastructure(rootPrimaryKey, ephemeralRootPrivilegedKey) {
+    async setupRoot(rootKey, ephemeralRootPrivilegedKey) {
         if (this.currentUMPToken == null) {
             throw new Error('A UMP token must exist before setting up root infrastructure!');
         }
-        this.rootPrimaryKey = rootPrimaryKey;
+        this.rootPrimaryKey = rootKey;
         // Store ephemeral key if provided, for one-time use by the manager
         let oneTimePrivilegedKey = ephemeralRootPrivilegedKey == null ? undefined : new sdk_1.PrivateKey(ephemeralRootPrivilegedKey);
         // Create the ROOT PrivilegedKeyManager
@@ -1935,7 +1941,7 @@ class CWIStyleWalletManager {
         this.profiles = []; // Clear existing profiles before loading
         if (this.currentUMPToken.profilesEncrypted != null && this.currentUMPToken.profilesEncrypted.length > 0) {
             try {
-                const decryptedProfileBytes = new sdk_1.SymmetricKey(rootPrimaryKey).decrypt(this.currentUMPToken.profilesEncrypted);
+                const decryptedProfileBytes = new sdk_1.SymmetricKey(rootKey).decrypt(this.currentUMPToken.profilesEncrypted);
                 const profilesJson = sdk_1.Utils.toUTF8(decryptedProfileBytes);
                 const profiles = JSON.parse(profilesJson);
                 if (!Array.isArray(profiles) || profiles.length > 1000 || !profiles.every(isValidProfile)) {
@@ -1947,7 +1953,7 @@ class CWIStyleWalletManager {
                 this.profiles = [];
                 this.telemetry.capture({
                     name: 'wallet-toolbox.profile.load-failed',
-                    component: 'wallet-toolbox.cwi-manager',
+                    component: CWI_COMPONENT,
                     severity: 'error',
                     error
                 });
@@ -1965,7 +1971,7 @@ class CWIStyleWalletManager {
      * Includes authentication checks and admin originator protection.
      * ---------------------------------------------------------------------------------------
      */
-    checkAuthAndUnderlying(originator) {
+    assertReady(originator) {
         if (!this.authenticated) {
             throw new Error('User is not authenticated.');
         }
@@ -1979,92 +1985,92 @@ class CWIStyleWalletManager {
     }
     // Example proxy method (repeat pattern for all others)
     async getPublicKey(args, originator) {
-        this.checkAuthAndUnderlying(originator);
-        return await this.underlying.getPublicKey(args, originator);
+        this.assertReady(originator);
+        return this.underlying.getPublicKey(args, originator);
     }
     async revealCounterpartyKeyLinkage(args, originator) {
-        this.checkAuthAndUnderlying(originator);
-        return await this.underlying.revealCounterpartyKeyLinkage(args, originator);
+        this.assertReady(originator);
+        return this.underlying.revealCounterpartyKeyLinkage(args, originator);
     }
     async revealSpecificKeyLinkage(args, originator) {
-        this.checkAuthAndUnderlying(originator);
-        return await this.underlying.revealSpecificKeyLinkage(args, originator);
+        this.assertReady(originator);
+        return this.underlying.revealSpecificKeyLinkage(args, originator);
     }
     async encrypt(args, originator) {
-        this.checkAuthAndUnderlying(originator);
-        return await this.underlying.encrypt(args, originator);
+        this.assertReady(originator);
+        return this.underlying.encrypt(args, originator);
     }
     async decrypt(args, originator) {
-        this.checkAuthAndUnderlying(originator);
-        return await this.underlying.decrypt(args, originator);
+        this.assertReady(originator);
+        return this.underlying.decrypt(args, originator);
     }
     async createHmac(args, originator) {
-        this.checkAuthAndUnderlying(originator);
-        return await this.underlying.createHmac(args, originator);
+        this.assertReady(originator);
+        return this.underlying.createHmac(args, originator);
     }
     async verifyHmac(args, originator) {
-        this.checkAuthAndUnderlying(originator);
-        return await this.underlying.verifyHmac(args, originator);
+        this.assertReady(originator);
+        return this.underlying.verifyHmac(args, originator);
     }
     async createSignature(args, originator) {
-        this.checkAuthAndUnderlying(originator);
-        return await this.underlying.createSignature(args, originator);
+        this.assertReady(originator);
+        return this.underlying.createSignature(args, originator);
     }
     async verifySignature(args, originator) {
-        this.checkAuthAndUnderlying(originator);
-        return await this.underlying.verifySignature(args, originator);
+        this.assertReady(originator);
+        return this.underlying.verifySignature(args, originator);
     }
     async createAction(args, originator) {
-        this.checkAuthAndUnderlying(originator);
-        return await this.underlying.createAction(args, originator);
+        this.assertReady(originator);
+        return this.underlying.createAction(args, originator);
     }
     async signAction(args, originator) {
-        this.checkAuthAndUnderlying(originator);
-        return await this.underlying.signAction(args, originator);
+        this.assertReady(originator);
+        return this.underlying.signAction(args, originator);
     }
     async abortAction(args, originator) {
-        this.checkAuthAndUnderlying(originator);
-        return await this.underlying.abortAction(args, originator);
+        this.assertReady(originator);
+        return this.underlying.abortAction(args, originator);
     }
     async listActions(args, originator) {
-        this.checkAuthAndUnderlying(originator);
-        return await this.underlying.listActions(args, originator);
+        this.assertReady(originator);
+        return this.underlying.listActions(args, originator);
     }
     async internalizeAction(args, originator) {
-        this.checkAuthAndUnderlying(originator);
-        return await this.underlying.internalizeAction(args, originator);
+        this.assertReady(originator);
+        return this.underlying.internalizeAction(args, originator);
     }
     async listOutputs(args, originator) {
-        this.checkAuthAndUnderlying(originator);
-        return await this.underlying.listOutputs(args, originator);
+        this.assertReady(originator);
+        return this.underlying.listOutputs(args, originator);
     }
     async relinquishOutput(args, originator) {
-        this.checkAuthAndUnderlying(originator);
-        return await this.underlying.relinquishOutput(args, originator);
+        this.assertReady(originator);
+        return this.underlying.relinquishOutput(args, originator);
     }
     async acquireCertificate(args, originator) {
-        this.checkAuthAndUnderlying(originator);
-        return await this.underlying.acquireCertificate(args, originator);
+        this.assertReady(originator);
+        return this.underlying.acquireCertificate(args, originator);
     }
     async listCertificates(args, originator) {
-        this.checkAuthAndUnderlying(originator);
-        return await this.underlying.listCertificates(args, originator);
+        this.assertReady(originator);
+        return this.underlying.listCertificates(args, originator);
     }
     async proveCertificate(args, originator) {
-        this.checkAuthAndUnderlying(originator);
-        return await this.underlying.proveCertificate(args, originator);
+        this.assertReady(originator);
+        return this.underlying.proveCertificate(args, originator);
     }
     async relinquishCertificate(args, originator) {
-        this.checkAuthAndUnderlying(originator);
-        return await this.underlying.relinquishCertificate(args, originator);
+        this.assertReady(originator);
+        return this.underlying.relinquishCertificate(args, originator);
     }
     async discoverByIdentityKey(args, originator) {
-        this.checkAuthAndUnderlying(originator);
-        return await this.underlying.discoverByIdentityKey(args, originator);
+        this.assertReady(originator);
+        return this.underlying.discoverByIdentityKey(args, originator);
     }
     async discoverByAttributes(args, originator) {
-        this.checkAuthAndUnderlying(originator);
-        return await this.underlying.discoverByAttributes(args, originator);
+        this.assertReady(originator);
+        return this.underlying.discoverByAttributes(args, originator);
     }
     async isAuthenticated(_, originator) {
         if (!this.authenticated) {
@@ -2082,23 +2088,23 @@ class CWIStyleWalletManager {
         while (!this.authenticated || this.underlying == null) {
             await new Promise(resolve => setTimeout(resolve, 100));
         }
-        return await this.underlying.waitForAuthentication({}, originator);
+        return this.underlying.waitForAuthentication({}, originator);
     }
     async getHeight(_, originator) {
-        this.checkAuthAndUnderlying(originator);
-        return await this.underlying.getHeight({}, originator);
+        this.assertReady(originator);
+        return this.underlying.getHeight({}, originator);
     }
     async getHeaderForHeight(args, originator) {
-        this.checkAuthAndUnderlying(originator);
-        return await this.underlying.getHeaderForHeight(args, originator);
+        this.assertReady(originator);
+        return this.underlying.getHeaderForHeight(args, originator);
     }
     async getNetwork(_, originator) {
-        this.checkAuthAndUnderlying(originator);
-        return await this.underlying.getNetwork({}, originator);
+        this.assertReady(originator);
+        return this.underlying.getNetwork({}, originator);
     }
     async getVersion(_, originator) {
-        this.checkAuthAndUnderlying(originator);
-        return await this.underlying.getVersion({}, originator);
+        this.assertReady(originator);
+        return this.underlying.getVersion({}, originator);
     }
 }
 exports.CWIStyleWalletManager = CWIStyleWalletManager;