@aztec/aztec 0.0.1-commit.f2ce05ee → 0.0.1-commit.f5a9928

package/dest/deploy/bridging.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Fee-juice bridging for the `fee-juice` deploy policy: bridge Fee Juice from L1
+ * ({@link bridgeFeeJuice}) and wait for the L1→L2 message to become available
+ * ({@link waitForL1ToL2Message}). Fee Juice only — this is not a generic L1→L2 asset bridge.
+ * Node-only (pulls in `@aztec/aztec.js/ethereum` + viem).
+ *
+ * Nothing here sends the L2 claim tx — the caller feeds the returned claim into
+ * `FeeJuicePaymentMethodWithClaim` so the claim lands inside whatever tx the recipient is already
+ * sending.
+ */
+import type { AztecAddress } from '@aztec/aztec.js/addresses';
+import { L1FeeJuicePortalManager } from '@aztec/aztec.js/ethereum';
+import type { AztecNode } from '@aztec/aztec.js/node';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import type { Hex } from 'viem';
+/** Local vs. remote L1→L2 message advancement: warp cheats time forward, poll just waits. */
+export type BridgeTimingMode = 'warp' | 'poll';
+/** The claim produced by bridging: exactly the shape `FeeJuicePaymentMethodWithClaim` expects. */
+export type FeeJuiceClaim = Awaited<ReturnType<L1FeeJuicePortalManager['bridgeTokensPublic']>>;
+/**
+ * Decides how the L1 signer funds a bridge: mint from the fee-asset faucet handler, or transfer
+ * its existing Fee Juice. Pure — exercised directly by unit tests.
+ *
+ * - Balance covers the requested amount → transfer it (no mint, even when a faucet exists).
+ * - Balance short of the amount + faucet available → mint (the faucet path bridges the handler's
+ *   own mint amount and ignores `amount`).
+ * - Balance short + no faucet → throw, reporting the shortfall.
+ * - No `amount` requested → the faucet is required (there is nothing to size a transfer by).
+ */
+export declare function pickBridgeRoute(opts: {
+    hasFaucet: boolean;
+    l1Balance: bigint;
+    amount?: bigint;
+}): {
+    useFaucet: boolean;
+    amount?: bigint;
+};
+export interface BridgeFeeJuiceParams {
+    node: AztecNode;
+    l1RpcUrl: string;
+    l1ChainId: number;
+    recipient: AztecAddress;
+    /** Desired amount in wei. Optional only when a faucet exists (whose `mintAmount()` then wins). */
+    amount?: bigint;
+    /** L1 private key signing the bridge tx. When omitted, a fresh ephemeral key is generated. */
+    l1PrivateKey?: Hex;
+}
+/**
+ * Bridges fee juice to an L2 recipient, minting from the faucet handler or transferring the
+ * signer's balance per {@link pickBridgeRoute}. Returns the claim; the L1→L2 message it references
+ * becomes available later — see {@link waitForL1ToL2Message}.
+ */
+export declare function bridgeFeeJuice(params: BridgeFeeJuiceParams): Promise<FeeJuiceClaim>;
+export interface WaitForClaimParams {
+    node: AztecNode;
+    messageHash: Fr;
+    /**
+     * On `warp` (local) we cheat L1+L2 time forward via the node debug API until the message shows as
+     * available; on `poll` (every other network) we just check periodically.
+     */
+    mode: BridgeTimingMode;
+    /** Timeout before giving up (default 30 min for poll, 2 min for warp). */
+    timeoutMs?: number;
+    /** Warp-only: options for reaching the node's debug API. */
+    warpOpts?: {
+        nodeUrl?: string;
+    };
+}
+/** Waits until an L1→L2 message is available on the node (warping time forward in `warp` mode). */
+export declare function waitForL1ToL2Message(params: WaitForClaimParams): Promise<void>;
+/**
+ * Local-network helper: advances L1 + L2 time via the node debug API until the given L1→L2 message
+ * shows up as available, warping by one L2 slot (read from the node's rollup constants) per check.
+ * An in-process node (e.g. a test fixture's `AztecNodeService`) implements the debug interface
+ * directly; a remote node is reached via its debug RPC at `nodeUrl` — `warpL2TimeAtLeastBy` needs
+ * `AztecNode & AztecNodeDebug` (it reads the current L1 timestamp via the regular API before
+ * warping), and both clients target the same URL and expose their methods as own properties on the
+ * rpc proxy, so a shallow merge is safe.
+ */
+export declare function warpToL1ToL2Message(node: AztecNode, messageHash: Fr, opts?: {
+    nodeUrl?: string;
+    timeoutMs?: number;
+}): Promise<void>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYnJpZGdpbmcuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9kZXBsb3kvYnJpZGdpbmcudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7Ozs7OztHQVNHO0FBQ0gsT0FBTyxLQUFLLEVBQUUsWUFBWSxFQUFFLE1BQU0sMkJBQTJCLENBQUM7QUFDOUQsT0FBTyxFQUFFLHVCQUF1QixFQUFFLE1BQU0sMEJBQTBCLENBQUM7QUFFbkUsT0FBTyxLQUFLLEVBQUUsU0FBUyxFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFHdEQsT0FBTyxFQUFFLEVBQUUsRUFBRSxNQUFNLGdDQUFnQyxDQUFDO0FBS3BELE9BQU8sS0FBSyxFQUFFLEdBQUcsRUFBRSxNQUFNLE1BQU0sQ0FBQztBQVloQywrRkFBNkY7QUFDN0YsTUFBTSxNQUFNLGdCQUFnQixHQUFHLE1BQU0sR0FBRyxNQUFNLENBQUM7QUFFL0Msa0dBQWtHO0FBQ2xHLE1BQU0sTUFBTSxhQUFhLEdBQUcsT0FBTyxDQUFDLFVBQVUsQ0FBQyx1QkFBdUIsQ0FBQyxvQkFBb0IsQ0FBQyxDQUFDLENBQUMsQ0FBQztBQUUvRjs7Ozs7Ozs7O0dBU0c7QUFDSCx3QkFBZ0IsZUFBZSxDQUFDLElBQUksRUFBRTtJQUFFLFNBQVMsRUFBRSxPQUFPLENBQUM7SUFBQyxTQUFTLEVBQUUsTUFBTSxDQUFDO0lBQUMsTUFBTSxDQUFDLEVBQUUsTUFBTSxDQUFBO0NBQUUsR0FBRztJQUNqRyxTQUFTLEVBQUUsT0FBTyxDQUFDO0lBQ25CLE1BQU0sQ0FBQyxFQUFFLE1BQU0sQ0FBQztDQUNqQixDQWtCQTtBQUVELE1BQU0sV0FBVyxvQkFBb0I7SUFDbkMsSUFBSSxFQUFFLFNBQVMsQ0FBQztJQUNoQixRQUFRLEVBQUUsTUFBTSxDQUFDO0lBQ2pCLFNBQVMsRUFBRSxNQUFNLENBQUM7SUFDbEIsU0FBUyxFQUFFLFlBQVksQ0FBQztJQUN4QixrR0FBa0c7SUFDbEcsTUFBTSxDQUFDLEVBQUUsTUFBTSxDQUFDO0lBQ2hCLDhGQUE4RjtJQUM5RixZQUFZLENBQUMsRUFBRSxHQUFHLENBQUM7Q0FDcEI7QUFFRDs7OztHQUlHO0FBQ0gsd0JBQXNCLGNBQWMsQ0FBQyxNQUFNLEVBQUUsb0JBQW9CLEdBQUcsT0FBTyxDQUFDLGFBQWEsQ0FBQyxDQWV6RjtBQUVELE1BQU0sV0FBVyxrQkFBa0I7SUFDakMsSUFBSSxFQUFFLFNBQVMsQ0FBQztJQUNoQixXQUFXLEVBQUUsRUFBRSxDQUFDO0lBQ2hCOzs7T0FHRztJQUNILElBQUksRUFBRSxnQkFBZ0IsQ0FBQztJQUN2QiwwRUFBMEU7SUFDMUUsU0FBUyxDQUFDLEVBQUUsTUFBTSxDQUFDO0lBQ25CLDREQUE0RDtJQUM1RCxRQUFRLENBQUMsRUFBRTtRQUFFLE9BQU8sQ0FBQyxFQUFFLE1BQU0sQ0FBQTtLQUFFLENBQUM7Q0FDakM7QUFFRCxxR0FBbUc7QUFDbkcsd0JBQXNCLG9CQUFvQixDQUFDLE1BQU0sRUFBRSxrQkFBa0IsR0FBRyxPQUFPLENBQUMsSUFBSSxDQUFDLENBaUNwRjtBQUVEOzs7Ozs7OztHQVFHO0FBQ0gsd0JBQXNCLG1CQUFtQixDQUN2QyxJQUFJLEVBQUUsU0FBUyxFQUNmLFdBQVcsRUFBRSxFQUFFLEVBQ2YsSUFBSSxHQUFFO0lBQUUsT0FBTyxDQUFDLEVBQUUsTUFBTSxDQUFDO0lBQUMsU0FBUyxDQUFDLEVBQUUsTUFBTSxDQUFBO0NBQU8sR0FDbEQsT0FBTyxDQUFDLElBQUksQ0FBQyxDQXNCZiJ9

package/dest/deploy/bridging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridging.d.ts","sourceRoot":"","sources":["../../src/deploy/bridging.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAGtD,OAAO,EAAE,EAAE,EAAE,MAAM,gCAAgC,CAAC;AAKpD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAYhC,+FAA6F;AAC7F,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,CAAC;AAE/C,kGAAkG;AAClG,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,uBAAuB,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC;AAE/F;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IACjG,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAkBA;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,YAAY,CAAC;IACxB,kGAAkG;IAClG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8FAA8F;IAC9F,YAAY,CAAC,EAAE,GAAG,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC,CAezF;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW,EAAE,EAAE,CAAC;IAChB;;;OAGG;IACH,IAAI,EAAE,gBAAgB,CAAC;IACvB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACjC;AAED,qGAAmG;AACnG,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiCpF;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,SAAS,EACf,WAAW,EAAE,EAAE,EACf,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAClD,OAAO,CAAC,IAAI,CAAC,CAsBf"}

package/dest/deploy/bridging.js

@@ -0,0 +1,121 @@
+/**
+ * Fee-juice bridging for the `fee-juice` deploy policy: bridge Fee Juice from L1
+ * ({@link bridgeFeeJuice}) and wait for the L1→L2 message to become available
+ * ({@link waitForL1ToL2Message}). Fee Juice only — this is not a generic L1→L2 asset bridge.
+ * Node-only (pulls in `@aztec/aztec.js/ethereum` + viem).
+ *
+ * Nothing here sends the L2 claim tx — the caller feeds the returned claim into
+ * `FeeJuicePaymentMethodWithClaim` so the claim lands inside whatever tx the recipient is already
+ * sending.
+ */ import { L1FeeJuicePortalManager } from '@aztec/aztec.js/ethereum';
+import { isL1ToL2MessageReady } from '@aztec/aztec.js/messaging';
+import { createEthereumChain } from '@aztec/ethereum/chain';
+import { createExtendedL1Client } from '@aztec/ethereum/client';
+import { createLogger } from '@aztec/foundation/log';
+import { retryUntil } from '@aztec/foundation/retry';
+import { createAztecNodeDebugClient } from '@aztec/stdlib/interfaces/client';
+import { generatePrivateKey } from 'viem/accounts';
+const logger = createLogger('deploy:bridging');
+/** Wait between availability checks in `warp` mode — each iteration also warps the clock forward. */ const WARP_POLL_INTERVAL_MS = 1000;
+/** Wait between availability checks in `poll` mode (a real network; nothing to do but wait). */ const POLL_INTERVAL_MS = 5_000;
+/** Throttle for the "still waiting" progress log in the poll loop. */ const POLL_LOG_INTERVAL_MS = 30_000;
+/**
+ * Decides how the L1 signer funds a bridge: mint from the fee-asset faucet handler, or transfer
+ * its existing Fee Juice. Pure — exercised directly by unit tests.
+ *
+ * - Balance covers the requested amount → transfer it (no mint, even when a faucet exists).
+ * - Balance short of the amount + faucet available → mint (the faucet path bridges the handler's
+ *   own mint amount and ignores `amount`).
+ * - Balance short + no faucet → throw, reporting the shortfall.
+ * - No `amount` requested → the faucet is required (there is nothing to size a transfer by).
+ */ export function pickBridgeRoute(opts) {
+    const { hasFaucet, l1Balance, amount } = opts;
+    if (amount === undefined) {
+        if (!hasFaucet) {
+            throw new Error('bridgeFeeJuice: `amount` is required when no fee-asset faucet is available.');
+        }
+        return {
+            useFaucet: true
+        };
+    }
+    if (l1Balance >= amount) {
+        return {
+            useFaucet: false,
+            amount
+        };
+    }
+    if (hasFaucet) {
+        return {
+            useFaucet: true
+        };
+    }
+    throw new Error(`L1 signer holds ${l1Balance} wei of Fee Juice but ${amount} was requested, and no fee-asset faucet is ` + `available to mint the difference.`);
+}
+/**
+ * Bridges fee juice to an L2 recipient, minting from the faucet handler or transferring the
+ * signer's balance per {@link pickBridgeRoute}. Returns the claim; the L1→L2 message it references
+ * becomes available later — see {@link waitForL1ToL2Message}.
+ */ export async function bridgeFeeJuice(params) {
+    const { node, l1RpcUrl, l1ChainId, recipient } = params;
+    const l1PrivateKey = params.l1PrivateKey ?? generatePrivateKey();
+    const chain = createEthereumChain([
+        l1RpcUrl
+    ], l1ChainId);
+    const l1Client = createExtendedL1Client(chain.rpcUrls, l1PrivateKey, chain.chainInfo);
+    const portalManager = await L1FeeJuicePortalManager.new(node, l1Client, logger);
+    const tokenManager = portalManager.getTokenManager();
+    const route = pickBridgeRoute({
+        hasFaucet: tokenManager.handlerAddress !== undefined,
+        l1Balance: await tokenManager.getL1TokenBalance(l1Client.account.address),
+        amount: params.amount
+    });
+    return await portalManager.bridgeTokensPublic(recipient, route.amount, route.useFaucet);
+}
+/** Waits until an L1→L2 message is available on the node (warping time forward in `warp` mode). */ export async function waitForL1ToL2Message(params) {
+    const { node, messageHash, mode } = params;
+    if (mode === 'warp') {
+        await warpToL1ToL2Message(node, messageHash, {
+            ...params.warpOpts,
+            timeoutMs: params.timeoutMs ?? 120_000
+        });
+        return;
+    }
+    const timeoutMs = params.timeoutMs ?? 30 * 60_000;
+    const startedAt = Date.now();
+    let lastLog = startedAt;
+    await retryUntil(async ()=>{
+        if (await isL1ToL2MessageReady(node, messageHash)) {
+            return true;
+        }
+        if (Date.now() - lastLog > POLL_LOG_INTERVAL_MS) {
+            lastLog = Date.now();
+            logger.info('Still waiting for L1→L2 message to become available', {
+                messageHash: messageHash.toString(),
+                elapsedMs: Date.now() - startedAt,
+                timeoutMs
+            });
+        }
+        return undefined;
+    }, `L1→L2 message ${messageHash.toString()}`, timeoutMs / 1000, POLL_INTERVAL_MS / 1000);
+}
+/**
+ * Local-network helper: advances L1 + L2 time via the node debug API until the given L1→L2 message
+ * shows up as available, warping by one L2 slot (read from the node's rollup constants) per check.
+ * An in-process node (e.g. a test fixture's `AztecNodeService`) implements the debug interface
+ * directly; a remote node is reached via its debug RPC at `nodeUrl` — `warpL2TimeAtLeastBy` needs
+ * `AztecNode & AztecNodeDebug` (it reads the current L1 timestamp via the regular API before
+ * warping), and both clients target the same URL and expose their methods as own properties on the
+ * rpc proxy, so a shallow merge is safe.
+ */ export async function warpToL1ToL2Message(node, messageHash, opts = {}) {
+    const nodeUrl = opts.nodeUrl ?? 'http://localhost:8080';
+    const timeoutMs = opts.timeoutMs ?? 120_000;
+    const fullNode = typeof node.warpL2TimeAtLeastBy === 'function' ? node : Object.assign({}, node, createAztecNodeDebugClient(nodeUrl));
+    const { slotDuration } = await node.getL1Constants();
+    await retryUntil(async ()=>{
+        if (await isL1ToL2MessageReady(node, messageHash)) {
+            return true;
+        }
+        await fullNode.warpL2TimeAtLeastBy(slotDuration);
+        return undefined;
+    }, `L1→L2 message ${messageHash.toString()} (warping)`, timeoutMs / 1000, WARP_POLL_INTERVAL_MS / 1000);
+}

package/dest/deploy/fees.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Fee handling for the deploy framework. Each account pays per its own {@link FeePolicy} — which
+ * may override the spec-wide default:
+ *
+ * - `sponsored`  → a SponsoredFPC pays (the local-network default). All sponsored accounts share
+ *   one payment method.
+ * - `fee-juice`  → the account pays from its own Fee Juice; if below `threshold` with work to do,
+ *   bridge `fundAmount` from L1. The bridge claim is single-use: the first paying tx claims it
+ *   (`FeeJuicePaymentMethodWithClaim`) and the rest spend the balance. Pending claims are persisted
+ *   (see ./state.ts) so a crash between bridge and claim resumes.
+ */
+import type { AztecAddress } from '@aztec/aztec.js/addresses';
+import { type FeePaymentMethod } from '@aztec/aztec.js/fee';
+import { Fr } from '@aztec/aztec.js/fields';
+import type { AztecNode } from '@aztec/aztec.js/node';
+import type { Wallet } from '@aztec/aztec.js/wallet';
+import type { GasFees } from '@aztec/stdlib/gas';
+import type { Hex } from 'viem';
+import type { AccountFunding, DeployReporter } from './reporter.js';
+import type { DeployState } from './state.js';
+import type { FeePolicy } from './types.js';
+/** The `fee` field of a send-options object. */
+export interface SendFee {
+    paymentMethod?: FeePaymentMethod;
+    gasSettings?: {
+        maxFeesPerGas: GasFees;
+    };
+}
+/**
+ * Sane fee defaults: local pays via SponsoredFPC; every other network pays from bridged Fee Juice.
+ * The threshold/fundAmount pair trades off L1 round-trips (too low → frequent re-bridges) against
+ * stranding Fee Juice, which is non-transferable, on the account (too high).
+ */
+export declare function defaultFeePolicy(local: boolean): FeePolicy;
+/** The public Fee Juice balance of `address` (any address — contract or account), read via `from`. */
+export declare function publicFeeJuiceBalance(wallet: Wallet, address: AztecAddress, from: AztecAddress): Promise<bigint>;
+/**
+ * Resolves an account's funding posture under `policy` — what the plan reports and what
+ * {@link prepareFeeSession} acts on. `idle` accounts (no pending work) are never funded; sponsored
+ * accounts never read a balance; fee-juice accounts are `funded` iff their balance clears the
+ * threshold, else `not-funded` (a bridge will top them up).
+ */
+export declare function accountFunding(policy: FeePolicy, wallet: Wallet, account: AztecAddress, hasWork: boolean): Promise<AccountFunding>;
+/** What {@link obtainFeeJuiceClaim} needs to produce a consumable claim for a recipient. */
+export interface ObtainFeeJuiceClaimOpts {
+    /** Whether the target is a local (anvil) network — drives warp-vs-poll + L1 defaults. */
+    local: boolean;
+    node: AztecNode;
+    /** The node's URL — reaches its debug API for local time-warping while the bridge settles. */
+    nodeUrl?: string;
+    recipient: AztecAddress;
+    /** Amount to bridge (wei). */
+    amount: bigint;
+    /** L1 connection + funder, defaulted per {@link resolveL1Config}. */
+    l1: {
+        l1FunderKey?: Hex;
+        l1RpcUrl?: string;
+        l1ChainId?: number;
+    };
+    state: DeployState;
+    persist: () => void;
+    reporter: DeployReporter;
+}
+/**
+ * A single-use Fee Juice claim for `recipient` (used by `fund` steps): resumes the persisted claim
+ * when present, else bridges `amount` from L1 and waits for the L1→L2 message. The claim persists
+ * before the wait, so a crash mid-wait resumes it instead of stranding the bridged funds. The
+ * caller consumes it (e.g. via `FeeJuice.claim`) and calls `onConsumed` once that tx mines.
+ */
+export declare function obtainFeeJuiceClaim(opts: ObtainFeeJuiceClaimOpts): Promise<{
+    claimAmount: bigint;
+    claimSecret: Fr;
+    messageLeafIndex: bigint;
+    /** Drops the persisted resume entry — call once the consuming tx mines. */
+    onConsumed: () => void;
+}>;
+/** Per-account fee dispensing for one run, prepared by {@link prepareFeeSession}. */
+export interface FeeSession {
+    /**
+     * Fee options for the next tx from `account`, plus `onConsumed` to call after it lands (clears a
+     * one-time bridge claim from persisted state). Subsequent calls pay from balance.
+     */
+    next(account: AztecAddress): {
+        fee: SendFee;
+        onConsumed: () => void;
+    };
+    /**
+     * Whether `account`'s next tx will carry its one-time bridge claim. The runner serializes such an
+     * account's first tx: the claim must mine before its balance-paying txs fan out.
+     */
+    hasPendingClaim(account: AztecAddress): boolean;
+}
+/** What {@link prepareFeeSession} needs to fund a run's working accounts. */
+export interface PrepareFeeSessionOpts {
+    /** Whether the target is a local (anvil) network — drives warp-vs-poll + L1 defaults. */
+    local: boolean;
+    node: AztecNode;
+    /** The node's URL — reaches its debug API for local time-warping while a bridge settles. */
+    nodeUrl?: string;
+    wallet: Wallet;
+    /**
+     * Working accounts (those with pending work) with their resolved {@link FeePolicy} + funding (from
+     * {@link accountFunding}) — so this function doesn't re-read balances.
+     */
+    accounts: {
+        address: AztecAddress;
+        policy: FeePolicy;
+        funding: AccountFunding;
+    }[];
+    state: DeployState;
+    persist: () => void;
+    reporter: DeployReporter;
+}
+/**
+ * Resolves fees ahead of execution, per account: registers the shared SponsoredFPC (for sponsored
+ * accounts), or tops up a fee-juice account via a bridge (reusing a persisted pending claim when
+ * present). Returns a {@link FeeSession} that dispenses the right fee per tx, by sending account.
+ */
+export declare function prepareFeeSession(opts: PrepareFeeSessionOpts): Promise<FeeSession>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZmVlcy5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2RlcGxveS9mZWVzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7Ozs7O0dBVUc7QUFDSCxPQUFPLEtBQUssRUFBRSxZQUFZLEVBQUUsTUFBTSwyQkFBMkIsQ0FBQztBQUM5RCxPQUFPLEVBQWtDLEtBQUssZ0JBQWdCLEVBQTZCLE1BQU0scUJBQXFCLENBQUM7QUFDdkgsT0FBTyxFQUFFLEVBQUUsRUFBRSxNQUFNLHdCQUF3QixDQUFDO0FBQzVDLE9BQU8sS0FBSyxFQUFFLFNBQVMsRUFBRSxNQUFNLHNCQUFzQixDQUFDO0FBRXRELE9BQU8sS0FBSyxFQUFFLE1BQU0sRUFBRSxNQUFNLHdCQUF3QixDQUFDO0FBQ3JELE9BQU8sS0FBSyxFQUFFLE9BQU8sRUFBRSxNQUFNLG1CQUFtQixDQUFDO0FBRWpELE9BQU8sS0FBSyxFQUFFLEdBQUcsRUFBRSxNQUFNLE1BQU0sQ0FBQztBQUloQyxPQUFPLEtBQUssRUFBRSxjQUFjLEVBQUUsY0FBYyxFQUFFLE1BQU0sZUFBZSxDQUFDO0FBQ3BFLE9BQU8sS0FBSyxFQUFFLFdBQVcsRUFBRSxNQUFNLFlBQVksQ0FBQztBQUM5QyxPQUFPLEtBQUssRUFBRSxTQUFTLEVBQUUsTUFBTSxZQUFZLENBQUM7QUFPNUMsZ0RBQWdEO0FBQ2hELE1BQU0sV0FBVyxPQUFPO0lBQ3RCLGFBQWEsQ0FBQyxFQUFFLGdCQUFnQixDQUFDO0lBQ2pDLFdBQVcsQ0FBQyxFQUFFO1FBQUUsYUFBYSxFQUFFLE9BQU8sQ0FBQTtLQUFFLENBQUM7Q0FDMUM7QUFFRDs7OztHQUlHO0FBQ0gsd0JBQWdCLGdCQUFnQixDQUFDLEtBQUssRUFBRSxPQUFPLEdBQUcsU0FBUyxDQVMxRDtBQUVELHdHQUFzRztBQUN0Ryx3QkFBc0IscUJBQXFCLENBQ3pDLE1BQU0sRUFBRSxNQUFNLEVBQ2QsT0FBTyxFQUFFLFlBQVksRUFDckIsSUFBSSxFQUFFLFlBQVksR0FDakIsT0FBTyxDQUFDLE1BQU0sQ0FBQyxDQUdqQjtBQUVEOzs7OztHQUtHO0FBQ0gsd0JBQXNCLGNBQWMsQ0FDbEMsTUFBTSxFQUFFLFNBQVMsRUFDakIsTUFBTSxFQUFFLE1BQU0sRUFDZCxPQUFPLEVBQUUsWUFBWSxFQUNyQixPQUFPLEVBQUUsT0FBTyxHQUNmLE9BQU8sQ0FBQyxjQUFjLENBQUMsQ0FXekI7QUFvQkQsNEZBQTRGO0FBQzVGLE1BQU0sV0FBVyx1QkFBdUI7SUFDdEMsMkZBQXlGO0lBQ3pGLEtBQUssRUFBRSxPQUFPLENBQUM7SUFDZixJQUFJLEVBQUUsU0FBUyxDQUFDO0lBQ2hCLGdHQUE4RjtJQUM5RixPQUFPLENBQUMsRUFBRSxNQUFNLENBQUM7SUFDakIsU0FBUyxFQUFFLFlBQVksQ0FBQztJQUN4Qiw4QkFBOEI7SUFDOUIsTUFBTSxFQUFFLE1BQU0sQ0FBQztJQUNmLHFFQUFxRTtJQUNyRSxFQUFFLEVBQUU7UUFBRSxXQUFXLENBQUMsRUFBRSxHQUFHLENBQUM7UUFBQyxRQUFRLENBQUMsRUFBRSxNQUFNLENBQUM7UUFBQyxTQUFTLENBQUMsRUFBRSxNQUFNLENBQUE7S0FBRSxDQUFDO0lBQ2pFLEtBQUssRUFBRSxXQUFXLENBQUM7SUFDbkIsT0FBTyxFQUFFLE1BQU0sSUFBSSxDQUFDO0lBQ3BCLFFBQVEsRUFBRSxjQUFjLENBQUM7Q0FDMUI7QUFFRDs7Ozs7R0FLRztBQUNILHdCQUFzQixtQkFBbUIsQ0FBQyxJQUFJLEVBQUUsdUJBQXVCLEdBQUcsT0FBTyxDQUFDO0lBQ2hGLFdBQVcsRUFBRSxNQUFNLENBQUM7SUFDcEIsV0FBVyxFQUFFLEVBQUUsQ0FBQztJQUNoQixnQkFBZ0IsRUFBRSxNQUFNLENBQUM7SUFDekIsNkVBQTJFO0lBQzNFLFVBQVUsRUFBRSxNQUFNLElBQUksQ0FBQztDQUN4QixDQUFDLENBMENEO0FBRUQscUZBQXFGO0FBQ3JGLE1BQU0sV0FBVyxVQUFVO0lBQ3pCOzs7T0FHRztJQUNILElBQUksQ0FBQyxPQUFPLEVBQUUsWUFBWSxHQUFHO1FBQUUsR0FBRyxFQUFFLE9BQU8sQ0FBQztRQUFDLFVBQVUsRUFBRSxNQUFNLElBQUksQ0FBQTtLQUFFLENBQUM7SUFDdEU7OztPQUdHO0lBQ0gsZUFBZSxDQUFDLE9BQU8sRUFBRSxZQUFZLEdBQUcsT0FBTyxDQUFDO0NBQ2pEO0FBRUQsNkVBQTZFO0FBQzdFLE1BQU0sV0FBVyxxQkFBcUI7SUFDcEMsMkZBQXlGO0lBQ3pGLEtBQUssRUFBRSxPQUFPLENBQUM7SUFDZixJQUFJLEVBQUUsU0FBUyxDQUFDO0lBQ2hCLDhGQUE0RjtJQUM1RixPQUFPLENBQUMsRUFBRSxNQUFNLENBQUM7SUFDakIsTUFBTSxFQUFFLE1BQU0sQ0FBQztJQUNmOzs7T0FHRztJQUNILFFBQVEsRUFBRTtRQUFFLE9BQU8sRUFBRSxZQUFZLENBQUM7UUFBQyxNQUFNLEVBQUUsU0FBUyxDQUFDO1FBQUMsT0FBTyxFQUFFLGNBQWMsQ0FBQTtLQUFFLEVBQUUsQ0FBQztJQUNsRixLQUFLLEVBQUUsV0FBVyxDQUFDO0lBQ25CLE9BQU8sRUFBRSxNQUFNLElBQUksQ0FBQztJQUNwQixRQUFRLEVBQUUsY0FBYyxDQUFDO0NBQzFCO0FBRUQ7Ozs7R0FJRztBQUNILHdCQUFzQixpQkFBaUIsQ0FBQyxJQUFJLEVBQUUscUJBQXFCLEdBQUcsT0FBTyxDQUFDLFVBQVUsQ0FBQyxDQXlHeEYifQ==

package/dest/deploy/fees.d.ts.map

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

package/dest/deploy/fees.js

@@ -0,0 +1,278 @@
+/**
+ * Fee handling for the deploy framework. Each account pays per its own {@link FeePolicy} — which
+ * may override the spec-wide default:
+ *
+ * - `sponsored`  → a SponsoredFPC pays (the local-network default). All sponsored accounts share
+ *   one payment method.
+ * - `fee-juice`  → the account pays from its own Fee Juice; if below `threshold` with work to do,
+ *   bridge `fundAmount` from L1. The bridge claim is single-use: the first paying tx claims it
+ *   (`FeeJuicePaymentMethodWithClaim`) and the rest spend the balance. Pending claims are persisted
+ *   (see ./state.ts) so a crash between bridge and claim resumes.
+ */ import { FeeJuicePaymentMethodWithClaim, SponsoredFeePaymentMethod } from '@aztec/aztec.js/fee';
+import { Fr } from '@aztec/aztec.js/fields';
+import { FeeJuiceContract } from '@aztec/aztec.js/protocol';
+import { registerDeployedSponsoredFPCInWalletAndGetAddress } from '../local-network/sponsored_fpc.js';
+import { bridgeFeeJuice, waitForL1ToL2Message } from './bridging.js';
+/** Anvil's first pre-funded dev key — used as the local-network L1 funder. Published, non-secret. */ const ANVIL_DEV_KEY = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80';
+const DEFAULT_LOCAL_L1_RPC_URL = 'http://localhost:8545';
+const DEFAULT_LOCAL_L1_CHAIN_ID = 31337;
+/**
+ * Sane fee defaults: local pays via SponsoredFPC; every other network pays from bridged Fee Juice.
+ * The threshold/fundAmount pair trades off L1 round-trips (too low → frequent re-bridges) against
+ * stranding Fee Juice, which is non-transferable, on the account (too high).
+ */ export function defaultFeePolicy(local) {
+    if (local) {
+        return {
+            kind: 'sponsored'
+        };
+    }
+    return {
+        kind: 'fee-juice',
+        threshold: 100n * 10n ** 18n,
+        fundAmount: 1000n * 10n ** 18n
+    };
+}
+/** The public Fee Juice balance of `address` (any address — contract or account), read via `from`. */ export async function publicFeeJuiceBalance(wallet, address, from) {
+    const { result } = await FeeJuiceContract.at(wallet).methods.balance_of_public(address).simulate({
+        from
+    });
+    return BigInt(result.toString());
+}
+/**
+ * Resolves an account's funding posture under `policy` — what the plan reports and what
+ * {@link prepareFeeSession} acts on. `idle` accounts (no pending work) are never funded; sponsored
+ * accounts never read a balance; fee-juice accounts are `funded` iff their balance clears the
+ * threshold, else `not-funded` (a bridge will top them up).
+ */ export async function accountFunding(policy, wallet, account, hasWork) {
+    if (!hasWork) {
+        return {
+            kind: 'idle'
+        };
+    }
+    if (policy.kind === 'sponsored') {
+        return {
+            kind: 'sponsored'
+        };
+    }
+    const balance = await publicFeeJuiceBalance(wallet, account, account);
+    return balance >= policy.threshold ? {
+        kind: 'funded',
+        balance
+    } : {
+        kind: 'not-funded',
+        balance,
+        fundAmount: policy.fundAmount
+    };
+}
+/**
+ * Resolves the L1 connection + funder for a bridge from caller-supplied config, defaulting to anvil
+ * on local. The funder key falls back to anvil's dev key on local (its faucet `mint` is owner-gated,
+ * so an ephemeral key is rejected there); elsewhere an omitted key means an ephemeral key + the
+ * public faucet. Deliberately no env fallback — the framework never reads the environment.
+ */ function resolveL1Config(local, cfg) {
+    const l1RpcUrl = cfg.l1RpcUrl ?? (local ? DEFAULT_LOCAL_L1_RPC_URL : undefined);
+    const l1ChainId = cfg.l1ChainId ?? (local ? DEFAULT_LOCAL_L1_CHAIN_ID : undefined);
+    if (l1RpcUrl === undefined || l1ChainId === undefined) {
+        throw new Error('Bridging on a non-local network requires `l1RpcUrl` and `l1ChainId` (no hardcoded defaults).');
+    }
+    return {
+        l1RpcUrl,
+        l1ChainId,
+        l1PrivateKey: cfg.l1FunderKey ?? (local ? ANVIL_DEV_KEY : undefined)
+    };
+}
+/**
+ * A single-use Fee Juice claim for `recipient` (used by `fund` steps): resumes the persisted claim
+ * when present, else bridges `amount` from L1 and waits for the L1→L2 message. The claim persists
+ * before the wait, so a crash mid-wait resumes it instead of stranding the bridged funds. The
+ * caller consumes it (e.g. via `FeeJuice.claim`) and calls `onConsumed` once that tx mines.
+ */ export async function obtainFeeJuiceClaim(opts) {
+    const { local, node, nodeUrl, recipient, state, persist, reporter } = opts;
+    // Prefixed so a recipient that is also an auto-funded sender doesn't collide with its account claim.
+    const key = `fund:${recipient.toString()}`;
+    let claim;
+    const stored = state.pendingClaims[key];
+    if (stored) {
+        reporter.onBridge?.({
+            recipient,
+            amount: BigInt(stored.claimAmount),
+            reused: true
+        });
+        claim = {
+            claimAmount: BigInt(stored.claimAmount),
+            claimSecret: Fr.fromString(stored.claimSecret),
+            messageLeafIndex: BigInt(stored.messageLeafIndex)
+        };
+    } else {
+        reporter.onBridge?.({
+            recipient,
+            amount: opts.amount,
+            reused: false
+        });
+        const { l1RpcUrl, l1ChainId, l1PrivateKey } = resolveL1Config(local, opts.l1);
+        const bridged = await bridgeFeeJuice({
+            node,
+            recipient,
+            l1RpcUrl,
+            l1ChainId,
+            amount: opts.amount,
+            l1PrivateKey
+        });
+        state.pendingClaims[key] = {
+            claimAmount: bridged.claimAmount.toString(),
+            claimSecret: bridged.claimSecret.toString(),
+            messageLeafIndex: bridged.messageLeafIndex.toString()
+        };
+        persist();
+        await waitForL1ToL2Message({
+            node,
+            messageHash: Fr.fromHexString(bridged.messageHash),
+            mode: local ? 'warp' : 'poll',
+            ...nodeUrl ? {
+                warpOpts: {
+                    nodeUrl
+                }
+            } : {}
+        });
+        claim = {
+            claimAmount: bridged.claimAmount,
+            claimSecret: bridged.claimSecret,
+            messageLeafIndex: bridged.messageLeafIndex
+        };
+    }
+    return {
+        ...claim,
+        onConsumed: ()=>{
+            delete state.pendingClaims[key];
+            persist();
+        }
+    };
+}
+/**
+ * Resolves fees ahead of execution, per account: registers the shared SponsoredFPC (for sponsored
+ * accounts), or tops up a fee-juice account via a bridge (reusing a persisted pending claim when
+ * present). Returns a {@link FeeSession} that dispenses the right fee per tx, by sending account.
+ */ export async function prepareFeeSession(opts) {
+    const { local, node, nodeUrl, wallet, accounts, state, persist, reporter } = opts;
+    // Shared sponsored payment method: register the SponsoredFPC + read gas once, if anyone uses it.
+    let sponsoredFee;
+    if (accounts.some((a)=>a.policy.kind === 'sponsored')) {
+        const sponsoredFPCAddress = await registerDeployedSponsoredFPCInWalletAndGetAddress(wallet);
+        sponsoredFee = {
+            paymentMethod: new SponsoredFeePaymentMethod(sponsoredFPCAddress),
+            // 10x headroom because this one quote is reused for every tx in the run (the wallet's default would re-quote
+            // per tx at 1.5x min): congestion pricing can push the min fee well past the starting quote over a run of
+            // parallel layers. Overstating the cap is free — txs pay the going rate, not the cap, and the FPC pays anyway.
+            gasSettings: {
+                maxFeesPerGas: (await node.getCurrentMinFees()).mul(10)
+            }
+        };
+    }
+    // Bridge fee-juice top-ups. The L1 sends stay sequential — a shared funder key would collide on
+    // nonces — but the L1→L2 availability waits (the minutes-long part on a real network) run
+    // concurrently afterwards. Warp-mode waits run inline instead: warping manipulates global time,
+    // so concurrent warps would fight. Each claim persists as soon as it exists on L1, so a crash
+    // mid-wait resumes it instead of stranding the bridged funds; a resumed claim skips the wait (by
+    // resume time the message is available on any live network).
+    const claims = new Map();
+    const messageWaits = [];
+    for (const { address, policy, funding } of accounts){
+        if (policy.kind !== 'fee-juice' || funding.kind === 'funded') {
+            continue;
+        }
+        const key = address.toString();
+        let stored = state.pendingClaims[key];
+        if (stored) {
+            reporter.onBridge?.({
+                recipient: address,
+                amount: BigInt(stored.claimAmount),
+                reused: true
+            });
+        } else {
+            reporter.onBridge?.({
+                recipient: address,
+                amount: policy.fundAmount,
+                reused: false
+            });
+            // Local defaults to anvil; a non-local network must supply L1 connection details.
+            const { l1ChainId, l1RpcUrl, l1PrivateKey } = resolveL1Config(local, policy);
+            const bridged = await bridgeFeeJuice({
+                node,
+                recipient: address,
+                l1RpcUrl,
+                l1ChainId,
+                amount: policy.fundAmount,
+                l1PrivateKey
+            });
+            stored = {
+                claimAmount: bridged.claimAmount.toString(),
+                claimSecret: bridged.claimSecret.toString(),
+                messageLeafIndex: bridged.messageLeafIndex.toString()
+            };
+            state.pendingClaims[key] = stored;
+            persist();
+            const wait = waitForL1ToL2Message({
+                node,
+                messageHash: Fr.fromHexString(bridged.messageHash),
+                mode: local ? 'warp' : 'poll',
+                ...nodeUrl ? {
+                    warpOpts: {
+                        nodeUrl
+                    }
+                } : {}
+            });
+            if (local) {
+                await wait;
+            } else {
+                messageWaits.push(wait);
+            }
+        }
+        claims.set(key, new FeeJuicePaymentMethodWithClaim(address, {
+            claimAmount: BigInt(stored.claimAmount),
+            claimSecret: Fr.fromString(stored.claimSecret),
+            messageLeafIndex: BigInt(stored.messageLeafIndex)
+        }));
+    }
+    await Promise.all(messageWaits);
+    // Per-account dispenser state. A claim is single-use: the first `next()` for its account carries
+    // it, and `onConsumed` (invoked by the runner once that tx mines) drops the persisted resume entry.
+    const sessions = new Map();
+    for (const { address, policy } of accounts){
+        const key = address.toString();
+        sessions.set(key, {
+            sponsored: policy.kind === 'sponsored',
+            claim: claims.get(key)
+        });
+    }
+    return {
+        next: (account)=>{
+            const key = account.toString();
+            const session = sessions.get(key);
+            if (session?.sponsored) {
+                return {
+                    fee: sponsoredFee ?? {},
+                    onConsumed: ()=>{}
+                };
+            }
+            if (session?.claim) {
+                const claim = session.claim;
+                session.claim = undefined; // single-use: only this first tx carries it
+                return {
+                    fee: {
+                        paymentMethod: claim
+                    },
+                    onConsumed: ()=>{
+                        // claim is now spent on-chain; drop its resume entry
+                        delete state.pendingClaims[key];
+                        persist();
+                    }
+                };
+            }
+            return {
+                fee: {},
+                onConsumed: ()=>{}
+            }; // later txs (or already-funded): pay from the account's balance
+        },
+        hasPendingClaim: (account)=>sessions.get(account.toString())?.claim !== undefined
+    };
+}

package/dest/deploy/graph.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Dependency-graph utilities for the deploy framework: topological layering (which steps
+ * can run together) and a pretty-printer for the resulting plan.
+ */
+/**
+ * Group `nodes` into dependency layers (Kahn's algorithm). Each layer contains nodes whose
+ * dependencies all sit in earlier layers, so a layer's nodes are mutually independent and
+ * may run in parallel. Dependencies pointing outside `nodes` (e.g. already-satisfied work)
+ * are treated as satisfied. Throws on a cycle.
+ */
+export declare function topologicalLayers(nodes: string[], dependencies: Map<string, string[]>): string[][];
+/**
+ * Like {@link topologicalLayers}, but nodes for which `floatLate(node)` is true are scheduled as
+ * LATE as their dependents allow (ALAP) instead of as early as possible. Used to push batchable
+ * actions into the latest layer they can share, so same-account actions in adjacent layers coalesce
+ * into one tx. Fixed nodes (e.g. contract publishes, which unblock dependents and don't batch) keep
+ * their earliest layer; the relative order — and so the critical-path length — is unchanged. Throws
+ * on a cycle (via {@link topologicalLayers}).
+ */
+export declare function scheduleLayers(nodes: string[], dependencies: Map<string, string[]>, floatLate: (node: string) => boolean): string[][];
+/** One node in the printed plan. */
+export interface PlanRow {
+    /** e.g. "goCoin" */
+    name: string;
+    /** short tag, e.g. "Token · publishes class" */
+    tag?: string;
+    /** dependency names to show as `← a, b` */
+    dependencies?: string[];
+}
+/**
+ * Render a titled flat list of plan rows (no layer grouping). Use for the declared-contracts
+ * overview, whose `← ...` arrows are constructor-arg references — not an execution order.
+ */
+export declare function formatList(title: string, rows: PlanRow[]): string;
+/**
+ * Render a titled, layer-grouped section of the plan as an indented tree. Each layer's txs are
+ * submitted in parallel.
+ */
+export declare function formatLayers(title: string, layers: PlanRow[][]): string;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZ3JhcGguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9kZXBsb3kvZ3JhcGgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7OztHQUdHO0FBRUg7Ozs7O0dBS0c7QUFDSCx3QkFBZ0IsaUJBQWlCLENBQUMsS0FBSyxFQUFFLE1BQU0sRUFBRSxFQUFFLFlBQVksRUFBRSxHQUFHLENBQUMsTUFBTSxFQUFFLE1BQU0sRUFBRSxDQUFDLEdBQUcsTUFBTSxFQUFFLEVBQUUsQ0FpQmxHO0FBRUQ7Ozs7Ozs7R0FPRztBQUNILHdCQUFnQixjQUFjLENBQzVCLEtBQUssRUFBRSxNQUFNLEVBQUUsRUFDZixZQUFZLEVBQUUsR0FBRyxDQUFDLE1BQU0sRUFBRSxNQUFNLEVBQUUsQ0FBQyxFQUNuQyxTQUFTLEVBQUUsQ0FBQyxJQUFJLEVBQUUsTUFBTSxLQUFLLE9BQU8sR0FDbkMsTUFBTSxFQUFFLEVBQUUsQ0ErQ1o7QUFFRCxvQ0FBb0M7QUFDcEMsTUFBTSxXQUFXLE9BQU87SUFDdEIsb0JBQW9CO0lBQ3BCLElBQUksRUFBRSxNQUFNLENBQUM7SUFDYixpREFBZ0Q7SUFDaEQsR0FBRyxDQUFDLEVBQUUsTUFBTSxDQUFDO0lBQ2IsNkNBQTJDO0lBQzNDLFlBQVksQ0FBQyxFQUFFLE1BQU0sRUFBRSxDQUFDO0NBQ3pCO0FBRUQ7OztHQUdHO0FBQ0gsd0JBQWdCLFVBQVUsQ0FBQyxLQUFLLEVBQUUsTUFBTSxFQUFFLElBQUksRUFBRSxPQUFPLEVBQUUsR0FBRyxNQUFNLENBV2pFO0FBRUQ7OztHQUdHO0FBQ0gsd0JBQWdCLFlBQVksQ0FBQyxLQUFLLEVBQUUsTUFBTSxFQUFFLE1BQU0sRUFBRSxPQUFPLEVBQUUsRUFBRSxHQUFHLE1BQU0sQ0FjdkUifQ==