@bopen-io/wallet-toolbox 2.6.2-brc153.5 → 2.14.6

package/out/src/CWIStyleWalletManager.js

@@ -2,8 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CWIStyleWalletManager = exports.OverlayUMPTokenInteractor = exports.UMPTokenLookupError = exports.DEFAULT_PROFILE_ID = exports.MAX_STATE_SNAPSHOT_BYTES = exports.PBKDF2_MAX_ITERATIONS = exports.KDF_MAX_HASH_LENGTH = exports.ARGON2ID_MAX_PARALLELISM = exports.ARGON2ID_MAX_MEMORY_KIB = exports.ARGON2ID_MAX_ITERATIONS = exports.ARGON2ID_DEFAULT_HASH_LENGTH = exports.ARGON2ID_DEFAULT_PARALLELISM = exports.ARGON2ID_DEFAULT_MEMORY_KIB = exports.ARGON2ID_DEFAULT_ITERATIONS = exports.PBKDF2_NUM_ROUNDS = void 0;
 const sdk_1 = require("@bsv/sdk");
+const Hash_1 = require("@bsv/sdk/primitives/Hash");
+const utils_1 = require("@bsv/sdk/primitives/utils");
 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 +43,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) {
@@ -67,9 +66,9 @@ function addPasswordKdf(token, protocolFields, kdfVersionFieldIndex) {
     if (kdfAlgorithmField == null || kdfParamsField == null || kdfParamsField.length > 1024) {
         return false;
     }
-    const kdfParams = JSON.parse(sdk_1.Utils.toUTF8(kdfParamsField));
+    const kdfParams = JSON.parse((0, utils_1.toUTF8)(kdfParamsField));
     const passwordKdf = {
-        algorithm: sdk_1.Utils.toUTF8(kdfAlgorithmField),
+        algorithm: (0, utils_1.toUTF8)(kdfAlgorithmField),
         iterations: kdfParams.iterations,
         memoryKiB: kdfParams.memoryKiB,
         parallelism: kdfParams.parallelism,
@@ -123,6 +122,24 @@ function stripVerifiedPushDropSignature(fields, lockingPublicKey) {
     }
     return fields;
 }
+function decodeAuthenticatedUMPFields(lockingScript) {
+    const decoded = (0, sdk_1.decodeCanonicalPushDrop)(lockingScript, {
+        fieldCount: [12, 13, 15, 16],
+        maximumFieldBytes: exports.MAX_STATE_SNAPSHOT_BYTES,
+        maximumPayloadBytes: exports.MAX_STATE_SNAPSHOT_BYTES
+    });
+    const fields = stripVerifiedPushDropSignature(decoded.fields, decoded.lockingPublicKey);
+    if (fields.length !== decoded.fields.length - 1) {
+        throw new Error('UMP token field signature is missing or invalid');
+    }
+    const kdfVersionFieldIndex = findKdfVersionFieldIndex(fields);
+    if ((kdfVersionFieldIndex === -1 && fields.length > 12) ||
+        (kdfVersionFieldIndex === 11 && fields.length !== 14) ||
+        (kdfVersionFieldIndex === 12 && fields.length !== 15)) {
+        throw new Error('UMP token field layout is invalid');
+    }
+    return { ...decoded, fields };
+}
 /**
  * PBKDF-2 that prefers WebCrypto and falls back to hash-wasm.
  *
@@ -284,11 +301,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');
+            query: { presentationHash: (0, utils_1.toHex)(hash) }
+        }, 'presentation', options);
     }
     /**
      * Finds a UMP token on-chain by the given recovery key hash, if it exists.
@@ -297,13 +314,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');
+            query: { recoveryHash: (0, utils_1.toHex)(hash) }
+        }, '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,14 +338,14 @@ 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() ===
+        const matchingTokens = tokens.filter(token => (0, utils_1.toHex)(lookupKind === 'presentation' ? token.presentationHash : token.recoveryHash).toLowerCase() ===
             expectedHash);
         // A verified token is positive account-existence evidence. Empty, malformed,
         // rejected, or unavailable peers cannot override it. The resolver de-duplicates
@@ -340,28 +357,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 +419,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 +442,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,9 +454,9 @@ 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) {
-        const presentationHash = sdk_1.Utils.toHex(token.presentationHash);
-        const recoveryHash = sdk_1.Utils.toHex(token.recoveryHash);
+    consumesIdentity(tx, token) {
+        const presentationHash = (0, utils_1.toHex)(token.presentationHash);
+        const recoveryHash = (0, utils_1.toHex)(token.recoveryHash);
         for (const input of tx.inputs) {
             const source = input.sourceTransaction;
             if (source == null || input.sourceOutputIndex == null)
@@ -441,13 +465,10 @@ class OverlayUMPTokenInteractor {
             if (sourceOutput == null)
                 continue;
             try {
-                const decoded = sdk_1.PushDrop.decode(sourceOutput.lockingScript);
-                if (decoded.fields == null)
-                    continue;
-                const fields = stripVerifiedPushDropSignature(decoded.fields, decoded.lockingPublicKey);
+                const { fields } = decodeAuthenticatedUMPFields(sourceOutput.lockingScript);
                 if (fields.length < 11 || fields[6]?.length !== 32 || fields[7]?.length !== 32)
                     continue;
-                if (sdk_1.Utils.toHex(fields[6]) === presentationHash || sdk_1.Utils.toHex(fields[7]) === recoveryHash) {
+                if ((0, utils_1.toHex)(fields[6]) === presentationHash || (0, utils_1.toHex)(fields[7]) === recoveryHash) {
                     return true;
                 }
             }
@@ -463,7 +484,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 +503,7 @@ class OverlayUMPTokenInteractor {
             }
         }
     }
-    emptyLookupDiagnostics(correlationId) {
+    emptyStats(correlationId) {
         return {
             hostCount: 0,
             completedHosts: 0,
@@ -495,7 +516,7 @@ class OverlayUMPTokenInteractor {
             ...(correlationId !== undefined ? { correlationId } : {})
         };
     }
-    toLookupDiagnostics(resolution) {
+    diagnosticsFor(resolution) {
         const progress = resolution.progress;
         return {
             hostCount: progress.hostCount,
@@ -509,7 +530,7 @@ class OverlayUMPTokenInteractor {
             ...(progress.correlationId !== undefined ? { correlationId: progress.correlationId } : {})
         };
     }
-    lookupDiagnosticAttributes(diagnostics) {
+    lookupAttrs(diagnostics) {
         return {
             hostCount: diagnostics.hostCount,
             completedHosts: diagnostics.completedHosts,
@@ -521,7 +542,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 +552,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 +567,7 @@ class OverlayUMPTokenInteractor {
                 lookupKind,
                 reason,
                 durationMs: Date.now() - startedAt,
-                ...this.lookupDiagnosticAttributes(diagnostics)
+                ...this.lookupAttrs(diagnostics)
             },
             error
         });
@@ -566,13 +587,17 @@ 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' }];
+        const tokenScript = script.toHex();
+        const tokenOutput = [{ lockingScript: tokenScript, 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);
+        if (resolvedOldToken != null && inputToken != null) {
+            await this.assertOwnedUMPInput(wallet, adminOriginator, resolvedOldToken, inputToken);
+        }
         const inputs = resolvedOldToken?.currentOutpoint
             ? [
                 {
@@ -582,21 +607,40 @@ class OverlayUMPTokenInteractor {
                 }
             ]
             : [];
-        const createResult = await this.createUMPAction(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);
+        const createArgs = {
+            description: resolvedOldToken == null ? 'Create new UMP token' : 'Renew UMP token (consume old, create new)',
+            inputs,
+            outputs: tokenOutput,
+            inputBEEF: inputToken?.beef,
+            options: { randomizeOutputs: false, acceptDelayedBroadcast: false }
+        };
+        const inputSigners = Object.create(null);
+        if (resolvedOldToken?.currentOutpoint != null) {
+            const unlocker = new sdk_1.PushDrop(wallet, adminOriginator).unlock([2, 'admin user management token'], '1', 'self');
+            inputSigners[resolvedOldToken.currentOutpoint] = async (transaction, inputIndex) => await unlocker.sign(transaction, inputIndex);
         }
-        // 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);
+        const operation = resolvedOldToken == null ? 'create' : 'renew';
+        let transaction;
+        try {
+            transaction = await this.completeUMPAction(wallet, createArgs, inputSigners, adminOriginator);
         }
-        return await this.signAndBroadcastNewToken(wallet, adminOriginator, reference);
+        catch (error) {
+            this.telemetry.capture({
+                name: 'wallet-toolbox.ump.action.failed',
+                component: 'wallet-toolbox.ump',
+                severity: 'error',
+                attributes: {
+                    operation,
+                    oldTokenInputRequired: resolvedOldToken != null
+                },
+                error
+            });
+            throw error;
+        }
+        return await this.broadcastUMPTransaction(transaction, tokenScript, operation);
     }
     /** Assembles the ordered number[][] fields array from a UMPToken. */
-    buildUMPTokenFields(token) {
+    tokenFields(token) {
         const fields = [];
         fields[0] = token.passwordSalt;
         fields[1] = token.passwordPresentationPrimary;
@@ -614,7 +658,7 @@ class OverlayUMPTokenInteractor {
         if (token.umpVersion === 3 && token.passwordKdf != null) {
             const vi = token.profilesEncrypted == null ? 11 : 12;
             fields[vi] = [token.umpVersion];
-            fields[vi + 1] = sdk_1.Utils.toArray(token.passwordKdf.algorithm, 'utf8');
+            fields[vi + 1] = (0, utils_1.toArray)(token.passwordKdf.algorithm, 'utf8');
             const kdfParams = { iterations: token.passwordKdf.iterations };
             if (token.passwordKdf.memoryKiB !== undefined)
                 kdfParams.memoryKiB = token.passwordKdf.memoryKiB;
@@ -622,85 +666,61 @@ class OverlayUMPTokenInteractor {
                 kdfParams.parallelism = token.passwordKdf.parallelism;
             if (token.passwordKdf.hashLength !== undefined)
                 kdfParams.hashLength = token.passwordKdf.hashLength;
-            fields[vi + 2] = sdk_1.Utils.toArray(JSON.stringify(kdfParams), 'utf8');
+            fields[vi + 2] = (0, utils_1.toArray)(JSON.stringify(kdfParams), 'utf8');
         }
         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) {
-        try {
-            return await wallet.createAction({
-                description: resolvedOldToken == null ? 'Create new UMP token' : 'Renew UMP token (consume old, create new)',
-                inputs,
-                outputs,
-                inputBEEF: inputToken?.beef,
-                options: { randomizeOutputs: false, acceptDelayedBroadcast: false }
-            }, adminOriginator);
-        }
-        catch (error) {
-            this.telemetry.capture({
-                name: 'wallet-toolbox.ump.action.failed',
-                component: 'wallet-toolbox.ump',
-                severity: 'error',
-                attributes: {
-                    operation: resolvedOldToken == null ? 'create' : 'renew',
-                    oldTokenInputRequired: resolvedOldToken != null
-                },
-                error
-            });
-            throw error;
-        }
-    }
-    /** Handles a fully-finalized (no signable tx) createAction result — broadcasts and returns outpoint. */
-    async broadcastFinishedUMPAction(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.');
-        if (createResult.tx == null)
-            throw new Error('No final TX data to broadcast.');
-        const broadcastTx = sdk_1.Transaction.fromAtomicBEEF(createResult.tx);
-        const result = await this.broadcaster.broadcast(broadcastTx);
-        this.assertSuccessfulBroadcast(result, 'create-finalized');
-        return `${finalTxid}.0`;
-    }
-    /** Signs the old-token input and broadcasts — used during UMP token renewal. */
-    async signAndBroadcastWithOldToken(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.');
-        if (signResult.tx == null)
-            throw new Error('Final transaction data missing after signing renewed UMP token.');
-        const result = await this.broadcaster.broadcast(sdk_1.Transaction.fromAtomicBEEF(signResult.tx));
-        this.assertSuccessfulBroadcast(result, 'renew');
-        return `${finalTxid}.0`;
-    }
-    /** Signs without input spending and broadcasts — used when creating a brand-new UMP token. */
-    async signAndBroadcastNewToken(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.');
-        if (signResult.tx == null)
-            throw new Error('Final transaction data missing after signing new UMP token.');
-        const result = await this.broadcaster.broadcast(sdk_1.Transaction.fromAtomicBEEF(signResult.tx));
-        this.assertSuccessfulBroadcast(result, 'create');
-        return `${finalTxid}.0`;
-    }
-    assertSuccessfulBroadcast(result, operation) {
-        const succeeded = result.status === 'success';
+    /** Proves the exact predecessor is an authenticated token controlled by this wallet. */
+    async assertOwnedUMPInput(wallet, adminOriginator, oldToken, inputToken) {
+        const transaction = sdk_1.Transaction.fromBEEF(inputToken.beef);
+        const sourceOutput = transaction.outputs[inputToken.outputIndex];
+        if (sourceOutput == null)
+            throw new Error('Previous UMP token source output is missing.');
+        const decoded = decodeAuthenticatedUMPFields(sourceOutput.lockingScript);
+        if (decoded.fields[6]?.length !== 32 ||
+            decoded.fields[7]?.length !== 32 ||
+            (0, utils_1.toHex)(decoded.fields[6]) !== (0, utils_1.toHex)(oldToken.presentationHash) ||
+            (0, utils_1.toHex)(decoded.fields[7]) !== (0, utils_1.toHex)(oldToken.recoveryHash)) {
+            throw new Error('Previous UMP token identity does not match its authenticated source.');
+        }
+        const { publicKey } = await wallet.getPublicKey({
+            protocolID: [2, 'admin user management token'],
+            keyID: '1',
+            counterparty: 'self',
+            forSelf: true
+        }, adminOriginator);
+        if (publicKey.toLowerCase() !== decoded.lockingPublicKey.toString().toLowerCase()) {
+            throw new Error('Previous UMP token is not controlled by this wallet.');
+        }
+    }
+    /** Completes an action only after exact request, input, output, and final-transaction binding. */
+    async completeUMPAction(wallet, createArgs, inputSigners, adminOriginator) {
+        return await (0, sdk_1.completeBoundAction)(wallet, createArgs, { inputSigners }, adminOriginator);
+    }
+    /** Broadcasts a bound UMP transaction and returns the exact, uniquely matching token output. */
+    async broadcastUMPTransaction(transaction, tokenScript, operation) {
+        const normalizedScript = tokenScript.toLowerCase();
+        const matchingOutputs = transaction.outputs.flatMap((output, index) => output.satoshis === 1 && output.lockingScript.toHex().toLowerCase() === normalizedScript ? [index] : []);
+        if (matchingOutputs.length !== 1) {
+            throw new Error('Final UMP transaction must contain exactly one requested token output.');
+        }
+        const txid = transaction.id('hex');
+        const result = await this.broadcaster.broadcast(transaction);
+        this.assertBroadcast(result, operation, txid);
+        return `${txid}.${matchingOutputs[0]}`;
+    }
+    assertBroadcast(result, operation, expectedTxid) {
+        const succeeded = result.status === 'success' && result.txid.toLowerCase() === expectedTxid.toLowerCase();
         this.telemetry.capture({
             name: succeeded ? 'wallet-toolbox.ump.broadcast.completed' : 'wallet-toolbox.ump.broadcast.failed',
             component: 'wallet-toolbox.ump',
@@ -712,7 +732,8 @@ class OverlayUMPTokenInteractor {
             }
         });
         if (!succeeded) {
-            throw new Error(`UMP token broadcast failed (${result.code}).`);
+            const reason = result.status === 'error' ? result.code : 'transaction ID mismatch';
+            throw new Error(`UMP token broadcast failed (${reason}).`);
         }
     }
     /**
@@ -731,23 +752,19 @@ 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];
             if (txOutput == null)
                 return undefined;
-            const decoded = sdk_1.PushDrop.decode(txOutput.lockingScript);
-            if (decoded.fields == null || decoded.fields.length < 11 || decoded.fields.length > 16) {
-                return undefined;
-            }
-            const protocolFields = stripVerifiedPushDropSignature(decoded.fields, decoded.lockingPublicKey);
+            const { fields: protocolFields } = decodeAuthenticatedUMPFields(txOutput.lockingScript);
             if (protocolFields.length < 11 ||
                 protocolFields.slice(0, 11).some(field => field.length === 0 || field.length > exports.MAX_STATE_SNAPSHOT_BYTES)) {
                 return undefined;
@@ -787,6 +804,14 @@ class OverlayUMPTokenInteractor {
     async findByOutpoint(outpoint) {
         const correlationId = this.telemetry.enabled === true ? this.telemetry.createCorrelationId() : undefined;
         const startedAt = Date.now();
+        const match = /^([0-9a-f]{64})\.(0|[1-9]\d*)$/i.exec(outpoint);
+        const requestedOutputIndex = match == null ? Number.NaN : Number(match[2]);
+        if (match == null || !Number.isSafeInteger(requestedOutputIndex) || requestedOutputIndex > 0xffffffff) {
+            const diagnostics = this.emptyStats(correlationId);
+            this.lookupFailed('outpoint', 'token-malformed', diagnostics, startedAt);
+            throw new UMPTokenLookupError('token-malformed', diagnostics);
+        }
+        const normalizedOutpoint = `${match[1].toLowerCase()}.${requestedOutputIndex}`;
         let resolution;
         try {
             resolution = await this.resolver.queryDetailed({
@@ -800,20 +825,44 @@ 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;
         }
-        return resolution.answer.outputs[0];
+        const diagnostics = this.diagnosticsFor(resolution);
+        const matchingOutputs = [];
+        try {
+            for (const output of resolution.answer.outputs) {
+                if (!Number.isSafeInteger(output.outputIndex) || output.outputIndex < 0 || output.outputIndex > 0xffffffff) {
+                    throw new Error('UMP lookup returned an invalid output index');
+                }
+                const transaction = sdk_1.Transaction.fromBEEF(output.beef);
+                if (transaction.outputs[output.outputIndex] == null ||
+                    `${transaction.id('hex')}.${output.outputIndex}` !== normalizedOutpoint) {
+                    throw new Error('UMP lookup substituted the requested outpoint');
+                }
+                matchingOutputs.push(output);
+            }
+        }
+        catch (error) {
+            this.lookupFailed('outpoint', 'token-malformed', diagnostics, startedAt, error);
+            throw new UMPTokenLookupError('token-malformed', diagnostics, { cause: error });
+        }
+        if (matchingOutputs.length === 0) {
+            this.lookupFailed('outpoint', 'token-malformed', diagnostics, startedAt);
+            throw new UMPTokenLookupError('token-malformed', diagnostics);
+        }
+        matchingOutputs.sort((left, right) => right.beef.length - left.beef.length);
+        return matchingOutputs[0];
     }
 }
 exports.OverlayUMPTokenInteractor = OverlayUMPTokenInteractor;
@@ -955,21 +1004,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 +1028,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');
         }
@@ -992,22 +1043,22 @@ class CWIStyleWalletManager {
             throw new TypeError('Presentation key must contain exactly 32 bytes.');
         }
         this.authenticationFlow = 'unknown';
-        const hash = sdk_1.Hash.sha256(key);
+        const hash = (0, Hash_1.sha256)(key);
         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 +1081,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,17 +1103,17 @@ 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'));
+        const derivedPasswordKey = await derivePasswordKey(this.currentUMPToken, (0, utils_1.toArray)(password, 'utf8'));
         let rootPrimaryKey;
         let rootPrivilegedKey;
         if (this.authenticationMode === 'presentation-key-and-password') {
@@ -1078,11 +1129,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.');
         }
@@ -1092,7 +1143,7 @@ class CWIStyleWalletManager {
         const recoveryKey = (0, sdk_1.Random)(32);
         await this.recoveryKeySaver(recoveryKey);
         const passwordSalt = (0, sdk_1.Random)(32);
-        const passwordKey = await derivePasswordKey({ passwordSalt, passwordKdf: this.kdfConfig }, sdk_1.Utils.toArray(password, 'utf8'));
+        const passwordKey = await derivePasswordKey({ passwordSalt, passwordKdf: this.kdfConfig }, (0, utils_1.toArray)(password, 'utf8'));
         const rootPrimaryKey = (0, sdk_1.Random)(32);
         const rootPrivilegedKey = (0, sdk_1.Random)(32);
         // Build XOR-combined symmetric keys
@@ -1111,8 +1162,8 @@ class CWIStyleWalletManager {
             presentationRecoveryPrimary: presentationRecovery.encrypt(rootPrimaryKey),
             passwordPrimaryPrivileged: primaryPassword.encrypt(rootPrivilegedKey),
             presentationRecoveryPrivileged: presentationRecovery.encrypt(rootPrivilegedKey),
-            presentationHash: sdk_1.Hash.sha256(this.presentationKey),
-            recoveryHash: sdk_1.Hash.sha256(recoveryKey),
+            presentationHash: (0, Hash_1.sha256)(this.presentationKey),
+            recoveryHash: (0, Hash_1.sha256)(recoveryKey),
             presentationKeyEncrypted: await wrapKey(this.presentationKey),
             passwordKeyEncrypted: await wrapKey(passwordKey),
             recoveryKeyEncrypted: await wrapKey(recoveryKey),
@@ -1121,7 +1172,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 +1182,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.')
                 });
@@ -1161,7 +1212,7 @@ class CWIStyleWalletManager {
         }
         if (this.authenticationMode === 'recovery-key-and-password') {
             // Wait for password
-            const hash = sdk_1.Hash.sha256(recoveryKey);
+            const hash = (0, Hash_1.sha256)(recoveryKey);
             const token = await this.UMPTokenInteractor.findByRecoveryKeyHash(hash);
             if (token == null)
                 throw new Error('No user found with this recovery key');
@@ -1179,7 +1230,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);
         }
     }
@@ -1196,7 +1247,7 @@ class CWIStyleWalletManager {
             throw new Error('No root primary key or current UMP token set');
         }
         const snapshotKey = (0, sdk_1.Random)(32);
-        const snapshotPreimageWriter = new sdk_1.Utils.Writer();
+        const snapshotPreimageWriter = new utils_1.Writer();
         // Write root primary key
         snapshotPreimageWriter.write(this.rootPrimaryKey);
         // Write serialized UMP token (must have outpoint)
@@ -1210,7 +1261,7 @@ class CWIStyleWalletManager {
         const snapshotPreimage = snapshotPreimageWriter.toArray();
         const snapshotPayload = new sdk_1.SymmetricKey(snapshotKey).encrypt(snapshotPreimage);
         // Build final snapshot (Version 2)
-        const snapshotWriter = new sdk_1.Utils.Writer();
+        const snapshotWriter = new utils_1.Writer();
         snapshotWriter.writeUInt8(2); // Version
         snapshotWriter.write(snapshotKey);
         snapshotWriter.write(this.activeProfileId); // Active profile ID
@@ -1221,7 +1272,7 @@ class CWIStyleWalletManager {
         }
         this.telemetry.capture({
             name: 'wallet-toolbox.snapshot.saved',
-            component: 'wallet-toolbox.cwi-manager',
+            component: CWI_COMPONENT,
             severity: 'info',
             attributes: {
                 formatVersion: 2,
@@ -1243,7 +1294,7 @@ class CWIStyleWalletManager {
                 snapshot.some(byte => !Number.isInteger(byte) || byte < 0 || byte > 255)) {
                 throw new Error('Snapshot is empty, oversized, or contains invalid bytes.');
             }
-            const reader = new sdk_1.Utils.Reader(snapshot);
+            const reader = new utils_1.Reader(snapshot);
             const version = reader.readUInt8();
             let snapshotKey;
             let encryptedPayload;
@@ -1262,22 +1313,22 @@ class CWIStyleWalletManager {
             }
             // Decrypt payload
             const decryptedPayload = new sdk_1.SymmetricKey(snapshotKey).decrypt(encryptedPayload);
-            const payloadReader = new sdk_1.Utils.Reader(decryptedPayload);
+            const payloadReader = new utils_1.Reader(decryptedPayload);
             // Read root primary key
             const rootPrimaryKey = payloadReader.read(32);
             // Read serialized UMP token
-            const tokenLen = payloadReader.readVarIntNum();
+            const tokenLen = payloadReader.readVarIntNumStrict(false);
             const tokenBytes = payloadReader.read(tokenLen);
             const token = this.deserializeUMPToken(tokenBytes);
             // 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 +1340,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 +1369,7 @@ class CWIStyleWalletManager {
             return false;
         }
         this.currentUMPToken = refreshed;
-        await this.setupRootInfrastructure(this.rootPrimaryKey);
+        await this.setupRoot(this.rootPrimaryKey);
         this.saveSnapshot();
         return true;
     }
@@ -1395,7 +1446,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 +1481,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
         );
     }
@@ -1494,12 +1545,12 @@ class CWIStyleWalletManager {
             passwordSalt,
             passwordKdf: kdfToUse
         };
-        const newPasswordKey = await derivePasswordKey(tempTokenForKdf, sdk_1.Utils.toArray(newPassword, 'utf8'));
+        const newPasswordKey = await derivePasswordKey(tempTokenForKdf, (0, utils_1.toArray)(newPassword, 'utf8'));
         // Decrypt existing factors needed for re-encryption, using the *root* privileged key manager
         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 +1561,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 +1580,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 +1601,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 +1671,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 +1684,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) {
@@ -1655,7 +1706,7 @@ class CWIStyleWalletManager {
         let profilesEncrypted;
         if (profiles != null && profiles.length > 0) {
             const profilesJson = JSON.stringify(profiles);
-            const profilesBytes = sdk_1.Utils.toArray(profilesJson, 'utf8');
+            const profilesBytes = (0, utils_1.toArray)(profilesJson, 'utf8');
             profilesEncrypted = new sdk_1.SymmetricKey(rootPrimaryKey).encrypt(profilesBytes);
         }
         // Construct the new UMP token data.
@@ -1670,8 +1721,8 @@ class CWIStyleWalletManager {
             presentationRecoveryPrimary: presentationRecovery.encrypt(rootPrimaryKey),
             passwordPrimaryPrivileged: primaryPassword.encrypt(rootPrivilegedKey),
             presentationRecoveryPrivileged: presentationRecovery.encrypt(rootPrivilegedKey),
-            presentationHash: sdk_1.Hash.sha256(presentationKey),
-            recoveryHash: sdk_1.Hash.sha256(recoveryKey),
+            presentationHash: (0, Hash_1.sha256)(presentationKey),
+            recoveryHash: (0, Hash_1.sha256)(recoveryKey),
             presentationKeyEncrypted: (await tempRootPrivilegedKeyManager.encrypt({
                 plaintext: presentationKey,
                 protocolID: [2, 'admin key wrapping'],
@@ -1703,7 +1754,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 +1778,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' }
                 });
@@ -1742,7 +1793,7 @@ class CWIStyleWalletManager {
         if (!token.currentOutpoint) {
             throw new Error('Token must have outpoint for serialization');
         }
-        const writer = new sdk_1.Utils.Writer();
+        const writer = new utils_1.Writer();
         const hasKdfMetadata = token.umpVersion === 3 && token.passwordKdf;
         writer.writeUInt8(hasKdfMetadata ? 3 : 2); // Version 3 for KDF, 2 for legacy
         const writeArray = (arr) => {
@@ -1773,7 +1824,7 @@ class CWIStyleWalletManager {
         if (hasKdfMetadata) {
             writer.writeUInt8(1); // Flag indicating KDF metadata present
             writer.writeUInt8(token.umpVersion); // On-chain UMP version
-            const algorithmBytes = sdk_1.Utils.toArray(token.passwordKdf.algorithm, 'utf8');
+            const algorithmBytes = (0, utils_1.toArray)(token.passwordKdf.algorithm, 'utf8');
             writeArray(algorithmBytes);
             // Serialize KDF params as JSON
             const kdfParams = {
@@ -1788,7 +1839,7 @@ class CWIStyleWalletManager {
             if (token.passwordKdf.hashLength !== undefined) {
                 kdfParams.hashLength = token.passwordKdf.hashLength;
             }
-            const kdfParamsBytes = sdk_1.Utils.toArray(JSON.stringify(kdfParams), 'utf8');
+            const kdfParamsBytes = (0, utils_1.toArray)(JSON.stringify(kdfParams), 'utf8');
             writeArray(kdfParamsBytes);
         }
         else if (writer.toArray()[0] === 3) {
@@ -1796,7 +1847,7 @@ class CWIStyleWalletManager {
             writer.writeUInt8(0); // Flag indicating no KDF metadata
         }
         // Write outpoint string
-        const outpointBytes = sdk_1.Utils.toArray(token.currentOutpoint, 'utf8');
+        const outpointBytes = (0, utils_1.toArray)(token.currentOutpoint, 'utf8');
         writer.writeVarIntNum(outpointBytes.length);
         writer.write(outpointBytes);
         return writer.toArray();
@@ -1805,13 +1856,13 @@ class CWIStyleWalletManager {
      * Deserializes a UMP token from binary format (Handles Version 1, 2, and 3).
      */
     deserializeUMPToken(bin) {
-        const reader = new sdk_1.Utils.Reader(bin);
+        const reader = new utils_1.Reader(bin);
         const version = reader.readUInt8();
         if (version !== 1 && version !== 2 && version !== 3) {
             throw new Error(`Unsupported UMP token serialization version: ${version}`);
         }
         const readArray = () => {
-            const length = reader.readVarIntNum();
+            const length = reader.readVarIntNumStrict(false);
             if (length <= 0 || length > exports.MAX_STATE_SNAPSHOT_BYTES) {
                 throw new Error('UMP token field exceeds allowed bounds.');
             }
@@ -1845,9 +1896,9 @@ class CWIStyleWalletManager {
             if (kdfFlag === 1) {
                 umpVersion = reader.readUInt8(); // On-chain UMP version
                 const algorithmBytes = readArray();
-                const algorithm = sdk_1.Utils.toUTF8(algorithmBytes);
+                const algorithm = (0, utils_1.toUTF8)(algorithmBytes);
                 const kdfParamsBytes = readArray();
-                const kdfParamsJson = sdk_1.Utils.toUTF8(kdfParamsBytes);
+                const kdfParamsJson = (0, utils_1.toUTF8)(kdfParamsBytes);
                 const kdfParams = JSON.parse(kdfParamsJson);
                 passwordKdf = {
                     algorithm,
@@ -1862,9 +1913,9 @@ class CWIStyleWalletManager {
             }
         }
         // Read outpoint string
-        const outpointLen = reader.readVarIntNum();
+        const outpointLen = reader.readVarIntNumStrict(false);
         const outpointBytes = reader.read(outpointLen);
-        const currentOutpoint = sdk_1.Utils.toUTF8(outpointBytes);
+        const currentOutpoint = (0, utils_1.toUTF8)(outpointBytes);
         if (currentOutpoint.length > 128 || !/^[^\s.:]+[.:]\d+$/.test(currentOutpoint)) {
             throw new Error('Serialized UMP token contains an invalid outpoint.');
         }
@@ -1895,11 +1946,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
@@ -1913,7 +1964,7 @@ class CWIStyleWalletManager {
             // 2. Otherwise, derive from password
             const password = await this.passwordRetriever(reason, async (passwordCandidate) => {
                 try {
-                    const derivedPasswordKey = await derivePasswordKey(this.currentUMPToken, sdk_1.Utils.toArray(passwordCandidate, 'utf8'));
+                    const derivedPasswordKey = await derivePasswordKey(this.currentUMPToken, (0, utils_1.toArray)(passwordCandidate, 'utf8'));
                     const privilegedDecryptor = this.XOR(this.rootPrimaryKey, derivedPasswordKey);
                     const decryptedPrivileged = new sdk_1.SymmetricKey(privilegedDecryptor).decrypt(this.currentUMPToken.passwordPrimaryPrivileged);
                     return !!decryptedPrivileged; // Test passes if decryption works
@@ -1926,7 +1977,7 @@ class CWIStyleWalletManager {
                 }
             });
             // Decrypt the root privileged key using the confirmed password (with token-driven KDF)
-            const derivedPasswordKey = await derivePasswordKey(this.currentUMPToken, sdk_1.Utils.toArray(password, 'utf8'));
+            const derivedPasswordKey = await derivePasswordKey(this.currentUMPToken, (0, utils_1.toArray)(password, 'utf8'));
             const privilegedDecryptor = this.XOR(this.rootPrimaryKey, derivedPasswordKey);
             const rootPrivilegedBytes = new sdk_1.SymmetricKey(privilegedDecryptor).decrypt(this.currentUMPToken.passwordPrimaryPrivileged);
             return new sdk_1.PrivateKey(rootPrivilegedBytes); // Return the ROOT key object
@@ -1935,8 +1986,8 @@ 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 profilesJson = sdk_1.Utils.toUTF8(decryptedProfileBytes);
+                const decryptedProfileBytes = new sdk_1.SymmetricKey(rootKey).decrypt(this.currentUMPToken.profilesEncrypted);
+                const profilesJson = (0, utils_1.toUTF8)(decryptedProfileBytes);
                 const profiles = JSON.parse(profilesJson);
                 if (!Array.isArray(profiles) || profiles.length > 1000 || !profiles.every(isValidProfile)) {
                     throw new Error('Decrypted profile data is invalid or exceeds supported bounds.');
@@ -1947,7 +1998,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 +2016,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 +2030,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 +2133,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;