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

package/out/src/services/Services.js

@@ -4,6 +4,7 @@ exports.Services = void 0;
 exports.validateScriptHash = validateScriptHash;
 exports.toBinaryBaseBlockHeader = toBinaryBaseBlockHeader;
 const sdk_1 = require("@bsv/sdk");
+const utils_1 = require("@bsv/sdk/primitives/utils");
 const ServiceCollection_1 = require("./ServiceCollection");
 const createDefaultWalletServicesOptions_1 = require("./createDefaultWalletServicesOptions");
 const WhatsOnChain_1 = require("./providers/WhatsOnChain");
@@ -17,7 +18,28 @@ const ChaintracksChainTracker_1 = require("./chaintracker/ChaintracksChainTracke
 const WalletError_1 = require("../sdk/WalletError");
 const utilityHelpers_1 = require("../utility/utilityHelpers");
 const utilityHelpers_noBuffer_1 = require("../utility/utilityHelpers.noBuffer");
+const classifyOutputUtxo_1 = require("./classifyOutputUtxo");
+const validateMerklePathResult_1 = require("./validateMerklePathResult");
+const validateStatusForTxidsResult_1 = require("./validateStatusForTxidsResult");
+const validateRawTxResult_1 = require("./validateRawTxResult");
+const validateUtxoStatusResult_1 = require("./validateUtxoStatusResult");
+const validateScriptHashHistoryResult_1 = require("./validateScriptHashHistoryResult");
+const validatePostBeefResult_1 = require("./validatePostBeefResult");
+const fiatRateValidation_1 = require("./fiatRateValidation");
+const getCanonicalMerklePath_1 = require("./getCanonicalMerklePath");
+function copyFiatExchangeRates(rates) {
+    return {
+        timestamp: new Date(rates.timestamp.getTime()),
+        base: rates.base,
+        rates: { ...rates.rates },
+        rateTimestamps: rates.rateTimestamps == null
+            ? undefined
+            : Object.fromEntries(Object.entries(rates.rateTimestamps).map(([key, value]) => [key, new Date(value.getTime())]))
+    };
+}
 class Services {
+    identityChainTracker;
+    identityChainTrackerInit;
     static getStatusForTxidsBatchLimit = 20;
     static createDefaultOptions(chain) {
         return (0, createDefaultWalletServicesOptions_1.createDefaultWalletServicesOptions)(chain);
@@ -103,6 +125,17 @@ class Services {
             this.getStatusForTxidsServices
                 .add({ name: 'WhatsOnChain', service: this.whatsonchain.getStatusForTxids.bind(this.whatsonchain) });
         }
+        if (this.arcade != null) {
+            // Arcade's lifecycle store keeps status reconciliation available when
+            // the explorer is disabled or unavailable. Keep the existing explorer
+            // first when configured because a successful `unknown` is a valid,
+            // conservative answer and the shared collection does not merge partial
+            // results from multiple providers.
+            this.getStatusForTxidsServices.add({
+                name: 'Arcade',
+                service: this.arcade.getStatusForTxids.bind(this.arcade)
+            });
+        }
         this.getScriptHashHistoryServices = new ServiceCollection_1.ServiceCollection('getScriptHashHistory');
         if (hasWhatsOnChain) {
             // prettier-ignore
@@ -122,9 +155,11 @@ class Services {
             // prettier-ignore
             this.postBeefServices.add({ name: 'GorillaPoolArcBeef', service: this.arcGorillaPool.postBeef.bind(this.arcGorillaPool) });
         }
-        // prettier-ignore
-        this.postBeefServices
-            .add({ name: 'TaalArcBeef', service: this.arcTaal.postBeef.bind(this.arcTaal) });
+        if (this.options.arcUrl != null && this.options.arcUrl !== '') {
+            // prettier-ignore
+            this.postBeefServices
+                .add({ name: 'TaalArcBeef', service: this.arcTaal.postBeef.bind(this.arcTaal) });
+        }
         if (hasBitails && this.bitails != null) {
             this.postBeefServices.add({ name: 'Bitails', service: this.bitails.postBeef.bind(this.bitails) });
         }
@@ -162,49 +197,81 @@ class Services {
         };
     }
     async getChainTracker() {
-        if (this.options.chaintracks == null) {
-            throw new WERR_errors_1.WERR_INVALID_PARAMETER('options.chaintracks', "valid to enable 'getChainTracker' service.");
+        while (true) {
+            if (this.options.chainTracker != null)
+                return this.options.chainTracker;
+            if (this.options.chaintracks == null) {
+                throw new WERR_errors_1.WERR_INVALID_PARAMETER('options.chainTracker or options.chaintracks', "valid to enable 'getChainTracker' service.");
+            }
+            const desired = this.options.chaintracks;
+            if (this.identityChainTracker?.chaintracks === desired)
+                return this.identityChainTracker;
+            if (this.identityChainTrackerInit != null) {
+                await this.identityChainTrackerInit.catch(() => undefined);
+                continue;
+            }
+            const previous = this.identityChainTracker;
+            const created = new ChaintracksChainTracker_1.ChaintracksChainTracker(this.chain, desired, {
+                telemetry: this.options.telemetry
+            });
+            this.identityChainTracker = created;
+            const init = Promise.resolve().then(async () => {
+                if (previous != null)
+                    await previous.dispose();
+                return created;
+            });
+            this.identityChainTrackerInit = init;
+            try {
+                await init.catch(() => created);
+            }
+            finally {
+                if (this.identityChainTrackerInit === init)
+                    this.identityChainTrackerInit = undefined;
+            }
         }
-        return new ChaintracksChainTracker_1.ChaintracksChainTracker(this.chain, this.options.chaintracks, {
-            telemetry: this.options.telemetry
-        });
     }
     async getBsvExchangeRate() {
         this.options.bsvExchangeRate = await this.whatsonchain.updateBsvExchangeRate(this.options.bsvExchangeRate, this.options.bsvUpdateMsecs);
         return this.options.bsvExchangeRate.rate;
     }
     async getFiatExchangeRate(currency, base) {
-        base ||= 'USD';
-        if (currency === base)
+        const normalizedCurrency = (0, fiatRateValidation_1.normalizeFiatCurrency)(currency);
+        const normalizedBase = (0, fiatRateValidation_1.normalizeFiatCurrency)(base ?? 'USD', 'base');
+        if (normalizedCurrency === normalizedBase)
             return 1;
-        const required = base === 'USD' ? [currency] : [currency, base];
-        await this.updateFiatExchangeRates(required, this.options.fiatUpdateMsecs);
-        const rates = this.options.fiatExchangeRates;
-        const c = rates.rates?.[currency];
-        const b = rates.rates?.[base];
-        if (typeof c !== 'number') {
-            throw new WERR_errors_1.WERR_INVALID_PARAMETER('currency', `valid fiat currency '${currency}' with an exchange rate.`);
+        const required = normalizedBase === 'USD' ? [normalizedCurrency] : [normalizedCurrency, normalizedBase];
+        const rates = await this.updateFiatExchangeRates(required, this.options.fiatUpdateMsecs);
+        const c = rates.rates?.[normalizedCurrency];
+        const b = rates.rates?.[normalizedBase];
+        if (!(0, fiatRateValidation_1.isValidFiatRate)(c)) {
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('currency', `valid fiat currency '${normalizedCurrency}' with an exchange rate.`);
+        }
+        if (!(0, fiatRateValidation_1.isValidFiatRate)(b)) {
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('base', `valid fiat currency '${normalizedBase}' with an exchange rate.`);
         }
-        if (typeof b !== 'number') {
-            throw new WERR_errors_1.WERR_INVALID_PARAMETER('base', `valid fiat currency '${base}' with an exchange rate.`);
+        const result = c / b;
+        if (!(0, fiatRateValidation_1.isValidFiatRate)(result)) {
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('currency', 'a finite and bounded conversion result.');
         }
-        return c / b;
+        return result;
     }
     async getFiatExchangeRates(targetCurrencies) {
-        await this.updateFiatExchangeRates(targetCurrencies, this.options.fiatUpdateMsecs);
-        const stored = this.options.fiatExchangeRates;
+        const targets = (0, fiatRateValidation_1.normalizeFiatCurrencies)(targetCurrencies);
+        const stored = await this.updateFiatExchangeRates(targets, this.options.fiatUpdateMsecs);
         const rates = {};
-        for (const c of targetCurrencies) {
+        for (const c of targets) {
             const v = stored.rates?.[c];
-            if (typeof v === 'number') {
+            if ((0, fiatRateValidation_1.isValidFiatRate)(v)) {
                 rates[c] = v;
             }
         }
         return {
-            timestamp: stored.timestamp,
+            timestamp: new Date(stored.timestamp.getTime()),
             base: 'USD',
             rates,
-            rateTimestamps: stored.rateTimestamps
+            rateTimestamps: stored.rateTimestamps == null
+                ? undefined
+                : Object.fromEntries(Object.entries(stored.rateTimestamps).map(([key, value]) => [key, new Date(value.getTime())]))
         };
     }
     get getProofsCount() {
@@ -223,21 +290,48 @@ class Services {
         const services = this.getStatusForTxidsServices;
         if (useNext === true)
             services.next();
-        let r0 = {
+        const normalizedTxids = txids.map((txid, index) => (0, validateMerklePathResult_1.normalizeTxid)(txid, `txids[${index}]`));
+        let fallback = {
             name: '<noservices>',
             status: 'error',
             error: new WERR_errors_1.WERR_INTERNAL('No services available.'),
             results: []
         };
+        const resultsByTxid = new Map();
+        const unresolved = new Set(normalizedTxids);
+        const providerNames = [];
+        let successfulProvider = false;
+        const rank = (result) => {
+            if (result.status === 'mined')
+                return 4;
+            if (result.status === 'known')
+                return 3;
+            if (result.terminal === true)
+                return 2;
+            return 1;
+        };
         for (let tries = 0; tries < services.count; tries++) {
             const stc = services.serviceToCall;
             try {
-                const r = await this.getStatusForTxidsBatched(stc, txids);
+                const requestedTxids = [...unresolved];
+                if (requestedTxids.length === 0)
+                    break;
+                const r = await this.getStatusForTxidsBatched(stc, requestedTxids);
                 if (r.status === 'success') {
                     services.addServiceCallSuccess(stc);
-                    r0 = r;
-                    break;
+                    successfulProvider = true;
+                    providerNames.push(stc.providerName);
+                    for (const result of r.results) {
+                        const current = resultsByTxid.get(result.txid);
+                        if (current == null || rank(result) > rank(current))
+                            resultsByTxid.set(result.txid, result);
+                        if (result.status === 'mined' || result.status === 'known')
+                            unresolved.delete(result.txid);
+                    }
+                    services.next();
+                    continue;
                 }
+                fallback = r;
                 if (r.error != null)
                     services.addServiceCallError(stc, r.error);
                 else
@@ -245,18 +339,25 @@ class Services {
             }
             catch (error_) {
                 const e = WalletError_1.WalletError.fromUnknown(error_);
+                fallback = { name: stc.providerName, status: 'error', error: e, results: [] };
                 services.addServiceCallError(stc, e);
             }
             services.next();
         }
-        return r0;
+        if (!successfulProvider)
+            return fallback;
+        return {
+            name: [...new Set(providerNames)].join(','),
+            status: 'success',
+            results: normalizedTxids.map(txid => resultsByTxid.get(txid) ?? { txid, status: 'unknown', depth: undefined })
+        };
     }
     async getStatusForTxidsBatched(stc, txids) {
         const results = [];
         let error;
         for (let i = 0; i < txids.length; i += Services.getStatusForTxidsBatchLimit) {
             const batch = txids.slice(i, i + Services.getStatusForTxidsBatchLimit);
-            const r = await stc.service(batch);
+            const r = (0, validateStatusForTxidsResult_1.validateStatusForTxidsResult)(await stc.service(batch), batch, stc.providerName);
             if (r.status !== 'success') {
                 return r;
             }
@@ -276,18 +377,16 @@ class Services {
      * @returns script hash in 'hashLE' format, which is the default.
      */
     hashOutputScript(script) {
-        const hash = sdk_1.Utils.toHex((0, utilityHelpers_1.sha256Hash)(sdk_1.Utils.toArray(script, 'hex')));
+        const hash = (0, utils_1.toHex)((0, utilityHelpers_1.sha256Hash)((0, utils_1.toArray)(script, 'hex')));
         return hash;
     }
     async isUtxo(output) {
-        if (output.lockingScript == null) {
-            throw new WERR_errors_1.WERR_INVALID_PARAMETER('output.lockingScript', 'validated by storage provider validateOutputScript.');
-        }
-        const hash = this.hashOutputScript(sdk_1.Utils.toHex(output.lockingScript));
-        const or = await this.getUtxoStatus(hash, undefined, `${output.txid ?? ''}.${output.vout}`);
-        return or.isUtxo === true;
+        return (0, classifyOutputUtxo_1.requireConclusiveUtxo)(await (0, classifyOutputUtxo_1.classifyOutputUtxo)(this, output));
     }
     async getUtxoStatus(output, outputFormat, outpoint, useNext, logger) {
+        validateScriptHash(output, outputFormat);
+        const normalizedOutput = output.toLowerCase();
+        const normalizedOutpoint = (0, validateUtxoStatusResult_1.normalizeWalletOutpoint)(outpoint);
         const services = this.getUtxoStatusServices;
         if (useNext === true)
             services.next();
@@ -299,7 +398,8 @@ class Services {
         };
         logger?.group('services getUtxoStatus');
         for (let retry = 0; retry < 2; retry++) {
-            r0 = (await this.tryUtxoStatusProviders(services, output, outputFormat, outpoint, logger)) ?? r0;
+            r0 =
+                (await this.tryUtxoStatusProviders(services, normalizedOutput, outputFormat, normalizedOutpoint, logger)) ?? r0;
             if (r0.status === 'success')
                 break;
             await (0, utilityHelpers_1.wait)(2000);
@@ -311,7 +411,7 @@ class Services {
         for (let tries = 0; tries < services.count; tries++) {
             const stc = services.serviceToCall;
             try {
-                const r = await stc.service(output, outputFormat, outpoint);
+                const r = (0, validateUtxoStatusResult_1.validateUtxoStatusResult)(await stc.service(output, outputFormat, outpoint), outpoint, stc.providerName);
                 logger?.log(`${stc.providerName} status ${r.status}`);
                 if (r.status === 'success') {
                     services.addServiceCallSuccess(stc);
@@ -330,6 +430,7 @@ class Services {
         return undefined;
     }
     async getScriptHashHistory(hash, useNext, logger) {
+        const normalizedHash = (0, validateMerklePathResult_1.normalizeTxid)(hash, 'hash');
         const services = this.getScriptHashHistoryServices;
         if (useNext === true)
             services.next();
@@ -343,10 +444,11 @@ class Services {
         for (let tries = 0; tries < services.count; tries++) {
             const stc = services.serviceToCall;
             try {
-                const r = await stc.service(hash);
+                const r = (0, validateScriptHashHistoryResult_1.validateScriptHashHistoryResult)(await stc.service(normalizedHash), stc.providerName);
                 logger?.log(`${stc.providerName} status ${r.status}`);
                 if (r.status === 'success') {
                     r0 = r;
+                    services.addServiceCallSuccess(stc);
                     break;
                 }
                 if (r.error != null)
@@ -385,10 +487,15 @@ class Services {
      * @returns
      */
     async postBeef(beef, txids, logger) {
+        const request = (0, validatePostBeefResult_1.snapshotPostBeefRequest)(beef, txids);
+        if (this.postBeefMode !== 'UntilSuccess' && this.postBeefMode !== 'PromiseAll') {
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('postBeefMode', "'UntilSuccess' or 'PromiseAll'");
+        }
         let rs = [];
         const services = this.postBeefServices;
         const stcs = services.allServicesToCall;
-        const softTimeoutMs = this.getPostBeefSoftTimeoutMs(beef);
+        const softTimeoutMs = this.getPostBeefSoftTimeoutMs(request.beefBytes.length);
+        const softTimedOut = new Set();
         logger?.group('services postBeef');
         switch (this.postBeefMode) {
             case 'UntilSuccess':
@@ -398,8 +505,7 @@ class Services {
                     rs.push(r);
                     if (r.status === 'success')
                         break;
-                    const softTimedOut = r.notes?.some(n => n.what === 'postBeefServiceTimeout') === true;
-                    if (!softTimedOut && r.txidResults?.every(txr => txr.serviceError)) {
+                    if (!softTimedOut.has(stc) && r.txidResults.every(txr => txr.serviceError)) {
                         // move this service to the end of the list
                         this.postBeefServices.moveServiceToLast(stc);
                     }
@@ -415,7 +521,10 @@ class Services {
         logger?.groupEnd();
         return rs;
         async function callService(stc, timeoutMs) {
-            const callPromise = stc.service(beef, txids);
+            const callPromise = Promise.resolve()
+                .then(async () => await stc.service(sdk_1.Beef.fromBinaryStrict(request.beefBytes), [...request.txids]))
+                .then(result => (0, validatePostBeefResult_1.validatePostBeefResult)(result, request.txids, stc.providerName))
+                .catch(() => (0, validatePostBeefResult_1.makePostBeefServiceError)(stc.providerName, request.txids, 'postBeefServiceError'));
             let r;
             if (timeoutMs == null || timeoutMs <= 0) {
                 r = await callPromise;
@@ -423,7 +532,10 @@ class Services {
             else {
                 let timeoutHandle;
                 const timeoutPromise = new Promise(resolve => {
-                    timeoutHandle = setTimeout(() => resolve(makeServiceTimeoutResult(stc.providerName, txids, timeoutMs)), timeoutMs);
+                    timeoutHandle = setTimeout(() => {
+                        softTimedOut.add(stc);
+                        resolve((0, validatePostBeefResult_1.makePostBeefServiceError)(stc.providerName, request.txids, 'postBeefServiceTimeout', timeoutMs));
+                    }, timeoutMs);
                 });
                 r = await Promise.race([callPromise, timeoutPromise]);
                 if (timeoutHandle != null)
@@ -442,39 +554,34 @@ class Services {
             }
             return r;
         }
-        function makeServiceTimeoutResult(providerName, txids, timeoutMs) {
-            return {
-                name: providerName,
-                status: 'error',
-                txidResults: txids.map(txid => ({
-                    txid,
-                    status: 'error',
-                    serviceError: true,
-                    data: { detail: `timeout after ${timeoutMs}ms` }
-                })),
-                notes: [{ when: new Date().toISOString(), what: 'postBeefServiceTimeout', providerName, timeoutMs }]
-            };
-        }
     }
-    getPostBeefSoftTimeoutMs(beef) {
-        const baseMs = Math.max(0, this.postBeefUntilSuccessSoftTimeoutMs);
-        const perKbMs = Math.max(0, this.postBeefUntilSuccessSoftTimeoutPerKbMs);
-        const maxMs = Math.max(baseMs, this.postBeefUntilSuccessSoftTimeoutMaxMs);
+    getPostBeefSoftTimeoutMs(beefBytes) {
+        const maximum = 60 * 60 * 1000;
+        const valid = (value, name) => {
+            if (!Number.isSafeInteger(value) || value < 0 || value > maximum) {
+                throw new WERR_errors_1.WERR_INVALID_PARAMETER(name, `an integer from 0 through ${maximum}`);
+            }
+            return value;
+        };
+        const baseMs = valid(this.postBeefUntilSuccessSoftTimeoutMs, 'postBeefUntilSuccessSoftTimeoutMs');
+        const perKbMs = valid(this.postBeefUntilSuccessSoftTimeoutPerKbMs, 'postBeefUntilSuccessSoftTimeoutPerKbMs');
+        const maxMs = Math.max(baseMs, valid(this.postBeefUntilSuccessSoftTimeoutMaxMs, 'postBeefUntilSuccessSoftTimeoutMaxMs'));
         if (perKbMs <= 0)
             return Math.min(baseMs, maxMs);
-        const beefBytes = beef.toBinary().length;
         const extraMs = Math.ceil((beefBytes / 1024) * perKbMs);
         return Math.min(maxMs, baseMs + extraMs);
     }
     async getRawTx(txid, useNext) {
+        const normalizedTxid = (0, validateMerklePathResult_1.normalizeTxid)(txid);
         const services = this.getRawTxServices;
         if (useNext === true)
             services.next();
-        const r0 = { txid };
+        const r0 = { txid: normalizedTxid };
         for (let tries = 0; tries < services.count; tries++) {
             const stc = services.serviceToCall;
             try {
-                const done = this.applyRawTxResult(r0, txid, await stc.service(txid, this.chain), services, stc);
+                const result = (0, validateRawTxResult_1.validateRawTxResult)(await stc.service(normalizedTxid, this.chain), normalizedTxid, stc.providerName);
+                const done = this.applyRawTxResult(r0, normalizedTxid, result, services, stc);
                 if (done)
                     break;
             }
@@ -488,9 +595,9 @@ class Services {
     applyRawTxResult(r0, txid, r, services, stc) {
         if (r.rawTx != null) {
             const hash = (0, utilityHelpers_noBuffer_1.asString)((0, utilityHelpers_1.doubleSha256BE)(r.rawTx));
-            if (hash === (0, utilityHelpers_noBuffer_1.asString)(txid)) {
+            if (hash === txid) {
                 r0.rawTx = r.rawTx;
-                r0.name = r.name;
+                r0.name = stc.providerName;
                 r0.error = undefined;
                 services.addServiceCallSuccess(stc);
                 return true;
@@ -559,71 +666,179 @@ class Services {
             const chaintracks = this.options.chaintracks;
             return await chaintracks.currentHeight();
         };
-        return await this.invokeChaintracksWithRetry(method, 'current_height');
+        try {
+            return await this.invokeChaintracksWithRetry(method, 'current_height');
+        }
+        catch (error_) {
+            // Chaintracks is otherwise this method's single point of failure, and a
+            // wallet UI that cannot read the present height is broadly unusable
+            // (observed live 2026-08-11: a CORS-blocked chaintracks fetch in a
+            // webview-hosted wallet). Mirror `hashToHeader`'s existing belt: fall
+            // back to WhatsOnChain, and rethrow the ORIGINAL chaintracks error when
+            // the fallback cannot answer either.
+            try {
+                return (await this.whatsonchain.getChainInfo()).blocks;
+            }
+            catch {
+                throw error_;
+            }
+        }
     }
     async hashToHeader(hash) {
+        const normalizedHash = (0, validateMerklePathResult_1.normalizeTxid)(hash, 'hash');
         const method = async () => {
             const chaintracks = this.options.chaintracks;
-            const header = await chaintracks.findHeaderForBlockHash(hash);
+            const header = await chaintracks.findHeaderForBlockHash(normalizedHash);
             return header;
         };
         let header = await this.invokeChaintracksWithRetry(method, 'find_header_for_hash');
-        header ??= await this.whatsonchain.getBlockHeaderByHash(hash);
+        header ??= await this.whatsonchain.getBlockHeaderByHash(normalizedHash);
         if (header == null)
-            throw new WERR_errors_1.WERR_INVALID_PARAMETER('hash', `valid blockhash '${hash}' on mined chain ${this.chain}`);
-        return header;
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('hash', `valid blockhash '${normalizedHash}' on mined chain ${this.chain}`);
+        const validated = (0, validateMerklePathResult_1.copyValidatedBlockHeader)(header, true);
+        if (validated.hash !== normalizedHash) {
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('hash', `the hash of the returned mined header on chain ${this.chain}`);
+        }
+        return validated;
+    }
+    async authenticateProviderMerklePath(txid, result) {
+        // First copy and bind the provider's mutable proof/header response. Then
+        // resolve that header hash through the wallet's own chain service and bind
+        // the proof a second time to that canonical, proof-of-work-valid header.
+        // Bind the provider path to the declared height/root before using the
+        // declared hash as a lookup key. `hashToHeader` then authenticates that
+        // hash and returns the canonical owned header.
+        const providerResult = (0, validateMerklePathResult_1.validateMerklePathResult)(txid, result, false, false);
+        const canonicalHeader = await this.hashToHeader(providerResult.header.hash);
+        // `hashToHeader` already returns an owned, format-checked,
+        // proof-of-work-valid header. This second pass only binds the copied path
+        // to that canonical header's height and root.
+        return (0, validateMerklePathResult_1.validateMerklePathResult)(txid, { merklePath: providerResult.merklePath, header: canonicalHeader }, false, false);
+    }
+    async tryMerklePathProvider(txid, service, aggregate, logger) {
+        let result;
+        try {
+            result = (0, validateMerklePathResult_1.snapshotMerklePathResult)(await service.service(txid, this), true, service.providerName);
+        }
+        catch (error_) {
+            const error = WalletError_1.WalletError.fromUnknown(error_);
+            this.getMerklePathServices.addServiceCallError(service, error);
+            aggregate.error ??= error;
+            return false;
+        }
+        aggregate.notes?.push(...(result.notes ?? []));
+        aggregate.name ??= result.name ?? service.providerName;
+        if (result.merklePath != null) {
+            try {
+                await (0, getCanonicalMerklePath_1.validateCanonicalMerklePathResult)(txid, result, await this.getChainTracker());
+                if (result.header != null) {
+                    const authenticated = await this.authenticateProviderMerklePath(txid, result);
+                    result.merklePath = authenticated.merklePath;
+                    result.header = authenticated.header;
+                }
+                logger?.log(`${service.providerName} has authenticated canonical merklePath`);
+                Object.assign(aggregate, {
+                    merklePath: result.merklePath,
+                    header: result.header,
+                    name: result.name ?? service.providerName,
+                    error: undefined
+                });
+                this.getMerklePathServices.addServiceCallSuccess(service);
+                return true;
+            }
+            catch (error_) {
+                logger?.log(`${service.providerName} rejected non-canonical merklePath`);
+                result.error = WalletError_1.WalletError.fromUnknown(error_);
+            }
+        }
+        else {
+            logger?.log(`${service.providerName} no merklePath`);
+        }
+        if (result.error != null)
+            this.getMerklePathServices.addServiceCallError(service, result.error);
+        else
+            this.getMerklePathServices.addServiceCallFailure(service);
+        aggregate.error ??= result.error;
+        return false;
     }
     async getMerklePath(txid, useNext, logger) {
+        const normalizedTxid = (0, validateMerklePathResult_1.normalizeTxid)(txid);
         const services = this.getMerklePathServices;
         if (useNext === true)
             services.next();
-        const r0 = { notes: [] };
+        const result = { notes: [] };
         logger?.group('services getMerklePath');
         for (let tries = 0; tries < services.count; tries++) {
-            const stc = services.serviceToCall;
+            if (await this.tryMerklePathProvider(normalizedTxid, services.serviceToCall, result, logger))
+                break;
+            services.next();
+        }
+        logger?.groupEnd?.();
+        return result;
+    }
+    async getValidatedMerklePath(txid, validate) {
+        const normalizedTxid = (0, validateMerklePathResult_1.normalizeTxid)(txid);
+        const services = this.getMerklePathServices;
+        const calls = services.allServicesToCall;
+        const start = services.index;
+        let error;
+        for (let i = 0; i < calls.length; i++) {
+            const call = calls[(start + i) % calls.length];
             try {
-                const r = await stc.service(txid, this);
-                if (r.notes != null) {
-                    r0.notes = r0.notes ?? [];
-                    r0.notes.push(...r.notes);
-                }
-                r0.name ??= r.name;
-                if (r.merklePath == null) {
-                    logger?.log(`${stc.providerName} no merklePath`);
-                }
-                else {
-                    logger?.log(`${stc.providerName} has merklePath`);
-                    // If we have a proof, call it done.
-                    r0.merklePath = r.merklePath;
-                    r0.header = r.header;
-                    r0.name = r.name;
-                    r0.error = undefined;
-                    services.addServiceCallSuccess(stc);
-                    break;
+                const result = (0, validateMerklePathResult_1.snapshotMerklePathResult)(await call.service(normalizedTxid, this), true, call.providerName);
+                if (result.merklePath == null) {
+                    throw result.error ?? new WERR_errors_1.WERR_INVALID_OPERATION('Proof provider returned no Merkle path');
                 }
-                if (r.error != null)
-                    services.addServiceCallError(stc, r.error);
-                else
-                    services.addServiceCallFailure(stc);
-                if (r.error != null && r0.error == null) {
-                    // If we have an error and didn't before...
-                    r0.error = r.error;
+                await (0, getCanonicalMerklePath_1.validateCanonicalMerklePathResult)(normalizedTxid, result, await this.getChainTracker());
+                // Some legacy/custom proof providers return a path without a header;
+                // this method's explicit validator contract exists so its caller can
+                // resolve and authenticate that header independently. When a provider
+                // does supply a header, apply the standard built-in boundary first.
+                let candidate = result;
+                if (result.header != null) {
+                    const authenticated = await this.authenticateProviderMerklePath(normalizedTxid, result);
+                    candidate = {
+                        name: call.providerName,
+                        notes: result.notes,
+                        merklePath: authenticated.merklePath,
+                        header: authenticated.header
+                    };
                 }
+                await validate(candidate);
+                services.addServiceCallSuccess(call);
+                return candidate;
             }
-            catch (error_) {
-                const e = WalletError_1.WalletError.fromUnknown(error_);
-                services.addServiceCallError(stc, e);
+            catch (cause) {
+                error = WalletError_1.WalletError.fromUnknown(cause);
+                services.addServiceCallError(call, error);
             }
-            services.next();
         }
-        return r0;
+        return { error, notes: [] };
     }
     async updateFiatExchangeRates(targetCurrencies, updateMsecs) {
         updateMsecs ??= 1000 * 60 * 60 * 24;
+        if (!Number.isSafeInteger(updateMsecs) || updateMsecs < 0 || updateMsecs > 10 * 365 * 24 * 60 * 60 * 1000) {
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('updateMsecs', 'a bounded non-negative safe integer.');
+        }
+        const targets = (0, fiatRateValidation_1.normalizeFiatCurrencies)(targetCurrencies);
         const freshnessDate = new Date(Date.now() - updateMsecs);
-        const stored = this.options.fiatExchangeRates;
+        let stored;
+        try {
+            const normalized = (0, fiatRateValidation_1.normalizeFiatExchangeRates)(this.options.fiatExchangeRates, []);
+            stored = {
+                ...normalized,
+                rateTimestamps: (0, fiatRateValidation_1.normalizeFiatRateTimestamps)(this.options.fiatExchangeRates.rateTimestamps)
+            };
+        }
+        catch {
+            stored = {
+                timestamp: new Date(Date.UTC(2000, 0, 1)),
+                base: 'USD',
+                rates: { USD: 1 }
+            };
+        }
         const storedRates = stored.rates ?? {};
-        const toFetch = this.collectStaleCurrencies(targetCurrencies, storedRates, stored, freshnessDate);
+        const toFetch = this.collectStaleCurrencies(targets, storedRates, stored, freshnessDate);
         if (toFetch.length === 0) {
             this.options.fiatExchangeRates = {
                 timestamp: stored.timestamp,
@@ -631,16 +846,16 @@ class Services {
                 rates: storedRates,
                 rateTimestamps: stored.rateTimestamps
             };
-            return this.options.fiatExchangeRates;
+            return copyFiatExchangeRates(this.options.fiatExchangeRates);
         }
         const fetched = await this.fetchFiatRates(toFetch);
         if (fetched == null) {
             if (Object.keys(storedRates).length > 0)
-                return stored;
+                return copyFiatExchangeRates(stored);
             throw new WERR_errors_1.WERR_INTERNAL();
         }
         this.options.fiatExchangeRates = this.mergeFiatRates(stored, storedRates, fetched);
-        return this.options.fiatExchangeRates;
+        return copyFiatExchangeRates(this.options.fiatExchangeRates);
     }
     collectStaleCurrencies(targetCurrencies, storedRates, stored, freshnessDate) {
         const toFetch = [];
@@ -652,7 +867,8 @@ class Services {
             }
             const v = storedRates[c];
             const ts = stored.rateTimestamps?.[c] ?? stored.timestamp;
-            const fresh = typeof v === 'number' && ts instanceof Date && ts > freshnessDate;
+            const tsValue = ts instanceof Date ? ts.getTime() : Number.NaN;
+            const fresh = (0, fiatRateValidation_1.isValidFiatRate)(v) && Number.isFinite(tsValue) && tsValue <= Date.now() + 5 * 60 * 1000 && ts > freshnessDate;
             if (!fresh)
                 toFetch.push(c);
         }
@@ -663,12 +879,10 @@ class Services {
         for (let tries = 0; tries < services.count; tries++) {
             const stc = services.serviceToCall;
             try {
-                const r = await stc.service(toFetch, this.options);
-                if (toFetch.every(c => c === 'USD' || typeof r.rates?.[c] === 'number')) {
-                    services.addServiceCallSuccess(stc);
-                    return r;
-                }
-                services.addServiceCallFailure(stc);
+                const raw = await stc.service(toFetch, this.options);
+                const rates = (0, fiatRateValidation_1.normalizeFiatExchangeRates)(raw, toFetch);
+                services.addServiceCallSuccess(stc);
+                return rates;
             }
             catch (error_) {
                 services.addServiceCallError(stc, WalletError_1.WalletError.fromUnknown(error_));
@@ -678,11 +892,12 @@ class Services {
         return undefined;
     }
     mergeFiatRates(stored, storedRates, fetched) {
+        fetched = (0, fiatRateValidation_1.normalizeFiatExchangeRates)(fetched, []);
         const nextRates = { ...storedRates };
         const nextTimestamps = { ...stored.rateTimestamps };
         for (const c of fetched.rates != null ? Object.keys(fetched.rates) : []) {
             const v = fetched.rates?.[c];
-            if (typeof v === 'number') {
+            if ((0, fiatRateValidation_1.isValidFiatRate)(v)) {
                 nextRates[c] = v;
                 nextTimestamps[c] = fetched.timestamp;
             }
@@ -728,6 +943,13 @@ class Services {
 }
 exports.Services = Services;
 function validateScriptHash(output, outputFormat) {
+    if (typeof output !== 'string' ||
+        output.length === 0 ||
+        output.length % 2 !== 0 ||
+        output.length > validateRawTxResult_1.MAX_RAW_TRANSACTION_BYTES * 2 ||
+        !/^[0-9a-fA-F]+$/.test(output)) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('output', `nonempty hexadecimal bytes up to ${validateRawTxResult_1.MAX_RAW_TRANSACTION_BYTES} bytes`);
+    }
     let b = (0, utilityHelpers_noBuffer_1.asArray)(output);
     if (outputFormat == null) {
         if (b.length === 32)
@@ -737,8 +959,12 @@ function validateScriptHash(output, outputFormat) {
     }
     switch (outputFormat) {
         case 'hashBE':
+            if (b.length !== 32)
+                throw new WERR_errors_1.WERR_INVALID_PARAMETER('output', 'exactly 32 bytes for hashBE');
             break;
         case 'hashLE':
+            if (b.length !== 32)
+                throw new WERR_errors_1.WERR_INVALID_PARAMETER('output', 'exactly 32 bytes for hashLE');
             b = b.reverse();
             break;
         case 'script':
@@ -758,7 +984,7 @@ function validateScriptHash(output, outputFormat) {
  * @publicbody
  */
 function toBinaryBaseBlockHeader(header) {
-    const writer = new sdk_1.Utils.Writer();
+    const writer = new utils_1.Writer();
     writer.writeUInt32LE(header.version);
     writer.writeReverse((0, utilityHelpers_noBuffer_1.asArray)(header.previousHash));
     writer.writeReverse((0, utilityHelpers_noBuffer_1.asArray)(header.merkleRoot));