@bsv/wallet-toolbox-client 2.8.0 → 2.10.0

package/out/index.client.cjs

@@ -4081,7 +4081,7 @@ var EntitySyncState = class EntitySyncState extends EntityBase {
 		log += formatSyncSection("OUTPUTS", c.outputs, (r) => `${r.outputId} ${r.txid}.${r.vout} ${r.transactionId} ${r.spendable ? "spendable" : ""} sats:${r.satoshis}`);
 		return log;
 	}
-	async processSyncChunk(writer, args, chunk) {
+	async processSyncChunk(writer, args, chunk, trx) {
 		const mes = [
 			new MergeEntity(chunk.provenTxs, EntityProvenTx.mergeFind, this.syncMap.provenTx),
 			new MergeEntity(chunk.outputBaskets, EntityOutputBasket.mergeFind, this.syncMap.outputBasket),
@@ -4102,16 +4102,16 @@ var EntitySyncState = class EntitySyncState extends EntityBase {
 		let done = true;
 		if (chunk.user != null) {
 			const ei = chunk.user;
-			const { found, eo } = await EntityUser.mergeFind(writer, this.userId, ei);
+			const { found, eo } = await EntityUser.mergeFind(writer, this.userId, ei, trx);
 			if (found) {
-				if (await eo.mergeExisting(writer, args.since, ei)) {
+				if (await eo.mergeExisting(writer, args.since, ei, void 0, trx)) {
 					maxUpdated_at = maxDate(maxUpdated_at, ei.updated_at);
 					updates++;
 				}
 			}
 		}
 		for (const me of mes) {
-			const r = await me.merge(args.since, writer, this.userId, this.syncMap);
+			const r = await me.merge(args.since, writer, this.userId, this.syncMap, trx);
 			me.esm.count += me.stateArray?.length || 0;
 			updates += r.updates;
 			inserts += r.inserts;
@@ -4122,7 +4122,7 @@ var EntitySyncState = class EntitySyncState extends EntityBase {
 			this.when = maxUpdated_at;
 			for (const me of mes) me.esm.count = 0;
 		}
-		await this.updateStorage(writer, false);
+		await this.updateStorage(writer, false, trx);
 		return {
 			done,
 			maxUpdated_at,
@@ -8254,28 +8254,70 @@ function verifyActionBatchManifestDigest(manifest) {
 //#endregion
 //#region ../src/utility/beefForTxids.ts
 /**
-* Return the minimal subgraph needed to prove the requested transactions.
+* Return a minimal BEEF when the source contains data outside the requested
+* transaction dependency closure. Return undefined when no pruning is needed.
 *
-* Parents are added before children so the resulting BEEF preserves dependency
-* order. Shared ancestors and bumps are merged only once.
+* This form lets forwarding clients retain the caller's original bytes in the
+* common no-op case instead of rebuilding and reserializing an equivalent BEEF.
+*/
+function pruneBeefForTxids(source, txids) {
+	const selection = selectTransactions(source, txids);
+	if (selection.transactions.size === source.txs.length && selection.bumpIndexes.size === source.bumps.length) return;
+	return copySelection(source, selection);
+}
+/**
+* Return an independent minimal BEEF needed to prove the requested transactions.
+*
+* Transactions remain in source order and are sorted by Beef when serialized.
+* The source is indexed and walked once, using an explicit stack so a hostile
+* dependency depth cannot exhaust the JavaScript call stack.
 */
 function beefForTxids(source, txids) {
-	const beef = new _bsv_sdk.Beef();
+	return copySelection(source, selectTransactions(source, txids));
+}
+function selectTransactions(source, txids) {
+	const byTxid = /* @__PURE__ */ new Map();
+	for (const tx of source.txs) byTxid.set(tx.txid, tx);
+	const transactions = /* @__PURE__ */ new Set();
+	const bumpIndexes = /* @__PURE__ */ new Set();
 	const visited = /* @__PURE__ */ new Set();
-	const visit = (txid) => {
-		if (visited.has(txid)) return;
+	const stack = [...txids];
+	while (stack.length > 0) {
+		const txid = stack.pop();
+		if (txid == null || visited.has(txid)) continue;
 		visited.add(txid);
-		const sourceTx = source.findTxid(txid);
-		if (sourceTx == null) return;
-		if (sourceTx.tx != null) {
-			for (const input of sourceTx.tx.inputs) if (input.sourceTXID != null) visit(input.sourceTXID);
-		}
-		if (sourceTx.bumpIndex != null) beef.mergeBump(source.bumps[sourceTx.bumpIndex]);
-		beef.mergeBeefTx(sourceTx);
+		const tx = byTxid.get(txid);
+		if (tx == null) continue;
+		transactions.add(tx);
+		const bumpIndex = tx.bumpIndex;
+		if (bumpIndex != null && Number.isSafeInteger(bumpIndex) && bumpIndex >= 0 && bumpIndex < source.bumps.length) bumpIndexes.add(bumpIndex);
+		for (const inputTxid of tx.inputTxids) if (!visited.has(inputTxid)) stack.push(inputTxid);
+	}
+	return {
+		transactions,
+		bumpIndexes
 	};
-	for (const txid of txids) visit(txid);
+}
+function copySelection(source, selection) {
+	const beef = new _bsv_sdk.Beef(source.version);
+	const bumpIndexMap = /* @__PURE__ */ new Map();
+	for (let index = 0; index < source.bumps.length; index++) {
+		if (!selection.bumpIndexes.has(index)) continue;
+		bumpIndexMap.set(index, beef.bumps.length);
+		beef.bumps.push(cloneMerklePath(source.bumps[index]));
+	}
+	for (const sourceTx of source.txs) {
+		if (!selection.transactions.has(sourceTx)) continue;
+		const bumpIndex = sourceTx.bumpIndex == null ? void 0 : bumpIndexMap.get(sourceTx.bumpIndex);
+		const rawTx = sourceTx.rawTxUint8Array;
+		const copy = rawTx == null ? _bsv_sdk.BeefTx.fromTxid(sourceTx.txid, bumpIndex) : new _bsv_sdk.BeefTx(Uint8Array.from(rawTx), bumpIndex, Array.from(sourceTx.inputTxids));
+		beef.txs.push(copy);
+	}
 	return beef;
 }
+function cloneMerklePath(source) {
+	return new _bsv_sdk.MerklePath(source.blockHeight, source.path.map((level) => level.map((leaf) => ({ ...leaf }))), false, false);
+}
 //#endregion
 //#region ../src/storage/methods/offsetKey.ts
 function keyOffsetToHashedSecret(pub, keyOffset) {
@@ -10973,7 +11015,7 @@ function validateRequiredOutputs(storage, userId, vargs) {
 * @returns {xinputs} extended validated required inputs.
 */
 async function validateRequiredInputs(storage, userId, vargs) {
-	const beef = new _bsv_sdk.Beef();
+	let beef = new _bsv_sdk.Beef();
 	if (vargs.inputs.length === 0) return {
 		storageBeef: beef,
 		beef,
@@ -10999,6 +11041,7 @@ async function validateRequiredInputs(storage, userId, vargs) {
 		inputsByTxid[input.outpoint.txid] ||= [];
 		inputsByTxid[input.outpoint.txid].push(input);
 	}
+	beef = beefForTxids(beef, Object.keys(inputsByTxid));
 	const localKnownInputTxids = {};
 	for (const [txid, txInputs] of Object.entries(inputsByTxid)) localKnownInputTxids[txid] = txInputs.every((input) => {
 		const output = preloadedOutputsByOutpoint[`${input.outpoint.txid}.${input.outpoint.vout}`];
@@ -15260,11 +15303,19 @@ var StorageProvider = class StorageProvider extends StorageReaderWriter {
 		return await this.updateOutput(output.outputId, { basketId: void 0 });
 	}
 	async processSyncChunk(args, chunk) {
-		const user = verifyTruthy(await this.findUserByIdentityKey(args.identityKey));
-		return await new EntitySyncState(verifyOne(await this.findSyncStates({ partial: {
-			storageIdentityKey: args.fromStorageIdentityKey,
-			userId: user.userId
-		} }))).processSyncChunk(this, args, chunk);
+		return await this.transaction(async (trx) => {
+			const user = verifyTruthy(verifyOneOrNone(await this.findUsers({
+				partial: { identityKey: args.identityKey },
+				trx
+			})));
+			return await new EntitySyncState(verifyOne(await this.findSyncStates({
+				partial: {
+					storageIdentityKey: args.fromStorageIdentityKey,
+					userId: user.userId
+				},
+				trx
+			}))).processSyncChunk(this, args, chunk, trx);
+		});
 	}
 	/**
 	* Handles storage changes when a valid MerklePath and mined block header are found for a ProvenTxReq txid.
@@ -17329,8 +17380,10 @@ var StorageIdb = class extends StorageProvider {
 			await tx.done;
 			return r;
 		} catch (err) {
-			tx.abort();
-			await tx.done;
+			try {
+				tx.abort();
+				await tx.done;
+			} catch {}
 			throw err;
 		}
 	}
@@ -18297,6 +18350,25 @@ var StorageClientBase = class {
 	* @returns `StorageCreateActionResults` supporting additional wallet processing to yield `createAction` results.
 	*/
 	async createAction(auth, args) {
+		if (args.inputBEEF != null) if (args.inputs.length === 0) args = {
+			...args,
+			inputBEEF: void 0
+		};
+		else {
+			let source;
+			try {
+				source = _bsv_sdk.Beef.fromBinary(args.inputBEEF);
+			} catch {
+				source = void 0;
+			}
+			if (source != null) {
+				const pruned = pruneBeefForTxids(source, args.inputs.map((input) => input.outpoint.txid));
+				if (pruned != null) args = {
+					...args,
+					inputBEEF: pruned.toBinary()
+				};
+			}
+		}
 		return await this.rpcCall("createAction", [auth, args]);
 	}
 	/**
@@ -19597,6 +19669,24 @@ function isLiveBlockHeader(header) {
 	return "chainWork" in header && typeof header.previousHash === "string";
 }
 //#endregion
+//#region ../src/services/chaintracker/chaintracks/Api/BulkFileDataValidatorApi.ts
+/**
+* Identifies deterministic rejection of the supplied immutable bytes.
+* Operational failures such as worker crashes and queue saturation deliberately
+* use ordinary errors so callers preserve the cache entry and avoid downloading
+* a replacement that cannot be validated.
+*
+* @public
+*/
+var BulkFileDataValidationError = class extends Error {
+	data;
+	constructor(message, data) {
+		super(message);
+		this.data = data;
+		this.name = "BulkFileDataValidationError";
+	}
+};
+//#endregion
 //#region ../src/services/chaintracker/chaintracks/util/HeightRange.ts
 /**
 * Represents a range of block heights.
@@ -19815,6 +19905,8 @@ var Chaintracks = class {
 	lastPresentHeight = -1;
 	lastPresentHeightMsecs = 0;
 	lastPresentHeightMaxAge = 60 * 1e3;
+	presentHeightRefresh;
+	mainLoopHeartbeatMsecs = 0;
 	lock = new SingleWriterMultiReaderLock();
 	sourceStatus = /* @__PURE__ */ new Map();
 	constructor(options) {
@@ -19852,12 +19944,31 @@ var Chaintracks = class {
 		return this.chain;
 	}
 	/**
-	* Caches and returns most recently sourced value if less than one minute old.
-	* @returns the current externally available chain height (via bulk ingestors).
+	* Returns the last known valid height immediately and refreshes stale state
+	* once in the background. Cold start waits for the single shared refresh.
 	*/
 	async getPresentHeight() {
 		const now = Date.now();
 		if (this.lastPresentHeight >= 0 && now - this.lastPresentHeightMsecs < this.lastPresentHeightMaxAge) return this.lastPresentHeight;
+		if (this.lastPresentHeight >= 0) {
+			this.refreshPresentHeight().catch((error) => {
+				this.log(`Background present-height refresh failed: ${WalletError.fromUnknown(error).message}`);
+			});
+			return this.lastPresentHeight;
+		}
+		return await this.refreshPresentHeight();
+	}
+	async refreshPresentHeight() {
+		if (this.presentHeightRefresh != null) return await this.presentHeightRefresh;
+		const refresh = this.loadPresentHeight();
+		this.presentHeightRefresh = refresh;
+		try {
+			return await refresh;
+		} finally {
+			if (this.presentHeightRefresh === refresh) this.presentHeightRefresh = void 0;
+		}
+	}
+	async loadPresentHeight() {
 		for (const [index, bulk] of this.bulkIngestors.entries()) {
 			const source = this.sourceName("bulk", index, bulk);
 			try {
@@ -19865,7 +19976,7 @@ var Chaintracks = class {
 				if (presentHeight != null && Number.isInteger(presentHeight) && presentHeight >= 0) {
 					this.markSourceSuccess(source, "bulk");
 					this.lastPresentHeight = presentHeight;
-					this.lastPresentHeightMsecs = now;
+					this.lastPresentHeightMsecs = Date.now();
 					return presentHeight;
 				}
 			} catch (uerr) {
@@ -19880,7 +19991,7 @@ var Chaintracks = class {
 			const localHeight = Math.max(ranges.bulk.maxHeight, ranges.live.maxHeight);
 			if (localHeight >= 0) {
 				this.lastPresentHeight = localHeight;
-				this.lastPresentHeightMsecs = now;
+				this.lastPresentHeightMsecs = Date.now();
 				return localHeight;
 			}
 		} catch (error) {
@@ -19891,6 +20002,19 @@ var Chaintracks = class {
 	async currentHeight() {
 		return await this.getPresentHeight();
 	}
+	/** Returns local process state without locks, storage reads, or network I/O. */
+	getAvailabilitySnapshot() {
+		return {
+			available: this.available,
+			startupError: this.startupError?.message,
+			presentHeight: this.lastPresentHeight >= 0 ? this.lastPresentHeight : void 0,
+			presentHeightUpdatedAt: this.lastPresentHeightMsecs > 0 ? new Date(this.lastPresentHeightMsecs).toISOString() : void 0,
+			presentHeightRefreshInFlight: this.presentHeightRefresh != null,
+			mainLoopHeartbeatAt: this.mainLoopHeartbeatMsecs > 0 ? new Date(this.mainLoopHeartbeatMsecs).toISOString() : void 0,
+			sources: Array.from(this.sourceStatus.values()).map((status) => ({ ...status })),
+			bulkData: this.storage.bulkManager.getStats()
+		};
+	}
 	async subscribeHeaders(listener) {
 		const ID = randomBytesBase64(8);
 		this.callbacks.header[ID] = listener;
@@ -19955,6 +20079,7 @@ var Chaintracks = class {
 			for (const liveIn of this.liveIngestors) await liveIn.shutdown();
 			for (const bulkIn of this.bulkIngestors) await bulkIn.shutdown();
 			await Promise.all(this.promises);
+			await this.storage.bulkManager.destroy();
 			await this.storage.destroy();
 			this.available = false;
 			this.stopMainThread = false;
@@ -20236,9 +20361,11 @@ var Chaintracks = class {
 		const syncCheckRepeatMsecs = 1800 * 1e3;
 		while (!this.stopMainThread) try {
 			const now = Date.now();
+			this.mainLoopHeartbeatMsecs = now;
 			lastSyncCheck = now;
 			lastBulkSync = await this.runBulkSyncIfNeeded(now, lastBulkSync, cdnSyncRepeatMsecs);
 			await this.processLiveHeaderQueue(lastSyncCheck, syncCheckRepeatMsecs);
+			this.mainLoopHeartbeatMsecs = Date.now();
 		} catch (error_) {
 			const e = WalletError.fromUnknown(error_);
 			if (this.available) this.log(`Error occurred during chaintracks main thread processing: ${e.stack || e.message}`);
@@ -20250,7 +20377,7 @@ var Chaintracks = class {
 	}
 	/** Returns (potentially updated) lastBulkSync timestamp. */
 	async runBulkSyncIfNeeded(now, lastBulkSync, cdnSyncRepeatMsecs) {
-		const presentHeight = await this.getPresentHeight();
+		const presentHeight = await this.refreshPresentHeight();
 		const before = await this.storage.getAvailableHeightRanges();
 		let skipBulkSync = !before.live.isEmpty && before.live.maxHeight >= presentHeight - this.addLiveRecursionLimit / 2;
 		if (skipBulkSync && now - lastBulkSync > cdnSyncRepeatMsecs) skipBulkSync = false;
@@ -21399,12 +21526,12 @@ var ChaintracksFetch = class {
 		this.maxRetryMsecs = positiveSafeInteger(options.maxRetryMsecs, DEFAULT_MAX_RETRY_MSECS, "maxRetryMsecs");
 		this.random = options.random ?? Math.random;
 	}
-	async download(url, maxResponseBytes) {
+	async download(url, maxResponseBytes, options) {
 		const responseLimit = maxResponseBytes == null ? this.maxResponseBytes : Math.min(this.maxResponseBytes, positiveSafeInteger(maxResponseBytes, this.maxResponseBytes, "maxResponseBytes"));
 		return await this.requestBytes(url, {
 			method: "GET",
 			headers: { Accept: "application/octet-stream" }
-		}, "download", responseLimit);
+		}, "download", responseLimit, options);
 	}
 	async fetchJson(url) {
 		const bytes = await this.requestBytes(url, {
@@ -21413,8 +21540,9 @@ var ChaintracksFetch = class {
 		}, "fetch JSON", this.maxResponseBytes);
 		return JSON.parse(new TextDecoder().decode(bytes));
 	}
-	async requestBytes(url, init, kind, maxResponseBytes) {
+	async requestBytes(url, init, kind, maxResponseBytes, downloadOptions) {
 		for (let retry = 0;; retry++) {
+			if (retry > 0) await downloadOptions?.beforeRetry?.(retry + 1);
 			const controller = new AbortController();
 			const timeout = setTimeout(() => controller.abort(), this.timeoutMsecs);
 			try {
@@ -21490,6 +21618,38 @@ var ChaintracksFetch = class {
 	}
 };
 //#endregion
+//#region ../src/services/chaintracker/chaintracks/util/InlineBulkFileDataValidator.ts
+/**
+* Portable complete-object validator. Node services should normally inject
+* `NodeBulkFileDataValidator`; browser and mobile consumers retain this
+* dependency-free fallback.
+*
+* @public
+*/
+var InlineBulkFileDataValidator = class {
+	async validate(request) {
+		try {
+			const expectedLength = request.count * 80;
+			if (request.data.length !== expectedLength) throw new WERR_INVALID_PARAMETER("file.data", `bulk file ${request.fileName} data length ${request.data.length} does not match expected count ${request.count}`);
+			const fileHash = asString(_bsv_sdk.Hash.sha256(asArray(request.data)), "base64");
+			if (request.fileHash != null && fileHash !== request.fileHash) throw new WERR_INVALID_PARAMETER("fileHash", `a match for retrieved data for ${request.fileName}`);
+			const { lastHeaderHash, lastChainWork } = validateBufferOfHeaders(request.data, request.prevHash, 0, request.count, request.prevChainWork);
+			if (request.lastHash && request.lastHash !== lastHeaderHash) throw new WERR_INVALID_PARAMETER("file.lastHash", `expected ${request.lastHash} but got ${lastHeaderHash}`);
+			if (request.lastChainWork && request.lastChainWork !== lastChainWork) throw new WERR_INVALID_PARAMETER("file.lastChainWork", `expected ${request.lastChainWork} but got ${lastChainWork}`);
+			if (request.firstHeight === 0 && request.chain != null) validateGenesisHeader(request.data, request.chain);
+			return {
+				data: request.data,
+				fileHash,
+				lastHeaderHash,
+				lastChainWork
+			};
+		} catch (error) {
+			if (error instanceof BulkFileDataValidationError) throw error;
+			throw new BulkFileDataValidationError(error instanceof Error ? error.message : String(error), request.data);
+		}
+	}
+};
+//#endregion
 //#region ../src/services/chaintracker/chaintracks/util/BulkFileDataManager.ts
 /**
 * Manages bulk file data (typically 8MB chunks of 100,000 headers each).
@@ -21515,6 +21675,7 @@ var BulkFileDataManager = class BulkFileDataManager {
 	fileHashToIndex = {};
 	lock = new SingleWriterMultiReaderLock();
 	inFlightLoads = /* @__PURE__ */ new Map();
+	failedLoads = /* @__PURE__ */ new Map();
 	storage;
 	stats = {
 		memoryHits: 0,
@@ -21524,7 +21685,8 @@ var BulkFileDataManager = class BulkFileDataManager {
 		persistentCacheRejects: 0,
 		coalescedLoads: 0,
 		downloads: 0,
-		downloadedBytes: 0
+		downloadedBytes: 0,
+		loadBackoffs: 0
 	};
 	chain;
 	maxPerFile;
@@ -21533,6 +21695,8 @@ var BulkFileDataManager = class BulkFileDataManager {
 	fromKnownSourceUrl;
 	cache;
 	downloadBudget;
+	validator;
+	failedLoadRetryMsecs;
 	constructor(options) {
 		const resolvedOptions = typeof options === "object" ? options : BulkFileDataManager.createDefaultOptions(options);
 		this.chain = resolvedOptions.chain;
@@ -21542,10 +21706,17 @@ var BulkFileDataManager = class BulkFileDataManager {
 		this.fetch = resolvedOptions.fetch;
 		this.cache = resolvedOptions.cache;
 		this.downloadBudget = resolvedOptions.downloadBudget;
+		this.validator = resolvedOptions.validator ?? new InlineBulkFileDataValidator();
+		this.failedLoadRetryMsecs = resolvedOptions.failedLoadRetryMsecs ?? 30 * 1e3;
+		if (!Number.isSafeInteger(this.failedLoadRetryMsecs) || this.failedLoadRetryMsecs < 0) throw new WERR_INVALID_PARAMETER("failedLoadRetryMsecs", "a non-negative safe integer");
 		this.deleteBulkFilesNoLock();
 	}
 	getStats() {
-		return { ...this.stats };
+		return {
+			...this.stats,
+			validation: this.validator.getStats?.(),
+			downloadBudget: this.downloadBudget?.snapshot?.()
+		};
 	}
 	async deleteBulkFiles() {
 		return await this.lock.withWriteLock(async () => this.deleteBulkFilesNoLock());
@@ -21764,9 +21935,29 @@ var BulkFileDataManager = class BulkFileDataManager {
 		});
 	}
 	async getDataFromFile(file, offset, length) {
-		const bfd = this.getBfdForHeight(file.firstHeight);
-		if (bfd == null || bfd.count < file.count) throw new WERR_INVALID_PARAMETER("file", `a match for ${file.firstHeight}, ${file.count} in the BulkFileDataManager.`);
-		return await this.lock.withReadLock(async () => await this.getDataFromFileNoLock(bfd, offset, length));
+		const resolved = await this.lock.withReadLock(async () => {
+			const resolved = this.getBfdForHeight(file.firstHeight);
+			if (resolved == null || resolved.count < file.count) throw new WERR_INVALID_PARAMETER("file", `a match for ${file.firstHeight}, ${file.count} in the BulkFileDataManager.`);
+			return {
+				current: resolved,
+				snapshot: snapshotBfd(resolved)
+			};
+		});
+		return await this.getDataFromSnapshot(resolved.current, resolved.snapshot, offset, length);
+	}
+	async getDataFromSnapshot(original, snapshot, offset, length) {
+		const data = await this.getDataFromFileNoLock(snapshot, offset, length);
+		if (snapshot.data != null) await this.lock.withWriteLock(async () => {
+			if (this.bfds.includes(original) && original.fileHash === snapshot.fileHash && original.firstHeight === snapshot.firstHeight && original.count === snapshot.count) {
+				original.data = snapshot.data;
+				original.validated = true;
+				original.lastHash = snapshot.lastHash;
+				original.lastChainWork = snapshot.lastChainWork;
+				original.mru = Date.now();
+				this.ensureMaxRetained();
+			}
+		});
+		return data;
 	}
 	async getDataFromFileNoLock(bfd, offset, length) {
 		const fileLength = bfd.count * 80;
@@ -21777,15 +21968,19 @@ var BulkFileDataManager = class BulkFileDataManager {
 		return (await this.ensureData(bfd)).slice(offset, offset + length);
 	}
 	async findHeaderForHeightOrUndefined(height) {
-		return await this.lock.withReadLock(async () => {
+		const resolved = await this.lock.withReadLock(async () => {
 			if (!Number.isInteger(height) || height < 0) throw new WERR_INVALID_PARAMETER("height", `a non-negative integer (${height}).`);
 			const file = this.bfds.find((f) => f.firstHeight <= height && f.firstHeight + f.count > height);
 			if (file == null) return void 0;
-			const offset = (height - file.firstHeight) * 80;
-			const data = await this.getDataFromFileNoLock(file, offset, 80);
-			if (data == null) return void 0;
-			return deserializeBlockHeader(data, height, 0);
+			return {
+				current: file,
+				snapshot: snapshotBfd(file),
+				offset: (height - file.firstHeight) * 80
+			};
 		});
+		if (resolved == null) return void 0;
+		const data = await this.getDataFromSnapshot(resolved.current, resolved.snapshot, resolved.offset, 80);
+		return data == null ? void 0 : deserializeBlockHeader(data, height, 0);
 	}
 	async getFileForHeight(height) {
 		return await this.lock.withReadLock(async () => {
@@ -21840,22 +22035,30 @@ var BulkFileDataManager = class BulkFileDataManager {
 		return bfd;
 	}
 	async validateBfdData(bfd, expectedFileHash) {
-		await this.ensureData(bfd);
-		if (bfd.data?.length !== bfd.count * 80) throw new WERR_INVALID_PARAMETER("file.data", `bulk file ${bfd.fileName} data length ${bfd.data?.length} does not match expected count ${bfd.count}`);
-		bfd.fileHash = asString(_bsv_sdk.Hash.sha256(asArray(bfd.data)), "base64");
-		if (expectedFileHash && expectedFileHash !== bfd.fileHash) throw new WERR_INVALID_PARAMETER("file.fileHash", `expected ${expectedFileHash} but got ${bfd.fileHash}`);
-		this.validateBfdHeaders(bfd);
+		const data = await this.ensureData(bfd);
+		bfd.data = await this.validateRetrievedData(bfd, data, expectedFileHash);
 	}
-	validateBfdHeaders(bfd) {
+	async validateBfdHeaders(bfd, expectedFileHash = bfd.fileHash) {
 		const pbf = bfd.firstHeight > 0 ? this.getBfdForHeight(bfd.firstHeight - 1) : void 0;
 		const prevHash = pbf?.lastHash ?? "00".repeat(32);
 		const prevChainWork = pbf?.lastChainWork ?? "00".repeat(32);
-		const { lastHeaderHash, lastChainWork } = validateBufferOfHeaders(bfd.data, prevHash, 0, void 0, prevChainWork);
-		if (bfd.lastHash && bfd.lastHash !== lastHeaderHash) throw new WERR_INVALID_PARAMETER("file.lastHash", `expected ${bfd.lastHash} but got ${lastHeaderHash}`);
-		if (bfd.lastChainWork && bfd.lastChainWork !== lastChainWork) throw new WERR_INVALID_PARAMETER("file.lastChainWork", `expected ${bfd.lastChainWork} but got ${lastChainWork}`);
-		bfd.lastHash = lastHeaderHash;
-		bfd.lastChainWork = lastChainWork;
-		if (bfd.firstHeight === 0) validateGenesisHeader(bfd.data, bfd.chain);
+		const result = await this.validator.validate({
+			fileName: bfd.fileName,
+			data: bfd.data,
+			count: bfd.count,
+			fileHash: expectedFileHash,
+			firstHeight: bfd.firstHeight,
+			prevHash,
+			prevChainWork,
+			lastHash: bfd.lastHash,
+			lastChainWork: bfd.lastChainWork,
+			chain: bfd.chain
+		});
+		bfd.data = result.data;
+		bfd.fileHash = result.fileHash;
+		bfd.lastHash = result.lastHeaderHash;
+		bfd.lastChainWork = result.lastChainWork;
+		return result.data;
 	}
 	async ReValidate() {
 		return await this.lock.withReadLock(async () => await this.ReValidateNoLock());
@@ -22046,62 +22249,96 @@ var BulkFileDataManager = class BulkFileDataManager {
 			this.ensureMaxRetained();
 			return data;
 		}
+		const failed = this.failedLoads.get(key);
+		if (failed != null) {
+			if (Date.now() < failed.retryAt) {
+				this.stats.loadBackoffs++;
+				throw failed.error;
+			}
+			this.failedLoads.delete(key);
+		}
 		const load = this.loadAndValidateData(bfd);
 		this.inFlightLoads.set(key, load);
 		try {
 			const data = await load;
 			bfd.data = data;
 			bfd.validated = true;
+			this.failedLoads.delete(key);
 			bfd.mru = Date.now();
 			this.ensureMaxRetained();
 			return data;
+		} catch (error) {
+			const resolved = error instanceof Error ? error : new Error(String(error));
+			this.failedLoads.set(key, {
+				retryAt: Date.now() + this.failedLoadRetryMsecs,
+				error: resolved
+			});
+			throw resolved;
 		} finally {
 			if (this.inFlightLoads.get(key) === load) this.inFlightLoads.delete(key);
 		}
 	}
 	async loadAndValidateData(bfd) {
-		if (this.storage != null && bfd.fileId) {
-			const stored = await this.storage.getBulkFileData(bfd.fileId);
-			if (stored == null) throw new WERR_INVALID_PARAMETER("fileId", `valid, data not found for fileId ${bfd.fileId}`);
-			this.validateRetrievedData(bfd, stored);
-			this.stats.storageHits++;
-			return stored;
-		}
-		if (this.cache != null) {
-			const cached = await this.cache.get(bfd);
-			if (cached != null) try {
-				this.validateRetrievedData(bfd, cached);
-				this.stats.persistentCacheHits++;
-				return cached;
-			} catch (error) {
-				this.stats.persistentCacheRejects++;
-				await this.cache.delete?.(bfd);
-				this.log(`Rejected corrupt bulk-header cache entry ${bfd.fileName}: ${String(error)}`);
-			}
-			else this.stats.persistentCacheMisses++;
-		}
-		if (this.fetch != null && bfd.sourceUrl) {
-			const expectedBytes = bfd.count * 80;
-			await this.downloadBudget?.consume(expectedBytes);
-			const url = this.fetch.pathJoin(bfd.sourceUrl, bfd.fileName);
-			const downloaded = await this.fetch.download(url, expectedBytes);
-			if (downloaded == null) throw new WERR_INVALID_PARAMETER("sourceUrl", `data not found for sourceUrl ${url}`);
-			this.validateRetrievedData(bfd, downloaded);
-			this.stats.downloads++;
-			this.stats.downloadedBytes += downloaded.length;
-			await this.cache?.set(bfd, downloaded);
-			return downloaded;
-		}
+		const stored = await this.loadFromStorage(bfd);
+		if (stored != null) return stored;
+		const cached = await this.loadFromCache(bfd);
+		if (cached != null) return cached;
+		const downloaded = await this.loadFromRemote(bfd);
+		if (downloaded != null) return downloaded;
 		throw new WERR_INVALID_PARAMETER("data", `defined. Unable to retrieve data for ${bfd.fileName}`);
 	}
-	validateRetrievedData(bfd, data) {
-		if (data.length !== bfd.count * 80) throw new WERR_INVALID_PARAMETER("file.data", `bulk file ${bfd.fileName} data length ${data.length} does not match expected count ${bfd.count}`);
-		if (asString(_bsv_sdk.Hash.sha256(asArray(data)), "base64") !== bfd.fileHash) throw new WERR_INVALID_PARAMETER("fileHash", `a match for retrieved data for ${bfd.fileName}`);
+	async loadFromStorage(bfd) {
+		if (this.storage == null || !bfd.fileId) return void 0;
+		const stored = await this.storage.getBulkFileData(bfd.fileId);
+		if (stored == null) throw new WERR_INVALID_PARAMETER("fileId", `valid, data not found for fileId ${bfd.fileId}`);
+		const validated = await this.validateRetrievedData(bfd, stored);
+		this.stats.storageHits++;
+		return validated;
+	}
+	async loadFromCache(bfd) {
+		if (this.cache == null) return void 0;
+		const cached = await this.cache.get(bfd);
+		if (cached == null) {
+			this.stats.persistentCacheMisses++;
+			return;
+		}
+		try {
+			const validated = await this.validateRetrievedData(bfd, cached);
+			this.stats.persistentCacheHits++;
+			await this.cache.promoteValidated?.(bfd, validated);
+			return validated;
+		} catch (error) {
+			if (!(error instanceof BulkFileDataValidationError)) throw error;
+			this.stats.persistentCacheRejects++;
+			let rejectedData = error.data;
+			if (!(rejectedData instanceof Uint8Array) && cached.byteLength > 0) rejectedData = cached;
+			await this.cache.quarantine?.(bfd, String(error), rejectedData);
+			this.log(`Rejected corrupt bulk-header cache entry ${bfd.fileName}: ${String(error)}`);
+			return;
+		}
+	}
+	async loadFromRemote(bfd) {
+		if (this.fetch == null || !bfd.sourceUrl) return void 0;
+		const expectedBytes = bfd.count * 80;
+		await this.downloadBudget?.consume(expectedBytes);
+		const url = this.fetch.pathJoin(bfd.sourceUrl, bfd.fileName);
+		const downloaded = await this.fetch.download(url, expectedBytes, { beforeRetry: async () => await this.downloadBudget?.consume(expectedBytes) });
+		if (downloaded == null) throw new WERR_INVALID_PARAMETER("sourceUrl", `data not found for sourceUrl ${url}`);
+		const validated = await this.validateRetrievedData(bfd, downloaded);
+		this.stats.downloads++;
+		this.stats.downloadedBytes += validated.length;
+		await this.cache?.set(bfd, validated);
+		return validated;
+	}
+	async validateRetrievedData(bfd, data, expectedFileHash = bfd.fileHash) {
 		const candidate = {
 			...bfd,
 			data
 		};
-		this.validateBfdHeaders(candidate);
+		const validated = await this.validateBfdHeaders(candidate, expectedFileHash);
+		bfd.lastHash = candidate.lastHash;
+		bfd.lastChainWork = candidate.lastChainWork;
+		return validated;
 	}
 	ensureMaxRetained() {
 		if (this.maxRetained === void 0) return;
@@ -22137,17 +22374,24 @@ var BulkFileDataManager = class BulkFileDataManager {
 			i++;
 			const data = await reader.read();
 			if (data == null || data.length === 0) break;
-			const last = validateBufferOfHeaders(data, lastHeaderHash, 0, void 0, lastChainWork);
-			await toFs.writeFile(toPath(i), data);
-			const fileHash = asString(_bsv_sdk.Hash.sha256(asArray(data)), "base64");
+			const validated = await this.validator.validate({
+				fileName: toFileName(i),
+				data,
+				count: data.length / 80,
+				firstHeight,
+				prevHash: lastHeaderHash,
+				prevChainWork: lastChainWork,
+				chain
+			});
+			await toFs.writeFile(toPath(i), validated.data);
 			const file = {
 				chain,
-				count: data.length / 80,
-				fileHash,
+				count: validated.data.length / 80,
+				fileHash: validated.fileHash,
 				fileName: toFileName(i),
 				firstHeight,
-				lastChainWork: last.lastChainWork,
-				lastHash: last.lastHeaderHash,
+				lastChainWork: validated.lastChainWork,
+				lastHash: validated.lastHeaderHash,
 				prevChainWork: lastChainWork,
 				prevHash: lastHeaderHash,
 				sourceUrl
@@ -22159,7 +22403,16 @@ var BulkFileDataManager = class BulkFileDataManager {
 		}
 		await toFs.writeFile(toJsonPath(), asUint8Array(JSON.stringify(toBulkFiles), "utf8"));
 	}
+	async destroy() {
+		await this.validator.destroy?.();
+	}
 };
+function snapshotBfd(file) {
+	return {
+		...file,
+		data: file.data
+	};
+}
 function selectBulkHeaderFiles(files, chain, maxPerFile) {
 	const r = [];
 	let height = 0;
@@ -27028,7 +27281,8 @@ function createDefaultBulkFileDataManager(params) {
 		maxRetained: params.maxRetained,
 		fromKnownSourceUrl: params.cdnUrl,
 		cache: params.sources.bulkFileCache,
-		downloadBudget: params.sources.bulkFileDownloadBudget
+		downloadBudget: params.sources.bulkFileDownloadBudget,
+		validator: params.sources.bulkFileDataValidator
 	});
 }
 function createDefaultChaintracksStorageOptions(params) {
@@ -27553,6 +27807,7 @@ var FixedWindowBulkFileDownloadBudget = class {
 		return {
 			maxBytes: this.maxBytes,
 			consumedBytes: this.consumedBytes,
+			remainingBytes: this.maxBytes - this.consumedBytes,
 			windowStartedAt: this.windowStartedAt,
 			windowMsecs: this.windowMsecs
 		};
@@ -30784,6 +31039,7 @@ var SetupClient = class SetupClient {
 };
 //#endregion
 //#region ../src/CWIStyleWalletManager.ts
+const CWI_COMPONENT = "wallet-toolbox.cwi-manager";
 /**
 * Number of rounds used in PBKDF2 for deriving password keys.
 */
@@ -31016,11 +31272,11 @@ var OverlayUMPTokenInteractor = class {
 	* @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: _bsv_sdk.Utils.toHex(hash) }
-		}, "presentation");
+		}, "presentation", options);
 	}
 	/**
 	* Finds a UMP token on-chain by the given recovery key hash, if it exists.
@@ -31029,13 +31285,13 @@ var OverlayUMPTokenInteractor = class {
 	* @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: _bsv_sdk.Utils.toHex(hash) }
-		}, "recovery");
+		}, "recovery", options);
 	}
-	async findToken(question, lookupKind) {
+	async findToken(question, lookupKind, options) {
 		const correlationId = this.telemetry.enabled === true ? this.telemetry.createCorrelationId() : void 0;
 		const startedAt = Date.now();
 		this.telemetry.capture({
@@ -31052,34 +31308,39 @@ var OverlayUMPTokenInteractor = class {
 				correlationId
 			});
 		} 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) => _bsv_sdk.Utils.toHex(lookupKind === "presentation" ? token.presentationHash : token.recoveryHash).toLowerCase() === expectedHash);
 		if (matchingTokens.length > 1) {
 			const newest = this.resolveNewestToken(matchingTokens, resolution.answer.outputs);
 			if (newest != null) {
-				this.captureLookupCompleted(lookupKind, "found", diagnostics, startedAt, { supersededTokens: matchingTokens.length - 1 });
+				this.lookupDone(lookupKind, "found", diagnostics, startedAt, { supersededTokens: matchingTokens.length - 1 });
 				return newest;
 			}
+			const pinned = options?.pinnedOutpoint ? matchingTokens.find((token) => token.currentOutpoint === options.pinnedOutpoint) : void 0;
+			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];
 		}
 		if (resolution.progress.emptyHosts > 0) {
-			this.captureLookupCompleted(lookupKind, "not-found", diagnostics, startedAt);
+			this.lookupDone(lookupKind, "not-found", diagnostics, startedAt);
 			return;
 		}
 		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);
 	}
 	/**
@@ -31110,7 +31371,7 @@ var OverlayUMPTokenInteractor = class {
 				spent: /* @__PURE__ */ new Set()
 			};
 			evidence.txs.push(tx);
-			this.collectSpentOutpoints(tx, evidence.spent, /* @__PURE__ */ new Set());
+			this.collectSpends(tx, evidence.spent, /* @__PURE__ */ new Set());
 			evidenceByCandidate.set(outpoint, evidence);
 		} catch {}
 		if (evidenceByCandidate.size !== candidates.size) return void 0;
@@ -31119,7 +31380,7 @@ var OverlayUMPTokenInteractor = class {
 		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 void 0;
 		return candidates.get(provenContinuations[0]);
@@ -31130,7 +31391,7 @@ var OverlayUMPTokenInteractor = class {
 	* 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 = _bsv_sdk.Utils.toHex(token.presentationHash);
 		const recoveryHash = _bsv_sdk.Utils.toHex(token.recoveryHash);
 		for (const input of tx.inputs) {
@@ -31156,7 +31417,7 @@ var OverlayUMPTokenInteractor = class {
 	* 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();
@@ -31171,7 +31432,7 @@ var OverlayUMPTokenInteractor = class {
 			}
 		}
 	}
-	emptyLookupDiagnostics(correlationId) {
+	emptyStats(correlationId) {
 		return {
 			hostCount: 0,
 			completedHosts: 0,
@@ -31184,7 +31445,7 @@ var OverlayUMPTokenInteractor = class {
 			...correlationId !== void 0 ? { correlationId } : {}
 		};
 	}
-	toLookupDiagnostics(resolution) {
+	diagnosticsFor(resolution) {
 		const progress = resolution.progress;
 		return {
 			hostCount: progress.hostCount,
@@ -31198,7 +31459,7 @@ var OverlayUMPTokenInteractor = class {
 			...progress.correlationId !== void 0 ? { correlationId: progress.correlationId } : {}
 		};
 	}
-	lookupDiagnosticAttributes(diagnostics) {
+	lookupAttrs(diagnostics) {
 		return {
 			hostCount: diagnostics.hostCount,
 			completedHosts: diagnostics.completedHosts,
@@ -31210,7 +31471,7 @@ var OverlayUMPTokenInteractor = class {
 			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",
@@ -31220,12 +31481,12 @@ var OverlayUMPTokenInteractor = class {
 				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",
@@ -31235,7 +31496,7 @@ var OverlayUMPTokenInteractor = class {
 				lookupKind,
 				reason,
 				durationMs: Date.now() - startedAt,
-				...this.lookupDiagnosticAttributes(diagnostics)
+				...this.lookupAttrs(diagnostics)
 			},
 			error
 		});
@@ -31253,27 +31514,27 @@ var OverlayUMPTokenInteractor = class {
 	* @returns The outpoint of the newly created UMP token (e.g. "abcd1234...ef.0").
 	*/
 	async buildAndSend(wallet, adminOriginator, token, oldTokenToConsume) {
-		const fields = this.buildUMPTokenFields(token);
+		const fields = this.tokenFields(token);
 		const tokenOutput = [{
 			lockingScript: (await new _bsv_sdk.PushDrop(wallet, adminOriginator).lock(fields, [2, "admin user management token"], "1", "self", true, true)).toHex(),
 			satoshis: 1,
 			outputDescription: "New UMP token output"
 		}];
-		const { resolvedOldToken, inputToken } = await this.resolveOldTokenInput(oldTokenToConsume);
+		const { resolvedOldToken, inputToken } = await this.resolveOldInput(oldTokenToConsume);
 		const inputs = resolvedOldToken?.currentOutpoint ? [{
 			outpoint: resolvedOldToken.currentOutpoint,
 			unlockingScriptLength: 73,
 			inputDescription: "Consume old UMP token"
 		}] : [];
-		const createResult = await this.createUMPAction(wallet, adminOriginator, inputs, tokenOutput, inputToken, resolvedOldToken);
-		if (!createResult.signableTransaction) return await this.broadcastFinishedUMPAction(createResult);
+		const createResult = await this.createAction(wallet, adminOriginator, inputs, tokenOutput, inputToken, resolvedOldToken);
+		if (!createResult.signableTransaction) return this.broadcastFinal(createResult);
 		const reference = createResult.signableTransaction.reference;
 		const partialTx = _bsv_sdk.Transaction.fromBEEF(createResult.signableTransaction.tx);
-		if (resolvedOldToken?.currentOutpoint) return await this.signAndBroadcastWithOldToken(wallet, adminOriginator, reference, partialTx);
-		return await this.signAndBroadcastNewToken(wallet, adminOriginator, reference);
+		if (resolvedOldToken?.currentOutpoint) return this.renewToken(wallet, adminOriginator, reference, partialTx);
+		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;
@@ -31300,20 +31561,20 @@ var OverlayUMPTokenInteractor = class {
 		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: void 0,
 			inputToken: void 0
 		};
 		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.");
+		if (inputToken == null) 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)",
@@ -31340,43 +31601,43 @@ var OverlayUMPTokenInteractor = class {
 		}
 	}
 	/** 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 ? _bsv_sdk.Transaction.fromAtomicBEEF(createResult.tx).id("hex") : void 0);
-		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.");
+		if (!finalTxid) throw new Error("UMP transaction was not finalized.");
+		if (createResult.tx == null) throw new Error("UMP transaction data missing.");
 		const broadcastTx = _bsv_sdk.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 unlockingScript = await new _bsv_sdk.PushDrop(wallet, adminOriginator).unlock([2, "admin user management token"], "1", "self").sign(partialTx, 0);
 		const signResult = await wallet.signAction({
 			reference,
 			spends: { 0: { unlockingScript: unlockingScript.toHex() } }
 		}, adminOriginator);
 		const finalTxid = signResult.txid || (signResult.tx == null ? "" : _bsv_sdk.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.");
+		if (!finalTxid) throw new Error("Could not finalize renewed UMP token.");
+		if (signResult.tx == null) throw new Error("Renewed UMP token transaction data missing.");
 		const result = await this.broadcaster.broadcast(_bsv_sdk.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 ? "" : _bsv_sdk.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.");
+		if (!finalTxid) throw new Error("Could not finalize new UMP token.");
+		if (signResult.tx == null) throw new Error("New UMP token transaction data missing.");
 		const result = await this.broadcaster.broadcast(_bsv_sdk.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",
@@ -31405,12 +31666,12 @@ var OverlayUMPTokenInteractor = class {
 		if (answer.type !== "output-list" || answer.outputs.length === 0) 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 = _bsv_sdk.Transaction.fromBEEF(output.beef);
 			const txOutput = tx.outputs[output.outputIndex];
@@ -31460,14 +31721,14 @@ var OverlayUMPTokenInteractor = class {
 				correlationId
 			});
 		} 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) {
 			if (resolution.progress.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;
@@ -31609,20 +31870,20 @@ var CWIStyleWalletManager = class {
 		if (this._initSnapshot !== void 0) {
 			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
 				});
@@ -31631,9 +31892,11 @@ var CWIStyleWalletManager = class {
 		}
 	}
 	/**
-	* 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");
 		if (this.authenticationMode === "recovery-key-and-password") throw new Error("Presentation key is not needed in this mode");
 		if (key.length !== 32 || key.some((byte) => !Number.isInteger(byte) || byte < 0 || byte > 255)) throw new TypeError("Presentation key must contain exactly 32 bytes.");
@@ -31642,17 +31905,17 @@ var CWIStyleWalletManager = class {
 		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",
@@ -31672,7 +31935,7 @@ var CWIStyleWalletManager = class {
 		}
 		this.telemetry.capture({
 			name: "wallet-toolbox.authentication.account-lookup.completed",
-			component: "wallet-toolbox.cwi-manager",
+			component: CWI_COMPONENT,
 			severity: "info",
 			attributes: {
 				lookupKind: "presentation",
@@ -31688,11 +31951,11 @@ var CWIStyleWalletManager = class {
 		if (this.authenticated) throw new Error("User is already authenticated");
 		if (this.authenticationMode === "presentation-key-and-recovery-key") throw new Error("Password is not needed in this mode");
 		if (this.authenticationFlow === "unknown") 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);
-		else await this.handleNewUserPassword(password);
+		if (this.authenticationFlow === "existing-user") await this.unlockExisting(password);
+		else 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, _bsv_sdk.Utils.toArray(password, "utf8"));
 		let rootPrimaryKey;
@@ -31705,11 +31968,11 @@ var CWIStyleWalletManager = class {
 			rootPrimaryKey = new _bsv_sdk.SymmetricKey(this.XOR(this.recoveryKey, derivedPasswordKey)).decrypt(this.currentUMPToken.passwordRecoveryPrimary);
 			rootPrivilegedKey = new _bsv_sdk.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.");
 		if (this.presentationKey == null) throw new Error("No presentation key provided for new-user flow.");
 		const recoveryKey = (0, _bsv_sdk.Random)(32);
@@ -31748,14 +32011,14 @@ var CWIStyleWalletManager = class {
 			passwordKdf: this.kdfConfig
 		};
 		this.currentUMPToken = newToken;
-		await this.setupRootInfrastructure(rootPrimaryKey);
+		await this.setupRoot(rootPrimaryKey);
 		await this.switchProfile(DEFAULT_PROFILE_ID);
 		if (this.newWalletFunder != null && this.underlying != null) try {
 			await this.newWalletFunder(this.presentationKey, this.underlying, this.adminOriginator);
 		} catch (error) {
 			this.telemetry.capture({
 				name: "wallet-toolbox.authentication.new-wallet-funding.failed",
-				component: "wallet-toolbox.cwi-manager",
+				component: CWI_COMPONENT,
 				severity: "error",
 				error: /* @__PURE__ */ new Error("New wallet funding failed.")
 			});
@@ -31786,7 +32049,7 @@ var CWIStyleWalletManager = class {
 			const xorKey = this.XOR(this.presentationKey, recoveryKey);
 			const rootPrimaryKey = new _bsv_sdk.SymmetricKey(xorKey).decrypt(this.currentUMPToken.presentationRecoveryPrimary);
 			const rootPrivilegedKey = new _bsv_sdk.SymmetricKey(xorKey).decrypt(this.currentUMPToken.presentationRecoveryPrivileged);
-			await this.setupRootInfrastructure(rootPrimaryKey, rootPrivilegedKey);
+			await this.setupRoot(rootPrimaryKey, rootPrivilegedKey);
 			await this.switchProfile(this.activeProfileId);
 		}
 	}
@@ -31817,7 +32080,7 @@ var CWIStyleWalletManager = class {
 		if (snapshot.length > 16777216) throw new Error("Snapshot exceeds the maximum supported size.");
 		this.telemetry.capture({
 			name: "wallet-toolbox.snapshot.saved",
-			component: "wallet-toolbox.cwi-manager",
+			component: CWI_COMPONENT,
 			severity: "info",
 			attributes: {
 				formatVersion: 2,
@@ -31855,12 +32118,12 @@ var CWIStyleWalletManager = class {
 			const tokenBytes = payloadReader.read(tokenLen);
 			const token = this.deserializeUMPToken(tokenBytes);
 			this.currentUMPToken = token;
-			await this.setupRootInfrastructure(rootPrimaryKey);
+			await this.setupRoot(rootPrimaryKey);
 			await this.switchProfile(activeProfileId);
 			this.authenticationFlow = "existing-user";
 			this.telemetry.capture({
 				name: "wallet-toolbox.snapshot.loaded",
-				component: "wallet-toolbox.cwi-manager",
+				component: CWI_COMPONENT,
 				severity: "info",
 				attributes: {
 					formatVersion: version,
@@ -31871,7 +32134,7 @@ var CWIStyleWalletManager = class {
 			this.destroy();
 			this.telemetry.capture({
 				name: "wallet-toolbox.snapshot.load-failed",
-				component: "wallet-toolbox.cwi-manager",
+				component: CWI_COMPONENT,
 				severity: "error",
 				error
 			});
@@ -31888,7 +32151,7 @@ var CWIStyleWalletManager = class {
 		if (refreshed == null) return false;
 		if (refreshed.currentOutpoint && currentToken.currentOutpoint && refreshed.currentOutpoint === currentToken.currentOutpoint) return false;
 		this.currentUMPToken = refreshed;
-		await this.setupRootInfrastructure(this.rootPrimaryKey);
+		await this.setupRoot(this.rootPrimaryKey);
 		this.saveSnapshot();
 		return true;
 	}
@@ -31947,7 +32210,7 @@ var CWIStyleWalletManager = class {
 			createdAt: Math.floor(Date.now() / 1e3)
 		};
 		this.profiles.push(newProfile);
-		await this.updateAuthFactors(this.currentUMPToken.passwordSalt, await this.getFactor("passwordKey"), await this.getFactor("presentationKey"), await this.getFactor("recoveryKey"), this.rootPrimaryKey, await this.getFactor("privilegedKey"), this.profiles);
+		await this.updateFactors(this.currentUMPToken.passwordSalt, await this.getFactor("passwordKey"), await this.getFactor("presentationKey"), await this.getFactor("recoveryKey"), this.rootPrimaryKey, await this.getFactor("privilegedKey"), this.profiles);
 		return newProfile.id;
 	}
 	/**
@@ -31964,7 +32227,7 @@ var CWIStyleWalletManager = class {
 		if (profileIndex === -1) throw new Error("Profile not found.");
 		this.profiles.splice(profileIndex, 1);
 		if (this.activeProfileId.every((x, i) => x === profileId[i])) await this.switchProfile(DEFAULT_PROFILE_ID);
-		await this.updateAuthFactors(this.currentUMPToken.passwordSalt, await this.getFactor("passwordKey"), await this.getFactor("presentationKey"), await this.getFactor("recoveryKey"), this.rootPrimaryKey, await this.getFactor("privilegedKey"), this.profiles);
+		await this.updateFactors(this.currentUMPToken.passwordSalt, await this.getFactor("passwordKey"), await this.getFactor("presentationKey"), await this.getFactor("recoveryKey"), this.rootPrimaryKey, await this.getFactor("privilegedKey"), this.profiles);
 	}
 	/**
 	* Switches the active profile. This re-derives keys and rebuilds the underlying wallet.
@@ -32005,14 +32268,14 @@ var CWIStyleWalletManager = class {
 		const recoveryKey = await this.getFactor("recoveryKey");
 		const presentationKey = await this.getFactor("presentationKey");
 		const rootPrivilegedKey = await this.getFactor("privilegedKey");
-		await this.updateAuthFactors(passwordSalt, newPasswordKey, presentationKey, recoveryKey, this.rootPrimaryKey, rootPrivilegedKey, this.profiles);
+		await this.updateFactors(passwordSalt, newPasswordKey, presentationKey, recoveryKey, this.rootPrimaryKey, rootPrivilegedKey, this.profiles);
 	}
 	/**
 	* Retrieves the current recovery key. Requires privileged access.
 	*/
 	async getRecoveryKey() {
 		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.
@@ -32024,7 +32287,7 @@ var CWIStyleWalletManager = class {
 		const rootPrivilegedKey = await this.getFactor("privilegedKey");
 		const newRecoveryKey = (0, _bsv_sdk.Random)(32);
 		await this.recoveryKeySaver(newRecoveryKey);
-		await this.updateAuthFactors(this.currentUMPToken.passwordSalt, passwordKey, presentationKey, newRecoveryKey, this.rootPrimaryKey, rootPrivilegedKey, this.profiles);
+		await this.updateFactors(this.currentUMPToken.passwordSalt, passwordKey, presentationKey, newRecoveryKey, this.rootPrimaryKey, rootPrivilegedKey, this.profiles);
 	}
 	/**
 	* Changes the user's presentation key.
@@ -32035,7 +32298,7 @@ var CWIStyleWalletManager = class {
 		const recoveryKey = await this.getFactor("recoveryKey");
 		const passwordKey = await this.getFactor("passwordKey");
 		const rootPrivilegedKey = await this.getFactor("privilegedKey");
-		await this.updateAuthFactors(this.currentUMPToken.passwordSalt, passwordKey, newPresentationKey, recoveryKey, this.rootPrimaryKey, rootPrivilegedKey, this.profiles);
+		await this.updateFactors(this.currentUMPToken.passwordSalt, passwordKey, newPresentationKey, recoveryKey, this.rootPrimaryKey, rootPrivilegedKey, this.profiles);
 		if (this.presentationKey != null) this.presentationKey = newPresentationKey;
 	}
 	/**
@@ -32081,7 +32344,7 @@ var CWIStyleWalletManager = class {
 		} 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
@@ -32094,7 +32357,7 @@ var CWIStyleWalletManager = class {
 	* 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, profiles) {
+	async updateFactors(passwordSalt, passwordKey, presentationKey, recoveryKey, rootPrimaryKey, rootPrivilegedKey, profiles) {
 		if (!this.authenticated || this.rootPrimaryKey == null || this.currentUMPToken == null) throw new Error("Wallet is not properly authenticated or missing data for update.");
 		const oldTokenToConsume = { ...this.currentUMPToken };
 		if (!oldTokenToConsume.currentOutpoint) throw new Error("Cannot update UMP token: Old token has no outpoint.");
@@ -32145,7 +32408,7 @@ var CWIStyleWalletManager = class {
 		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" }
 			});
@@ -32161,7 +32424,7 @@ var CWIStyleWalletManager = class {
 				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" }
 				});
@@ -32288,9 +32551,9 @@ var CWIStyleWalletManager = class {
 	* @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;
 		let oneTimePrivilegedKey = ephemeralRootPrivilegedKey == null ? void 0 : new _bsv_sdk.PrivateKey(ephemeralRootPrivilegedKey);
 		this.rootPrivilegedKeyManager = new PrivilegedKeyManager(async (reason) => {
 			if (oneTimePrivilegedKey != null) {
@@ -32311,7 +32574,7 @@ var CWIStyleWalletManager = class {
 		});
 		this.profiles = [];
 		if (this.currentUMPToken.profilesEncrypted != null && this.currentUMPToken.profilesEncrypted.length > 0) try {
-			const decryptedProfileBytes = new _bsv_sdk.SymmetricKey(rootPrimaryKey).decrypt(this.currentUMPToken.profilesEncrypted);
+			const decryptedProfileBytes = new _bsv_sdk.SymmetricKey(rootKey).decrypt(this.currentUMPToken.profilesEncrypted);
 			const profilesJson = _bsv_sdk.Utils.toUTF8(decryptedProfileBytes);
 			const profiles = JSON.parse(profilesJson);
 			if (!Array.isArray(profiles) || profiles.length > 1e3 || !profiles.every(isValidProfile)) throw new Error("Decrypted profile data is invalid or exceeds supported bounds.");
@@ -32320,7 +32583,7 @@ var CWIStyleWalletManager = class {
 			this.profiles = [];
 			this.telemetry.capture({
 				name: "wallet-toolbox.profile.load-failed",
-				component: "wallet-toolbox.cwi-manager",
+				component: CWI_COMPONENT,
 				severity: "error",
 				error
 			});
@@ -32329,98 +32592,98 @@ var CWIStyleWalletManager = class {
 		}
 		this.authenticated = true;
 	}
-	checkAuthAndUnderlying(originator) {
+	assertReady(originator) {
 		if (!this.authenticated) throw new Error("User is not authenticated.");
 		if (this.underlying == null) throw new Error("Underlying wallet for the active profile is not initialized.");
 		if (originator === this.adminOriginator) throw new Error("External applications are not allowed to use the admin originator.");
 	}
 	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) throw new Error("User is not authenticated.");
@@ -32430,23 +32693,23 @@ var CWIStyleWalletManager = class {
 	async waitForAuthentication(_, originator) {
 		if (originator === this.adminOriginator) throw new Error("External applications are not allowed to use the admin originator.");
 		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);
 	}
 };
 //#endregion
@@ -32790,6 +33053,8 @@ const DEFAULT_MAX_RESPONSE_BYTES = 1024 * 1024;
 const MAX_CONFIGURED_TIMEOUT_MS = 12e4;
 const MAX_CONFIGURED_REQUEST_BYTES = 10 * 1024 * 1024;
 const MAX_CONFIGURED_RESPONSE_BYTES = 10 * 1024 * 1024;
+const WAB_COMPONENT = "wallet-toolbox.wab-transport";
+const WAB_REQUEST_EVENT = "wallet-toolbox.wab.request.";
 const defaultFetch = typeof globalThis !== "undefined" && typeof globalThis.fetch === "function" ? globalThis.fetch.bind(globalThis) : void 0;
 /**
 * A privacy-safe WAB transport failure. Response bodies and request payloads
@@ -32828,8 +33093,8 @@ function normalizeServerUrl(serverUrl) {
 	} catch {
 		throw new WABClientError("WAB_INVALID_CONFIGURATION", "WAB server URL must be an absolute URL.", false);
 	}
-	if (parsed.username !== "" || parsed.password !== "" || parsed.search !== "" || parsed.hash !== "") throw new WABClientError("WAB_INVALID_CONFIGURATION", "WAB server URL must not contain credentials, a query, or a fragment.", false);
-	if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && isLocalHostname(parsed.hostname))) throw new WABClientError("WAB_INVALID_CONFIGURATION", "WAB server URL must use HTTPS. Plain HTTP is allowed only for localhost development.", false);
+	if (parsed.username !== "" || parsed.password !== "" || parsed.search !== "" || parsed.hash !== "") throw new WABClientError("WAB_INVALID_CONFIGURATION", "WAB URL cannot include credentials, query, or fragment.", false);
+	if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && isLocalHostname(parsed.hostname))) throw new WABClientError("WAB_INVALID_CONFIGURATION", "WAB URL requires HTTPS except on localhost.", false);
 	let pathname = parsed.pathname;
 	while (pathname.endsWith("/")) pathname = pathname.slice(0, -1);
 	return {
@@ -32839,7 +33104,7 @@ function normalizeServerUrl(serverUrl) {
 }
 function normalizePositiveInteger(value, fallback, maximum, name) {
 	const resolved = value ?? fallback;
-	if (!Number.isInteger(resolved) || resolved <= 0 || resolved > maximum) throw new WABClientError("WAB_INVALID_CONFIGURATION", `${name} must be a positive integer no greater than ${maximum}.`, false);
+	if (!Number.isInteger(resolved) || resolved <= 0 || resolved > maximum) throw new WABClientError("WAB_INVALID_CONFIGURATION", `${name} must be an integer from 1 to ${maximum}.`, false);
 	return resolved;
 }
 function assertSafePath(path) {
@@ -32864,20 +33129,20 @@ var WABTransport = class {
 	serverUrl;
 	serverOrigin;
 	telemetry;
-	fetchClient;
-	timeoutMs;
-	maxRequestBytes;
-	maxResponseBytes;
+	fetcher;
+	timeout;
+	requestLimit;
+	responseLimit;
 	constructor(serverUrl, options = {}) {
 		const normalized = normalizeServerUrl(serverUrl);
 		this.serverUrl = normalized.baseUrl;
 		this.serverOrigin = normalized.origin;
-		const fetchClient = options.fetch ?? defaultFetch;
-		if (typeof fetchClient !== "function") throw new WABClientError("WAB_INVALID_CONFIGURATION", "WABClient requires a fetch implementation.", false);
-		this.fetchClient = fetchClient;
-		this.timeoutMs = normalizePositiveInteger(options.timeoutMs, DEFAULT_TIMEOUT_MS, MAX_CONFIGURED_TIMEOUT_MS, "timeoutMs");
-		this.maxRequestBytes = normalizePositiveInteger(options.maxRequestBytes, DEFAULT_MAX_REQUEST_BYTES, MAX_CONFIGURED_REQUEST_BYTES, "maxRequestBytes");
-		this.maxResponseBytes = normalizePositiveInteger(options.maxResponseBytes, DEFAULT_MAX_RESPONSE_BYTES, MAX_CONFIGURED_RESPONSE_BYTES, "maxResponseBytes");
+		const fetcher = options.fetch ?? defaultFetch;
+		if (typeof fetcher !== "function") throw new WABClientError("WAB_INVALID_CONFIGURATION", "WABClient requires a fetch implementation.", false);
+		this.fetcher = fetcher;
+		this.timeout = normalizePositiveInteger(options.timeoutMs, DEFAULT_TIMEOUT_MS, MAX_CONFIGURED_TIMEOUT_MS, "timeoutMs");
+		this.requestLimit = normalizePositiveInteger(options.maxRequestBytes, DEFAULT_MAX_REQUEST_BYTES, MAX_CONFIGURED_REQUEST_BYTES, "maxRequestBytes");
+		this.responseLimit = normalizePositiveInteger(options.maxResponseBytes, DEFAULT_MAX_RESPONSE_BYTES, MAX_CONFIGURED_RESPONSE_BYTES, "maxResponseBytes");
 		this.telemetry = new _bsv_sdk.Telemetry(options.telemetry);
 	}
 	createCorrelationId() {
@@ -32885,38 +33150,9 @@ var WABTransport = class {
 		return isSafeCorrelationId(correlationId) ? correlationId : new _bsv_sdk.Telemetry().createCorrelationId();
 	}
 	async request(path, options) {
-		const metadata = this.createRequestMetadata(path, options);
-		this.captureRequestStarted(metadata);
-		const body = this.encodeRequestBody(options, metadata);
-		const timeout = this.startRequestTimeout(metadata.errorContext);
-		const response = await this.fetchResponse(metadata, body, timeout);
-		const responseContext = this.createResponseContext(response, metadata);
-		this.assertSuccessfulResponse(response, responseContext, metadata, timeout);
-		const responseText = await this.readResponseText(response, responseContext, metadata, timeout);
-		const parsed = this.parseResponseObject(responseText, response, responseContext, metadata);
-		this.telemetry.capture({
-			name: "wallet-toolbox.wab.request.completed",
-			component: "wallet-toolbox.wab-transport",
-			severity: "info",
-			correlationId: metadata.correlationId,
-			attributes: {
-				operation: metadata.operation,
-				method: metadata.method,
-				route: metadata.path,
-				serverOrigin: this.serverOrigin,
-				status: response.status,
-				endpointMarkerPresent: responseContext.endpointMarkerPresent,
-				responseCorrelationMatched: responseContext.responseCorrelationMatched,
-				responseBytes: new TextEncoder().encode(responseText).byteLength,
-				durationMs: Date.now() - metadata.startedAt
-			}
-		});
-		return parsed;
-	}
-	createRequestMetadata(path, options) {
 		assertSafePath(path);
 		const correlationId = options.correlationId != null && isSafeCorrelationId(options.correlationId) ? options.correlationId : this.createCorrelationId();
-		return {
+		const metadata = {
 			method: options.method ?? "POST",
 			path,
 			operation: options.operation,
@@ -32928,46 +33164,73 @@ var WABTransport = class {
 				route: path
 			}
 		};
-	}
-	captureRequestStarted(metadata) {
 		this.telemetry.capture({
-			name: "wallet-toolbox.wab.request.started",
-			component: "wallet-toolbox.wab-transport",
+			name: `${WAB_REQUEST_EVENT}started`,
+			component: WAB_COMPONENT,
 			severity: "debug",
+			correlationId,
+			attributes: {
+				operation: metadata.operation,
+				method: metadata.method,
+				route: path,
+				serverOrigin: this.serverOrigin
+			}
+		});
+		const body = this.bodyFor(options, metadata);
+		const timeout = this.startTimer(metadata.errorContext);
+		const response = await this.fetch(metadata, body, timeout);
+		const responseContext = {
+			...metadata.errorContext,
+			endpointMarkerPresent: isWabResponse(response),
+			responseCorrelationMatched: response.headers.get("X-Correlation-ID") === correlationId
+		};
+		this.checkResponse(response, responseContext, metadata, timeout);
+		const responseText = await this.readText(response, responseContext, metadata, timeout);
+		const parsed = this.parse(responseText, response, responseContext, metadata);
+		this.telemetry.capture({
+			name: `${WAB_REQUEST_EVENT}completed`,
+			component: WAB_COMPONENT,
+			severity: "info",
 			correlationId: metadata.correlationId,
 			attributes: {
 				operation: metadata.operation,
 				method: metadata.method,
 				route: metadata.path,
-				serverOrigin: this.serverOrigin
+				serverOrigin: this.serverOrigin,
+				status: response.status,
+				endpointMarkerPresent: responseContext.endpointMarkerPresent,
+				responseCorrelationMatched: responseContext.responseCorrelationMatched,
+				responseBytes: new TextEncoder().encode(responseText).byteLength,
+				durationMs: Date.now() - metadata.startedAt
 			}
 		});
+		return parsed;
 	}
-	encodeRequestBody(options, metadata) {
+	bodyFor(options, metadata) {
 		let body;
 		try {
 			body = options.body === void 0 ? void 0 : JSON.stringify(options.body);
 		} catch (cause) {
-			const error = new WABClientError("WAB_INVALID_REQUEST", "WAB request payload could not be encoded.", false, void 0, {
+			const error = new WABClientError("WAB_INVALID_REQUEST", "WAB request encoding failed.", false, void 0, {
 				...metadata.errorContext,
 				cause
 			});
-			this.captureRequestFailure(metadata, error);
+			this.report(metadata, error);
 			throw error;
 		}
 		if (options.body !== void 0 && body === void 0) {
-			const error = new WABClientError("WAB_INVALID_REQUEST", "WAB request payload must be JSON-serializable.", false, void 0, metadata.errorContext);
-			this.captureRequestFailure(metadata, error);
+			const error = new WABClientError("WAB_INVALID_REQUEST", "WAB request is not JSON-serializable.", false, void 0, metadata.errorContext);
+			this.report(metadata, error);
 			throw error;
 		}
-		if (body != null && new TextEncoder().encode(body).byteLength > this.maxRequestBytes) {
-			const error = new WABClientError("WAB_REQUEST_TOO_LARGE", "WAB request exceeded the configured size limit.", false, void 0, metadata.errorContext);
-			this.captureRequestFailure(metadata, error);
+		if (body != null && new TextEncoder().encode(body).byteLength > this.requestLimit) {
+			const error = new WABClientError("WAB_REQUEST_TOO_LARGE", "WAB request exceeds its size limit.", false, void 0, metadata.errorContext);
+			this.report(metadata, error);
 			throw error;
 		}
 		return body;
 	}
-	startRequestTimeout(errorContext) {
+	startTimer(errorContext) {
 		const timeout = {
 			controller: new AbortController(),
 			timedOut: false
@@ -32977,12 +33240,12 @@ var WABTransport = class {
 				timeout.timedOut = true;
 				timeout.controller.abort();
 				reject(new WABClientError("WAB_TIMEOUT", "WAB request timed out.", true, void 0, errorContext));
-			}, this.timeoutMs);
+			}, this.timeout);
 		});
 		return timeout;
 	}
-	async fetchResponse(metadata, body, timeout) {
-		const requestPromise = Promise.resolve().then(() => this.fetchClient(`${this.serverUrl}${metadata.path}`, {
+	async fetch(metadata, body, timeout) {
+		const requestPromise = Promise.resolve().then(() => this.fetcher(`${this.serverUrl}${metadata.path}`, {
 			method: metadata.method,
 			headers: {
 				Accept: "application/json",
@@ -33006,33 +33269,26 @@ var WABTransport = class {
 				...metadata.errorContext,
 				cause
 			});
-			else error = new WABClientError("WAB_NETWORK_ERROR", "WAB request failed before receiving a response.", true, void 0, {
+			else error = new WABClientError("WAB_NETWORK_ERROR", "WAB request failed before response.", true, void 0, {
 				...metadata.errorContext,
 				cause
 			});
-			this.captureRequestFailure(metadata, error);
+			this.report(metadata, error);
 			throw error;
 		}
 	}
-	createResponseContext(response, metadata) {
-		return {
-			...metadata.errorContext,
-			endpointMarkerPresent: isWabResponse(response),
-			responseCorrelationMatched: response.headers.get("X-Correlation-ID") === metadata.correlationId
-		};
-	}
-	assertSuccessfulResponse(response, responseContext, metadata, timeout) {
+	checkResponse(response, responseContext, metadata, timeout) {
 		if (response.ok) return;
 		if (timeout.timer !== void 0) clearTimeout(timeout.timer);
 		const endpointMismatch = response.status === 404 && responseContext.endpointMarkerPresent !== true;
-		const error = new WABClientError(endpointMismatch ? "WAB_ENDPOINT_MISMATCH" : "WAB_HTTP_ERROR", endpointMismatch ? "Configured WAB endpoint did not return a compatible WAB response." : `WAB request failed with HTTP status ${response.status}.`, isRetryableStatus(response.status), response.status, responseContext);
-		this.captureRequestFailure(metadata, error);
+		const error = new WABClientError(endpointMismatch ? "WAB_ENDPOINT_MISMATCH" : "WAB_HTTP_ERROR", endpointMismatch ? "WAB endpoint is incompatible." : `WAB request failed with HTTP status ${response.status}.`, isRetryableStatus(response.status), response.status, responseContext);
+		this.report(metadata, error);
 		response.body?.cancel().catch(() => {});
 		throw error;
 	}
-	async readResponseText(response, responseContext, metadata, timeout) {
+	async readText(response, responseContext, metadata, timeout) {
 		try {
-			return await Promise.race([this.readBoundedResponse(response, responseContext), timeout.promise]);
+			return await Promise.race([this.read(response, responseContext), timeout.promise]);
 		} catch (cause) {
 			let error;
 			if (cause instanceof WABClientError) error = cause;
@@ -33040,17 +33296,17 @@ var WABTransport = class {
 				...responseContext,
 				cause
 			});
-			else error = new WABClientError("WAB_INVALID_RESPONSE", "WAB response could not be read.", true, response.status, {
+			else error = new WABClientError("WAB_INVALID_RESPONSE", "WAB response read failed.", true, response.status, {
 				...responseContext,
 				cause
 			});
-			this.captureRequestFailure(metadata, error);
+			this.report(metadata, error);
 			throw error;
 		} finally {
 			if (timeout.timer !== void 0) clearTimeout(timeout.timer);
 		}
 	}
-	parseResponseObject(responseText, response, responseContext, metadata) {
+	parse(responseText, response, responseContext, metadata) {
 		let parsed;
 		try {
 			parsed = JSON.parse(responseText);
@@ -33059,37 +33315,32 @@ var WABTransport = class {
 				...responseContext,
 				cause
 			});
-			this.captureRequestFailure(metadata, error);
+			this.report(metadata, error);
 			throw error;
 		}
 		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
 			const error = new WABClientError("WAB_INVALID_RESPONSE", "WAB response must be a JSON object.", true, response.status, responseContext);
-			this.captureRequestFailure(metadata, error);
+			this.report(metadata, error);
 			throw error;
 		}
 		return parsed;
 	}
-	captureRequestFailure(metadata, error) {
-		this.captureFailure(metadata.operation, metadata.method, metadata.path, metadata.correlationId, metadata.startedAt, error);
-	}
-	async readBoundedResponse(response, responseContext) {
-		await this.rejectOversizedDeclaredResponse(response, responseContext);
-		const reader = response.body?.getReader();
-		if (reader == null) return await this.readBoundedArrayBuffer(response, responseContext);
-		return await this.readBoundedStream(reader, response, responseContext);
-	}
-	async rejectOversizedDeclaredResponse(response, responseContext) {
+	async read(response, responseContext) {
 		const contentLength = Number(response.headers.get("content-length"));
-		if (!Number.isFinite(contentLength) || contentLength <= this.maxResponseBytes) return;
-		await this.cancelResponseBody(response);
-		throw this.responseTooLargeError(response, responseContext);
+		if (Number.isFinite(contentLength) && contentLength > this.responseLimit) {
+			await this.stopBody(response);
+			throw this.sizeError(response, responseContext);
+		}
+		const reader = response.body?.getReader();
+		if (reader == null) return this.readBuffer(response, responseContext);
+		return this.readStream(reader, response, responseContext);
 	}
-	async readBoundedArrayBuffer(response, responseContext) {
+	async readBuffer(response, responseContext) {
 		const bytes = new Uint8Array(await response.arrayBuffer());
-		if (bytes.byteLength > this.maxResponseBytes) throw this.responseTooLargeError(response, responseContext);
+		if (bytes.byteLength > this.responseLimit) throw this.sizeError(response, responseContext);
 		return new TextDecoder().decode(bytes);
 	}
-	async readBoundedStream(reader, response, responseContext) {
+	async readStream(reader, response, responseContext) {
 		const chunks = [];
 		let total = 0;
 		while (true) {
@@ -33097,15 +33348,12 @@ var WABTransport = class {
 			if (done) break;
 			if (value == null) continue;
 			total += value.byteLength;
-			if (total > this.maxResponseBytes) {
-				await this.cancelResponseReader(reader);
-				throw this.responseTooLargeError(response, responseContext);
+			if (total > this.responseLimit) {
+				await this.stopReader(reader);
+				throw this.sizeError(response, responseContext);
 			}
 			chunks.push(value);
 		}
-		return this.decodeChunks(chunks, total);
-	}
-	decodeChunks(chunks, total) {
 		const bytes = new Uint8Array(total);
 		let offset = 0;
 		for (const chunk of chunks) {
@@ -33114,35 +33362,35 @@ var WABTransport = class {
 		}
 		return new TextDecoder().decode(bytes);
 	}
-	responseTooLargeError(response, responseContext) {
-		return new WABClientError("WAB_RESPONSE_TOO_LARGE", "WAB response exceeded the configured size limit.", false, response.status, responseContext);
+	sizeError(response, responseContext) {
+		return new WABClientError("WAB_RESPONSE_TOO_LARGE", "WAB response exceeds its size limit.", false, response.status, responseContext);
 	}
-	async cancelResponseBody(response) {
+	async stopBody(response) {
 		try {
 			await response.body?.cancel();
 		} catch {}
 	}
-	async cancelResponseReader(reader) {
+	async stopReader(reader) {
 		try {
 			await reader.cancel();
 		} catch {}
 	}
-	captureFailure(operation, method, path, correlationId, startedAt, error) {
+	report(metadata, error) {
 		this.telemetry.capture({
-			name: "wallet-toolbox.wab.request.failed",
-			component: "wallet-toolbox.wab-transport",
+			name: `${WAB_REQUEST_EVENT}failed`,
+			component: WAB_COMPONENT,
 			severity: error.retryable ? "warn" : "error",
-			correlationId,
+			correlationId: metadata.correlationId,
 			attributes: {
-				operation,
-				method,
-				route: path,
+				operation: metadata.operation,
+				method: metadata.method,
+				route: metadata.path,
 				serverOrigin: this.serverOrigin,
 				retryable: error.retryable,
 				...error.status !== void 0 ? { status: error.status } : {},
 				...error.endpointMarkerPresent !== void 0 ? { endpointMarkerPresent: error.endpointMarkerPresent } : {},
 				...error.responseCorrelationMatched !== void 0 ? { responseCorrelationMatched: error.responseCorrelationMatched } : {},
-				durationMs: Date.now() - startedAt
+				durationMs: Date.now() - metadata.startedAt
 			},
 			error
 		});
@@ -33251,8 +33499,8 @@ var WABClient = class {
 	constructor(serverUrl, options = {}) {
 		this.transport = new WABTransport(serverUrl, options);
 	}
-	async getInfo() {
-		return await this.transport.request("/info", {
+	getInfo() {
+		return this.transport.request("/info", {
 			method: "GET",
 			operation: "get-info"
 		});
@@ -33262,15 +33510,15 @@ var WABClient = class {
 	}
 	async startAuthMethod(authMethod, presentationKey, payload, correlationId) {
 		assertHexIdentifier(presentationKey, "presentationKey");
-		return await authMethod.startAuth(this.transport.serverUrl, presentationKey, payload, this.transport, correlationId);
+		return authMethod.startAuth(this.transport.serverUrl, presentationKey, payload, this.transport, correlationId);
 	}
 	async completeAuthMethod(authMethod, presentationKey, payload, correlationId) {
 		assertHexIdentifier(presentationKey, "presentationKey");
-		return await authMethod.completeAuth(this.transport.serverUrl, presentationKey, payload, this.transport, correlationId);
+		return authMethod.completeAuth(this.transport.serverUrl, presentationKey, payload, this.transport, correlationId);
 	}
 	async listLinkedMethods(presentationKey) {
 		assertHexIdentifier(presentationKey, "presentationKey");
-		return await this.transport.request("/user/linkedMethods", {
+		return this.transport.request("/user/linkedMethods", {
 			operation: "list-linked-methods",
 			body: { presentationKey }
 		});
@@ -33278,7 +33526,7 @@ var WABClient = class {
 	async unlinkMethod(presentationKey, authMethodId) {
 		assertHexIdentifier(presentationKey, "presentationKey");
 		if (!Number.isSafeInteger(authMethodId) || authMethodId <= 0) throw new TypeError("authMethodId must be a positive safe integer.");
-		return await this.transport.request("/user/unlinkMethod", {
+		return this.transport.request("/user/unlinkMethod", {
 			operation: "unlink-method",
 			body: {
 				presentationKey,
@@ -33288,14 +33536,14 @@ var WABClient = class {
 	}
 	async requestFaucet(presentationKey) {
 		assertHexIdentifier(presentationKey, "presentationKey");
-		return await this.transport.request("/faucet/request", {
+		return this.transport.request("/faucet/request", {
 			operation: "request-faucet",
 			body: { presentationKey }
 		});
 	}
 	async deleteUser(presentationKey) {
 		assertHexIdentifier(presentationKey, "presentationKey");
-		return await this.transport.request("/user/delete", {
+		return this.transport.request("/user/delete", {
 			operation: "delete-user",
 			body: { presentationKey }
 		});
@@ -33304,7 +33552,7 @@ var WABClient = class {
 		assertMethodType(methodType);
 		assertHexIdentifier(userIdHash, "userIdHash");
 		const normalizedPayload = normalizeAuthPayload(methodType, payload);
-		return await this.transport.request("/auth/start", {
+		return this.transport.request("/auth/start", {
 			operation: "start-share-auth",
 			body: {
 				methodType,
@@ -33317,7 +33565,7 @@ var WABClient = class {
 		assertMethodType(methodType);
 		assertHexIdentifier(userIdHash, "userIdHash");
 		const normalizedPayload = normalizeAuthPayload(methodType, payload);
-		return await this.transport.request("/share/store", {
+		return this.transport.request("/share/store", {
 			operation: "store-share",
 			body: {
 				methodType,
@@ -33331,7 +33579,7 @@ var WABClient = class {
 		assertMethodType(methodType);
 		assertHexIdentifier(userIdHash, "userIdHash");
 		const normalizedPayload = normalizeAuthPayload(methodType, payload);
-		return await this.transport.request("/share/retrieve", {
+		return this.transport.request("/share/retrieve", {
 			operation: "retrieve-share",
 			body: {
 				methodType,
@@ -33344,7 +33592,7 @@ var WABClient = class {
 		assertMethodType(methodType);
 		assertHexIdentifier(userIdHash, "userIdHash");
 		const normalizedPayload = normalizeAuthPayload(methodType, payload);
-		return await this.transport.request("/share/update", {
+		return this.transport.request("/share/update", {
 			operation: "update-share",
 			body: {
 				methodType,
@@ -33358,7 +33606,7 @@ var WABClient = class {
 		assertMethodType(methodType);
 		assertHexIdentifier(userIdHash, "userIdHash");
 		const normalizedPayload = normalizeAuthPayload(methodType, payload);
-		return await this.transport.request("/share/delete", {
+		return this.transport.request("/share/delete", {
 			operation: "delete-share-user",
 			body: {
 				methodType,
@@ -33372,9 +33620,13 @@ var WABClient = class {
 //#region ../src/WalletAuthenticationManager.ts
 const DEFAULT_AUTH_SESSION_TTL_MS = 600 * 1e3;
 const MAX_AUTH_SESSION_TTL_MS = 3600 * 1e3;
+const AUTH_COMPONENT = "wallet-toolbox.authentication-manager";
+const AUTH_EVENT = "wallet-toolbox.authentication.";
+const EXISTING_USER = "existing-user";
+const NEW_USER = "new-user";
 var WABAccountContinuityError = class extends Error {
 	code = "WERR_WAB_ACCOUNT_CONTINUITY";
-	constructor(message = "WAB and UMP account state did not agree. Retry or use account recovery.") {
+	constructor(message = "WAB and UMP accounts disagree; retry or recover.") {
 		super(message);
 		this.name = "WABAccountContinuityError";
 	}
@@ -33389,6 +33641,7 @@ var WalletAuthenticationManager = class extends CWIStyleWalletManager {
 	wabClient;
 	authMethod;
 	authSession;
+	phoneChangeSession;
 	authSessionTtlMs;
 	constructor(...[adminOriginator, walletBuilder, interactor, recoveryKeySaver, passwordRetriever, wabClient, authMethod, stateSnapshot, options = {}]) {
 		super(adminOriginator, walletBuilder, interactor, recoveryKeySaver, passwordRetriever, async (presentationKey, wallet, adminOriginator) => {
@@ -33411,7 +33664,7 @@ var WalletAuthenticationManager = class extends CWIStyleWalletManager {
 					description: "Fund wallet",
 					options: { acceptDelayedBroadcast: false }
 				}, adminOriginator);
-				if (faucetRedeemTXCreationResult.signableTransaction == null) throw new Error("Faucet redemption did not return a signableTransaction");
+				if (faucetRedeemTXCreationResult.signableTransaction == null) throw new Error("Faucet redemption was not signable.");
 				const faucetRedeemTX = _bsv_sdk.Transaction.fromAtomicBEEF(faucetRedeemTXCreationResult.signableTransaction.tx);
 				const faucetRedemptionPuzzle = new _bsv_sdk.RPuzzle();
 				const randomRedemptionPrivateKey = _bsv_sdk.PrivateKey.fromRandom();
@@ -33444,7 +33697,7 @@ var WalletAuthenticationManager = class extends CWIStyleWalletManager {
 	* using the chosen AuthMethodInteractor.
 	*/
 	async startAuth(payload) {
-		if (this.authMethod == null) throw new Error("No AuthMethod selected in WalletAuthenticationManager");
+		if (this.authMethod == null) throw new Error("No WAB authentication method selected.");
 		const authMethod = this.authMethod;
 		if (this.authenticated) throw new Error("User is already authenticated");
 		this.cancelAuth();
@@ -33457,8 +33710,8 @@ var WalletAuthenticationManager = class extends CWIStyleWalletManager {
 			...correlationId !== void 0 ? { correlationId } : {}
 		};
 		this.telemetry.capture({
-			name: "wallet-toolbox.authentication.wab-start.started",
-			component: "wallet-toolbox.authentication-manager",
+			name: `${AUTH_EVENT}wab-start.started`,
+			component: AUTH_COMPONENT,
 			severity: "debug",
 			correlationId,
 			attributes: { methodType: authMethod.methodType }
@@ -33470,8 +33723,8 @@ var WalletAuthenticationManager = class extends CWIStyleWalletManager {
 				throw new Error(message);
 			}
 			this.telemetry.capture({
-				name: "wallet-toolbox.authentication.wab-start.completed",
-				component: "wallet-toolbox.authentication-manager",
+				name: `${AUTH_EVENT}wab-start.completed`,
+				component: AUTH_COMPONENT,
 				severity: "info",
 				correlationId,
 				attributes: { methodType: authMethod.methodType }
@@ -33479,8 +33732,8 @@ var WalletAuthenticationManager = class extends CWIStyleWalletManager {
 		} catch (error) {
 			this.cancelAuth();
 			this.telemetry.capture({
-				name: "wallet-toolbox.authentication.wab-start.failed",
-				component: "wallet-toolbox.authentication-manager",
+				name: `${AUTH_EVENT}wab-start.failed`,
+				component: AUTH_COMPONENT,
 				severity: "warn",
 				correlationId,
 				attributes: { methodType: authMethod.methodType },
@@ -33493,22 +33746,22 @@ var WalletAuthenticationManager = class extends CWIStyleWalletManager {
 	* Completes the WAB-based flow, retrieving the final presentationKey from WAB if successful.
 	*/
 	async completeAuth(payload) {
-		if (this.authMethod == null || this.authSession == null) throw new Error("No AuthMethod selected in WalletAuthenticationManager or startAuth has yet to be called.");
+		if (this.authMethod == null || this.authSession == null) throw new Error("Start WAB authentication first.");
 		const authMethod = this.authMethod;
 		if (this.authSession.methodType !== authMethod.methodType) {
 			this.cancelAuth();
-			throw new Error("The selected authentication method changed. Start authentication again.");
+			throw new Error("WAB authentication method changed; restart.");
 		}
 		if (Date.now() >= this.authSession.expiresAt) {
 			this.cancelAuth();
-			throw new Error("The WAB authentication session expired. Start authentication again.");
+			throw new Error("WAB authentication expired; restart.");
 		}
 		const session = this.authSession;
 		const result = await this.wabClient.completeAuthMethod(authMethod, session.presentationKey, payload, session.correlationId);
 		if (result.success !== true || result.presentationKey == null || result.presentationKey.length === 0) {
 			this.telemetry.capture({
-				name: "wallet-toolbox.authentication.wab-complete.rejected",
-				component: "wallet-toolbox.authentication-manager",
+				name: `${AUTH_EVENT}wab-complete.rejected`,
+				component: AUTH_COMPONENT,
 				severity: "warn",
 				correlationId: session.correlationId,
 				attributes: { methodType: session.methodType }
@@ -33523,11 +33776,11 @@ var WalletAuthenticationManager = class extends CWIStyleWalletManager {
 		this.cancelAuth();
 		const wabAccountStatus = this.inferAccountStatus(result, session.presentationKey);
 		try {
-			await this.providePresentationKey(_bsv_sdk.Utils.toArray(result.presentationKey, "hex"));
+			await this.provideWABPresentationKey(result, wabAccountStatus);
 		} catch (error) {
 			this.telemetry.capture({
-				name: "wallet-toolbox.authentication.ump-continuity.failed",
-				component: "wallet-toolbox.authentication-manager",
+				name: `${AUTH_EVENT}ump-continuity.failed`,
+				component: AUTH_COMPONENT,
 				severity: "warn",
 				correlationId: session.correlationId,
 				attributes: {
@@ -33538,18 +33791,18 @@ var WalletAuthenticationManager = class extends CWIStyleWalletManager {
 			});
 			throw error;
 		}
-		if (wabAccountStatus === "existing-user" && this.authenticationFlow !== "existing-user") {
+		if (wabAccountStatus === EXISTING_USER && this.authenticationFlow !== EXISTING_USER) {
 			super.destroy();
 			const error = new WABAccountContinuityError();
 			this.telemetry.capture({
-				name: "wallet-toolbox.authentication.account-continuity.mismatch",
-				component: "wallet-toolbox.authentication-manager",
+				name: `${AUTH_EVENT}account-continuity.mismatch`,
+				component: AUTH_COMPONENT,
 				severity: "error",
 				correlationId: session.correlationId,
 				attributes: {
 					methodType: session.methodType,
 					wabAccountStatus,
-					umpAccountStatus: "new-user"
+					umpAccountStatus: NEW_USER
 				},
 				error
 			});
@@ -33557,8 +33810,8 @@ var WalletAuthenticationManager = class extends CWIStyleWalletManager {
 		}
 		const continuity = wabAccountStatus === this.authenticationFlow ? "matched" : "ump-existing";
 		this.telemetry.capture({
-			name: "wallet-toolbox.authentication.completed",
-			component: "wallet-toolbox.authentication-manager",
+			name: `${AUTH_EVENT}completed`,
+			component: AUTH_COMPONENT,
 			severity: continuity === "matched" ? "info" : "warn",
 			correlationId: session.correlationId,
 			attributes: {
@@ -33572,23 +33825,131 @@ var WalletAuthenticationManager = class extends CWIStyleWalletManager {
 	cancelAuth() {
 		this.authSession = void 0;
 	}
+	readPendingPhoneChange(result) {
+		const presentationKey = result.pendingPresentationKey;
+		const changeId = result.pendingPhoneChangeId;
+		if (presentationKey === void 0 && changeId === void 0) return void 0;
+		if (!/^[0-9a-fA-F]{64}$/.test(presentationKey ?? "") || !Number.isSafeInteger(changeId) || changeId <= 0) throw new WABAccountContinuityError("WAB returned invalid pending phone-change data.");
+		return {
+			presentationKey,
+			changeId
+		};
+	}
+	async provideWABPresentationKey(result, wabAccountStatus) {
+		const umpTokenOutpoint = typeof result.umpTokenOutpoint === "string" ? result.umpTokenOutpoint : void 0;
+		const lookupOptions = umpTokenOutpoint == null ? void 0 : { pinnedOutpoint: umpTokenOutpoint };
+		const pending = this.readPendingPhoneChange(result);
+		let usePending = false;
+		try {
+			await this.providePresentationKey(_bsv_sdk.Utils.toArray(result.presentationKey, "hex"), lookupOptions);
+		} catch (error) {
+			if (pending == null) throw error;
+			usePending = true;
+		}
+		if (pending != null && (usePending || wabAccountStatus === EXISTING_USER && this.authenticationFlow !== EXISTING_USER)) {
+			await this.providePresentationKey(_bsv_sdk.Utils.toArray(pending.presentationKey, "hex"), lookupOptions);
+			if (this.authenticationFlow === EXISTING_USER) await this.finalizePendingPhoneChange(result.presentationKey, pending);
+		}
+	}
+	async finalizePendingPhoneChange(currentPresentationKey, pending) {
+		const finalized = await this.phoneChange("finalize", {
+			changeId: pending.changeId,
+			presentationKey: currentPresentationKey,
+			newPresentationKey: pending.presentationKey
+		});
+		if (finalized.success !== true || finalized.changeId !== pending.changeId) throw new WABAccountContinuityError(finalized.message || "WAB could not finalize the pending phone change.");
+	}
+	/**
+	* Starts OTP verification for a replacement phone number. The same number
+	* is valid and intentionally produces a fresh presentation key/hash.
+	*/
+	async startPhoneNumberChange(phoneNumber) {
+		if (!this.authenticated) throw new Error("Not authenticated");
+		const normalizedPhone = phoneNumber.trim();
+		const currentPresentationKey = _bsv_sdk.Utils.toHex(await this.getFactor("presentationKey"));
+		const response = await this.phoneChange("start", {
+			presentationKey: currentPresentationKey,
+			phoneNumber: normalizedPhone
+		});
+		if (response.success !== true) throw new Error(response.message || "Phone change failed");
+		this.phoneChangeSession = {
+			phoneNumber: normalizedPhone,
+			presentationKey: currentPresentationKey
+		};
+	}
+	/**
+	* Completes phone verification and stages the WAB association before
+	* publishing the UMP key rotation. WAB retains both the current and pending
+	* presentation keys until finalization, so either side of an interrupted
+	* transition remains recoverable on the next verified login.
+	*/
+	async completePhoneNumberChange(otp) {
+		const session = this.phoneChangeSession;
+		if (session == null) throw new Error("No phone change");
+		if (session.changeToken == null) {
+			const authorization = await this.phoneChange("complete", {
+				presentationKey: session.presentationKey,
+				phoneNumber: session.phoneNumber,
+				otp: otp.trim()
+			});
+			if (authorization.success !== true) throw new Error(authorization.message || "Phone change failed");
+			if (/^[0-9a-fA-F]{64}$/.test(authorization.pendingPresentationKey ?? "") && Number.isSafeInteger(authorization.pendingPhoneChangeId) && authorization.pendingPhoneChangeId > 0) {
+				session.newKey = _bsv_sdk.Utils.toArray(authorization.pendingPresentationKey, "hex");
+				session.changeId = authorization.pendingPhoneChangeId;
+			} else if (typeof authorization.changeToken === "string" && authorization.changeToken.length > 0) session.changeToken = authorization.changeToken;
+			else throw new Error(authorization.message || "Phone change failed");
+		}
+		session.newKey ??= (0, _bsv_sdk.Random)(32);
+		if (session.changeId == null) {
+			const committed = await this.phoneChange("commit", {
+				changeToken: session.changeToken,
+				presentationKey: session.presentationKey,
+				newPresentationKey: _bsv_sdk.Utils.toHex(session.newKey)
+			});
+			if (committed.success !== true || !Number.isSafeInteger(committed.changeId) || committed.changeId <= 0) throw new Error(committed.message || "Phone change failed");
+			session.changeId = committed.changeId;
+		}
+		const changeId = session.changeId;
+		if (session.umpUpdated !== true) {
+			await this.changePresentationKey(session.newKey);
+			session.umpUpdated = true;
+		}
+		const finalized = await this.phoneChange("finalize", {
+			changeId,
+			presentationKey: session.presentationKey,
+			newPresentationKey: _bsv_sdk.Utils.toHex(session.newKey)
+		});
+		if (finalized.success !== true || finalized.changeId !== changeId) throw new Error(finalized.message || "Phone change failed");
+		this.phoneChangeSession = void 0;
+		return { changeId };
+	}
+	cancelPhoneNumberChange() {
+		this.phoneChangeSession = void 0;
+	}
 	destroy() {
 		this.cancelAuth();
+		this.cancelPhoneNumberChange();
 		super.destroy();
 	}
+	phoneChange(phase, body) {
+		return this.wabClient.transport.request(`/auth/phone-change/${phase}`, {
+			operation: "phone-change",
+			body
+		});
+	}
 	inferAccountStatus(result, temporaryPresentationKey) {
 		if (result.presentationKey == null) throw new WABAccountContinuityError("WAB did not return a presentation key.");
 		const keyMatchesTemporary = this.constantTimeHexEqual(result.presentationKey, temporaryPresentationKey);
 		const rawAccountStatus = result.accountStatus;
-		if (rawAccountStatus !== void 0 && rawAccountStatus !== "new-user" && rawAccountStatus !== "existing-user") throw new WABAccountContinuityError("WAB returned an invalid account-continuity status.");
+		if (rawAccountStatus !== void 0 && rawAccountStatus !== NEW_USER && rawAccountStatus !== EXISTING_USER) throw new WABAccountContinuityError("WAB returned an invalid account status.");
 		const rawExistingUser = result.existingUser;
-		if (rawExistingUser !== void 0 && typeof rawExistingUser !== "boolean") throw new WABAccountContinuityError("WAB returned an invalid existing-user status.");
-		if (rawAccountStatus !== void 0 && rawExistingUser !== void 0 && rawAccountStatus === "existing-user" !== rawExistingUser) throw new WABAccountContinuityError("WAB returned contradictory account-continuity statuses.");
+		if (rawExistingUser !== void 0 && typeof rawExistingUser !== "boolean") throw new WABAccountContinuityError("WAB returned invalid existing-user data.");
+		if (rawAccountStatus !== void 0 && rawExistingUser !== void 0 && rawAccountStatus === EXISTING_USER !== rawExistingUser) throw new WABAccountContinuityError("WAB returned conflicting account status.");
 		let compatibilityStatus;
-		if (typeof rawExistingUser === "boolean") compatibilityStatus = rawExistingUser ? "existing-user" : "new-user";
+		if (typeof rawExistingUser === "boolean") compatibilityStatus = rawExistingUser ? EXISTING_USER : NEW_USER;
 		const explicitStatus = rawAccountStatus ?? compatibilityStatus;
-		if (explicitStatus === "new-user" && !keyMatchesTemporary || explicitStatus === "existing-user" && keyMatchesTemporary) throw new WABAccountContinuityError("WAB returned contradictory account-continuity data.");
-		return explicitStatus ?? (keyMatchesTemporary ? "new-user" : "existing-user");
+		if (explicitStatus === NEW_USER && !keyMatchesTemporary || explicitStatus === EXISTING_USER && keyMatchesTemporary) throw new WABAccountContinuityError("WAB returned conflicting account status.");
+		return explicitStatus ?? (keyMatchesTemporary ? NEW_USER : EXISTING_USER);
 	}
 	constantTimeHexEqual(left, right) {
 		if (left.length !== right.length) return false;
@@ -36828,6 +37189,7 @@ exports.BHServiceClient = BHServiceClient;
 exports.BRC153_REFERENCE_PREFIX = BRC153_REFERENCE_PREFIX;
 exports.BulkFileDataManager = BulkFileDataManager;
 exports.BulkFileDataReader = BulkFileDataReader;
+exports.BulkFileDataValidationError = BulkFileDataValidationError;
 exports.BulkFilesReader = BulkFilesReader;
 exports.BulkFilesReaderFs = BulkFilesReaderFs;
 exports.BulkFilesReaderStorage = BulkFilesReaderStorage;
@@ -36876,6 +37238,7 @@ exports.EntityUser = EntityUser;
 exports.FixedWindowBulkFileDownloadBudget = FixedWindowBulkFileDownloadBudget;
 exports.GoChaintracksServiceClient = GoChaintracksServiceClient;
 exports.HeightRange = HeightRange;
+exports.InlineBulkFileDataValidator = InlineBulkFileDataValidator;
 exports.KDF_MAX_HASH_LENGTH = KDF_MAX_HASH_LENGTH;
 exports.LEGACY_MANAGED_CHANGE_MINIMUM_SATOSHIS = LEGACY_MANAGED_CHANGE_MINIMUM_SATOSHIS;
 exports.LiveIngestorBase = LiveIngestorBase;