@sig-net/midnight-contract-deploy 0.21.0-rc.8 → 0.21.0

package/dist/plumbing/funding.js

@@ -1,16 +1,8 @@
-// Account funding primitives for the root-funds-children model. Fees are paid
-// in DUST, which only generates on NIGHT registered for dust generation, so a
-// wallet is fee-ready only once it holds NIGHT that is registered and has
-// generated spendable dust. One ROOT wallet (the local genesis mint, or a
-// faucet-funded seed on a deployed network) holds the funds and pays out to
-// the role wallets (deployer, invoker, mpc responder); the roles themselves
-// are generated per environment and topped up from root.
-//
-// These are mechanical primitives (read a balance, assert root is funded,
-// fund one child). The pipeline that resolves/persists seeds, decides the
-// per-child amount, and prints addresses lives in the integration-tests setup.
+import { formatDust } from "./format-dust.js";
 import { isLocalStandaloneNetwork } from "./network-id.js";
-import { deriveAccountKeys, deriveAddresses, registerNightForDustGeneration, transferNight, waitForSpendableDust, withSyncedWalletFacade, } from "./wallet.js";
+import { deriveAccountKeys, deriveAddresses, registerNightForDustGeneration, transferNight, waitForSpendableDust, } from "./wallet.js";
+/** The registry's root wallet label, shared by every primitive that logs it. */
+const ROOT_LABEL = "root";
 /**
  * Sum a wallet's unshielded NIGHT across its UTXOs, in base units.
  *
@@ -32,29 +24,32 @@ export function deriveWalletAddresses(seed, config) {
     return deriveAddresses(deriveAccountKeys(seed, config.networkId), config.networkId);
 }
 /**
- * Sync a wallet and read its funding snapshot (addresses + NIGHT + DUST).
+ * Read a wallet's funding snapshot (addresses + NIGHT + DUST) from its synced
+ * state, syncing it first if the registry has not opened it yet.
  *
- * @param config - The stack the wallet connects to.
+ * @param wallets - The registry holding the wallet.
  * @param seed - The wallet seed (hex or mnemonic).
+ * @param label - The wallet's role name, for the sync log.
  * @returns The synced {@link AccountFunding}.
  */
-export async function readAccountFunding(config, seed) {
-    const keys = deriveAccountKeys(seed, config.networkId);
-    const addresses = deriveAddresses(keys, config.networkId);
-    return withSyncedWalletFacade(keys, config, (_facade, state) => Promise.resolve({
-        addresses,
+export async function readAccountFunding(wallets, seed, label) {
+    const { facade, keys } = await wallets.wallet(seed, label);
+    const state = await facade.waitForSyncedState();
+    return {
+        addresses: deriveAddresses(keys, wallets.config.networkId),
         night: totalNight(state),
         dust: state.dust.balance(new Date()),
-    }));
+    };
 }
 /**
- * A wallet is fee-ready when it holds NIGHT and that NIGHT has generated spendable dust.
+ * A wallet is fee-ready when its spendable DUST covers `minimumDust`.
  *
  * @param funding - The wallet's measured funding.
+ * @param minimumDust - The spendable DUST that counts as ready, in base units, 1 (any dust at all) by default.
  * @returns Whether the wallet can pay fees right now.
  */
-export function isFeeReady(funding) {
-    return funding.night > 0n && funding.dust > 0n;
+export function isFeeReady(funding, minimumDust = 1n) {
+    return funding.dust >= minimumDust;
 }
 /**
  * A wallet holds no NIGHT and no DUST, so it cannot pay fees until its NIGHT
@@ -86,10 +81,14 @@ export class WalletUnfundedError extends Error {
  * generation, so every unregistered NIGHT UTXO the wallet holds is registered
  * here first, whatever its current dust: a faucet top-up or transfer change
  * arrives unregistered, and leaving it so while older dust lasts would let
- * the wallet's dust generation shrink with every spend. Then a wallet with
- * spendable dust returns it, and one without waits until its first dust
- * appears (a few blocks). The facade must be started and synced, and `state`
- * must be its synced state (see `withSyncedWalletFacade` in wallet.ts).
+ * the wallet's dust generation shrink with every spend. Then a wallet holding
+ * at least `minimumDust` of spendable dust returns it, and one without waits
+ * until it does: a few blocks for a fresh registration, longer for a
+ * multi-transaction budget. A flow about to submit several transactions
+ * passes their total fee as `minimumDust`, so a wallet that cannot cover
+ * them stops here with the shortfall named and nothing submitted. The facade
+ * must be started and synced, and `state` must be its synced state (see
+ * `withSyncedWalletFacade` in wallet.ts).
  *
  * @param facade - A started wallet facade for `keys`, which submits the registration.
  * @param keys - The key material of the same wallet. Its keystore signs the registration.
@@ -97,15 +96,17 @@ export class WalletUnfundedError extends Error {
  * @param networkId - The network the wallet lives on, which prefixes the
  *   NIGHT receive address the no-NIGHT error prints for faucet funding.
  * @param faucetUrl - The network's faucet for the no-NIGHT hint, when one is known.
- * @returns The wallet's spendable DUST balance, always positive.
- * @throws {WalletUnfundedError} If the wallet holds neither NIGHT nor DUST.
- * @throws {Error} If no dust appears in time after registration (see
+ * @param minimumDust - The spendable DUST to require, in base units, 1 (any dust at all) by default.
+ * @param timeoutMs - Spendable DUST wait deadline in milliseconds, after registration.
+ * @returns The wallet's spendable DUST balance, at least `minimumDust`.
+ * @throws {WalletUnfundedError} If the wallet holds no NIGHT and less than `minimumDust` of DUST.
+ * @throws {Error} If the dust stays below `minimumDust` for the wait's timeout (see
  *   {@link waitForSpendableDust}).
  */
-export async function ensureFeeReady(facade, keys, state, networkId, faucetUrl) {
+export async function ensureFeeReady(facade, keys, state, networkId, faucetUrl, minimumDust = 1n, timeoutMs) {
     const dust = state.dust.balance(new Date());
     if (totalNight(state) === 0n) {
-        if (dust > 0n)
+        if (dust >= minimumDust)
             return dust;
         throw new WalletUnfundedError(deriveAddresses(keys, networkId).unshielded, faucetUrl);
     }
@@ -113,10 +114,10 @@ export async function ensureFeeReady(facade, keys, state, networkId, faucetUrl)
     if (registered > 0) {
         console.log(`registered ${String(registered)} NIGHT UTXO(s) for dust generation`);
     }
-    if (dust > 0n)
+    if (dust >= minimumDust)
         return dust;
-    console.log("waiting for spendable DUST...");
-    return waitForSpendableDust(facade);
+    console.log(`waiting for spendable DUST (have ${formatDust(dust)}, need at least ${formatDust(minimumDust)})...`);
+    return waitForSpendableDust(facade, minimumDust, timeoutMs);
 }
 // A freshly composed local stack has a window where the indexer reports a
 // synced (empty) state before it has indexed the genesis block that funds the
@@ -135,7 +136,7 @@ const GENESIS_INDEX_TIMEOUT_MS = 120_000;
  * {@link ensureFeeReady}: a faucet-funded root needs its NIGHT registered for
  * dust generation before it holds any spendable DUST.
  *
- * @param config - The stack the root wallet connects to.
+ * @param wallets - The registry holding the root wallet.
  * @param rootSeed - The root wallet seed.
  * @param faucetUrl - The network's faucet URL for the underfunded message.
  * @returns The root's fee-ready funding snapshot.
@@ -144,62 +145,65 @@ const GENESIS_INDEX_TIMEOUT_MS = 120_000;
  *   {@link waitForSpendableDust}): root is funded but not yet fee-ready, so
  *   this is a plain error, not a funding stop.
  */
-export async function assertRootFunded(config, rootSeed, faucetUrl) {
-    const keys = deriveAccountKeys(rootSeed, config.networkId);
-    const addresses = deriveAddresses(keys, config.networkId);
-    return withSyncedWalletFacade(keys, config, async (facade, state) => {
-        let night = totalNight(state);
-        if (night === 0n && isLocalStandaloneNetwork(config.networkId)) {
-            const deadline = Date.now() + GENESIS_INDEX_TIMEOUT_MS;
-            while (night === 0n && Date.now() < deadline) {
-                await new Promise((resolve) => setTimeout(resolve, GENESIS_INDEX_POLL_INTERVAL_MS));
-                state = await facade.waitForSyncedState();
-                night = totalNight(state);
-            }
-        }
-        if (night === 0n) {
-            throw new WalletUnfundedError(addresses.unshielded, faucetUrl);
+export async function assertRootFunded(wallets, rootSeed, faucetUrl) {
+    const { networkId } = wallets.config;
+    const { facade, keys } = await wallets.wallet(rootSeed, ROOT_LABEL);
+    const addresses = deriveAddresses(keys, networkId);
+    let state = await facade.waitForSyncedState();
+    let night = totalNight(state);
+    if (night === 0n && isLocalStandaloneNetwork(networkId)) {
+        const deadline = Date.now() + GENESIS_INDEX_TIMEOUT_MS;
+        while (night === 0n && Date.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, GENESIS_INDEX_POLL_INTERVAL_MS));
+            state = await facade.waitForSyncedState();
+            night = totalNight(state);
         }
-        const dust = await ensureFeeReady(facade, keys, state, config.networkId, faucetUrl);
-        return { addresses, night, dust };
-    });
+    }
+    if (night === 0n) {
+        throw new WalletUnfundedError(addresses.unshielded, faucetUrl);
+    }
+    const dust = await ensureFeeReady(facade, keys, state, networkId, faucetUrl);
+    return { addresses, night, dust };
 }
 /**
  * Bring one child wallet to fee-ready by topping it up from root: if it holds
  * no NIGHT, transfer `amount` from root and wait for the child to see it, then
  * finish through {@link ensureFeeReady}. A child that already holds NIGHT but
- * no dust yet is only registered and waited on (no transfer). Call only for a
- * child that is not already fee-ready.
+ * no dust yet is registered and waited on. A sufficient DUST balance returns immediately.
  *
- * @param config - The stack both wallets connect to.
+ * @param wallets - The registry holding both wallets.
  * @param rootSeed - The funding wallet's seed.
  * @param childSeed - The child wallet's seed.
+ * @param childLabel - The child's role name, for the sync log.
  * @param amount - NIGHT to transfer when the child holds none, in base units.
+ * @param minimumDust - Required spendable DUST in SPECKs.
  * @returns The child's post-funding snapshot.
  * @throws {Error} If root cannot cover the transfer, or dust never appears in time.
  */
-export async function fundChildFromRoot(config, rootSeed, childSeed, amount) {
-    const rootKeys = deriveAccountKeys(rootSeed, config.networkId);
-    const childKeys = deriveAccountKeys(childSeed, config.networkId);
-    const childAddresses = deriveAddresses(childKeys, config.networkId);
-    const before = await withSyncedWalletFacade(childKeys, config, (_f, s) => Promise.resolve(totalNight(s)));
-    if (before === 0n) {
-        await withSyncedWalletFacade(rootKeys, config, async (rootFacade, rootState) => {
-            await transferNight(rootFacade, rootKeys, rootState, childAddresses.unshielded, config.networkId, amount);
-        });
+export async function fundChildFromRoot(wallets, rootSeed, childSeed, childLabel, amount, minimumDust = 1n) {
+    const { networkId } = wallets.config;
+    const child = await wallets.wallet(childSeed, childLabel);
+    const childAddresses = deriveAddresses(child.keys, networkId);
+    let state = await child.facade.waitForSyncedState();
+    const available = state.dust.balance(new Date());
+    if (available >= minimumDust) {
+        console.log(`${childLabel}: available ${formatDust(available)} DUST, required ${formatDust(minimumDust)} DUST, funding skipped`);
+        return { addresses: childAddresses, night: totalNight(state), dust: available };
     }
-    return withSyncedWalletFacade(childKeys, config, async (childFacade, childState) => {
-        // Wait for the transferred NIGHT UTXO to land in the child's synced view.
-        let state = childState;
-        for (let i = 0; i < 40 && totalNight(state) === 0n; i++) {
-            await new Promise((resolve) => setTimeout(resolve, 3_000));
-            state = await childFacade.waitForSyncedState();
-        }
-        if (totalNight(state) === 0n) {
-            throw new Error(`child wallet ${childAddresses.unshielded} shows no NIGHT after funding from root`);
-        }
-        const dust = await ensureFeeReady(childFacade, childKeys, state, config.networkId);
-        return { addresses: childAddresses, night: totalNight(state), dust };
-    });
+    if (totalNight(state) === 0n) {
+        const root = await wallets.wallet(rootSeed, ROOT_LABEL);
+        const rootState = await root.facade.waitForSyncedState();
+        await transferNight(root.facade, root.keys, rootState, childAddresses.unshielded, networkId, amount);
+    }
+    // Wait for the transferred NIGHT UTXO to land in the child's synced view.
+    for (let i = 0; i < 40 && totalNight(state) === 0n; i++) {
+        await new Promise((resolve) => setTimeout(resolve, 3_000));
+        state = await child.facade.waitForSyncedState();
+    }
+    if (totalNight(state) === 0n) {
+        throw new Error(`child wallet ${childAddresses.unshielded} shows no NIGHT after funding from root`);
+    }
+    const dust = await ensureFeeReady(child.facade, child.keys, state, networkId, undefined, minimumDust);
+    return { addresses: childAddresses, night: totalNight(state), dust };
 }
 //# sourceMappingURL=funding.js.map

package/dist/plumbing/funding.js.map

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

package/dist/plumbing/network-id.d.ts

@@ -1,5 +1,5 @@
 import type { NetworkId as MidnightSDKNetworkId } from "@midnight-ntwrk/midnight-js/network-id";
-import { MidnightNetwork } from "@sig-net/midnight";
+import { type DeployedNetwork, MidnightNetwork } from "@sig-net/midnight";
 export { MidnightNetwork };
 /** A Midnight network id: the SDK's bare-string type plus the named networks. */
 export type NetworkId = MidnightSDKNetworkId | MidnightNetwork;
@@ -17,4 +17,13 @@ export declare const NETWORK_IDS: readonly NetworkId[];
  * @returns Whether the genesis mint wallet holds spendable funds here.
  */
 export declare function isLocalStandaloneNetwork(networkId: NetworkId): boolean;
+/** Every deployed network, the ones the SDK may publish counterparty values for. */
+export declare const DEPLOYED_NETWORKS: readonly DeployedNetwork[];
+/**
+ * Narrow a network id to a deployed network.
+ *
+ * @param networkId - The network to classify.
+ * @returns The same id as a {@link DeployedNetwork}, or undefined for the local standalone stack.
+ */
+export declare function deployedNetwork(networkId: NetworkId): DeployedNetwork | undefined;
 //# sourceMappingURL=network-id.d.ts.map

package/dist/plumbing/network-id.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"network-id.d.ts","sourceRoot":"","sources":["../../src/plumbing/network-id.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,IAAI,oBAAoB,EAAE,MAAM,wCAAwC,CAAC;AAChG,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAE,eAAe,EAAE,CAAC;AAE3B,iFAAiF;AACjF,MAAM,MAAM,SAAS,GAAG,oBAAoB,GAAG,eAAe,CAAC;AAG/D,oEAAoE;AACpE,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAAmC,CAAC;AAEhF;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAGtE"}
+{"version":3,"file":"network-id.d.ts","sourceRoot":"","sources":["../../src/plumbing/network-id.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,IAAI,oBAAoB,EAAE,MAAM,wCAAwC,CAAC;AAChG,OAAO,EAAE,KAAK,eAAe,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAE1E,OAAO,EAAE,eAAe,EAAE,CAAC;AAE3B,iFAAiF;AACjF,MAAM,MAAM,SAAS,GAAG,oBAAoB,GAAG,eAAe,CAAC;AAG/D,oEAAoE;AACpE,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAAmC,CAAC;AAEhF;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAGtE;AAED,oFAAoF;AACpF,eAAO,MAAM,iBAAiB,EAAE,SAAS,eAAe,EAKvD,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,SAAS,GAAG,eAAe,GAAG,SAAS,CAMjF"}

package/dist/plumbing/network-id.js

@@ -18,4 +18,24 @@ export function isLocalStandaloneNetwork(networkId) {
     const undeployed = MidnightNetwork.Undeployed;
     return networkId === undeployed;
 }
+/** Every deployed network, the ones the SDK may publish counterparty values for. */
+export const DEPLOYED_NETWORKS = [
+    MidnightNetwork.Stagenet,
+    MidnightNetwork.Preview,
+    MidnightNetwork.Preprod,
+    MidnightNetwork.Mainnet,
+];
+/**
+ * Narrow a network id to a deployed network.
+ *
+ * @param networkId - The network to classify.
+ * @returns The same id as a {@link DeployedNetwork}, or undefined for the local standalone stack.
+ */
+export function deployedNetwork(networkId) {
+    const id = networkId;
+    return DEPLOYED_NETWORKS.find((network) => {
+        const candidate = network;
+        return candidate === id;
+    });
+}
 //# sourceMappingURL=network-id.js.map

package/dist/plumbing/network-id.js.map

@@ -1 +1 @@
-{"version":3,"file":"network-id.js","sourceRoot":"","sources":["../../src/plumbing/network-id.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAE,eAAe,EAAE,CAAC;AAK3B,+DAA+D;AAC/D,oEAAoE;AACpE,MAAM,CAAC,MAAM,WAAW,GAAyB,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;AAEhF;;;;;;;;;;GAUG;AACH,MAAM,UAAU,wBAAwB,CAAC,SAAoB;IAC3D,MAAM,UAAU,GAAc,eAAe,CAAC,UAAU,CAAC;IACzD,OAAO,SAAS,KAAK,UAAU,CAAC;AAClC,CAAC"}
+{"version":3,"file":"network-id.js","sourceRoot":"","sources":["../../src/plumbing/network-id.ts"],"names":[],"mappings":"AAOA,OAAO,EAAwB,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAE1E,OAAO,EAAE,eAAe,EAAE,CAAC;AAK3B,+DAA+D;AAC/D,oEAAoE;AACpE,MAAM,CAAC,MAAM,WAAW,GAAyB,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;AAEhF;;;;;;;;;;GAUG;AACH,MAAM,UAAU,wBAAwB,CAAC,SAAoB;IAC3D,MAAM,UAAU,GAAc,eAAe,CAAC,UAAU,CAAC;IACzD,OAAO,SAAS,KAAK,UAAU,CAAC;AAClC,CAAC;AAED,oFAAoF;AACpF,MAAM,CAAC,MAAM,iBAAiB,GAA+B;IAC3D,eAAe,CAAC,QAAQ;IACxB,eAAe,CAAC,OAAO;IACvB,eAAe,CAAC,OAAO;IACvB,eAAe,CAAC,OAAO;CACxB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,SAAoB;IAClD,MAAM,EAAE,GAAW,SAAS,CAAC;IAC7B,OAAO,iBAAiB,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE;QACxC,MAAM,SAAS,GAAW,OAAO,CAAC;QAClC,OAAO,SAAS,KAAK,EAAE,CAAC;IAC1B,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/plumbing/wallet.d.ts

@@ -2,7 +2,7 @@ import * as ledger from "@midnightntwrk/ledger-v9";
 import { type FacadeState, type TransactionIdentifier, WalletFacade } from "@midnightntwrk/wallet-sdk-facade";
 import { type UnshieldedKeystore } from "@midnightntwrk/wallet-sdk-unshielded-wallet";
 import type { MidnightNodeConfig } from "./midnight-node-config.ts";
-import type { NetworkId } from "./network-id.ts";
+import { type NetworkId } from "./network-id.ts";
 export type { FacadeState, TransactionIdentifier, WalletFacade, } from "@midnightntwrk/wallet-sdk-facade";
 export type { EncPublicKey } from "@midnightntwrk/ledger-v9";
 /** The live key material for one account. Reused for signing / balancing. */
@@ -18,35 +18,42 @@ export interface WalletAddresses {
     dust: string;
 }
 /**
- * Default `additionalFeeOverhead` the facade balances transactions with: it
- * burns `feesWithMargin(params, feeBlocksMargin) + additionalFeeOverhead`
- * per transaction, so the overhead is burned as dust on EVERY submitted
- * transaction.
+ * The `additionalFeeOverhead` a facade balances with when its
+ * {@link WalletFacadeOptions} name none: 5e13 on the local standalone chain,
+ * whose dust is free, and 0 on every deployed network, whose dust is scarce.
  *
- * The overhead compensates for the wallet sdk pricing a PROOF-ERASED
- * transaction while the node prices the real proof bytes. The node's fee
- * consequently exceeds the wallet's estimate by an amount that grows with
- * proof size, and the node rejects the spend with
- * Malformed(BalanceCheckOverspend) when the wallet under-provides. 5e13
- * covers the gap this repo's circuits produce, with headroom, and the excess
- * is simply burned dust. The default is tuned for local fakenet chains where
- * dust is free: real-network deploys may want a lower value (see
- * {@link WalletFacadeOptions}).
+ * @param networkId - The network the facade connects to.
+ * @returns The overhead burned as dust on top of every transaction's estimated fee.
  */
-export declare const DEFAULT_ADDITIONAL_FEE_OVERHEAD = 50000000000000n;
+export declare function defaultAdditionalFeeOverhead(networkId: NetworkId): bigint;
 /**
  * Optional tuning knobs for {@link initialiseWalletFacade} (and
- * {@link withSyncedWalletFacade}, which passes them through).
+ * {@link withSyncedWalletFacade} and {@link WalletRegistry}, which pass them
+ * through).
  */
 export interface WalletFacadeOptions {
     /**
      * Flat fee overhead added on top of the estimated fee of every submitted
      * transaction, burned as dust each time. Defaults to
-     * {@link DEFAULT_ADDITIONAL_FEE_OVERHEAD} (5e13), which is tuned for local
-     * fakenet chains: real-network deploys may want it lower.
+     * {@link defaultAdditionalFeeOverhead} for the facade's network.
      */
     additionalFeeOverhead?: bigint;
 }
+/** The DUST a facade refusal reports holding and needing, in base units. */
+export interface DustShortfall {
+    /** The DUST the facade found available to the refused call. */
+    readonly have: bigint;
+    /** The DUST the refused call needs. */
+    readonly need: bigint;
+}
+/**
+ * The amounts a facade refusal names when it refuses for lack of DUST.
+ *
+ * @param error - What a facade call threw.
+ * @returns The named shortfall, or undefined for a refusal that names no
+ *   amount and for any other error.
+ */
+export declare function dustShortfall(error: unknown): DustShortfall | undefined;
 /**
  * Parse a seed and derive the three role keys (Zswap / NightExternal / Dust).
  * Pure crypto — no network. This is the step that exercises the ledger WASM.
@@ -75,6 +82,31 @@ export declare function deriveAddresses(keys: AccountKeys, networkId: NetworkId)
  * @returns The constructed facade, not yet syncing.
  */
 export declare function initialiseWalletFacade(keys: AccountKeys, config: MidnightNodeConfig, options?: WalletFacadeOptions): Promise<WalletFacade>;
+/**
+ * Wait until the wallet's spendable DUST (fee) balance reaches `minimumDust`,
+ * polling the synced facade state and logging each reading. Pair with
+ * {@link registerNightForDustGeneration}: a wallet whose NIGHT was just
+ * registered has no dust for a few blocks.
+ *
+ * @param facade - A started wallet facade.
+ * @param minimumDust - The spendable DUST to wait for, in base units (1 = any dust at all).
+ * @param timeoutMs - Give-up deadline in milliseconds.
+ * @returns The first spendable dust balance at or above `minimumDust`.
+ * @throws {Error} If the balance stays below `minimumDust` for `timeoutMs`.
+ */
+export declare function waitForSpendableDust(facade: WalletFacade, minimumDust: bigint, timeoutMs?: number): Promise<bigint>;
+/**
+ * The fee the facade prices a serialized unproven transaction at: the
+ * ledger's fee with the facade's block margin plus the network's overhead
+ * (see {@link defaultAdditionalFeeOverhead}). The balancing inputs the
+ * facade adds at submission carry a further small fee, so this is the floor
+ * of what submitting the transaction burns.
+ *
+ * @param facade - A started facade, whose network sets the overhead.
+ * @param serializedTransaction - The unproven transaction bytes.
+ * @returns The transaction's fee in DUST base units.
+ */
+export declare function estimateUnprovenTransactionFee(facade: WalletFacade, serializedTransaction: Uint8Array): Promise<bigint>;
 /**
  * Balance, sign, prove and submit a serialized unproven transaction (e.g. a
  * contract deploy built by `buildDeployTransaction` in deploy.ts). Proving
@@ -111,26 +143,20 @@ export declare function transferNight(facade: WalletFacade, keys: AccountKeys, s
  * wallet can pay transaction fees (fees are paid in DUST, which only
  * generates on registered NIGHT). Registers ONLY unregistered UTXOs — the
  * node rejects a re-registration of an already-registered one — and submits
- * nothing when there is nothing new to register.
+ * nothing when there is nothing new to register. A first-time registration
+ * pays its own fee out of the dust its NIGHT UTXOs have generated since they
+ * landed, and a UTXO that landed moments ago has not yet generated it: the
+ * facade refuses naming the shortfall (see {@link dustShortfall}), and this
+ * waits for exactly that amount to generate before registering again.
  *
  * @param facade - A started wallet facade for `keys` (builds, proves and submits the registration).
  * @param keys - The key material of the same wallet; its unshielded keystore signs the registration.
  * @param state - The synced facade state to read the NIGHT UTXOs from.
  * @returns How many NIGHT UTXOs this call registered (0 = nothing unregistered, including no NIGHT at all).
- * @throws {Error} If the node rejects the registration transaction.
+ * @throws {Error} If the fee does not generate within {@link GENERATED_DUST_TIMEOUT_MS}, or
+ *   the node rejects the registration transaction.
  */
 export declare function registerNightForDustGeneration(facade: WalletFacade, keys: AccountKeys, state: FacadeState): Promise<number>;
-/**
- * Wait until the wallet's spendable DUST (fee) balance is positive, polling
- * the synced facade state. Pair with {@link registerNightForDustGeneration}:
- * a wallet whose NIGHT was just registered has no dust for a few blocks.
- *
- * @param facade - A started wallet facade.
- * @param timeoutMs - Give-up deadline in milliseconds.
- * @returns The first positive dust balance observed.
- * @throws {Error} If no dust appears within `timeoutMs`.
- */
-export declare function waitForSpendableDust(facade: WalletFacade, timeoutMs?: number): Promise<bigint>;
 /**
  * Run `fn` against a started-and-synced {@link WalletFacade}, then stop the
  * facade — even when `fn` throws. The one place the start / wait-for-sync /
@@ -144,4 +170,57 @@ export declare function waitForSpendableDust(facade: WalletFacade, timeoutMs?: n
  * @throws {Error} Whatever {@link initialiseWalletFacade}, the facade start/sync, or `fn` throws.
  */
 export declare function withSyncedWalletFacade<T>(keys: AccountKeys, config: MidnightNodeConfig, fn: (facade: WalletFacade, state: FacadeState) => Promise<T>, options?: WalletFacadeOptions): Promise<T>;
+/** A wallet a {@link WalletRegistry} holds started and synced. */
+export interface RegisteredWallet {
+    /** The wallet's role name, as logged. */
+    readonly label: string;
+    /** The wallet's key material, for balancing and signing. */
+    readonly keys: AccountKeys;
+    /** The started facade. Later `waitForSyncedState()` calls catch it up incrementally. */
+    readonly facade: WalletFacade;
+}
+/**
+ * The dedup key a {@link WalletRegistry} files a seed under: its normalised
+ * hex, so two spellings of one seed (0x-prefixed, upper case, a mnemonic and
+ * its derived hex) share a facade.
+ *
+ * @param seed - The wallet seed, as hex or a BIP-39 mnemonic.
+ * @returns The seed's normalised hex.
+ * @throws {ParseError} If the seed parses as neither form.
+ */
+export declare function walletRegistryKey(seed: string): string;
+/**
+ * One started, synced facade per wallet for the life of a pipeline: the
+ * first request for a seed builds, starts and fully syncs its facade (the
+ * expensive step on a deployed network, where a fresh facade scans the chain
+ * from nothing), every later request returns the same running facade, whose
+ * `waitForSyncedState()` only catches up incrementally. {@link close} stops
+ * every facade once, at the end.
+ */
+export declare class WalletRegistry {
+    readonly config: MidnightNodeConfig;
+    private readonly options;
+    private readonly wallets;
+    /**
+     * @param config - The stack every facade in the registry connects to.
+     * @param options - Facade tuning passed to every facade built here.
+     */
+    constructor(config: MidnightNodeConfig, options?: WalletFacadeOptions);
+    /**
+     * The started, synced wallet for `seed`, built on first request.
+     *
+     * @param seed - The wallet seed, as hex or a BIP-39 mnemonic.
+     * @param label - The wallet's role name, used in the sync log lines.
+     * @returns The registered wallet.
+     * @throws {Error} Whatever building, starting or syncing the facade throws. The
+     *   failed entry is dropped, so a later request retries.
+     */
+    wallet(seed: string, label: string): Promise<RegisteredWallet>;
+    private open;
+    /**
+     * Stop every facade the registry opened. Safe to call more than once and
+     * with nothing opened.
+     */
+    close(): Promise<void>;
+}
 //# sourceMappingURL=wallet.d.ts.map

package/dist/plumbing/wallet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wallet.d.ts","sourceRoot":"","sources":["../../src/plumbing/wallet.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,MAAM,MAAM,0BAA0B,CAAC;AAWnD,OAAO,EACL,KAAK,WAAW,EAEhB,KAAK,qBAAqB,EAE1B,YAAY,EACb,MAAM,kCAAkC,CAAC;AAG1C,OAAO,EAGL,KAAK,kBAAkB,EAExB,MAAM,6CAA6C,CAAC;AAErD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAKjD,YAAY,EACV,WAAW,EACX,qBAAqB,EACrB,YAAY,GACb,MAAM,kCAAkC,CAAC;AAI1C,YAAY,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE7D,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,kBAAkB,EAAE,MAAM,CAAC,eAAe,CAAC;IAC3C,aAAa,EAAE,MAAM,CAAC,aAAa,CAAC;IACpC,kBAAkB,EAAE,kBAAkB,CAAC;CACxC;AAED,+DAA+D;AAC/D,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,+BAA+B,kBAAsB,CAAC;AAKnE;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,WAAW,CAqBjF;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,GAAG,eAAe,CAUxF;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,kBAAkB,EAC1B,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,YAAY,CAAC,CA+BvB;AAmDD;;;;;;;;;;;GAWG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,WAAW,EACjB,qBAAqB,EAAE,UAAU,GAChC,OAAO,CAAC,qBAAqB,CAAC,CAsBhC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,WAAW,EAClB,mBAAmB,EAAE,MAAM,EAC3B,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,qBAAqB,CAAC,CAmBhC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,MAAM,CAAC,CAiBjB;AAMD;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,YAAY,EACpB,SAAS,SAAU,GAClB,OAAO,CAAC,MAAM,CAAC,CAajB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,kBAAkB,EAC1B,EAAE,EAAE,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EAC5D,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,CAAC,CAAC,CAWZ"}
+{"version":3,"file":"wallet.d.ts","sourceRoot":"","sources":["../../src/plumbing/wallet.ts"],"names":[],"mappings":"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"}