@aztec-labs/wallet-sdk 6.0.0-nightly.20260829

package/dest/base-wallet/base_wallet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base_wallet.d.ts","sourceRoot":"","sources":["../../src/base-wallet/base_wallet.ts"],"names":[],"mappings":"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"}

package/dest/base-wallet/base_wallet.js

@@ -0,0 +1,503 @@
+import { NO_FROM } from '@aztec-labs/aztec.js/account';
+import { DefaultWaitOpts, NO_WAIT, extractOffchainOutput } from '@aztec-labs/aztec.js/contracts';
+import { waitForTx } from '@aztec-labs/aztec.js/node';
+import { ContractInitializationStatus, TxSimulationResultWithAppOffset } from '@aztec-labs/aztec.js/wallet';
+import { AccountFeePaymentMethodOptions } from '@aztec-labs/entrypoints/account';
+import { DefaultEntrypoint } from '@aztec-labs/entrypoints/default';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { createLogger } from '@aztec-labs/foundation/log';
+import { displayDebugLogs } from '@aztec-labs/pxe/client/lazy';
+import { decodeFromAbi } from '@aztec-labs/stdlib/abi';
+import { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import { computePartialAddress } from '@aztec-labs/stdlib/contract';
+import { SimulationError } from '@aztec-labs/stdlib/errors';
+import { Gas, GasFees, GasSettings, ManaUsageEstimate } from '@aztec-labs/stdlib/gas';
+import { computeSiloedPrivateInitializationNullifier, computeSiloedPublicInitializationNullifier } from '@aztec-labs/stdlib/hash';
+import { deriveKeys, deriveKeysFromMasterSecretKeys } from '@aztec-labs/stdlib/keys';
+import { mergeExecutionPayloads } from '@aztec-labs/stdlib/tx';
+import { inspect } from 'util';
+import { assertGasLimitsWithinNetworkLimits } from './get_gas_limits.js';
+import { buildMergedSimulationResult, extractOptimizablePublicStaticCalls, simulateViaNode } from './utils.js';
+/**
+ * A base class for Wallet implementations
+ */ export class BaseWallet {
+    pxe;
+    aztecNode;
+    log;
+    minFeePadding;
+    cancellableTransactions;
+    // Poll interval (in seconds) injected into sendTx waits when the caller does not specify one. Left undefined on
+    // production wallets so the DefaultWaitOpts 1s cadence stands; test wallets talking to in-process nodes lower it.
+    defaultWaitInterval;
+    // A wallet is instantiated for a particular chain, so chain info never changes during its lifetime.
+    // We cache it here because getChainInfo is called frequently (every tx simulation, send, auth wit, etc.).
+    nodeInfoPromise;
+    // Protected because we want to force wallets to instantiate their own PXE.
+    constructor(pxe, aztecNode, log = createLogger('wallet-sdk:base_wallet')){
+        this.pxe = pxe;
+        this.aztecNode = aztecNode;
+        this.log = log;
+        this.minFeePadding = 0.5;
+        this.cancellableTransactions = false;
+    }
+    scopesFrom(from, additionalScopes, sendMessagesAs) {
+        // The sendMessagesAs account must be in scope so that its tagging secrets can be accessed.
+        const tagSenderScopes = sendMessagesAs ? [
+            sendMessagesAs
+        ] : [];
+        const baseScopes = from === NO_FROM ? [] : [
+            from
+        ];
+        const allScopes = [
+            ...baseScopes,
+            ...additionalScopes,
+            ...tagSenderScopes
+        ];
+        const scopeSet = new Set(allScopes.map((address)=>address.toString()));
+        return [
+            ...scopeSet
+        ].map(AztecAddress.fromStringUnsafe);
+    }
+    /**
+   * Picks the sender address PXE should tag private messages with. Returns `undefined` when there is no signing
+   * account (`from === NO_FROM`) and no explicit override; in that case any private log emitted by the tx using
+   * the wallet-supplied default sender will fail the "Sender for tags is not set" assertion.
+   * @param from - Tx sender, or `NO_FROM`.
+   * @param sendMessagesAs - Explicit override.
+   */ senderForTagsFrom(from, sendMessagesAs) {
+        return sendMessagesAs ?? (from === NO_FROM ? undefined : from);
+    }
+    /**
+   * Returns the list of aliased contacts associated with the wallet.
+   * This base implementation directly returns PXE's senders, but note that in general contacts are a superset of senders.
+   *  - Senders: Addresses we check during synching in case they sent us notes,
+   *  - Contacts: more general concept akin to a phone's contact list.
+   * @returns The aliased collection of AztecAddresses that form this wallet's address book
+   */ async getAddressBook() {
+        const sources = await this.pxe.getTaggingSecretSources({
+            kind: 'address-derived'
+        });
+        return sources.map((source)=>({
+                item: source.sender,
+                alias: ''
+            }));
+    }
+    /**
+   * Fetches and caches the node info for the wallet's lifetime, since a wallet talks to a single network and
+   * node info never changes. A rejected fetch clears the cache so the next call retries instead of replaying
+   * the cached rejection forever — important because the gas-limit fill-in and validation (run on every send)
+   * depend on it.
+   */ getNodeInfo() {
+        if (!this.nodeInfoPromise) {
+            this.nodeInfoPromise = this.aztecNode.getNodeInfo().catch((err)=>{
+                this.nodeInfoPromise = undefined;
+                throw err;
+            });
+        }
+        return this.nodeInfoPromise;
+    }
+    async getChainInfo() {
+        const { l1ChainId, rollupVersion } = await this.getNodeInfo();
+        return {
+            chainId: new Fr(l1ChainId),
+            version: new Fr(rollupVersion)
+        };
+    }
+    /**
+   * Returns the maximum gas limits a single transaction may declare on this wallet's network (the
+   * node-advertised `txsLimits.gas`). Internal helper used to fill in default gas limits when sending a
+   * transaction without explicit limits, and to validate caller-provided limits before sending. Backed by
+   * the cached node info, since a wallet talks to a single network.
+   */ async getMaxTxGasLimits() {
+        const { txsLimits } = await this.getNodeInfo();
+        return new Gas(txsLimits.gas.daGas, txsLimits.gas.l2Gas);
+    }
+    async createTxExecutionRequestFromPayloadAndFee(executionPayload, from, feeOptions) {
+        const feeExecutionPayload = await feeOptions.walletFeePaymentMethod?.getExecutionPayload();
+        const finalExecutionPayload = feeExecutionPayload ? mergeExecutionPayloads([
+            feeExecutionPayload,
+            executionPayload
+        ]) : executionPayload;
+        const chainInfo = await this.getChainInfo();
+        if (from === NO_FROM) {
+            const entrypoint = new DefaultEntrypoint();
+            return entrypoint.createTxExecutionRequest(finalExecutionPayload, feeOptions.gasSettings, chainInfo);
+        } else {
+            const fromAccount = await this.getAccountFromAddress(from);
+            const executionOptions = {
+                txNonce: Fr.random(),
+                cancellable: this.cancellableTransactions,
+                // If from is an address, feeOptions include the way the account contract should handle the fee payment
+                feePaymentMethodOptions: feeOptions.accountFeePaymentMethodOptions
+            };
+            return fromAccount.createTxExecutionRequest(finalExecutionPayload, feeOptions.gasSettings, chainInfo, executionOptions);
+        }
+    }
+    async createAuthWit(from, messageHashOrIntent) {
+        const account = await this.getAccountFromAddress(from);
+        const chainInfo = await this.getChainInfo();
+        return account.createAuthWit(messageHashOrIntent, chainInfo);
+    }
+    /**
+   * Request capabilities from the wallet.
+   *
+   * This method is wallet-implementation-dependent and must be provided by classes extending BaseWallet.
+   * Embedded wallets typically don't support capability-based authorization (no user authorization flow),
+   * while external wallets (browser extensions, hardware wallets) implement this to reduce authorization
+   * friction by allowing apps to request permissions upfront.
+   *
+   * TODO: Consider making it abstract so implementing it is a conscious decision. Leaving it as-is
+   * while the feature stabilizes.
+   *
+   * @param _manifest - Application capability manifest declaring what operations the app needs
+   */ requestCapabilities(_manifest) {
+        throw new Error('Not implemented');
+    }
+    async batch(methods) {
+        const results = [];
+        for (const method of methods){
+            const { name, args } = method;
+            // Type safety is guaranteed by the BatchedMethod type, which ensures that:
+            // 1. `name` is a valid batchable method name
+            // 2. `args` matches the parameter types of that specific method
+            // 3. The return type is correctly mapped in BatchResults<T>
+            // We use dynamic dispatch here for simplicity, but the types are enforced at the call site.
+            const fn = this[name];
+            const result = await fn.apply(this, args);
+            // Wrap result with method name for discriminated union deserialization
+            results.push({
+                name,
+                result
+            });
+        }
+        return results;
+    }
+    /**
+   * Completes partial user-provided fee options with wallet defaults.
+   * @param config - Fee completion config.
+   */ async completeFeeOptions(config) {
+        const { from, feePayer, gasSettings, forEstimation, congestionEstimate } = config;
+        const maxFeesPerGas = gasSettings?.maxFeesPerGas ?? (await this.getMinFees(congestionEstimate)).mul(1 + this.minFeePadding);
+        let accountFeePaymentMethodOptions;
+        // If from is an address, we need to determine the appropriate fee payment method options for the
+        // account contract entrypoint to use
+        if (from !== NO_FROM) {
+            if (!feePayer) {
+                // The transaction does not include a fee payment method, so we set the flag
+                // for the account to use its fee juice balance
+                accountFeePaymentMethodOptions = AccountFeePaymentMethodOptions.PREEXISTING_FEE_JUICE;
+            } else {
+                // The transaction includes fee payment method, so we check if we are the fee payer for it
+                // (this can only happen if the embedded payment method is FeeJuiceWithClaim)
+                accountFeePaymentMethodOptions = from.equals(feePayer) ? AccountFeePaymentMethodOptions.FEE_JUICE_WITH_CLAIM : AccountFeePaymentMethodOptions.EXTERNAL;
+            }
+        }
+        const gasSettingsOverrides = {
+            gasLimits: gasSettings?.gasLimits ? Gas.from(gasSettings.gasLimits) : undefined,
+            teardownGasLimits: gasSettings?.teardownGasLimits ? Gas.from(gasSettings.teardownGasLimits) : undefined,
+            maxFeesPerGas,
+            maxPriorityFeesPerGas: gasSettings?.maxPriorityFeesPerGas ?? GasFees.empty()
+        };
+        // When estimating gas (simulation), use high limits so the simulation doesn't run out of gas.
+        // When sending for real without explicit limits, declare the most a single tx may use on this network
+        // (the node's per-tx admission limit), so the proposer does not skip the tx for over-declaring gas.
+        let fullGasSettings;
+        if (forEstimation) {
+            // Estimation deliberately uses very high internal limits, which the node exempts from gas-limit
+            // admission during simulation, so we do not validate against the network admission limit here.
+            fullGasSettings = GasSettings.forEstimation(gasSettingsOverrides);
+        } else {
+            const maxTxGasLimits = await this.getMaxTxGasLimits();
+            // If the caller declared explicit gas limits, reject them up front when they exceed the network's
+            // per-tx admission limit (mirroring the node's MaxGasLimitsValidator). Otherwise fill in the limit.
+            if (gasSettingsOverrides.gasLimits) {
+                assertGasLimitsWithinNetworkLimits(gasSettingsOverrides.gasLimits, maxTxGasLimits);
+            }
+            fullGasSettings = GasSettings.fallback({
+                ...gasSettingsOverrides,
+                gasLimits: gasSettingsOverrides.gasLimits ?? maxTxGasLimits
+            });
+        }
+        this.log.debug(`Using L2 gas settings`, fullGasSettings);
+        return {
+            gasSettings: fullGasSettings,
+            walletFeePaymentMethod: undefined,
+            accountFeePaymentMethodOptions
+        };
+    }
+    /**
+   * Returns the worst-case min fee across predicted future slots.
+   * Falls back to getCurrentMinFees if the node doesn't support getPredictedMinFees.
+   * @param estimate - The mana usage estimate to use for fee prediction. Defaults to Limit for conservative estimation.
+   */ async getMinFees(estimate = ManaUsageEstimate.Limit) {
+        try {
+            const predicted = await this.aztecNode.getPredictedMinFees(estimate);
+            if (predicted.length === 0) {
+                return this.aztecNode.getCurrentMinFees();
+            }
+            return predicted.reduce((worst, fees)=>fees.feePerL2Gas > worst.feePerL2Gas ? fees : worst);
+        } catch (err) {
+            // Fallback for old nodes that don't support getPredictedMinFees.
+            // Only fall back on method-not-found errors (JSON-RPC code -32601); rethrow others.
+            if (err?.cause?.code === -32601 || err?.message?.includes('Method not found')) {
+                return this.aztecNode.getCurrentMinFees();
+            }
+            throw err;
+        }
+    }
+    async registerSender(address, _alias = '') {
+        await this.pxe.registerTaggingSecretSource({
+            kind: 'address-derived',
+            sender: address
+        });
+        return address;
+    }
+    async registerContract(instance, artifact, secretKeyOrKeys) {
+        // Classes and instances are registered independently: register the artifact (if provided) then the instance.
+        // Neither call validates that the artifact matches the class the instance runs, a missing artifact only surfaces
+        // when the contract is later simulated.
+        if (artifact) {
+            await this.pxe.registerContractClass(artifact);
+        }
+        const contractAddress = await this.pxe.registerContract(instance);
+        if (secretKeyOrKeys) {
+            // PXE never receives the account seed (from which the message-signing/fallback secret keys could be re-derived):
+            // the wallet derives the keys here. Of these, PXE only reads and stores the four privacy secret keys and the
+            // message-signing and fallback *public* keys — it never touches the message-signing or fallback secret keys.
+            //
+            // Since PXE recomputes the address from those keys, we assert it matches the instance's address: a mismatch means
+            // the provided keys don't correspond to this account.
+            const derivedKeys = secretKeyOrKeys instanceof Fr ? await deriveKeys(secretKeyOrKeys) : await deriveKeysFromMasterSecretKeys(secretKeyOrKeys);
+            const { address } = await this.pxe.registerAccount(derivedKeys, await computePartialAddress(instance));
+            if (!address.equals(contractAddress)) {
+                throw new Error(`Registered account address ${address.toString()} does not match contract instance address ${contractAddress.toString()}: the provided keys do not correspond to this account.`);
+            }
+        }
+    }
+    registerContractClass(artifact) {
+        return this.pxe.registerContractClass(artifact);
+    }
+    /**
+   * Simulates calls through the standard PXE path (account entrypoint).
+   * @param executionPayload - The execution payload to simulate.
+   * @param opts - Simulation options.
+   */ async simulateViaEntrypoint(executionPayload, opts) {
+        const txRequest = await this.createTxExecutionRequestFromPayloadAndFee(executionPayload, opts.from, opts.feeOptions);
+        const result = await this.pxe.simulateTx(txRequest, {
+            simulatePublic: true,
+            skipTxValidation: opts.skipTxValidation,
+            skipFeeEnforcement: opts.skipFeeEnforcement,
+            scopes: this.scopesFrom(opts.from, opts.additionalScopes ?? [], opts.sendMessagesAs),
+            senderForTags: this.senderForTagsFrom(opts.from, opts.sendMessagesAs),
+            overrides: opts.overrides
+        });
+        const appCallOffset = await this.computeAppCallOffset(opts.from, opts.feeOptions);
+        return TxSimulationResultWithAppOffset.fromResultAndOffset(result, appCallOffset);
+    }
+    /**
+   * Computes the index where the app's calls begin in the flattened array of calls (0 = entrypoint/root, 1..N = fee
+   * calls, N+1 = app).
+   * @param from - The sender address, or NO_FROM for the default entrypoint.
+   * @param feeOptions - Fee options containing the wallet fee payment method.
+   */ async computeAppCallOffset(from, feeOptions) {
+        if (from === NO_FROM) {
+            return 0;
+        }
+        const feeExecutionPayload = await feeOptions.walletFeePaymentMethod?.getExecutionPayload();
+        return (feeExecutionPayload?.calls.length ?? 0) + 1; // +1 for entrypoint
+    }
+    /**
+   * Simulates a transaction, optimizing leading public static calls by running them directly
+   * on the node while sending the remaining calls through the standard PXE path.
+   * Return values from both paths are merged back in original call order.
+   * @param executionPayload - The execution payload to simulate.
+   * @param opts - Simulation options (from address, fee settings, etc.).
+   * @returns The merged simulation result.
+   */ async simulateTx(executionPayload, opts) {
+        const feeOptions = await this.completeFeeOptions({
+            from: opts.from,
+            feePayer: executionPayload.feePayer,
+            gasSettings: opts.fee?.gasSettings,
+            forEstimation: true,
+            congestionEstimate: opts.fee?.congestionEstimate
+        });
+        const { optimizableCalls, remainingCalls } = extractOptimizablePublicStaticCalls(executionPayload);
+        const remainingPayload = {
+            ...executionPayload,
+            calls: remainingCalls
+        };
+        const chainInfo = await this.getChainInfo();
+        let blockHeader;
+        // PXE might not be synced yet, so we pull the latest header from the node
+        // To keep things consistent, we'll always try with PXE first
+        try {
+            blockHeader = await this.pxe.getSyncedBlockHeader();
+        } catch  {
+            blockHeader = (await this.aztecNode.getBlockData('latest')).header;
+        }
+        const simulationOrigin = opts.from === NO_FROM ? AztecAddress.ZERO : opts.from;
+        const [optimizedResults, normalResult] = await Promise.all([
+            optimizableCalls.length > 0 ? simulateViaNode(this.aztecNode, optimizableCalls, simulationOrigin, chainInfo, feeOptions.gasSettings, blockHeader, opts.skipFeeEnforcement ?? true, this.getContractName.bind(this), opts.overrides) : Promise.resolve([]),
+            remainingCalls.length > 0 ? this.simulateViaEntrypoint(remainingPayload, {
+                from: opts.from,
+                feeOptions,
+                additionalScopes: opts.additionalScopes,
+                skipTxValidation: opts.skipTxValidation,
+                skipFeeEnforcement: opts.skipFeeEnforcement ?? true,
+                sendMessagesAs: opts.sendMessagesAs,
+                overrides: opts.overrides
+            }) : Promise.resolve(null)
+        ]);
+        return buildMergedSimulationResult(optimizedResults, normalResult);
+    }
+    async profileTx(executionPayload, opts) {
+        const feeOptions = await this.completeFeeOptions({
+            from: opts.from,
+            feePayer: executionPayload.feePayer,
+            gasSettings: opts.fee?.gasSettings,
+            congestionEstimate: opts.fee?.congestionEstimate
+        });
+        const txRequest = await this.createTxExecutionRequestFromPayloadAndFee(executionPayload, opts.from, feeOptions);
+        return this.pxe.profileTx(txRequest, {
+            profileMode: opts.profileMode,
+            skipProofGeneration: opts.skipProofGeneration ?? true,
+            scopes: this.scopesFrom(opts.from, opts.additionalScopes ?? [], opts.sendMessagesAs),
+            senderForTags: this.senderForTagsFrom(opts.from, opts.sendMessagesAs)
+        });
+    }
+    async sendTx(executionPayload, opts) {
+        const feeOptions = await this.completeFeeOptions({
+            from: opts.from,
+            feePayer: executionPayload.feePayer,
+            gasSettings: opts.fee?.gasSettings,
+            congestionEstimate: opts.fee?.congestionEstimate
+        });
+        const txRequest = await this.createTxExecutionRequestFromPayloadAndFee(executionPayload, opts.from, feeOptions);
+        const provenTx = await this.pxe.proveTx(txRequest, {
+            scopes: this.scopesFrom(opts.from, opts.additionalScopes ?? [], opts.sendMessagesAs),
+            senderForTags: this.senderForTagsFrom(opts.from, opts.sendMessagesAs)
+        });
+        const offchainOutput = extractOffchainOutput(provenTx.getOffchainEffects(), provenTx.publicInputs.constants.anchorBlockHeader.globalVariables.timestamp);
+        const tx = await provenTx.toTx();
+        const txHash = tx.getTxHash();
+        this.log.debug(`Sending transaction ${txHash}`);
+        await this.aztecNode.sendTx(tx).catch((err)=>{
+            throw this.contextualizeError(err, inspect(tx));
+        });
+        this.log.info(`Sent transaction ${txHash}`);
+        // If wait is NO_WAIT, return txHash immediately
+        if (opts.wait === NO_WAIT) {
+            return {
+                txHash,
+                ...offchainOutput
+            };
+        }
+        // Otherwise, wait for the full receipt (default behavior on wait: undefined)
+        const callerWaitOpts = typeof opts.wait === 'object' ? opts.wait : undefined;
+        const waitOpts = this.defaultWaitInterval !== undefined && callerWaitOpts?.interval === undefined ? {
+            ...callerWaitOpts,
+            interval: this.defaultWaitInterval
+        } : callerWaitOpts;
+        // The tx was just sent, so an immediate first poll cannot find it mined; skip one poll interval up front.
+        const initialDelay = waitOpts?.initialDelay ?? waitOpts?.interval ?? DefaultWaitOpts.interval;
+        const receipt = await waitForTx(this.aztecNode, txHash, {
+            ...waitOpts,
+            initialDelay
+        });
+        // Display debug logs from public execution if present (served in test mode only)
+        if (receipt.isMined() && receipt.debugLogs?.length) {
+            await displayDebugLogs(receipt.debugLogs, this.getContractName.bind(this));
+        }
+        return {
+            receipt,
+            ...offchainOutput
+        };
+    }
+    /**
+   * Resolves a contract address to a human-readable name via PXE, if available.
+   * @param address - The contract address to resolve.
+   */ async getContractName(address) {
+        const instance = await this.pxe.getContractInstance(address);
+        if (!instance) {
+            return undefined;
+        }
+        // Contract names are class-stable (an upgrade preserves the contract name), so the original class artifact is a
+        // sufficient source for the display name without resolving the current class against the node.
+        // TODO: if a contract were to be upgraded and its original artifact never registered, then this would fail and we'd
+        // want to fallback to the current class.
+        const artifact = await this.pxe.getContractArtifact(instance.originalContractClassId);
+        return artifact?.name;
+    }
+    contextualizeError(err, ...context) {
+        let contextStr = '';
+        if (context.length > 0) {
+            contextStr = `\nContext:\n${context.join('\n')}`;
+        }
+        if (err instanceof SimulationError) {
+            err.setAztecContext(contextStr);
+        } else {
+            this.log.error(err.name, err);
+            this.log.debug(contextStr);
+        }
+        return err;
+    }
+    executeUtility(call, opts) {
+        return this.pxe.executeUtility(call, {
+            authwits: opts.authWitnesses,
+            scopes: opts.scopes
+        });
+    }
+    async getPrivateEvents(eventDef, eventFilter) {
+        const pxeEvents = await this.pxe.getPrivateEvents(eventDef.eventSelector, eventFilter);
+        const decodedEvents = pxeEvents.map((pxeEvent)=>{
+            return {
+                event: decodeFromAbi(eventDef.abiType, pxeEvent.packedEvent),
+                metadata: {
+                    l2BlockNumber: pxeEvent.l2BlockNumber,
+                    l2BlockHash: pxeEvent.l2BlockHash,
+                    txHash: pxeEvent.txHash
+                }
+            };
+        });
+        return decodedEvents;
+    }
+    /**
+   * Returns metadata about a contract, including whether it has been initialized, published, and updated.
+   * @param address - The contract address to query.
+   */ async getContractMetadata(address) {
+        const instance = await this.pxe.getContractInstance(address);
+        const publiclyRegisteredContractPromise = this.aztecNode.getContract(address);
+        let initializationStatus;
+        if (instance) {
+            // We have the instance, so we can compute the private initialization nullifier (which includes init_hash and is
+            // emitted by both private and public initializers) and get a definitive INITIALIZED/UNINITIALIZED answer.
+            const initNullifier = await computeSiloedPrivateInitializationNullifier(address, instance.initializationHash);
+            const witness = await this.aztecNode.getNullifierMembershipWitness('latest', initNullifier);
+            initializationStatus = witness ? ContractInitializationStatus.INITIALIZED : ContractInitializationStatus.UNINITIALIZED;
+        } else {
+            // Without the instance we lack the init_hash needed for the private nullifier. We fall back to checking the
+            // public initialization nullifier (computed from address alone). Not all contracts emit it (only those with
+            // public functions that require initialization checks), so its absence doesn't mean the contract is
+            // uninitialized.
+            const publicNullifier = await computeSiloedPublicInitializationNullifier(address);
+            const witness = await this.aztecNode.getNullifierMembershipWitness('latest', publicNullifier);
+            initializationStatus = witness ? ContractInitializationStatus.INITIALIZED : ContractInitializationStatus.UNKNOWN;
+        }
+        const publiclyRegisteredContract = await publiclyRegisteredContractPromise;
+        const isContractUpdated = publiclyRegisteredContract && !publiclyRegisteredContract.currentContractClassId.equals(publiclyRegisteredContract.originalContractClassId);
+        return {
+            instance: instance ?? undefined,
+            initializationStatus,
+            isContractPublished: !!publiclyRegisteredContract,
+            isContractUpdated: !!isContractUpdated,
+            updatedContractClassId: isContractUpdated ? publiclyRegisteredContract.currentContractClassId : undefined
+        };
+    }
+    async getContractClassMetadata(id) {
+        const publiclyRegisteredContractClass = await this.aztecNode.getContractClass(id);
+        return {
+            isArtifactRegistered: !!await this.pxe.getContractArtifact(id),
+            isContractClassPubliclyRegistered: !!publiclyRegisteredContractClass
+        };
+    }
+}

package/dest/base-wallet/get_gas_limits.d.ts

@@ -0,0 +1,36 @@
+import { Gas, type GasUsed } from '@aztec-labs/stdlib/gas';
+/**
+ * Returns suggested total and teardown gas limits for a simulated tx, clamped to the network's per-tx
+ * admission limits.
+ *
+ * The network only admits transactions that declare up to `maxTxGasLimits` per dimension (the
+ * node-advertised `txsLimits.gas`). Wallets pass the value read from their own node info, but since node info
+ * is remote input it is defensively clamped here to the per-tx protocol maxima so a value above them is never
+ * honored. If the simulated usage already exceeds the resulting admission limits the tx can never be included,
+ * so this throws a descriptive error instead of returning a limit the node would reject. Otherwise it pads the
+ * usage and clamps each dimension to the admission limit.
+ * @param gasUsed - The gas actually consumed during simulation.
+ * @param maxTxGasLimits - The maximum gas a single tx may declare on this network (the node-advertised `txsLimits.gas`).
+ * @param pad - Fraction to pad the suggested gas limits by (as a decimal, e.g. 0.1 for 10%). The effective
+ * padding shrinks to zero as usage approaches the network limit, since the network will not admit a higher
+ * declared limit regardless of the buffer.
+ */
+export declare function getGasLimits(gasUsed: GasUsed, maxTxGasLimits: Gas, pad?: number): {
+    /**
+     * Total gas limit for the tx, including teardown gas
+     */
+    gasLimits: Gas;
+    /**
+     * Portion of the total gas limit reserved for the teardown phase
+     */
+    teardownGasLimits: Gas;
+};
+/**
+ * Validates that caller-declared gas limits do not exceed the network's per-tx admission limits, throwing a
+ * descriptive error per dimension when they do. The node's inbound validation checks declared
+ * `gasSettings.gasLimits`, so we mirror that here to surface the rejection locally before the tx is sent.
+ * @param gasLimits - The gas limits the transaction will declare.
+ * @param maxTxGasLimits - The maximum gas a single tx may declare on this network (the node-advertised `txsLimits.gas`).
+ */
+export declare function assertGasLimitsWithinNetworkLimits(gasLimits: Gas, maxTxGasLimits: Gas): void;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZ2V0X2dhc19saW1pdHMuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9iYXNlLXdhbGxldC9nZXRfZ2FzX2xpbWl0cy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFDQSxPQUFPLEVBQUUsR0FBRyxFQUFFLEtBQUssT0FBTyxFQUFFLE1BQU0sd0JBQXdCLENBQUM7QUFFM0Q7Ozs7Ozs7Ozs7Ozs7OztHQWVHO0FBQ0gsd0JBQWdCLFlBQVksQ0FDMUIsT0FBTyxFQUFFLE9BQU8sRUFDaEIsY0FBYyxFQUFFLEdBQUcsRUFDbkIsR0FBRyxTQUFNLEdBQ1I7SUFDRDs7T0FFRztJQUNILFNBQVMsRUFBRSxHQUFHLENBQUM7SUFDZjs7T0FFRztJQUNILGlCQUFpQixFQUFFLEdBQUcsQ0FBQztDQUN4QixDQTZCQTtBQVFEOzs7Ozs7R0FNRztBQUNILHdCQUFnQixrQ0FBa0MsQ0FBQyxTQUFTLEVBQUUsR0FBRyxFQUFFLGNBQWMsRUFBRSxHQUFHLEdBQUcsSUFBSSxDQVc1RiJ9

package/dest/base-wallet/get_gas_limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get_gas_limits.d.ts","sourceRoot":"","sources":["../../src/base-wallet/get_gas_limits.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAE,KAAK,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAE3D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,OAAO,EAChB,cAAc,EAAE,GAAG,EACnB,GAAG,SAAM,GACR;IACD;;OAEG;IACH,SAAS,EAAE,GAAG,CAAC;IACf;;OAEG;IACH,iBAAiB,EAAE,GAAG,CAAC;CACxB,CA6BA;AAQD;;;;;;GAMG;AACH,wBAAgB,kCAAkC,CAAC,SAAS,EAAE,GAAG,EAAE,cAAc,EAAE,GAAG,GAAG,IAAI,CAW5F"}

package/dest/base-wallet/get_gas_limits.js

@@ -0,0 +1,55 @@
+import { MAX_PROCESSABLE_L2_GAS, MAX_TX_DA_GAS } from '@aztec-labs/constants';
+import { Gas } from '@aztec-labs/stdlib/gas';
+/**
+ * Returns suggested total and teardown gas limits for a simulated tx, clamped to the network's per-tx
+ * admission limits.
+ *
+ * The network only admits transactions that declare up to `maxTxGasLimits` per dimension (the
+ * node-advertised `txsLimits.gas`). Wallets pass the value read from their own node info, but since node info
+ * is remote input it is defensively clamped here to the per-tx protocol maxima so a value above them is never
+ * honored. If the simulated usage already exceeds the resulting admission limits the tx can never be included,
+ * so this throws a descriptive error instead of returning a limit the node would reject. Otherwise it pads the
+ * usage and clamps each dimension to the admission limit.
+ * @param gasUsed - The gas actually consumed during simulation.
+ * @param maxTxGasLimits - The maximum gas a single tx may declare on this network (the node-advertised `txsLimits.gas`).
+ * @param pad - Fraction to pad the suggested gas limits by (as a decimal, e.g. 0.1 for 10%). The effective
+ * padding shrinks to zero as usage approaches the network limit, since the network will not admit a higher
+ * declared limit regardless of the buffer.
+ */ export function getGasLimits(gasUsed, maxTxGasLimits, pad = 0.1) {
+    const { totalGas, teardownGas } = gasUsed;
+    // `maxTxGasLimits` is the node-advertised admission limit. Node info is remote input, so we defensively
+    // clamp to the per-tx protocol maxima so a value above them can never be honored.
+    const maxLimits = new Gas(Math.min(maxTxGasLimits.daGas, MAX_TX_DA_GAS), Math.min(maxTxGasLimits.l2Gas, MAX_PROCESSABLE_L2_GAS));
+    // The simulated usage must fit within the admission limits, otherwise the tx can never be included.
+    if (totalGas.daGas > maxLimits.daGas) {
+        throw new Error(`Transaction consumes ${totalGas.daGas} DA gas but the network only admits transactions declaring up to ${maxLimits.daGas} DA gas`);
+    }
+    if (totalGas.l2Gas > maxLimits.l2Gas) {
+        throw new Error(`Transaction consumes ${totalGas.l2Gas} L2 gas but the network only admits transactions declaring up to ${maxLimits.l2Gas} L2 gas`);
+    }
+    // Pad the limits by the buffer, then cap each dimension at the admission limit so the buffer cannot push a
+    // declared limit past what inbound validation accepts. Teardown is part of the total, so clamping it to the
+    // admission limit is safe.
+    return {
+        gasLimits: padGas(totalGas, pad, maxLimits),
+        teardownGasLimits: padGas(teardownGas, pad, maxLimits)
+    };
+}
+/** Pads each gas dimension, capping it at the network admission limit. */ function padGas(gas, pad, cap) {
+    const padded = gas.mul(1 + pad);
+    return new Gas(Math.min(padded.daGas, cap.daGas), Math.min(padded.l2Gas, cap.l2Gas));
+}
+/**
+ * Validates that caller-declared gas limits do not exceed the network's per-tx admission limits, throwing a
+ * descriptive error per dimension when they do. The node's inbound validation checks declared
+ * `gasSettings.gasLimits`, so we mirror that here to surface the rejection locally before the tx is sent.
+ * @param gasLimits - The gas limits the transaction will declare.
+ * @param maxTxGasLimits - The maximum gas a single tx may declare on this network (the node-advertised `txsLimits.gas`).
+ */ export function assertGasLimitsWithinNetworkLimits(gasLimits, maxTxGasLimits) {
+    if (gasLimits.daGas > maxTxGasLimits.daGas) {
+        throw new Error(`Declared DA gas limit (${gasLimits.daGas}) exceeds the maximum this network allows per tx (${maxTxGasLimits.daGas})`);
+    }
+    if (gasLimits.l2Gas > maxTxGasLimits.l2Gas) {
+        throw new Error(`Declared L2 gas limit (${gasLimits.l2Gas}) exceeds the maximum this network allows per tx (${maxTxGasLimits.l2Gas})`);
+    }
+}

package/dest/base-wallet/index.d.ts

@@ -0,0 +1,4 @@
+export { BaseWallet, type CompleteFeeOptionsConfig, type FeeOptions, type SimulateViaEntrypointOptions, } from './base_wallet.js';
+export { simulateViaNode, buildMergedSimulationResult, extractOptimizablePublicStaticCalls } from './utils.js';
+export { getGasLimits, assertGasLimitsWithinNetworkLimits } from './get_gas_limits.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9iYXNlLXdhbGxldC9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQ0wsVUFBVSxFQUNWLEtBQUssd0JBQXdCLEVBQzdCLEtBQUssVUFBVSxFQUNmLEtBQUssNEJBQTRCLEdBQ2xDLE1BQU0sa0JBQWtCLENBQUM7QUFDMUIsT0FBTyxFQUFFLGVBQWUsRUFBRSwyQkFBMkIsRUFBRSxtQ0FBbUMsRUFBRSxNQUFNLFlBQVksQ0FBQztBQUMvRyxPQUFPLEVBQUUsWUFBWSxFQUFFLGtDQUFrQyxFQUFFLE1BQU0scUJBQXFCLENBQUMifQ==

package/dest/base-wallet/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/base-wallet/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,KAAK,wBAAwB,EAC7B,KAAK,UAAU,EACf,KAAK,4BAA4B,GAClC,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,2BAA2B,EAAE,mCAAmC,EAAE,MAAM,YAAY,CAAC;AAC/G,OAAO,EAAE,YAAY,EAAE,kCAAkC,EAAE,MAAM,qBAAqB,CAAC"}

package/dest/base-wallet/index.js

@@ -0,0 +1,3 @@
+export { BaseWallet } from './base_wallet.js';
+export { simulateViaNode, buildMergedSimulationResult, extractOptimizablePublicStaticCalls } from './utils.js';
+export { getGasLimits, assertGasLimitsWithinNetworkLimits } from './get_gas_limits.js';