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

package/README.md

@@ -21,6 +21,9 @@ Everything is read from the environment:
 | `NETWORK_ID` | Target network: `undeployed` (local stack, the default), `stagenet`, `preview`, `preprod` or `mainnet`. Selects the default endpoints. |
 | `MIDNIGHT_NODE_URL`, `MIDNIGHT_NODE_INDEXER_URL`, `MIDNIGHT_NODE_INDEXER_WS_URL`, `MIDNIGHT_NODE_PROOF_SERVER_URL` | Optional per-endpoint overrides of the network defaults. |
 | `DEPLOYER_SEED` | The deploying wallet's seed (hex or mnemonic). On the local stack it defaults to the pre-funded genesis mint wallet. |
+| `MIDNIGHT_SIGNET_CONTRACT_ADDRESS` | Optional on a deployed network: the signet singleton a requester contract seals at deploy. `resolveSignetContractAddress` takes the singleton `@sig-net/midnight` publishes for the network when it is unset, and refuses a set value that disagrees with it. The local stack publishes none, so there it names the singleton you deployed. |
+| `MPC_SECP256K1_PUBKEY` | Optional on a deployed network: the MPC root public key a requester's derived accounts start from, in SEC1 hex or NEAR `secp256k1:<base58>` form. `resolveMpcRootPublicKey` takes the key `@sig-net/midnight` publishes for the network when it is unset, refuses a set value that disagrees with it, and returns `0x04…` uncompressed hex either way. |
+| `MIDNIGHT_FAUCET_URL` | The faucet named in the unfunded-wallet hint. Built in per network: stagenet `https://faucet.stagenet.shielded.tools`, preview `https://midnight-tmnight-preview.nethermind.dev`, preprod `https://midnight-tmnight-preprod.nethermind.dev`. Set it to override one of those, or to name a faucet for a network without one. |
 
 ## Usage
 
@@ -32,6 +35,8 @@ const { contractAddress, txId } = await deploySignetContract(process.env);
 
 The generic plumbing (network config, wallets, funding, transaction submission) is exported from the package root as well, for deploy scripts of other Compact contracts.
 
+A pipeline that touches several wallets, or one wallet several times, holds them in a `WalletRegistry`: the first request for a seed builds, starts and fully syncs its facade (on a deployed network a fresh facade scans the chain from nothing, and the sync logs a heartbeat with each sub-wallet's position every ten seconds), every later request returns the same running facade, and `close()` stops them all once. `deploySignetContract(env, wallets)` and the funding primitives (`assertRootFunded`, `readAccountFunding`, `fundChildFromRoot`) take the registry. Without one, `deploySignetContract` opens a private registry for its single wallet and closes it after.
+
 ## Deploying from CI
 
 The [sig-net/midnight-integration](https://github.com/sig-net/midnight-integration) repository deploys the singleton through its manually dispatched `deploy` workflow, which picks a network and a release tag and runs this flow on a runner with a local proof server.
@@ -42,7 +47,7 @@ The [sig-net/midnight-integration](https://github.com/sig-net/midnight-integrati
 
 ## Documentation
 
-The deployed contract is the singleton of the [sign bidirectional flow](https://github.com/sig-net/midnight-integration/blob/main/README.md#sign-bidirectional-flow), documented in the [sig-net/midnight-integration README](https://github.com/sig-net/midnight-integration/blob/main/README.md).
+The deployed contract is the singleton of the [sign bidirectional flow](https://github.com/sig-net/midnight-integration/blob/main/README.md#sign-bidirectional-protocol-flow), documented in the [sig-net/midnight-integration README](https://github.com/sig-net/midnight-integration/blob/main/README.md).
 
 ## Related packages
 

package/dist/deploy-signet-contract.d.ts

@@ -1,4 +1,4 @@
-import { type TransactionIdentifier } from "./plumbing/wallet.ts";
+import { type TransactionIdentifier, WalletRegistry } from "./plumbing/wallet.ts";
 /** The outcome of a successful signet-contract deployment. */
 export interface SignetContractDeployment {
     /** Address of the deployed signet contract on Midnight. */
@@ -12,15 +12,19 @@ export interface SignetContractDeployment {
  * logged to the console. The contract takes no constructor arguments. Any
  * funded wallet can deploy, and nothing about the deployer is sealed. The wallet
  * needs NIGHT only: {@link ensureFeeReady} registers it for dust generation
- * and waits for the first spendable DUST when the wallet has none yet.
+ * and waits for the deploy transaction's fee in spendable DUST when the
+ * wallet holds less.
  *
  * @param env - Environment map providing `DEPLOYER_SEED` and the shared
  *   Midnight node configuration (see `getMidnightNodeConfig`).
+ * @param wallets - A registry to take the deployer wallet from, when the caller
+ *   keeps wallets open across steps. Without one, a private registry is opened
+ *   for this deploy and closed after it.
  * @returns The deployed contract address and deploy transaction id.
  * @throws {WalletUnfundedError} If the deployer wallet holds neither NIGHT
  *   nor DUST: the error carries the wallet's NIGHT receive address to fund.
- * @throws {Error} If no spendable DUST appears after registering the wallet's
- *   NIGHT, or submission fails.
+ * @throws {Error} If the deploy's fee does not generate in spendable DUST after
+ *   registering the wallet's NIGHT, or submission fails.
  */
-export declare function deploySignetContract(env?: Record<string, string | undefined>): Promise<SignetContractDeployment>;
+export declare function deploySignetContract(env?: Record<string, string | undefined>, wallets?: WalletRegistry): Promise<SignetContractDeployment>;
 //# sourceMappingURL=deploy-signet-contract.d.ts.map

package/dist/deploy-signet-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deploy-signet-contract.d.ts","sourceRoot":"","sources":["../src/deploy-signet-contract.ts"],"names":[],"mappings":"AAWA,OAAO,EAGL,KAAK,qBAAqB,EAE3B,MAAM,sBAAsB,CAAC;AAM9B,8DAA8D;AAC9D,MAAM,WAAW,wBAAwB;IACvC,2DAA2D;IAC3D,eAAe,EAAE,MAAM,CAAC;IACxB,sDAAsD;IACtD,IAAI,EAAE,qBAAqB,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,OAAO,CAAC,wBAAwB,CAAC,CAqCnC"}
+{"version":3,"file":"deploy-signet-contract.d.ts","sourceRoot":"","sources":["../src/deploy-signet-contract.ts"],"names":[],"mappings":"AAWA,OAAO,EAGL,KAAK,qBAAqB,EAC1B,cAAc,EACf,MAAM,sBAAsB,CAAC;AAM9B,8DAA8D;AAC9D,MAAM,WAAW,wBAAwB;IACvC,2DAA2D;IAC3D,eAAe,EAAE,MAAM,CAAC;IACxB,sDAAsD;IACtD,IAAI,EAAE,qBAAqB,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,EACrD,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,wBAAwB,CAAC,CAyCnC"}

package/dist/deploy-signet-contract.js

@@ -8,7 +8,7 @@
 import { buildDeployTransaction, getDeployConfig } from "./plumbing/deploy.js";
 import { ensureFeeReady } from "./plumbing/funding.js";
 import { getFaucetUrl } from "./plumbing/midnight-node-config.js";
-import { deriveAccountKeys, submitUnprovenTransaction, withSyncedWalletFacade, } from "./plumbing/wallet.js";
+import { estimateUnprovenTransactionFee, submitUnprovenTransaction, WalletRegistry, } from "./plumbing/wallet.js";
 import { createSignetContractPrivateState, signetContractCompiledContract, } from "./signet-contract-binding.js";
 /**
  * Deploy the signet contract: read config from `env`, build and prove the
@@ -16,30 +16,43 @@ import { createSignetContractPrivateState, signetContractCompiledContract, } fro
  * logged to the console. The contract takes no constructor arguments. Any
  * funded wallet can deploy, and nothing about the deployer is sealed. The wallet
  * needs NIGHT only: {@link ensureFeeReady} registers it for dust generation
- * and waits for the first spendable DUST when the wallet has none yet.
+ * and waits for the deploy transaction's fee in spendable DUST when the
+ * wallet holds less.
  *
  * @param env - Environment map providing `DEPLOYER_SEED` and the shared
  *   Midnight node configuration (see `getMidnightNodeConfig`).
+ * @param wallets - A registry to take the deployer wallet from, when the caller
+ *   keeps wallets open across steps. Without one, a private registry is opened
+ *   for this deploy and closed after it.
  * @returns The deployed contract address and deploy transaction id.
  * @throws {WalletUnfundedError} If the deployer wallet holds neither NIGHT
  *   nor DUST: the error carries the wallet's NIGHT receive address to fund.
- * @throws {Error} If no spendable DUST appears after registering the wallet's
- *   NIGHT, or submission fails.
+ * @throws {Error} If the deploy's fee does not generate in spendable DUST after
+ *   registering the wallet's NIGHT, or submission fails.
  */
-export async function deploySignetContract(env = process.env) {
+export async function deploySignetContract(env = process.env, wallets) {
     const deployConfig = getDeployConfig(env);
     const { networkId } = deployConfig.midnightNodeConfig;
-    const accountKeys = deriveAccountKeys(deployConfig.deployerSeed, networkId);
+    const registry = wallets ?? new WalletRegistry(deployConfig.midnightNodeConfig);
     console.log(`deploying signet-contract to ${networkId} (${deployConfig.midnightNodeConfig.nodeUrl})`);
-    const { contractAddress, txId } = await withSyncedWalletFacade(accountKeys, deployConfig.midnightNodeConfig, async (facade, state) => {
-        await ensureFeeReady(facade, accountKeys, state, networkId, getFaucetUrl(env, networkId));
-        const deployTransaction = await buildDeployTransaction(signetContractCompiledContract, networkId, accountKeys.shieldedSecretKeys.coinPublicKey, createSignetContractPrivateState());
+    try {
+        const { facade, keys } = await registry.wallet(deployConfig.deployerSeed, "deployer");
+        const deployTransaction = await buildDeployTransaction(signetContractCompiledContract, networkId, keys.shieldedSecretKeys.coinPublicKey, createSignetContractPrivateState());
         console.log(`contract address (pre-submit): ${deployTransaction.contractAddress}`);
-        const submittedTxId = await submitUnprovenTransaction(facade, accountKeys, deployTransaction.serializedTransaction);
-        return { contractAddress: deployTransaction.contractAddress, txId: submittedTxId };
-    });
-    console.log(`submitted deploy tx ${txId}`);
-    console.log(`deployed signet-contract at ${contractAddress}`);
-    return { contractAddress, txId };
+        // The one transaction this deploy submits, priced before anything is sent.
+        const fee = await estimateUnprovenTransactionFee(facade, deployTransaction.serializedTransaction);
+        console.log(`fee budget: 1 transaction at about ${String(fee)} DUST`);
+        const state = await facade.waitForSyncedState();
+        await ensureFeeReady(facade, keys, state, networkId, getFaucetUrl(env, networkId), fee);
+        const txId = await submitUnprovenTransaction(facade, keys, deployTransaction.serializedTransaction);
+        const { contractAddress } = deployTransaction;
+        console.log(`submitted deploy tx ${txId}`);
+        console.log(`deployed signet-contract at ${contractAddress}`);
+        return { contractAddress, txId };
+    }
+    finally {
+        if (wallets === undefined)
+            await registry.close();
+    }
 }
 //# sourceMappingURL=deploy-signet-contract.js.map

package/dist/deploy-signet-contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"deploy-signet-contract.js","sourceRoot":"","sources":["../src/deploy-signet-contract.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,0EAA0E;AAC1E,0EAA0E;AAC1E,uEAAuE;AACvE,mEAAmE;AACnE,sEAAsE;AACtE,6DAA6D;AAE7D,OAAO,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAClE,OAAO,EACL,iBAAiB,EACjB,yBAAyB,EAEzB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,gCAAgC,EAChC,8BAA8B,GAC/B,MAAM,8BAA8B,CAAC;AAUtC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,GAAG,GAAuC,OAAO,CAAC,GAAG;IAErD,MAAM,YAAY,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IAC1C,MAAM,EAAE,SAAS,EAAE,GAAG,YAAY,CAAC,kBAAkB,CAAC;IAEtD,MAAM,WAAW,GAAG,iBAAiB,CAAC,YAAY,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;IAE5E,OAAO,CAAC,GAAG,CACT,gCAAgC,SAAS,KAAK,YAAY,CAAC,kBAAkB,CAAC,OAAO,GAAG,CACzF,CAAC;IAEF,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,GAAG,MAAM,sBAAsB,CAC5D,WAAW,EACX,YAAY,CAAC,kBAAkB,EAC/B,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE;QACtB,MAAM,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,EAAE,YAAY,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC;QAE1F,MAAM,iBAAiB,GAAG,MAAM,sBAAsB,CACpD,8BAA8B,EAC9B,SAAS,EACT,WAAW,CAAC,kBAAkB,CAAC,aAAa,EAC5C,gCAAgC,EAAE,CACnC,CAAC;QACF,OAAO,CAAC,GAAG,CAAC,kCAAkC,iBAAiB,CAAC,eAAe,EAAE,CAAC,CAAC;QAEnF,MAAM,aAAa,GAAG,MAAM,yBAAyB,CACnD,MAAM,EACN,WAAW,EACX,iBAAiB,CAAC,qBAAqB,CACxC,CAAC;QACF,OAAO,EAAE,eAAe,EAAE,iBAAiB,CAAC,eAAe,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;IACrF,CAAC,CACF,CAAC;IAEF,OAAO,CAAC,GAAG,CAAC,uBAAuB,IAAI,EAAE,CAAC,CAAC;IAC3C,OAAO,CAAC,GAAG,CAAC,+BAA+B,eAAe,EAAE,CAAC,CAAC;IAE9D,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC;AACnC,CAAC"}
+{"version":3,"file":"deploy-signet-contract.js","sourceRoot":"","sources":["../src/deploy-signet-contract.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,0EAA0E;AAC1E,0EAA0E;AAC1E,uEAAuE;AACvE,mEAAmE;AACnE,sEAAsE;AACtE,6DAA6D;AAE7D,OAAO,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAClE,OAAO,EACL,8BAA8B,EAC9B,yBAAyB,EAEzB,cAAc,GACf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,gCAAgC,EAChC,8BAA8B,GAC/B,MAAM,8BAA8B,CAAC;AAUtC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,GAAG,GAAuC,OAAO,CAAC,GAAG,EACrD,OAAwB;IAExB,MAAM,YAAY,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IAC1C,MAAM,EAAE,SAAS,EAAE,GAAG,YAAY,CAAC,kBAAkB,CAAC;IACtD,MAAM,QAAQ,GAAG,OAAO,IAAI,IAAI,cAAc,CAAC,YAAY,CAAC,kBAAkB,CAAC,CAAC;IAEhF,OAAO,CAAC,GAAG,CACT,gCAAgC,SAAS,KAAK,YAAY,CAAC,kBAAkB,CAAC,OAAO,GAAG,CACzF,CAAC;IAEF,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,YAAY,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;QAEtF,MAAM,iBAAiB,GAAG,MAAM,sBAAsB,CACpD,8BAA8B,EAC9B,SAAS,EACT,IAAI,CAAC,kBAAkB,CAAC,aAAa,EACrC,gCAAgC,EAAE,CACnC,CAAC;QACF,OAAO,CAAC,GAAG,CAAC,kCAAkC,iBAAiB,CAAC,eAAe,EAAE,CAAC,CAAC;QAEnF,2EAA2E;QAC3E,MAAM,GAAG,GAAG,MAAM,8BAA8B,CAC9C,MAAM,EACN,iBAAiB,CAAC,qBAAqB,CACxC,CAAC;QACF,OAAO,CAAC,GAAG,CAAC,sCAAsC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACtE,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,kBAAkB,EAAE,CAAC;QAChD,MAAM,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,YAAY,CAAC,GAAG,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,CAAC;QAExF,MAAM,IAAI,GAAG,MAAM,yBAAyB,CAC1C,MAAM,EACN,IAAI,EACJ,iBAAiB,CAAC,qBAAqB,CACxC,CAAC;QACF,MAAM,EAAE,eAAe,EAAE,GAAG,iBAAiB,CAAC;QAC9C,OAAO,CAAC,GAAG,CAAC,uBAAuB,IAAI,EAAE,CAAC,CAAC;QAC3C,OAAO,CAAC,GAAG,CAAC,+BAA+B,eAAe,EAAE,CAAC,CAAC;QAC9D,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC;IACnC,CAAC;YAAS,CAAC;QACT,IAAI,OAAO,KAAK,SAAS;YAAE,MAAM,QAAQ,CAAC,KAAK,EAAE,CAAC;IACpD,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export * from "./deploy-signet-contract.ts";
+export * from "./plumbing/counterparties.ts";
 export * from "./plumbing/deploy.ts";
 export * from "./plumbing/env.ts";
+export * from "./plumbing/format-dust.ts";
 export * from "./plumbing/funding.ts";
 export * from "./plumbing/midnight-node-config.ts";
 export * from "./plumbing/network-id.ts";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oCAAoC,CAAC;AACnD,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,oCAAoC,CAAC;AACnD,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC"}

package/dist/index.js

@@ -5,8 +5,10 @@
 // build/submit) the flow is built from. The plumbing is generic on purpose —
 // any contract package's deploy script composes it.
 export * from "./deploy-signet-contract.js";
+export * from "./plumbing/counterparties.js";
 export * from "./plumbing/deploy.js";
 export * from "./plumbing/env.js";
+export * from "./plumbing/format-dust.js";
 export * from "./plumbing/funding.js";
 export * from "./plumbing/midnight-node-config.js";
 export * from "./plumbing/network-id.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,2EAA2E;AAC3E,0EAA0E;AAC1E,oEAAoE;AACpE,6EAA6E;AAC7E,oDAAoD;AAEpD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oCAAoC,CAAC;AACnD,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,2EAA2E;AAC3E,0EAA0E;AAC1E,oEAAoE;AACpE,6EAA6E;AAC7E,oDAAoD;AAEpD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,oCAAoC,CAAC;AACnD,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC"}

package/dist/plumbing/counterparties.d.ts

@@ -0,0 +1,53 @@
+/** Which source supplied a resolved counterparty value. */
+export declare enum CounterpartyOrigin {
+    /** The environment variable named for it. */
+    Environment = "environment",
+    /** The value this SDK publishes for the network. */
+    Published = "published"
+}
+/** A counterparty value in its canonical spelling, and where it came from. */
+export interface ResolvedCounterparty {
+    readonly value: string;
+    readonly origin: CounterpartyOrigin;
+}
+/**
+ * The signet singleton a requester contract notifies, as 64 lowercase hex
+ * digits: `MIDNIGHT_SIGNET_CONTRACT_ADDRESS` when set (it must agree with the
+ * singleton the SDK publishes for a deployed network), else that published
+ * singleton.
+ *
+ * @param env - The environment to read `NETWORK_ID` and `MIDNIGHT_SIGNET_CONTRACT_ADDRESS` from.
+ * @returns The address and its origin, or undefined when neither source supplies one.
+ * @throws {Error} If the variable is malformed or disagrees with the published singleton.
+ */
+export declare function findSignetContractAddress(env: Record<string, string | undefined>): ResolvedCounterparty | undefined;
+/**
+ * {@link findSignetContractAddress}, failing when neither source supplies one.
+ *
+ * @param env - The environment to read `NETWORK_ID` and `MIDNIGHT_SIGNET_CONTRACT_ADDRESS` from.
+ * @returns The address and its origin.
+ * @throws {Error} If the variable is malformed, disagrees with the published singleton, or
+ *   is unset on a network the SDK publishes no singleton for.
+ */
+export declare function resolveSignetContractAddress(env: Record<string, string | undefined>): ResolvedCounterparty;
+/**
+ * The MPC root public key every client key derivation starts from, as
+ * `0x04…` uncompressed SEC1 hex: `MPC_SECP256K1_PUBKEY` in any spelling
+ * `normaliseSecp256k1PublicKey` accepts when set (it must agree with the key
+ * the SDK publishes for a deployed network), else that published key.
+ *
+ * @param env - The environment to read `NETWORK_ID` and `MPC_SECP256K1_PUBKEY` from.
+ * @returns The key and its origin, or undefined when neither source supplies one.
+ * @throws {Error} If the variable is not a secp256k1 public key or disagrees with the published key.
+ */
+export declare function findMpcRootPublicKey(env: Record<string, string | undefined>): ResolvedCounterparty | undefined;
+/**
+ * {@link findMpcRootPublicKey}, failing when neither source supplies one.
+ *
+ * @param env - The environment to read `NETWORK_ID` and `MPC_SECP256K1_PUBKEY` from.
+ * @returns The key and its origin.
+ * @throws {Error} If the variable is not a secp256k1 public key, disagrees with the published
+ *   key, or is unset on a network the SDK publishes no key for.
+ */
+export declare function resolveMpcRootPublicKey(env: Record<string, string | undefined>): ResolvedCounterparty;
+//# sourceMappingURL=counterparties.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"counterparties.d.ts","sourceRoot":"","sources":["../../src/plumbing/counterparties.ts"],"names":[],"mappings":"AAsBA,2DAA2D;AAC3D,oBAAY,kBAAkB;IAC5B,6CAA6C;IAC7C,WAAW,gBAAgB;IAC3B,oDAAoD;IACpD,SAAS,cAAc;CACxB;AAED,8EAA8E;AAC9E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;CACrC;AA+FD;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,oBAAoB,GAAG,SAAS,CAElC;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,oBAAoB,CAEtB;AAeD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,oBAAoB,GAAG,SAAS,CAElC;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,oBAAoB,CAEtB"}

package/dist/plumbing/counterparties.js

@@ -0,0 +1,143 @@
+// The two protocol counterparty values a requester contract seals for good:
+// the signet singleton it notifies (a deploy-time constructor argument) and
+// the MPC root public key its derived accounts start from (pinned at
+// initialise). On a deployed network this SDK publishes both, so a deploy
+// needs neither in its environment, and a value that IS set is checked
+// against the published one: a mismatch would seal an address the real MPC
+// never answers or a key it never signs under. The local standalone stack
+// publishes nothing: its setup deploys a singleton and generates a root key
+// per stack, and passes them through the same environment variables.
+import { getMpcRootPublicKey, getSignetContractAddress, normaliseSecp256k1PublicKey, stripHexPrefix, } from "@sig-net/midnight";
+import { envOrUndefined } from "./env.js";
+import { getMidnightNodeConfig } from "./midnight-node-config.js";
+import { deployedNetwork } from "./network-id.js";
+/** Which source supplied a resolved counterparty value. */
+export var CounterpartyOrigin;
+(function (CounterpartyOrigin) {
+    /** The environment variable named for it. */
+    CounterpartyOrigin["Environment"] = "environment";
+    /** The value this SDK publishes for the network. */
+    CounterpartyOrigin["Published"] = "published";
+})(CounterpartyOrigin || (CounterpartyOrigin = {}));
+/**
+ * The SDK's published value for a network.
+ *
+ * @param networkId - The network the run resolved.
+ * @param lookup - The published-value lookup (`getSignetContractAddress`, `getMpcRootPublicKey`).
+ * @returns The value, or undefined for the local stack and for a deployed network the SDK
+ *   holds no value for yet (the lookup throws there, and "not published yet" is a normal
+ *   state for a young network).
+ */
+function published(networkId, lookup) {
+    const network = deployedNetwork(networkId);
+    if (network === undefined)
+        return undefined;
+    try {
+        return lookup(network);
+    }
+    catch {
+        return undefined;
+    }
+}
+function find(env, spec) {
+    const { networkId } = getMidnightNodeConfig(env);
+    const supplied = envOrUndefined(env, spec.envVar);
+    const fromEnvironment = supplied === undefined ? undefined : spec.canonicalise(supplied);
+    const publishedRaw = published(networkId, spec.lookup);
+    const fromSdk = publishedRaw === undefined ? undefined : spec.canonicalise(publishedRaw);
+    if (fromEnvironment !== undefined && fromSdk !== undefined && fromEnvironment !== fromSdk) {
+        throw new Error(`${spec.envVar} (${fromEnvironment}) disagrees with ${spec.noun} the SDK publishes for ` +
+            `"${networkId}" (${fromSdk}). ${spec.disagreementConsequence}`);
+    }
+    if (fromEnvironment !== undefined) {
+        return { value: fromEnvironment, origin: CounterpartyOrigin.Environment };
+    }
+    if (fromSdk !== undefined) {
+        return { value: fromSdk, origin: CounterpartyOrigin.Published };
+    }
+    return undefined;
+}
+function resolve(env, spec) {
+    const found = find(env, spec);
+    if (found !== undefined)
+        return found;
+    const { networkId } = getMidnightNodeConfig(env);
+    const remedy = deployedNetwork(networkId) === undefined
+        ? spec.localStackRemedy
+        : `the SDK publishes no ${spec.noun.replace(/^the /, "")} for it yet`;
+    throw new Error(`${spec.envVar} is required on "${networkId}": ${remedy}.`);
+}
+const SIGNET_CONTRACT_ADDRESS = {
+    envVar: "MIDNIGHT_SIGNET_CONTRACT_ADDRESS",
+    noun: "the signet singleton",
+    lookup: getSignetContractAddress,
+    canonicalise: (value) => {
+        const digits = stripHexPrefix(value);
+        if (!/^[0-9a-fA-F]{64}$/.test(digits)) {
+            throw new Error(`MIDNIGHT_SIGNET_CONTRACT_ADDRESS is not a 32-byte contract address in hex: "${value}"`);
+        }
+        return digits.toLowerCase();
+    },
+    disagreementConsequence: "The real MPC answers only the published one, and a requester seals the address at deploy: " +
+        "reconcile them before deploying.",
+    localStackRemedy: "deploy one with deploySignetContract and set its address",
+};
+/**
+ * The signet singleton a requester contract notifies, as 64 lowercase hex
+ * digits: `MIDNIGHT_SIGNET_CONTRACT_ADDRESS` when set (it must agree with the
+ * singleton the SDK publishes for a deployed network), else that published
+ * singleton.
+ *
+ * @param env - The environment to read `NETWORK_ID` and `MIDNIGHT_SIGNET_CONTRACT_ADDRESS` from.
+ * @returns The address and its origin, or undefined when neither source supplies one.
+ * @throws {Error} If the variable is malformed or disagrees with the published singleton.
+ */
+export function findSignetContractAddress(env) {
+    return find(env, SIGNET_CONTRACT_ADDRESS);
+}
+/**
+ * {@link findSignetContractAddress}, failing when neither source supplies one.
+ *
+ * @param env - The environment to read `NETWORK_ID` and `MIDNIGHT_SIGNET_CONTRACT_ADDRESS` from.
+ * @returns The address and its origin.
+ * @throws {Error} If the variable is malformed, disagrees with the published singleton, or
+ *   is unset on a network the SDK publishes no singleton for.
+ */
+export function resolveSignetContractAddress(env) {
+    return resolve(env, SIGNET_CONTRACT_ADDRESS);
+}
+const MPC_ROOT_PUBLIC_KEY = {
+    envVar: "MPC_SECP256K1_PUBKEY",
+    noun: "the MPC root public key",
+    lookup: getMpcRootPublicKey,
+    canonicalise: normaliseSecp256k1PublicKey,
+    disagreementConsequence: "One of the two is wrong, and the key is sealed into every derived account: reconcile them " +
+        "before deploying.",
+    localStackRemedy: "set it to the root public key of the MPC facing this stack (a fakenet derives it from its " +
+        "MPC_ROOT_KEY)",
+};
+/**
+ * The MPC root public key every client key derivation starts from, as
+ * `0x04…` uncompressed SEC1 hex: `MPC_SECP256K1_PUBKEY` in any spelling
+ * `normaliseSecp256k1PublicKey` accepts when set (it must agree with the key
+ * the SDK publishes for a deployed network), else that published key.
+ *
+ * @param env - The environment to read `NETWORK_ID` and `MPC_SECP256K1_PUBKEY` from.
+ * @returns The key and its origin, or undefined when neither source supplies one.
+ * @throws {Error} If the variable is not a secp256k1 public key or disagrees with the published key.
+ */
+export function findMpcRootPublicKey(env) {
+    return find(env, MPC_ROOT_PUBLIC_KEY);
+}
+/**
+ * {@link findMpcRootPublicKey}, failing when neither source supplies one.
+ *
+ * @param env - The environment to read `NETWORK_ID` and `MPC_SECP256K1_PUBKEY` from.
+ * @returns The key and its origin.
+ * @throws {Error} If the variable is not a secp256k1 public key, disagrees with the published
+ *   key, or is unset on a network the SDK publishes no key for.
+ */
+export function resolveMpcRootPublicKey(env) {
+    return resolve(env, MPC_ROOT_PUBLIC_KEY);
+}
+//# sourceMappingURL=counterparties.js.map

package/dist/plumbing/counterparties.js.map

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

package/dist/plumbing/format-dust.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Format SPECKs as DUST with all 15 decimal places preserved when significant.
+ *
+ * @param specks - The amount in atomic DUST units.
+ * @returns The decimal DUST amount, without a unit suffix.
+ */
+export declare function formatDust(specks: bigint): string;
+//# sourceMappingURL=format-dust.d.ts.map

package/dist/plumbing/format-dust.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-dust.d.ts","sourceRoot":"","sources":["../../src/plumbing/format-dust.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKjD"}

package/dist/plumbing/format-dust.js

@@ -0,0 +1,14 @@
+/**
+ * Format SPECKs as DUST with all 15 decimal places preserved when significant.
+ *
+ * @param specks - The amount in atomic DUST units.
+ * @returns The decimal DUST amount, without a unit suffix.
+ */
+export function formatDust(specks) {
+    const magnitude = (specks < 0n ? -specks : specks).toString().padStart(16, "0");
+    let fraction = magnitude.slice(-15);
+    while (fraction.endsWith("0"))
+        fraction = fraction.slice(0, -1);
+    return `${specks < 0n ? "-" : ""}${magnitude.slice(0, -15)}${fraction ? `.${fraction}` : ""}`;
+}
+//# sourceMappingURL=format-dust.js.map

package/dist/plumbing/format-dust.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-dust.js","sourceRoot":"","sources":["../../src/plumbing/format-dust.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,MAAc;IACvC,MAAM,SAAS,GAAW,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IACxF,IAAI,QAAQ,GAAW,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;IAC5C,OAAO,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAChE,OAAO,GAAG,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;AAChG,CAAC"}

package/dist/plumbing/funding.d.ts

@@ -1,6 +1,6 @@
 import type { MidnightNodeConfig } from "./midnight-node-config.ts";
 import { type NetworkId } from "./network-id.ts";
-import { type AccountKeys, type FacadeState, type WalletAddresses, type WalletFacade } from "./wallet.ts";
+import { type AccountKeys, type FacadeState, type WalletAddresses, type WalletFacade, type WalletRegistry } from "./wallet.ts";
 /** A wallet's synced funding snapshot: its addresses and NIGHT/DUST balances (base units). */
 export interface AccountFunding {
     /** The wallet's three bech32m addresses (network-prefixed). */
@@ -20,20 +20,23 @@ export interface AccountFunding {
  */
 export declare function deriveWalletAddresses(seed: string, config: MidnightNodeConfig): WalletAddresses;
 /**
- * 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 declare function readAccountFunding(config: MidnightNodeConfig, seed: string): Promise<AccountFunding>;
+export declare function readAccountFunding(wallets: WalletRegistry, seed: string, label: string): Promise<AccountFunding>;
 /**
- * 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 declare function isFeeReady(funding: AccountFunding): boolean;
+export declare function isFeeReady(funding: AccountFunding, minimumDust?: bigint): boolean;
 /**
  * A wallet holds no NIGHT and no DUST, so it cannot pay fees until its NIGHT
  * receive address is funded (on a deployed network, via the network's
@@ -56,10 +59,14 @@ export declare 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.
@@ -67,12 +74,14 @@ export declare 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 declare function ensureFeeReady(facade: WalletFacade, keys: AccountKeys, state: FacadeState, networkId: NetworkId, faucetUrl?: string): Promise<bigint>;
+export declare function ensureFeeReady(facade: WalletFacade, keys: AccountKeys, state: FacadeState, networkId: NetworkId, faucetUrl?: string, minimumDust?: bigint, timeoutMs?: number): Promise<bigint>;
 /**
  * Ensure the root wallet is fee-ready, returning its snapshot. Root holds no
  * NIGHT on a deployed network before faucet funding, so this throws
@@ -84,7 +93,7 @@ export declare function ensureFeeReady(facade: WalletFacade, keys: AccountKeys,
  * {@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.
@@ -93,20 +102,21 @@ export declare function ensureFeeReady(facade: WalletFacade, keys: AccountKeys,
  *   {@link waitForSpendableDust}): root is funded but not yet fee-ready, so
  *   this is a plain error, not a funding stop.
  */
-export declare function assertRootFunded(config: MidnightNodeConfig, rootSeed: string, faucetUrl: string | undefined): Promise<AccountFunding>;
+export declare function assertRootFunded(wallets: WalletRegistry, rootSeed: string, faucetUrl: string | undefined): Promise<AccountFunding>;
 /**
  * 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 declare function fundChildFromRoot(config: MidnightNodeConfig, rootSeed: string, childSeed: string, amount: bigint): Promise<AccountFunding>;
+export declare function fundChildFromRoot(wallets: WalletRegistry, rootSeed: string, childSeed: string, childLabel: string, amount: bigint, minimumDust?: bigint): Promise<AccountFunding>;
 //# sourceMappingURL=funding.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"funding.d.ts","sourceRoot":"","sources":["../../src/plumbing/funding.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAA4B,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC3E,OAAO,EACL,KAAK,WAAW,EAGhB,KAAK,WAAW,EAIhB,KAAK,eAAe,EACpB,KAAK,YAAY,EAElB,MAAM,aAAa,CAAC;AAErB,8FAA8F;AAC9F,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAYD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,eAAe,CAE/F;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,kBAAkB,EAC1B,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,cAAc,CAAC,CAUzB;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAE3D;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAM1C,QAAQ,CAAC,YAAY,EAAE,MAAM;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS;IANxC;;;OAGG;IACH,YACW,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAAG,SAAS,EASvC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,SAAS,EACpB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAajB;AASD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,OAAO,CAAC,cAAc,CAAC,CAmBzB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,cAAc,CAAC,CAqCzB"}
+{"version":3,"file":"funding.d.ts","sourceRoot":"","sources":["../../src/plumbing/funding.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAA4B,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC3E,OAAO,EACL,KAAK,WAAW,EAGhB,KAAK,WAAW,EAIhB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,cAAc,EACpB,MAAM,aAAa,CAAC;AAKrB,8FAA8F;AAC9F,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAYD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,eAAe,CAE/F;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,cAAc,CAAC,CAQzB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,cAAc,EAAE,WAAW,SAAK,GAAG,OAAO,CAE7E;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAM1C,QAAQ,CAAC,YAAY,EAAE,MAAM;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS;IANxC;;;OAGG;IACH,YACW,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAAG,SAAS,EASvC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,SAAS,EACpB,SAAS,CAAC,EAAE,MAAM,EAClB,WAAW,SAAK,EAChB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAejB;AASD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,OAAO,CAAC,cAAc,CAAC,CAmBzB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,WAAW,SAAK,GACf,OAAO,CAAC,cAAc,CAAC,CA6CzB"}