@shieldedtech/moth-wallet 0.2.0

package/dist/sync/dust-registration-estimate.d.ts

@@ -0,0 +1,54 @@
+/** Per-UTxO generation figures, as the SDK's `estimateRegistration` reports
+ *  them. All amounts in Specks. */
+export interface DustGenerationSlice {
+    /** Backdated DUST this UTxO could contribute right now. */
+    generatedNow: bigint;
+    /** Specks per second this UTxO accrues (`night_value * decay_rate`). */
+    rate: bigint;
+    /** Ceiling this UTxO can ever reach (`night_value * night_dust_ratio`). */
+    maxCap: bigint;
+    /** Already backing DUST, so excluded from backdated fee payment — the
+     *  ledger's `!night_indices.contains_key(initial_nonce)` filter. */
+    registeredForDustGeneration: boolean;
+}
+export interface DustRegistrationEstimate {
+    /** What the registration costs, in Specks. */
+    fee: bigint;
+    /** Backdated DUST available to it right now. */
+    available: bigint;
+    /** Combined accrual, in Specks per second. */
+    rate: bigint;
+    /** The most this NIGHT could ever offer, however long the wallet waits. */
+    maxAvailable: bigint;
+    /** Whether registering would succeed now. */
+    affordable: boolean;
+    /**
+     * Seconds until `available` reaches `fee`.
+     *
+     * `0` when already affordable. `null` when waiting cannot get there — either
+     * nothing is accruing, or the ceiling is below the fee, in which case the
+     * answer is "hold more NIGHT", not "wait longer". Distinguishing these
+     * matters: telling someone to wait for something that will never arrive is
+     * worse than telling them nothing.
+     */
+    secondsUntilAffordable: number | null;
+}
+/** A rough, readable duration. Deliberately vague at the top end: the estimate
+ *  assumes the holding does not change, and "about 8 hours" carries that
+ *  honestly where "7h 55m 12s" would imply a precision it does not have. */
+export declare function describeWait(seconds: number): string;
+/**
+ * Registration cannot pay its own fee yet.
+ *
+ * A distinct type because this is not a failure in any useful sense — nothing
+ * was built, nothing booked, nothing spent, and the same call will succeed later
+ * with no change to the wallet. Callers that show it as an error alongside
+ * genuine ones (a dead node, a refused proof) mislead: this one just needs time,
+ * or more NIGHT.
+ */
+export declare class DustRegistrationNotYetError extends Error {
+    readonly estimate: DustRegistrationEstimate;
+    constructor(estimate: DustRegistrationEstimate, cause?: unknown);
+}
+export declare function estimateRegistrationAffordability(fee: bigint, slices: readonly DustGenerationSlice[]): DustRegistrationEstimate;
+//# sourceMappingURL=dust-registration-estimate.d.ts.map

package/dist/sync/dust-registration-estimate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dust-registration-estimate.d.ts","sourceRoot":"","sources":["../../src/sync/dust-registration-estimate.ts"],"names":[],"mappings":"AA6BA;mCACmC;AACnC,MAAM,WAAW,mBAAmB;IAClC,2DAA2D;IAC3D,YAAY,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf;wEACoE;IACpE,2BAA2B,EAAE,OAAO,CAAC;CACtC;AAED,MAAM,WAAW,wBAAwB;IACvC,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;;;;OAQG;IACH,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAYD;;4EAE4E;AAC5E,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CASpD;AAED;;;;;;;;GAQG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,QAAQ,CAAC,QAAQ,EAAE,wBAAwB,CAAC;gBAEhC,QAAQ,EAAE,wBAAwB,EAAE,KAAK,CAAC,EAAE,OAAO;CAehE;AAED,wBAAgB,iCAAiC,CAC/C,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,SAAS,mBAAmB,EAAE,GACrC,wBAAwB,CA+B1B"}

package/dist/sync/dust-registration-estimate.js

@@ -0,0 +1,103 @@
+// When a fresh wallet can actually register NIGHT for DUST generation.
+//
+// Registering is self-funding by design — it does not require the wallet to
+// already hold DUST, which would be a bootstrap deadlock. Instead a
+// DustRegistration carries `allow_fee_payment`, and the ledger lets the
+// transaction pay its own fee out of the DUST its NIGHT *would have* generated
+// had it been registered all along (midnight-ledger `spec/dust.md`, "because
+// registrations run a challenge of paying for their own fees…").
+//
+// Self-funding is not the same as free. `generationless_fee_availability`
+// (midnight-ledger `ledger/src/dust.rs`) caps that backdated amount at
+//
+//     elapsed_since_utxo_created * night_value * generation_decay_rate
+//
+// so it grows from zero. A wallet funded moments ago cannot cover the fee yet,
+// and one holding very little NIGHT accrues towards it slowly: at the ledger's
+// default parameters (5 DUST per NIGHT, ~1 week to cap) a 0.3 DUST registration
+// fee needs roughly 36s at 1,000 NIGHT, 6 min at 100, an hour at 10, and 10
+// hours at 1.
+//
+// Without a pre-flight the wallet builds the transaction, hands it to the SDK,
+// and surfaces the SDK's own guard as a failure after the fact — which reads as
+// a broken wallet rather than "not yet". Worse, our failure card blamed the
+// proof server, which has nothing to do with it. This computes the answer up
+// front so the wallet can say how long instead.
+//
+// Pure and WASM-free: the arithmetic is the part worth testing, and it needs no
+// facade, no chain and no proving.
+/** Specks in one DUST — the ledger's SPECKS_PER_DUST. */
+const SPECKS_PER_DUST = 1000000000000000n;
+/** Whole DUST to 4dp, for messages a person reads. */
+function formatDust(specks) {
+    const whole = specks / SPECKS_PER_DUST;
+    const frac = ((specks % SPECKS_PER_DUST) * 10000n) / SPECKS_PER_DUST;
+    return `${whole}.${frac.toString().padStart(4, '0')}`;
+}
+/** A rough, readable duration. Deliberately vague at the top end: the estimate
+ *  assumes the holding does not change, and "about 8 hours" carries that
+ *  honestly where "7h 55m 12s" would imply a precision it does not have. */
+export function describeWait(seconds) {
+    if (seconds < 60)
+        return `about ${Math.max(1, Math.round(seconds))} seconds`;
+    if (seconds < 3_600)
+        return `about ${Math.round(seconds / 60)} minutes`;
+    if (seconds < 86_400) {
+        const hours = Math.round((seconds / 3_600) * 10) / 10;
+        return `about ${hours} hour${hours === 1 ? '' : 's'}`;
+    }
+    const days = Math.round((seconds / 86_400) * 10) / 10;
+    return `about ${days} day${days === 1 ? '' : 's'}`;
+}
+/**
+ * Registration cannot pay its own fee yet.
+ *
+ * A distinct type because this is not a failure in any useful sense — nothing
+ * was built, nothing booked, nothing spent, and the same call will succeed later
+ * with no change to the wallet. Callers that show it as an error alongside
+ * genuine ones (a dead node, a refused proof) mislead: this one just needs time,
+ * or more NIGHT.
+ */
+export class DustRegistrationNotYetError extends Error {
+    estimate;
+    constructor(estimate, cause) {
+        const have = formatDust(estimate.available);
+        const need = formatDust(estimate.fee);
+        super(estimate.secondsUntilAffordable === null
+            ? `Registration costs ${need} DUST of backdated generation, but this NIGHT can only ever provide ` +
+                `${formatDust(estimate.maxAvailable)} DUST. Hold more NIGHT and try again.`
+            : `Registration pays its own fee from the DUST this NIGHT would already have generated. ` +
+                `It needs ${need} DUST and has ${have} so far — ${describeWait(estimate.secondsUntilAffordable)} to go. ` +
+                `Nothing was spent.`, { cause });
+        this.name = 'DustRegistrationNotYetError';
+        this.estimate = estimate;
+    }
+}
+export function estimateRegistrationAffordability(fee, slices) {
+    // Only UTxOs not already backing DUST can fund a registration by backdating.
+    const eligible = slices.filter((s) => !s.registeredForDustGeneration);
+    const sum = (pick) => eligible.reduce((total, s) => total + pick(s), 0n);
+    const available = sum((s) => s.generatedNow);
+    const rate = sum((s) => s.rate);
+    const maxAvailable = sum((s) => s.maxCap);
+    if (available >= fee) {
+        return { fee, available, rate, maxAvailable, affordable: true, secondsUntilAffordable: 0 };
+    }
+    // Unreachable rather than slow. Both cases are real: a wallet whose NIGHT is
+    // all registered already has no accrual to wait on, and a wallet holding too
+    // little NIGHT tops out below the fee.
+    const reachable = rate > 0n && maxAvailable >= fee;
+    const shortfall = fee - available;
+    return {
+        fee,
+        available,
+        rate,
+        maxAvailable,
+        affordable: false,
+        // Ceiling, not rounding: at the exact quotient the balance has only just
+        // reached the fee, and reporting a second early sends the user back to the
+        // same failure.
+        secondsUntilAffordable: reachable ? Number((shortfall + rate - 1n) / rate) : null,
+    };
+}
+//# sourceMappingURL=dust-registration-estimate.js.map

package/dist/sync/dust-registration-estimate.js.map

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

package/dist/sync/node-sync-store.d.ts

@@ -0,0 +1,10 @@
+import type { SyncStateStore } from './sync-store.js';
+export declare class NodeSyncStateStore implements SyncStateStore {
+    private readonly base;
+    constructor(base?: string);
+    private fileFor;
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+//# sourceMappingURL=node-sync-store.d.ts.map

package/dist/sync/node-sync-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-sync-store.d.ts","sourceRoot":"","sources":["../../src/sync/node-sync-store.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,iBAAiB,CAAC;AAEpD,qBAAa,kBAAmB,YAAW,cAAc;IACvD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;gBAElB,IAAI,CAAC,EAAE,MAAM;IAIzB,OAAO,CAAC,OAAO;IAIT,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAUxC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM9C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAOzC"}

package/dist/sync/node-sync-store.js

@@ -0,0 +1,42 @@
+// Filesystem-backed SyncStateStore preserving the legacy ~/.moth layout
+// (sync/<network>/<wallet>/<part>.dat, empty-ref/<network>/...).
+// This is the only sync module allowed to import node:* — it is exposed via
+// the package's "./*" subpath exports and must never be re-exported from the
+// barrel, which has to stay browser-bundleable.
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+export class NodeSyncStateStore {
+    base;
+    constructor(base) {
+        this.base = base ?? join(homedir(), '.moth');
+    }
+    fileFor(key) {
+        return join(this.base, ...key.split('/'));
+    }
+    async get(key) {
+        const file = this.fileFor(key);
+        if (!existsSync(file))
+            return null;
+        try {
+            return readFileSync(file, 'utf-8');
+        }
+        catch {
+            return null;
+        }
+    }
+    async put(key, value) {
+        const file = this.fileFor(key);
+        mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+        writeFileSync(file, value, { encoding: 'utf-8', mode: 0o600 });
+    }
+    async delete(key) {
+        try {
+            unlinkSync(this.fileFor(key));
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+//# sourceMappingURL=node-sync-store.js.map

package/dist/sync/node-sync-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-sync-store.js","sourceRoot":"","sources":["../../src/sync/node-sync-store.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,iEAAiE;AACjE,4EAA4E;AAC5E,6EAA6E;AAC7E,gDAAgD;AAEhD,OAAO,EAAC,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAC,MAAM,SAAS,CAAC;AACvF,OAAO,EAAC,IAAI,EAAE,OAAO,EAAC,MAAM,WAAW,CAAC;AACxC,OAAO,EAAC,OAAO,EAAC,MAAM,SAAS,CAAC;AAGhC,MAAM,OAAO,kBAAkB;IACZ,IAAI,CAAS;IAE9B,YAAY,IAAa;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC;IAC/C,CAAC;IAEO,OAAO,CAAC,GAAW;QACzB,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QACnC,IAAI,CAAC;YACH,OAAO,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACrC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAa;QAClC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC/B,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAC,CAAC,CAAC;QACzD,aAAa,CAAC,IAAI,EAAE,KAAK,EAAE,EAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAC,CAAC,CAAC;IAC/D,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,IAAI,CAAC;YACH,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;QAChC,CAAC;QAAC,MAAM,CAAC;YACP,YAAY;QACd,CAAC;IACH,CAAC;CACF"}

package/dist/sync/operations.d.ts

@@ -0,0 +1,138 @@
+import * as ledger from '@midnight-ntwrk/ledger-v8';
+import type { WalletFacade, UtxoWithMeta } from '@midnightntwrk/wallet-sdk/facade';
+import { DustRegistrationNotYetError, type DustRegistrationEstimate } from './dust-registration-estimate.js';
+export { DustRegistrationNotYetError, type DustRegistrationEstimate };
+/** The proven, signed, ready-to-submit transaction produced by the facade. */
+export type FinalizedTransaction = ledger.FinalizedTransaction;
+export type TxStage = 'building' | 'proving' | 'submitting';
+export interface SendRequest {
+    type: 'shielded' | 'unshielded';
+    tokenId: string;
+    amount: bigint;
+    to: string;
+}
+/** An input the wallet offers into a swap intent (no recipient — it's spent). */
+export interface SwapInput {
+    type: 'shielded' | 'unshielded';
+    tokenId: string;
+    amount: bigint;
+}
+export type { WalletKeys } from '../types/wallet.js';
+import type { WalletKeys } from '../types/wallet.js';
+/**
+ * Derive the typed key bundle from a 64-char BIP-39 hex seed. Option A key
+ * model (v8's D-KM-3): callers derive once at unlock and discard the raw seed
+ * immediately — the bundle holds everything the write paths need, so the seed
+ * is never threaded through the daemon or the extension messaging layers.
+ */
+export declare function deriveWalletKeys(seedHex: string): WalletKeys;
+/**
+ * Build, prove and sign a transfer, stopping short of submission.
+ * The dApp connector's makeTransfer/submitTransaction split needs the
+ * finalized transaction as a standalone artifact; sendTokens composes this
+ * with submission.
+ */
+export declare function buildTransferTransaction(facade: WalletFacade, keys: WalletKeys, networkId: string, requests: SendRequest[], onProgress?: (stage: TxStage) => void): Promise<FinalizedTransaction>;
+/**
+ * Estimate the complete DUST fee for a transfer, including the balancing
+ * transaction that pays it. The facade's transfer builder books selected
+ * inputs even when fee payment is disabled, so the temporary base transaction
+ * is always reverted before returning.
+ */
+export declare function estimateTransferFee(facade: WalletFacade, keys: WalletKeys, networkId: string, requests: SendRequest[]): Promise<bigint>;
+/**
+ * Submit a previously built transfer with retries.
+ */
+export declare function submitFinalizedTransaction(facade: WalletFacade, finalized: FinalizedTransaction): Promise<string>;
+/**
+ * Send tokens via the wallet facade using a pre-derived key bundle. Prefer this
+ * over {@link sendTokens} when the caller already holds WalletKeys (the daemon
+ * and the extension, which derive once at unlock and drop the seed — Option A /
+ * D-KM-3, docs/spec/wallet-service/05-key-management.md).
+ */
+export declare function sendTokensWithKeys(facade: WalletFacade, keys: WalletKeys, networkId: string, requests: SendRequest[], onProgress?: (stage: TxStage) => void): Promise<string>;
+/**
+ * Balance a dApp-supplied transaction (connector `balanceSealedTransaction` /
+ * `balanceUnsealedTransaction`): pay fees and add wallet inputs/outputs to
+ * remove imbalances, then prove + bind into a submit-ready FinalizedTransaction.
+ *
+ * `sealed` selects the input stage:
+ * - sealed   → Transaction<SignatureEnabled, Proof, Binding>    (FinalizedTransaction)
+ * - unsealed → Transaction<SignatureEnabled, Proof, PreBinding> (UnboundTransaction)
+ *
+ * The prove/finalize tail is the same as {@link buildTransferTransaction}.
+ */
+export declare function balanceTransaction(facade: WalletFacade, keys: WalletKeys, networkId: string, txBytes: Uint8Array, sealed: boolean, onProgress?: (stage: TxStage) => void): Promise<FinalizedTransaction>;
+/**
+ * Build a swap intent (connector `makeIntent`): the wallet's half of a swap,
+ * providing `inputs` (spent) and `outputs` (sent to recipients). Returns the
+ * raw unproven, unbound transaction from the SDK's `initSwap` — deliberately
+ * NOT proven or bound, so the dApp can combine it with the counterparty's half
+ * before the combined transaction is proven, balanced, and submitted.
+ *
+ * NOTE: the connector's `intentId` option is not honored — the SDK's `initSwap`
+ * exposes no segment-id control, so callers cannot pin the intent's id or opt
+ * out of transaction merging.
+ */
+export declare function buildSwapIntent(facade: WalletFacade, keys: WalletKeys, networkId: string, inputs: SwapInput[], outputs: SendRequest[], payFees: boolean, onProgress?: (stage: TxStage) => void): Promise<ledger.UnprovenTransaction>;
+/**
+ * Send tokens via the wallet facade. Convenience wrapper that derives a
+ * WalletKeys bundle from the seed and delegates to
+ * {@link sendTokensWithKeys}. Holds the seed in memory only for the
+ * duration of derivation — used by paths like the in-process `moth
+ * transfer` CLI command that already work in terms of seedHex.
+ */
+export declare function sendTokens(facade: WalletFacade, seedHex: string, networkId: string, requests: SendRequest[], onProgress?: (stage: TxStage) => void): Promise<string>;
+/**
+ * A NIGHT UTXO with its dust-registration status.
+ * `raw` is the underlying SDK object; pass it back to designate/dedesignate.
+ */
+export interface NightUtxo {
+    raw: UtxoWithMeta;
+    value: bigint;
+    registered: boolean;
+}
+/**
+ * List the active wallet's NIGHT UTXOs (registered + unregistered).
+ * Waits for the unshielded sub-wallet to be strict-complete — does NOT gate on
+ * aggregate `isSynced`, which never becomes true for a fresh wallet whose only
+ * activity is unshielded (e.g. a faucet-funded test wallet pre-dust-register).
+ */
+export declare function listNightUtxos(facade: WalletFacade): Promise<NightUtxo[]>;
+/**
+ * Register NIGHT UTXOs for DUST generation, using a pre-derived
+ * WalletKeys bundle (D-KM-3 path — preferred over the seedHex variant
+ * for daemon callers).
+ */
+export declare function designateForDustWithKeys(facade: WalletFacade, keys: WalletKeys, networkId: string, receiver?: string, onProgress?: (stage: TxStage) => void, selectedUtxos?: NightUtxo[]): Promise<string | null>;
+/**
+ * Register NIGHT UTXOs for DUST generation.
+ * If `selectedUtxos` is provided, registers exactly those; otherwise auto-selects
+ * all currently unregistered NIGHT UTXOs.
+ */
+export declare function designateForDust(facade: WalletFacade, seedHex: string, networkId: string, receiver?: string, onProgress?: (stage: TxStage) => void, selectedUtxos?: NightUtxo[]): Promise<string | null>;
+/**
+ * Whether registration can pay its own fee yet, and if not, how long until it
+ * can. Reads state and builds a throwaway transaction for costing; books
+ * nothing and spends nothing.
+ *
+ * Registration is self-funding — it draws on the DUST its NIGHT would have
+ * generated had it been registered all along — but that backdated amount starts
+ * at zero and grows with the NIGHT's age, so a freshly funded wallet cannot
+ * cover the fee yet. Without asking first, the wallet builds, proves, fails on
+ * the SDK's guard, and reports a defect where the honest answer is "not yet, try
+ * in about six minutes". See sync/dust-registration-estimate.ts.
+ */
+export declare function estimateDustRegistration(facade: WalletFacade, selectedUtxos?: NightUtxo[]): Promise<DustRegistrationEstimate>;
+/**
+ * Deregister NIGHT UTXOs from DUST generation, using a pre-derived
+ * WalletKeys bundle (D-KM-3 path).
+ */
+export declare function dedesignateFromDustWithKeys(facade: WalletFacade, keys: WalletKeys, networkId: string, onProgress?: (stage: TxStage) => void, selectedUtxos?: NightUtxo[]): Promise<string>;
+/**
+ * Deregister NIGHT UTXOs from DUST generation.
+ * If `selectedUtxos` is provided, deregisters exactly those; otherwise auto-selects
+ * all currently registered NIGHT UTXOs.
+ */
+export declare function dedesignateFromDust(facade: WalletFacade, seedHex: string, networkId: string, onProgress?: (stage: TxStage) => void, selectedUtxos?: NightUtxo[]): Promise<string>;
+//# sourceMappingURL=operations.d.ts.map

package/dist/sync/operations.d.ts.map

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