@bopen-io/wallet-toolbox 2.1.21-parity-fix.2 → 2.6.2-brc153.2

package/out/src/Wallet.js

@@ -17,34 +17,109 @@ const types_1 = require("./sdk/types");
 const WERR_errors_1 = require("./sdk/WERR_errors");
 const WalletError_1 = require("./sdk/WalletError");
 const utilityHelpers_noBuffer_1 = require("./utility/utilityHelpers.noBuffer");
+const resultBeef_1 = require("./signer/methods/resultBeef");
+const ActionBatchWorkspace_1 = require("./signer/actionBatch/ActionBatchWorkspace");
+function prepareKnownTxidsForCreateAction(wallet, args) {
+    if (!wallet.autoKnownTxids || args.options?.knownTxids != null)
+        return;
+    if (!wallet.telemetry.enabled) {
+        args.options.knownTxids = wallet.getKnownTxids(args.options?.knownTxids);
+        return;
+    }
+    args.options.knownTxids = wallet.telemetry.withSpan('wallet.create_action.prepare_known_txids', {
+        component: 'wallet-toolbox',
+        carrier: args,
+        attributes: { 'beef.tx_count': wallet.beef.txs.length }
+    }, span => {
+        const knownTxids = wallet.getKnownTxids(args.options?.knownTxids);
+        span.end({ attributes: { 'beef.known_txid_count': knownTxids.length } });
+        return knownTxids;
+    });
+}
+/**
+ * Build a {@link DiscoverCertificatesResult} from contact records so {@link Wallet.discoverByIdentityKey}
+ * and {@link Wallet.discoverByAttributes} can short-circuit on a local contacts hit. The synthetic
+ * certificate has `trust: Infinity` by default so downstream `transformVerifiableCertificatesWithTrust`
+ * style filtering treats contacts as authoritative.
+ */
+function synthesizeContactResult(contacts) {
+    const certificates = contacts.map(c => ({
+        type: c.type ?? 'contact',
+        subject: c.identityKey,
+        serialNumber: '',
+        certifier: c.identityKey,
+        revocationOutpoint: '',
+        signature: '',
+        fields: {},
+        keyring: {},
+        decryptedFields: c.decryptedFields ?? {},
+        publiclyRevealedKeyring: {},
+        certifierInfo: {
+            name: c.certifierInfo?.name ?? 'Contact',
+            iconUrl: c.certifierInfo?.iconUrl ?? '',
+            description: c.certifierInfo?.description ?? 'Locally saved contact',
+            trust: c.certifierInfo?.trust ?? Number.POSITIVE_INFINITY
+        }
+    }));
+    return {
+        totalCertificates: certificates.length,
+        certificates: certificates
+    };
+}
 function isWalletSigner(args) {
-    return args['isWalletSigner'];
+    return 'isWalletSigner' in args && args.isWalletSigner;
 }
 class Wallet {
+    chain;
+    keyDeriver;
+    storage;
+    settingsManager;
+    lookupResolver;
+    services;
+    monitor;
+    contactSource;
+    identityKey;
+    /**
+     * The wallet creates a `BeefParty` when it is created.
+     * All the Beefs that pass through the wallet are merged into this beef.
+     * Thus what it contains at any time is the union of all transactions and proof data processed.
+     * The class `BeefParty` derives from `Beef`, adding the ability to track the source of merged data.
+     *
+     * This allows it to generate beefs to send to a particular “party” (storage or the user)
+     * that includes “txid only proofs” for transactions they already know about.
+     * Over time, this allows an active wallet to drastically reduce the amount of data transmitted.
+     */
+    beef;
+    /**
+     * If true, signableTransactions will include sourceTransaction for each input,
+     * including those that do not require signature and those that were also contained
+     * in the inputBEEF.
+     */
+    includeAllSourceTransactions = true;
+    /**
+     * If true, txids that are known to the wallet's party beef do not need to be returned from storage.
+     */
+    autoKnownTxids = false;
+    /**
+     * If true, beefs returned to the user may contain txidOnly transactions.
+     */
+    returnTxidOnly = false;
+    trustSelf;
+    userParty;
+    proto;
+    privilegedKeyManager;
+    makeLogger;
+    pendingSignActions;
+    actionBatch;
+    scriptVerifier;
+    telemetry;
+    /**
+     * For repeatability testing, set to an array of random numbers from [0..1).
+     */
+    randomVals = undefined;
     constructor(argsOrSigner, services, monitor, privilegedKeyManager, makeLogger) {
-        /**
-         * If true, signableTransactions will include sourceTransaction for each input,
-         * including those that do not require signature and those that were also contained
-         * in the inputBEEF.
-         */
-        this.includeAllSourceTransactions = true;
-        /**
-         * If true, txids that are known to the wallet's party beef do not need to be returned from storage.
-         */
-        this.autoKnownTxids = false;
-        /**
-         * If true, beefs returned to the user may contain txidOnly transactions.
-         */
-        this.returnTxidOnly = false;
-        /**
-         * For repeatability testing, set to an array of random numbers from [0..1).
-         */
-        this.randomVals = undefined;
-        /** 2-minute cache of queryOverlay() results keyed by normalized query */
-        this._overlayCache = new Map();
-        const args = !isWalletSigner(argsOrSigner)
-            ? argsOrSigner
-            : {
+        const args = isWalletSigner(argsOrSigner)
+            ? {
                 chain: argsOrSigner.chain,
                 keyDeriver: argsOrSigner.keyDeriver,
                 storage: argsOrSigner.storage,
@@ -52,15 +127,19 @@ class Wallet {
                 monitor,
                 privilegedKeyManager,
                 makeLogger
-            };
-        if (args.storage._authId.identityKey != args.keyDeriver.identityKey)
+            }
+            : argsOrSigner;
+        if (args.storage._authId.identityKey != args.keyDeriver.identityKey) {
             throw new WERR_errors_1.WERR_INVALID_PARAMETER('storage', `authenticated as the same identityKey (${args.storage._authId.identityKey}) as the keyDeriver (${args.keyDeriver.identityKey}).`);
+        }
+        this.telemetry = new sdk_1.Telemetry(args.telemetry);
         this.settingsManager = args.settingsManager || new WalletSettingsManager_1.WalletSettingsManager(this);
         this.chain = args.chain;
         this.lookupResolver =
             args.lookupResolver ||
                 new sdk_1.LookupResolver({
-                    networkPreset: (0, utilityHelpers_1.toLookupNetworkPreset)(this.chain)
+                    networkPreset: (0, utilityHelpers_1.toLookupNetworkPreset)(this.chain),
+                    telemetry: args.telemetry
                 });
         this.keyDeriver = args.keyDeriver;
         this.storage = args.storage;
@@ -69,19 +148,23 @@ class Wallet {
         this.monitor = args.monitor;
         this.privilegedKeyManager = args.privilegedKeyManager;
         this.makeLogger = args.makeLogger;
+        this.contactSource = args.contactSource;
         this.identityKey = this.keyDeriver.identityKey;
         this.pendingSignActions = {};
+        this.actionBatch = new ActionBatchWorkspace_1.ActionBatchController(this, args.actionBatchMode ?? 'auto');
+        this.scriptVerifier = args.scriptVerifier;
         this.userParty = `user ${this.getClientChangeKeyPair().publicKey}`;
         this.beef = new sdk_1.BeefParty([this.userParty]);
         this.trustSelf = 'known';
-        if (this.services) {
+        if (this.services != null) {
             this.storage.setServices(this.services);
         }
     }
     async destroy() {
+        await this.actionBatch.abort();
         await this.storage.destroy();
-        if (this.privilegedKeyManager)
-            await this.privilegedKeyManager.destroyKey();
+        if (this.privilegedKeyManager != null)
+            this.privilegedKeyManager.destroyKey();
     }
     getClientChangeKeyPair() {
         const kp = {
@@ -93,90 +176,91 @@ class Wallet {
     async getIdentityKey() {
         return (await this.getPublicKey({ identityKey: true })).publicKey;
     }
-    getPublicKey(args, originator) {
+    async getPublicKey(args, _originator) {
         if (args.privileged) {
-            if (!this.privilegedKeyManager) {
+            if (this.privilegedKeyManager == null) {
                 throw new Error('Privileged operations require the Wallet to be configured with a privileged key manager.');
             }
-            return this.privilegedKeyManager.getPublicKey(args);
+            return await this.privilegedKeyManager.getPublicKey(args);
         }
-        return this.proto.getPublicKey(args);
+        return await this.proto.getPublicKey(args);
     }
-    revealCounterpartyKeyLinkage(args, originator) {
+    async revealCounterpartyKeyLinkage(args, _originator) {
         if (args.privileged) {
-            if (!this.privilegedKeyManager) {
+            if (this.privilegedKeyManager == null) {
                 throw new Error('Privileged operations require the Wallet to be configured with a privileged key manager.');
             }
-            return this.privilegedKeyManager.revealCounterpartyKeyLinkage(args);
+            return await this.privilegedKeyManager.revealCounterpartyKeyLinkage(args);
         }
-        return this.proto.revealCounterpartyKeyLinkage(args);
+        return await this.proto.revealCounterpartyKeyLinkage(args);
     }
-    revealSpecificKeyLinkage(args, originator) {
+    async revealSpecificKeyLinkage(args, _originator) {
         if (args.privileged) {
-            if (!this.privilegedKeyManager) {
+            if (this.privilegedKeyManager == null) {
                 throw new Error('Privileged operations require the Wallet to be configured with a privileged key manager.');
             }
-            return this.privilegedKeyManager.revealSpecificKeyLinkage(args);
+            return await this.privilegedKeyManager.revealSpecificKeyLinkage(args);
         }
-        return this.proto.revealSpecificKeyLinkage(args);
+        return await this.proto.revealSpecificKeyLinkage(args);
     }
-    encrypt(args, originator) {
+    async encrypt(args, _originator) {
         if (args.privileged) {
-            if (!this.privilegedKeyManager) {
+            if (this.privilegedKeyManager == null) {
                 throw new Error('Privileged operations require the Wallet to be configured with a privileged key manager.');
             }
-            return this.privilegedKeyManager.encrypt(args);
+            return await this.privilegedKeyManager.encrypt(args);
         }
-        return this.proto.encrypt(args);
+        return await this.proto.encrypt(args);
     }
-    decrypt(args, originator) {
+    async decrypt(args, _originator) {
         if (args.privileged) {
-            if (!this.privilegedKeyManager) {
+            if (this.privilegedKeyManager == null) {
                 throw new Error('Privileged operations require the Wallet to be configured with a privileged key manager.');
             }
-            return this.privilegedKeyManager.decrypt(args);
+            return await this.privilegedKeyManager.decrypt(args);
         }
-        return this.proto.decrypt(args);
+        return await this.proto.decrypt(args);
     }
-    createHmac(args, originator) {
+    async createHmac(args, _originator) {
         if (args.privileged) {
-            if (!this.privilegedKeyManager) {
+            if (this.privilegedKeyManager == null) {
                 throw new Error('Privileged operations require the Wallet to be configured with a privileged key manager.');
             }
-            return this.privilegedKeyManager.createHmac(args);
+            return await this.privilegedKeyManager.createHmac(args);
         }
-        return this.proto.createHmac(args);
+        return await this.proto.createHmac(args);
     }
-    verifyHmac(args, originator) {
+    async verifyHmac(args, _originator) {
         if (args.privileged) {
-            if (!this.privilegedKeyManager) {
+            if (this.privilegedKeyManager == null) {
                 throw new Error('Privileged operations require the Wallet to be configured with a privileged key manager.');
             }
-            return this.privilegedKeyManager.verifyHmac(args);
+            return await this.privilegedKeyManager.verifyHmac(args);
         }
-        return this.proto.verifyHmac(args);
+        return await this.proto.verifyHmac(args);
     }
-    createSignature(args, originator) {
+    async createSignature(args, _originator) {
         if (args.privileged) {
-            if (!this.privilegedKeyManager) {
+            if (this.privilegedKeyManager == null) {
                 throw new Error('Privileged operations require the Wallet to be configured with a privileged key manager.');
             }
-            return this.privilegedKeyManager.createSignature(args);
+            return await this.privilegedKeyManager.createSignature(args);
         }
-        return this.proto.createSignature(args);
+        return await this.proto.createSignature(args);
     }
-    verifySignature(args, originator) {
+    async verifySignature(args, _originator) {
         if (args.privileged) {
-            if (!this.privilegedKeyManager) {
+            if (this.privilegedKeyManager == null) {
                 throw new Error('Privileged operations require the Wallet to be configured with a privileged key manager.');
             }
-            return this.privilegedKeyManager.verifySignature(args);
+            return await this.privilegedKeyManager.verifySignature(args);
         }
-        return this.proto.verifySignature(args);
+        return await this.proto.verifySignature(args);
     }
     getServices() {
-        if (!this.services)
+        if (this.services == null) {
             throw new WERR_errors_1.WERR_INVALID_PARAMETER('services', 'valid in constructor arguments to be retreived here.');
+        }
         return this.services;
     }
     /**
@@ -185,7 +269,7 @@ class Wallet {
      * @param newKnownTxids Optional. Additional new txids known to be valid by the caller to be merged.
      */
     getKnownTxids(newKnownTxids) {
-        if (newKnownTxids) {
+        if (newKnownTxids != null) {
             for (const txid of newKnownTxids)
                 this.beef.mergeTxidOnly(txid);
         }
@@ -201,23 +285,48 @@ class Wallet {
         };
     }
     validateAuthAndArgs(args, validate, logger) {
-        const vargs = validate(args, logger);
-        const auth = { identityKey: this.identityKey };
-        return { vargs, auth };
+        if (!this.telemetry.enabled || typeof args !== 'object' || args == null) {
+            const vargs = validate(args, logger);
+            const auth = { identityKey: this.identityKey };
+            return { vargs, auth };
+        }
+        const span = this.telemetry.startSpan('wallet.validate_args', {
+            component: 'wallet-toolbox',
+            carrier: args
+        });
+        try {
+            const vargs = validate(args, logger);
+            if (typeof vargs === 'object' && vargs != null) {
+                this.telemetry.bindContext(vargs, span.context);
+            }
+            const auth = { identityKey: this.identityKey };
+            span.end({ attributes: { 'validation.result': 'ok' } });
+            return { vargs, auth };
+        }
+        catch (error) {
+            span.end({
+                status: 'error',
+                error,
+                attributes: { 'validation.result': 'rejected' }
+            });
+            throw error;
+        }
     }
-    //////////////////
+    /// ///////////////
     // List Methods
-    //////////////////
+    /// ///////////////
     async listActions(args, originator) {
         sdk_1.Validation.validateOriginator(originator);
         const { vargs } = this.validateAuthAndArgs(args, sdk_1.Validation.validateListActionsArgs);
-        const r = await this.storage.listActions(vargs);
+        const storageArgs = this.actionBatch.hasWorkspace ? { ...vargs, limit: 10000, offset: 0 } : vargs;
+        const r = this.actionBatch.overlayListActions(await this.storage.listActions(storageArgs), vargs);
         // Implement security policy to block customInstructions from output results.
         for (const action of r.actions) {
-            if (action.outputs)
+            if (action.outputs != null) {
                 for (const output of action.outputs) {
                     output.customInstructions = undefined;
                 }
+            }
         }
         return r;
     }
@@ -230,8 +339,11 @@ class Wallet {
         if (this.autoKnownTxids && !vargs.knownTxids) {
             vargs.knownTxids = this.getKnownTxids();
         }
-        const r = await this.storage.listOutputs(vargs);
-        if (r.BEEF) {
+        const storageArgs = this.actionBatch.hasWorkspace && vargs.basket !== types_1.specOpWalletBalance && !vargs.tags.includes(types_1.specOpWalletBalance)
+            ? { ...vargs, limit: 10000, offset: 0 }
+            : vargs;
+        const r = this.actionBatch.overlayListOutputs(await this.storage.listOutputs(storageArgs), vargs);
+        if (r.BEEF != null) {
             this.beef.mergeBeefFromParty(this.storageParty, (0, utilityHelpers_noBuffer_1.asArray)(r.BEEF));
             r.BEEF = this.verifyReturnedTxidOnlyBEEF(r.BEEF);
         }
@@ -243,151 +355,162 @@ class Wallet {
         const r = await this.storage.listCertificates(vargs);
         return r;
     }
-    //////////////////
+    /// ///////////////
     // Certificates
-    //////////////////
+    /// ///////////////
+    async acquireDirectCertificateProtocol(args) {
+        const { auth, vargs } = this.validateAuthAndArgs(args, sdk_1.Validation.validateAcquireDirectCertificateArgs);
+        vargs.subject = (await this.getPublicKey({
+            identityKey: true,
+            privileged: args.privileged,
+            privilegedReason: args.privilegedReason
+        })).publicKey;
+        try {
+            const certificate = new sdk_1.MasterCertificate(vargs.type, vargs.serialNumber, vargs.subject, vargs.certifier, vargs.revocationOutpoint, vargs.fields, vargs.keyringForSubject, vargs.signature);
+            await certificate.verify();
+            await sdk_1.MasterCertificate.decryptFields(this, vargs.keyringForSubject, vargs.fields, vargs.certifier, vargs.privileged, vargs.privilegedReason);
+        }
+        catch (error_) {
+            const error = WalletError_1.WalletError.fromUnknown(error_);
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('args', `valid encrypted and signed certificate and keyring from revealer. ${error.name}: ${error.message}`);
+        }
+        return await (0, acquireDirectCertificate_1.acquireDirectCertificate)(this, auth, vargs);
+    }
+    validateIssuedCertificateFields(certificate, expectedFields) {
+        if (Object.keys(certificate.fields).length !== Object.keys(expectedFields).length) {
+            throw new Error('Fields mismatch! Objects have different numbers of keys.');
+        }
+        for (const field of Object.keys(expectedFields)) {
+            if (!(field in certificate.fields)) {
+                throw new Error(`Missing field: ${field} in certificate.fields`);
+            }
+            if (certificate.fields[field] !== expectedFields[field]) {
+                throw new Error(`Invalid field! Expected: ${expectedFields[field]}, Received: ${certificate.fields[field]}`);
+            }
+        }
+    }
+    validateIssuedCertificate(certificate, vargs, expectedFields) {
+        if (certificate.type !== vargs.type) {
+            throw new Error(`Invalid certificate type! Expected: ${vargs.type}, Received: ${certificate.type}`);
+        }
+        if (certificate.subject !== this.identityKey) {
+            throw new Error(`Invalid certificate subject! Expected: ${this.identityKey}, Received: ${certificate.subject}`);
+        }
+        if (certificate.certifier !== vargs.certifier) {
+            throw new Error(`Invalid certifier! Expected: ${vargs.certifier}, Received: ${certificate.certifier}`);
+        }
+        if (!certificate.revocationOutpoint) {
+            throw new Error('Invalid revocationOutpoint!');
+        }
+        this.validateIssuedCertificateFields(certificate, expectedFields);
+    }
+    async acquireIssuedCertificateProtocol(args) {
+        const { auth, vargs } = this.validateAuthAndArgs(args, sdk_1.Validation.validateAcquireIssuanceCertificateArgs);
+        const clientNonce = await (0, sdk_1.createNonce)(this, vargs.certifier);
+        const authClient = new sdk_1.AuthFetch(this);
+        const { certificateFields, masterKeyring } = await sdk_1.MasterCertificate.createCertificateFields(this, vargs.certifier, vargs.fields);
+        const response = await authClient.fetch(`${vargs.certifierUrl}/signCertificate`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                clientNonce,
+                type: vargs.type,
+                fields: certificateFields,
+                masterKeyring
+            })
+        });
+        const responseIdentity = response.headers.get('x-bsv-auth-identity-key');
+        if (responseIdentity !== vargs.certifier) {
+            throw new Error(`Invalid certifier! Expected: ${vargs.certifier}, Received: ${responseIdentity}`);
+        }
+        const { certificate, serverNonce } = await response.json();
+        if (!certificate)
+            throw new Error('No certificate received from certifier!');
+        if (!serverNonce)
+            throw new Error('No serverNonce received from certifier!');
+        const signedCertificate = new sdk_1.Certificate(certificate.type, certificate.serialNumber, certificate.subject, certificate.certifier, certificate.revocationOutpoint, certificate.fields, certificate.signature);
+        await (0, sdk_1.verifyNonce)(serverNonce, this, vargs.certifier);
+        const { valid } = await this.verifyHmac({
+            hmac: sdk_1.Utils.toArray(signedCertificate.serialNumber, 'base64'),
+            data: sdk_1.Utils.toArray(clientNonce + serverNonce, 'base64'),
+            protocolID: [2, 'certificate issuance'],
+            keyID: serverNonce + clientNonce,
+            counterparty: vargs.certifier
+        });
+        if (!valid)
+            throw new Error('Invalid serialNumber');
+        this.validateIssuedCertificate(signedCertificate, vargs, certificateFields);
+        await signedCertificate.verify();
+        await sdk_1.MasterCertificate.decryptFields(this, masterKeyring, certificate.fields, vargs.certifier);
+        return await (0, acquireDirectCertificate_1.acquireDirectCertificate)(this, auth, {
+            ...certificate,
+            keyringRevealer: 'certifier',
+            keyringForSubject: masterKeyring,
+            privileged: vargs.privileged
+        });
+    }
     async acquireCertificate(args, originator) {
         sdk_1.Validation.validateOriginator(originator);
         if (args.acquisitionProtocol === 'direct') {
-            const { auth, vargs } = this.validateAuthAndArgs(args, sdk_1.Validation.validateAcquireDirectCertificateArgs);
-            vargs.subject = (await this.getPublicKey({
-                identityKey: true,
-                privileged: args.privileged,
-                privilegedReason: args.privilegedReason
-            })).publicKey;
-            try {
-                // Confirm that the information received adds up to a usable certificate...
-                // TODO: Clean up MasterCertificate to support decrypt on instance
-                const cert = new sdk_1.MasterCertificate(vargs.type, vargs.serialNumber, vargs.subject, vargs.certifier, vargs.revocationOutpoint, vargs.fields, vargs.keyringForSubject, vargs.signature);
-                await cert.verify();
-                // Verify certificate details
-                await sdk_1.MasterCertificate.decryptFields(this, vargs.keyringForSubject, vargs.fields, vargs.certifier, vargs.privileged, vargs.privilegedReason);
-            }
-            catch (eu) {
-                const e = WalletError_1.WalletError.fromUnknown(eu);
-                throw new WERR_errors_1.WERR_INVALID_PARAMETER('args', `valid encrypted and signed certificate and keyring from revealer. ${e.name}: ${e.message}`);
-            }
-            const r = await (0, acquireDirectCertificate_1.acquireDirectCertificate)(this, auth, vargs);
-            return r;
+            return await this.acquireDirectCertificateProtocol(args);
         }
         if (args.acquisitionProtocol === 'issuance') {
-            const { auth, vargs } = this.validateAuthAndArgs(args, sdk_1.Validation.validateAcquireIssuanceCertificateArgs);
-            // Create a random nonce that the server can verify
-            const clientNonce = await (0, sdk_1.createNonce)(this, vargs.certifier);
-            // TODO: Consider adding support to request certificates from a certifier before acquiring a certificate.
-            const authClient = new sdk_1.AuthFetch(this);
-            // Create a certificate master keyring
-            // The certifier is able to decrypt these fields as they are the counterparty
-            const { certificateFields, masterKeyring } = await sdk_1.MasterCertificate.createCertificateFields(this, vargs.certifier, vargs.fields);
-            // Make a Certificate Signing Request (CSR) to the certifier
-            const response = await authClient.fetch(`${vargs.certifierUrl}/signCertificate`, {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json'
-                },
-                body: JSON.stringify({
-                    clientNonce,
-                    type: vargs.type,
-                    fields: certificateFields,
-                    masterKeyring
-                })
-            });
-            if (response.headers.get('x-bsv-auth-identity-key') !== vargs.certifier) {
-                throw new Error(`Invalid certifier! Expected: ${vargs.certifier}, Received: ${response.headers.get('x-bsv-auth-identity-key')}`);
-            }
-            const { certificate, serverNonce } = await response.json();
-            // Validate the server response
-            if (!certificate) {
-                throw new Error('No certificate received from certifier!');
-            }
-            if (!serverNonce) {
-                throw new Error('No serverNonce received from certifier!');
-            }
-            const signedCertificate = new sdk_1.Certificate(certificate.type, certificate.serialNumber, certificate.subject, certificate.certifier, certificate.revocationOutpoint, certificate.fields, certificate.signature);
-            // Validate server nonce
-            await (0, sdk_1.verifyNonce)(serverNonce, this, vargs.certifier);
-            // Verify the server included our nonce
-            const { valid } = await this.verifyHmac({
-                hmac: sdk_1.Utils.toArray(signedCertificate.serialNumber, 'base64'),
-                data: sdk_1.Utils.toArray(clientNonce + serverNonce, 'base64'),
-                protocolID: [2, 'certificate issuance'],
-                keyID: serverNonce + clientNonce,
-                counterparty: vargs.certifier
-            });
-            if (!valid)
-                throw new Error('Invalid serialNumber');
-            // Validate the certificate received
-            if (signedCertificate.type !== vargs.type) {
-                throw new Error(`Invalid certificate type! Expected: ${vargs.type}, Received: ${signedCertificate.type}`);
-            }
-            if (signedCertificate.subject !== this.identityKey) {
-                throw new Error(`Invalid certificate subject! Expected: ${this.identityKey}, Received: ${signedCertificate.subject}`);
-            }
-            if (signedCertificate.certifier !== vargs.certifier) {
-                throw new Error(`Invalid certifier! Expected: ${vargs.certifier}, Received: ${signedCertificate.certifier}`);
-            }
-            if (!signedCertificate.revocationOutpoint) {
-                throw new Error(`Invalid revocationOutpoint!`);
-            }
-            if (Object.keys(signedCertificate.fields).length !== Object.keys(certificateFields).length) {
-                throw new Error(`Fields mismatch! Objects have different numbers of keys.`);
-            }
-            for (const field of Object.keys(certificateFields)) {
-                if (!(field in signedCertificate.fields)) {
-                    throw new Error(`Missing field: ${field} in certificate.fields`);
-                }
-                if (signedCertificate.fields[field] !== certificateFields[field]) {
-                    throw new Error(`Invalid field! Expected: ${certificateFields[field]}, Received: ${signedCertificate.fields[field]}`);
-                }
-            }
-            await signedCertificate.verify();
-            // Test decryption works
-            await sdk_1.MasterCertificate.decryptFields(this, masterKeyring, certificate.fields, vargs.certifier);
-            // Store the newly issued certificate
-            return await (0, acquireDirectCertificate_1.acquireDirectCertificate)(this, auth, {
-                ...certificate,
-                keyringRevealer: 'certifier',
-                keyringForSubject: masterKeyring,
-                privileged: vargs.privileged
-            });
+            return await this.acquireIssuedCertificateProtocol(args);
         }
         throw new WERR_errors_1.WERR_INVALID_PARAMETER('acquisitionProtocol', `valid.${args.acquisitionProtocol} is unrecognized.`);
     }
     async relinquishCertificate(args, originator) {
         sdk_1.Validation.validateOriginator(originator);
         this.validateAuthAndArgs(args, sdk_1.Validation.validateRelinquishCertificateArgs);
-        const r = await this.storage.relinquishCertificate(args);
+        await this.storage.relinquishCertificate(args);
         return { relinquished: true };
     }
     async proveCertificate(args, originator) {
-        originator = sdk_1.Validation.validateOriginator(originator);
+        sdk_1.Validation.validateOriginator(originator);
         const { auth, vargs } = this.validateAuthAndArgs(args, sdk_1.Validation.validateProveCertificateArgs);
         const r = await (0, proveCertificate_1.proveCertificate)(this, auth, vargs);
         return r;
     }
+    /** 2-minute cache of trust settings for identity resolution paths */
+    _trustSettingsCache;
+    /** 2-minute cache of queryOverlay() results keyed by normalized query */
+    _overlayCache = new Map();
     async discoverByIdentityKey(args, originator) {
         sdk_1.Validation.validateOriginator(originator);
         this.validateAuthAndArgs(args, sdk_1.Validation.validateDiscoverByIdentityKeyArgs);
         const TTL_MS = 2 * 60 * 1000;
         const now = Date.now();
+        const forceRefresh = args.forceRefresh === true;
+        // --- Contacts short-circuit (sub-10 ms typical, no network) ---
+        if (!forceRefresh && this.contactSource != null) {
+            try {
+                const contact = await this.contactSource.findByIdentityKey(args.identityKey);
+                if (contact != null) {
+                    return synthesizeContactResult([contact]);
+                }
+            }
+            catch {
+                // Contact source failures must never block the network path.
+            }
+        }
         // --- trustSettings cache (2 minutes) ---
-        let trustSettings = this._trustSettingsCache && this._trustSettingsCache.expiresAt > now
+        let trustSettings = this._trustSettingsCache != null && this._trustSettingsCache.expiresAt > now
             ? this._trustSettingsCache.trustSettings
             : undefined;
-        if (!trustSettings) {
+        if (trustSettings == null) {
             const settings = await this.settingsManager.get();
             trustSettings = settings.trustSettings;
             this._trustSettingsCache = { trustSettings, expiresAt: now + TTL_MS };
         }
         const certifiers = trustSettings.trustedCertifiers.map(c => c.identityKey).sort((a, b) => a.localeCompare(b));
-        // --- queryOverlay cache (2 minutes) ---
+        // --- queryOverlay cache (2 minutes, client-side, bounded staleness) ---
         const cacheKey = JSON.stringify({
             fn: 'discoverByIdentityKey',
             identityKey: args.identityKey,
             certifiers
         });
-        let cached = this._overlayCache.get(cacheKey);
-        if (!cached || cached.expiresAt <= now) {
+        let cached = forceRefresh ? undefined : this._overlayCache.get(cacheKey);
+        if (cached == null || cached.expiresAt <= now) {
             const value = await (0, identityUtils_1.queryOverlay)({ identityKey: args.identityKey, certifiers }, this.lookupResolver);
             cached = { value, expiresAt: now + TTL_MS };
             this._overlayCache.set(cacheKey, cached);
@@ -402,11 +525,24 @@ class Wallet {
         this.validateAuthAndArgs(args, sdk_1.Validation.validateDiscoverByAttributesArgs);
         const TTL_MS = 2 * 60 * 1000;
         const now = Date.now();
+        const forceRefresh = args.forceRefresh === true;
+        // --- Contacts short-circuit (optional, only when source supports attribute search) ---
+        if (!forceRefresh && this.contactSource?.findByAttributes != null && args.attributes != null) {
+            try {
+                const matches = await this.contactSource.findByAttributes(args.attributes);
+                if (Array.isArray(matches) && matches.length > 0) {
+                    return synthesizeContactResult(matches);
+                }
+            }
+            catch {
+                // Fall through to network path on contact-source failure.
+            }
+        }
         // --- trustSettings cache (2 minutes) ---
-        let trustSettings = this._trustSettingsCache && this._trustSettingsCache.expiresAt > now
+        let trustSettings = this._trustSettingsCache != null && this._trustSettingsCache.expiresAt > now
             ? this._trustSettingsCache.trustSettings
             : undefined;
-        if (!trustSettings) {
+        if (trustSettings == null) {
             const settings = await this.settingsManager.get();
             trustSettings = settings.trustSettings;
             this._trustSettingsCache = { trustSettings, expiresAt: now + TTL_MS };
@@ -419,14 +555,14 @@ class Wallet {
             const keys = Object.keys(args.attributes).sort((a, b) => a.localeCompare(b));
             attributesKey = JSON.stringify(args.attributes, keys);
         }
-        // --- queryOverlay cache (2 minutes) ---
+        // --- queryOverlay cache (2 minutes, client-side, bounded staleness) ---
         const cacheKey = JSON.stringify({
             fn: 'discoverByAttributes',
             attributes: attributesKey,
             certifiers
         });
-        let cached = this._overlayCache.get(cacheKey);
-        if (!cached || cached.expiresAt <= now) {
+        let cached = forceRefresh ? undefined : this._overlayCache.get(cacheKey);
+        if (cached == null || cached.expiresAt <= now) {
             const value = await (0, identityUtils_1.queryOverlay)({ attributes: args.attributes, certifiers }, this.lookupResolver);
             cached = { value, expiresAt: now + TTL_MS };
             this._overlayCache.set(cacheKey, cached);
@@ -441,28 +577,30 @@ class Wallet {
             return beef;
         const onlyTxids = beef.txs.filter(btx => btx.isTxidOnly).map(btx => btx.txid);
         for (const txid of onlyTxids) {
-            if (knownTxids && knownTxids.indexOf(txid) >= 0)
+            if (knownTxids?.includes(txid))
                 continue;
-            const btx = beef.findTxid(txid);
             const tx = this.beef.findAtomicTransaction(txid);
-            if (!tx)
+            if (tx == null)
                 throw new WERR_errors_1.WERR_INTERNAL(`unable to merge txid ${txid} into beef`);
             beef.mergeTransaction(tx);
         }
         for (const btx of beef.txs) {
-            if (knownTxids && knownTxids.indexOf(btx.txid) >= 0)
+            if (knownTxids?.includes(btx.txid))
                 continue;
             if (btx.isTxidOnly)
                 throw new WERR_errors_1.WERR_INTERNAL(`remaining txidOnly ${btx.txid} is not known`);
         }
         return beef;
     }
-    verifyReturnedTxidOnlyAtomicBEEF(beef, knownTxids) {
+    verifyReturnedTxidOnlyAtomicBEEF(beef, knownTxids, parsedBeef) {
         if (this.returnTxidOnly)
             return beef;
-        const b = sdk_1.Beef.fromBinary(beef);
+        const b = parsedBeef ?? sdk_1.Beef.fromBinary(beef);
         if (!b.atomicTxid)
             throw new WERR_errors_1.WERR_INTERNAL();
+        const hasUnknownTxidOnly = b.txs.some(btx => btx.isTxidOnly && !knownTxids?.includes(btx.txid));
+        if (!hasUnknownTxidOnly)
+            return beef;
         return this.verifyReturnedTxidOnly(b, knownTxids).toBinaryAtomic(b.atomicTxid);
     }
     verifyReturnedTxidOnlyBEEF(beef) {
@@ -472,87 +610,101 @@ class Wallet {
         return this.verifyReturnedTxidOnly(b).toBinary();
     }
     logMakeLogger(method, args) {
-        var _a;
-        const logger = (_a = this.makeLogger) === null || _a === void 0 ? void 0 : _a.call(this, args['log']);
+        const logger = this.makeLogger?.(args.log);
         this.logMethodStart(method, logger);
         return logger;
     }
     logMethodStart(method, logger) {
-        logger === null || logger === void 0 ? void 0 : logger.group(`Wallet ${method}`);
+        logger?.group(`Wallet ${method}`);
     }
     logResult(r, logger) {
-        var _a;
-        if (!logger)
+        if (logger == null)
             return;
         logger.groupEnd();
-        r['log'] = (_a = logger.flush) === null || _a === void 0 ? void 0 : _a.call(logger);
+        r.log = logger.flush?.();
     }
     logWalletError(eu, logger) {
-        var _a;
-        if (!logger)
+        if (logger == null)
             return;
         logger.error('WalletError:', WalletError_1.WalletError.unknownToJson(eu));
-        (_a = logger.flush) === null || _a === void 0 ? void 0 : _a.call(logger);
+        logger.flush?.();
     }
-    //////////////////
+    /// ///////////////
     // Actions
-    //////////////////
+    /// ///////////////
     async createAction(args, originator) {
-        var _a;
-        var _b;
-        const logger = this.logMakeLogger(`createAction`, args);
+        const logger = this.logMakeLogger('createAction', args);
         try {
             sdk_1.Validation.validateOriginator(originator);
-            if (!args.options)
-                args.options = {};
-            (_b = args.options).trustSelf || (_b.trustSelf = this.trustSelf);
-            if (this.autoKnownTxids && !args.options.knownTxids) {
-                args.options.knownTxids = this.getKnownTxids(args.options.knownTxids);
-            }
+            args.options ??= {};
+            args.options.trustSelf ||= this.trustSelf;
+            prepareKnownTxidsForCreateAction(this, args);
             const { auth, vargs } = this.validateAuthAndArgs(args, sdk_1.Validation.validateCreateActionArgs, logger);
-            logger === null || logger === void 0 ? void 0 : logger.log('validated args');
+            logger?.log('validated args');
             vargs.includeAllSourceTransactions = this.includeAllSourceTransactions;
-            if (this.randomVals && this.randomVals.length > 1) {
+            if (this.randomVals != null && this.randomVals.length > 1) {
                 vargs.randomVals = [...this.randomVals];
             }
             const r = await (0, createAction_1.createAction)(this, auth, vargs);
-            logger === null || logger === void 0 ? void 0 : logger.log('action created');
-            if (r.tx) {
-                this.beef.mergeBeefFromParty(this.storageParty, (0, utilityHelpers_noBuffer_1.asArray)(r.tx));
+            logger?.log('action created');
+            const resultBeef = (0, resultBeef_1.getResultBeef)(r);
+            if (r.tx != null) {
+                const merge = () => this.beef.mergeBeefFromParty(this.storageParty, resultBeef ?? r.tx);
+                if (this.telemetry.enabled) {
+                    this.telemetry.withSpan('wallet.create_action.merge_result_beef', {
+                        component: 'wallet-toolbox',
+                        carrier: args,
+                        attributes: {
+                            'beef.retained_tx_count_before': this.beef.txs.length,
+                            'beef.result_byte_count': r.tx.length
+                        }
+                    }, merge);
+                }
+                else {
+                    merge();
+                }
             }
-            if (r.tx) {
-                r.tx = this.verifyReturnedTxidOnlyAtomicBEEF(r.tx, (_a = args.options) === null || _a === void 0 ? void 0 : _a.knownTxids);
-                logger === null || logger === void 0 ? void 0 : logger.log('verify returned AtomicBEEF');
+            if (r.tx != null) {
+                const verify = () => this.verifyReturnedTxidOnlyAtomicBEEF(r.tx, args.options?.knownTxids, resultBeef);
+                r.tx = this.telemetry.enabled
+                    ? this.telemetry.withSpan('wallet.create_action.verify_result_beef', {
+                        component: 'wallet-toolbox',
+                        carrier: args,
+                        attributes: { 'beef.result_byte_count': r.tx.length }
+                    }, verify)
+                    : verify();
+                logger?.log('verify returned AtomicBEEF');
             }
             if (!vargs.isDelayed)
                 throwIfAnyUnsuccessfulCreateActions(r);
             this.logResult(r, logger);
             return r;
         }
-        catch (eu) {
-            this.logWalletError(eu, logger);
-            throw eu;
+        catch (error_) {
+            this.logWalletError(error_, logger);
+            throw error_;
         }
     }
     async signAction(args, originator) {
-        var _a;
         sdk_1.Validation.validateOriginator(originator);
         const { auth, vargs } = this.validateAuthAndArgs(args, sdk_1.Validation.validateSignActionArgs);
+        const prior = this.pendingSignActions[args.reference];
+        if (!prior) {
+            throw new WERR_errors_1.WERR_NOT_IMPLEMENTED('recovery of out-of-session signAction reference data is not yet implemented.');
+        }
         // createAction options are merged with undefined signAction options before validation...
         const r = await (0, signAction_1.signAction)(this, auth, args);
         if (!vargs.isDelayed)
             throwIfAnyUnsuccessfulSignActions(r);
-        const prior = this.pendingSignActions[args.reference];
-        if (!prior)
-            throw new WERR_errors_1.WERR_NOT_IMPLEMENTED('recovery of out-of-session signAction reference data is not yet implemented.');
-        if (r.tx)
-            r.tx = this.verifyReturnedTxidOnlyAtomicBEEF(r.tx, (_a = prior.args.options) === null || _a === void 0 ? void 0 : _a.knownTxids);
+        if (r.tx != null)
+            r.tx = this.verifyReturnedTxidOnlyAtomicBEEF(r.tx, prior.args.options?.knownTxids, (0, resultBeef_1.getResultBeef)(r));
+        delete this.pendingSignActions[args.reference];
         return r;
     }
     async internalizeAction(args, originator) {
         sdk_1.Validation.validateOriginator(originator);
         const { auth, vargs } = this.validateAuthAndArgs(args, sdk_1.Validation.validateInternalizeActionArgs);
-        if (vargs.labels.indexOf(types_1.specOpThrowReviewActions) >= 0)
+        if (vargs.labels.includes(types_1.specOpThrowReviewActions))
             throwDummyReviewActions();
         const r = await (0, internalizeAction_1.internalizeAction)(this, auth, args);
         throwIfUnsuccessfulInternalizeAction(r);
@@ -560,14 +712,17 @@ class Wallet {
     }
     async abortAction(args, originator) {
         sdk_1.Validation.validateOriginator(originator);
-        const { auth } = this.validateAuthAndArgs(args, sdk_1.Validation.validateAbortActionArgs);
+        this.validateAuthAndArgs(args, sdk_1.Validation.validateAbortActionArgs);
+        if (this.actionBatch.ownsReference(args.reference)) {
+            return { aborted: await this.actionBatch.abortAction(args.reference) };
+        }
         const r = await this.storage.abortAction(args);
         return r;
     }
     async relinquishOutput(args, originator) {
         sdk_1.Validation.validateOriginator(originator);
-        const { vargs } = this.validateAuthAndArgs(args, sdk_1.Validation.validateRelinquishOutputArgs);
-        const r = await this.storage.relinquishOutput(args);
+        this.validateAuthAndArgs(args, sdk_1.Validation.validateRelinquishOutputArgs);
+        await this.storage.relinquishOutput(args);
         return { relinquished: true };
     }
     async isAuthenticated(args, originator) {
@@ -636,7 +791,7 @@ class Wallet {
             labels: [label],
             description: label
         });
-        const iar = await toWallet.internalizeAction({
+        await toWallet.internalizeAction({
             tx: car.tx,
             outputs: [
                 {
@@ -657,15 +812,20 @@ class Wallet {
      * Uses `listOutputs` to iterate over chunks of up to 1000 outputs to
      * compute the sum of output satoshis.
      *
+     * For `default`, only wallet-managed BRC-29 change is included. Raw
+     * administrative `listOutputs({ basket: 'default' })` remains available to
+     * discover legacy incompatible rows for recovery.
+     *
      * @param {string} basket - Optional. Defaults to 'default', the wallet change basket.
      * @returns {WalletBalance} total sum of output satoshis and utxo details (satoshis and outpoints)
      */
     async balanceAndUtxos(basket = 'default') {
         const r = { total: 0, utxos: [] };
+        const listBasket = basket === 'default' ? types_1.specOpWalletManagedUtxos : basket;
         let offset = 0;
         for (;;) {
             const change = await this.listOutputs({
-                basket,
+                basket: listBasket,
                 limit: 1000,
                 offset
             });
@@ -686,7 +846,7 @@ class Wallet {
      * @returns {number} sum of output satoshis
      */
     async balance(args) {
-        args || (args = { basket: types_1.specOpWalletBalance });
+        args ||= { basket: types_1.specOpWalletBalance };
         if (args.basket !== types_1.specOpWalletBalance) {
             args.tags = [...(args.tags || []), types_1.specOpWalletBalance];
         }
@@ -706,10 +866,10 @@ class Wallet {
      */
     async reviewSpendableOutputs(all = false, release = false, optionalArgs) {
         const args = {
-            ...(optionalArgs || {}),
+            ...optionalArgs,
             basket: types_1.specOpInvalidChange
         };
-        args.tags || (args.tags = []);
+        args.tags ||= [];
         if (all)
             args.tags.push('all');
         if (release)
@@ -740,10 +900,11 @@ class Wallet {
     async listNoSendActions(args, abort = false) {
         const { vargs } = this.validateAuthAndArgs(args, sdk_1.Validation.validateListActionsArgs);
         vargs.labels.push(types_1.specOpNoSendActions);
-        if (abort)
+        if (abort) {
+            await this.actionBatch.abort();
             vargs.labels.push('abort');
-        const r = await this.storage.listActions(vargs);
-        return r;
+        }
+        return await this.listActions(vargs);
     }
     /**
      * Uses `listActions` special operation to return only actions with status 'failed'.
@@ -764,21 +925,21 @@ exports.Wallet = Wallet;
 function throwIfAnyUnsuccessfulCreateActions(r) {
     const ndrs = r.notDelayedResults;
     const swrs = r.sendWithResults;
-    if (!ndrs || !swrs || swrs.every(r => r.status === 'unproven'))
+    if (ndrs == null || swrs == null || swrs.every(r => r.status === 'unproven'))
         return;
     throw new WERR_errors_1.WERR_REVIEW_ACTIONS(ndrs, swrs, r.txid, r.tx, r.noSendChange);
 }
 function throwIfAnyUnsuccessfulSignActions(r) {
     const ndrs = r.notDelayedResults;
     const swrs = r.sendWithResults;
-    if (!ndrs || !swrs || swrs.every(r => r.status === 'unproven'))
+    if (ndrs == null || swrs == null || swrs.every(r => r.status === 'unproven'))
         return;
     throw new WERR_errors_1.WERR_REVIEW_ACTIONS(ndrs, swrs, r.txid, r.tx);
 }
 function throwIfUnsuccessfulInternalizeAction(r) {
     const ndrs = r.notDelayedResults;
     const swrs = r.sendWithResults;
-    if (!ndrs || !swrs || swrs.every(r => r.status === 'unproven'))
+    if (ndrs == null || swrs == null || swrs.every(r => r.status === 'unproven'))
         return;
     throw new WERR_errors_1.WERR_REVIEW_ACTIONS(ndrs, swrs, r.txid);
 }
@@ -788,7 +949,7 @@ function throwIfUnsuccessfulInternalizeAction(r) {
 function throwDummyReviewActions() {
     const b58Beef = 'gno9MC7VXii1KoCkc2nsVyYJpqzN3dhBzYATETJcys62emMKfpBof4R7GozwYEaSapUtnNvqQ57aaYYjm3U2dv9eUJ1sV46boHkQgppYmAz9YH8FdZduV8aJayPViaKcyPmbDhEw6UW8TM5iFZLXNs7HBnJHUKCeTdNK4FUEL7vAugxAV9WUUZ43BZjJk2SmSeps9TCXjt1Ci9fKWp3d9QSoYvTpxwzyUFHjRKtbUgwq55ZfkBp5bV2Bpz9qSuKywKewW7Hh4S1nCUScwwzpKDozb3zic1V9p2k8rQxoPsRxjUJ8bjhNDdsN8d7KukFuc3n47fXzdWttvnxwsujLJRGnQbgJuknQqx3KLf5kJXHzwjG6TzigZk2t24qeB6d3hbYiaDr2fFkUJBL3tukTHhfNkQYRXuz3kucVDzvejHyqJaF51mXG8BjMN5aQj91ZJXCaPVqkMWCzmvyaqmXMdRiJdSAynhXbQK91xf6RwdNhz1tg5f9B6oJJMhsi9UYSVymmax8VLKD9AKzBCBDcfyD83m3jyS1VgKGZn3SkQmr6bsoWq88L3GsMnnmYUGogvdAYarTqg3pzkjCMxHzmJBMN6ofnUk8c1sRTXQue7BbyUaN5uZu3KW6CmFsEfpuqVvnqFW93TU1jrPP2S8yz8AexAnARPCKE8Yz7RfVaT6RCavwQKL3u5iookwRWEZXW1QWmM37yJWHD87SjVynyg327a1CLwcBxmE2CB48QeNVGyQki4CTQMqw2o8TMhDPJej1g68oniAjBcxBLSCs7KGvK3k7AfrHbCMULX9CTibYhCjdFjbsbBoocqJpxxcvkMo1fEEiAzZuiBVZQDYktDdTVbhKHvYkW25HcYX75NJrpNAhm7AjFeKLzEVxqAQkMfvTufpESNRZF4kQqg2Rg8h2ajcKTd5cpEPwXCrZLHm4EaZEmZVbg3QNfGhn7BJu1bHMtLqPD4y8eJxm2uGrW6saf6qKYmmu64F8A667NbD4yskPRQ1S863VzwGpxxmgLc1Ta3R46jEqsAoRDoZVUaCgBBZG3Yg1CTgi1EVBMXU7qvY4n3h8o2FLCEMWY4KadnV3iD4FbcdCmg4yxBosNAZgbPjhgGjCimjh4YsLd9zymGLmivmz2ZBg5m3xaiXT9NN81X9C1JUujd';
     const beef = sdk_1.Beef.fromBinary(sdk_1.Utils.fromBase58(b58Beef));
-    const btx = beef.txs.slice(-1)[0];
+    const btx = beef.txs.at(-1);
     const txid = btx.txid;
     console.log('Throwing dummy WERR_REVIEW_ACTIONS');
     throw new WERR_errors_1.WERR_REVIEW_ACTIONS([