@mysten-incubation/devstack 0.0.1 → 0.1.0

package/dist/plugins/account/codegen.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"codegen.mjs","names":[],"sources":["../../../src/plugins/account/codegen.ts"],"sourcesContent":["// Account plugin — Codegenable contribution.\n//\n// Architecture §6 + 12-account.md \"Cross-component references\":\n// Codegen emits a constant address map keyed by account name so\n// downstream code can `import { accounts } from '<staged>/accounts'`\n// and read `accounts.alice.address` at the type level.\n//\n// Distilled-doc tension (12-account.md \"publicKey caveat\"):\n// impersonation accounts have a zero-buffer publicKey — emitting it\n// into the codegen bindings would be a type-level lie. The emitted\n// shape below carries the `source` discriminator INSTEAD of\n// publicKey; consumers branch on `source: 'impersonate'` rather than\n// publicKey-truthiness.\n//\n// SAFETY: the codegen output never emits secret material. Only the\n// `name`, `address`, `scheme`, and `source` fields land on disk.\n// `sensitive: false` is correct because none of these are secret.\n\nimport { Effect } from 'effect';\n\nimport type { CodegenableDecl } from '../../contracts/codegenable.ts';\n\n/** The typed shape the emitted file exports. Per-account record keyed\n *  by name. */\nexport interface AccountBindings {\n\treadonly name: string;\n\treadonly address: string;\n\treadonly scheme: 'ed25519' | 'secp256k1' | 'secp256r1';\n\treadonly source: 'real' | 'impersonate';\n}\n\n/** Construct the Codegenable contribution. One emit per account.\n *\n *  The emitter name is `account/${name}` (literal) so multiple\n *  accounts in a single stack get co-located but typed-distinct\n *  emissions; the codegen orchestrator can fold them into a single\n *  `accounts` namespace at staging time. */\nexport const makeAccountCodegen = <Name extends string>(parts: {\n\treadonly name: Name;\n\treadonly resolved: AccountBindings;\n}): CodegenableDecl<`account/${Name}`> => ({\n\tkind: 'codegenable',\n\temitterName: `account/${parts.name}` as `account/${Name}`,\n\toutputPath: `accounts/${parts.name}.ts`,\n\tsensitive: false,\n\temit: (ctx) =>\n\t\tEffect.sync(() => {\n\t\t\tctx.exportConst(parts.name, parts.resolved);\n\t\t\treturn ctx.done();\n\t\t}),\n});\n"],"mappings":";;;;;;;;AAqCA,MAAa,sBAA2C,WAGb;CAC1C,MAAM;CACN,aAAa,WAAW,MAAM;CAC9B,YAAY,YAAY,MAAM,KAAK;CACnC,WAAW;CACX,OAAO,QACN,OAAO,WAAW;AACjB,MAAI,YAAY,MAAM,MAAM,MAAM,SAAS;AAC3C,SAAO,IAAI,MAAM;GAChB;CACH"}
+{"version":3,"file":"codegen.mjs","names":[],"sources":["../../../src/plugins/account/codegen.ts"],"sourcesContent":["// Account plugin — Codegenable contribution.\n//\n// Architecture §6 + 12-account.md \"Cross-component references\":\n// Codegen emits a constant address map keyed by account name so\n// downstream code can `import { accounts } from '<staged>/accounts'`\n// and read `accounts.alice.address` at the type level.\n//\n// Distilled-doc tension (12-account.md \"publicKey caveat\"):\n// impersonation accounts have a zero-buffer publicKey — emitting it\n// into the codegen bindings would be a type-level lie. The emitted\n// shape below carries the `source` discriminator INSTEAD of\n// publicKey; consumers branch on `source: 'impersonate'` rather than\n// publicKey-truthiness.\n//\n// SAFETY: the codegen output never emits secret material. Only the\n// `name`, `address`, `scheme`, and `source` fields land on disk.\n// `sensitive: false` is correct because none of these are secret.\n\nimport type { CodegenableDecl } from '../../contracts/codegenable.ts';\n\nimport { defineSimpleConstExport } from '../internal/codegen-helpers.ts';\n\n/** The typed shape the emitted file exports. Per-account record keyed\n *  by name. */\nexport interface AccountBindings {\n\treadonly name: string;\n\treadonly address: string;\n\treadonly scheme: 'ed25519' | 'secp256k1' | 'secp256r1';\n\treadonly source: 'real' | 'impersonate';\n}\n\n/** Construct the Codegenable contribution. One emit per account.\n *\n *  The emitter name is `account/${name}` (literal) so multiple\n *  accounts in a single stack get co-located but typed-distinct\n *  emissions; the codegen orchestrator can fold them into a single\n *  `accounts` namespace at staging time. */\nexport const makeAccountCodegen = <Name extends string>(parts: {\n\treadonly name: Name;\n\treadonly resolved: AccountBindings;\n}): CodegenableDecl<`account/${Name}`> =>\n\tdefineSimpleConstExport({\n\t\temitterName: `account/${parts.name}` as `account/${Name}`,\n\t\toutputPath: `accounts/${parts.name}.ts`,\n\t\texportName: parts.name,\n\t\tvalue: parts.resolved,\n\t\taggregate: {\n\t\t\tkind: 'account',\n\t\t\tbucket: 'accounts.ts',\n\t\t\t// Pass-through: this decl's exported map already keys by\n\t\t\t// account name, which is the aggregate's merge key.\n\t\t\tproject: (exported) => exported,\n\t\t},\n\t});\n"],"mappings":";;;;;;;;AAqCA,MAAa,sBAA2C,UAIvD,wBAAwB;CACvB,aAAa,WAAW,MAAM;CAC9B,YAAY,YAAY,MAAM,KAAK;CACnC,YAAY,MAAM;CAClB,OAAO,MAAM;CACb,WAAW;EACV,MAAM;EACN,QAAQ;EAGR,UAAU,aAAa;EACvB;CACD,CAAC"}

package/dist/plugins/account/errors.d.mts

@@ -1,7 +1,7 @@
 //#region src/plugins/account/errors.d.ts
 /** Phases for `AccountAcquireError`. Closed sum — adding a phase
  *  requires editing this list AND the cause-walker's display table. */
-type AccountAcquirePhase = 'validate-name' | 'load-keystore' | 'read-env' | 'decode-inline' | 'bind-signer' | 'bind-impersonation-slot' | 'generate-keypair' | 'persist-keypair' | 'read-persisted-keypair' | 'restrict-permissions' | 'derive-address' | 'unsupported-scheme' | 'await-chain-ready' | 'fund-default' | 'fund-cross-cutting' | 'register';
+type AccountAcquirePhase = 'validate-name' | 'validate-funding' | 'load-keystore' | 'read-env' | 'decode-inline' | 'bind-signer' | 'bind-impersonation-slot' | 'generate-keypair' | 'persist-keypair' | 'read-persisted-keypair' | 'restrict-permissions' | 'derive-address' | 'unsupported-scheme' | 'await-chain-ready' | 'fund-default' | 'fund-cross-cutting' | 'register';
 /** Account acquisition error — raised by the variant resolvers and
  *  the funding pass. Carries the per-variant + per-phase column. */
 interface AccountAcquireError {
@@ -13,11 +13,38 @@ interface AccountAcquireError {
   readonly hint?: string;
   readonly cause?: unknown;
 }
-/** Phases for `AccountSignError`. The "sign-and-execute" surface is
- *  the canonical entry point; the impersonation refusal lives here
- *  so a synchronous throw maps cleanly onto an async catch boundary
- *  when callers wrap the resolved-account signer in `Effect.try`. */
-type AccountSignPhase = 'build-tx' | 'sign' | 'submit' | 'await-finality' | 'dependent-package-not-found' | 'lease-acquire' | 'impersonation-bypass-attempt';
+/** Phases for `AccountSignError`. Strictly transport / lifecycle
+ *  failures along the sign-and-execute pipeline — `signAndExecute`
+ *  itself returns a `SignAndExecuteResult` discriminated union for
+ *  the on-chain outcome (success vs `FailedTransaction`), so
+ *  on-chain failures are NOT in this phase set. The impersonation
+ *  refusal lives here so a synchronous throw maps cleanly onto an
+ *  async catch boundary when callers wrap the resolved-account
+ *  signer in `Effect.try`.
+ *
+ *   - `build-tx`         — transaction serialisation threw before
+ *                          signing.
+ *   - `sign`             — the signer rejected / threw.
+ *   - `submit`           — `executeTransaction` transport failure
+ *                          (RPC unreachable, network error). The
+ *                          response never arrived.
+ *   - `no-digest`        — `executeTransaction` returned a response
+ *                          that violates the SDK envelope contract
+ *                          (`$kind` missing OR `Transaction.digest`
+ *                          missing OR `FailedTransaction.digest`
+ *                          missing). Protocol violation, not a
+ *                          transport failure — kept distinct so
+ *                          `'submit'` keeps a single failure-kind
+ *                          (per §2 "phases describe steps, not
+ *                          failure kinds").
+ *   - `await-finality`   — `waitForTransaction` failed AFTER a
+ *                          submit-success; the digest exists but the
+ *                          finality wait broke.
+ *   - `dependent-package-not-found`
+ *   - `lease-acquire`
+ *   - `impersonation-bypass-attempt`
+ */
+type AccountSignPhase = 'build-tx' | 'sign' | 'submit' | 'no-digest' | 'await-finality' | 'dependent-package-not-found' | 'lease-acquire' | 'impersonation-bypass-attempt';
 /** Account sign/execute error — raised by the per-account signer's
  *  `signAndExecute` / `signTransaction` / `signPersonalMessage`
  *  surfaces.

package/dist/plugins/account/errors.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"errors.mjs","names":[],"sources":["../../../src/plugins/account/errors.ts"],"sourcesContent":["// Account plugin — typed errors.\n//\n// Distilled-doc finding (12-account.md \"Acquisition vs signing error\n// split\" invariant): two error families must not be mixed. Acquisition\n// errors (keystore unreadable, faucet exhausted, scheme unsupported)\n// surface as `AccountAcquireError`; signing errors (gRPC failure,\n// finality wait, locked-shared-object) surface as `AccountSignError`.\n// Mixing them breaks downstream `catchTag` boundaries — the engine's\n// pretty-cause walker also dispatches on `_tag`, so any merger here\n// would force a renderer-side branch on `phase` instead.\n//\n// Effect v4: plain interface + `_tag` literal discriminator (no\n// subclassing). The architecture's per-plugin tagged-error convention\n// (12-account.md \"Promote the sign/execute error to the same\n// tagged-error class shape\") is honored here — both errors are\n// uniform-shape, the cause walker handles them by `_tag`.\n\n/** Phases for `AccountAcquireError`. Closed sum — adding a phase\n *  requires editing this list AND the cause-walker's display table. */\nexport type AccountAcquirePhase =\n\t| 'validate-name'\n\t| 'load-keystore'\n\t| 'read-env'\n\t| 'decode-inline'\n\t| 'bind-signer'\n\t| 'bind-impersonation-slot'\n\t| 'generate-keypair'\n\t| 'persist-keypair'\n\t| 'read-persisted-keypair'\n\t| 'restrict-permissions'\n\t| 'derive-address'\n\t| 'unsupported-scheme'\n\t| 'await-chain-ready'\n\t| 'fund-default'\n\t| 'fund-cross-cutting'\n\t| 'register';\n\n/** Account acquisition error — raised by the variant resolvers and\n *  the funding pass. Carries the per-variant + per-phase column. */\nexport interface AccountAcquireError {\n\treadonly _tag: 'AccountAcquireError';\n\treadonly phase: AccountAcquirePhase;\n\treadonly accountName: string;\n\treadonly variant: AccountVariantKind;\n\treadonly message: string;\n\treadonly hint?: string;\n\treadonly cause?: unknown;\n}\n\nexport const accountAcquireError = (\n\tparts: Omit<AccountAcquireError, '_tag'>,\n): AccountAcquireError => ({ _tag: 'AccountAcquireError', ...parts });\n\n/** Phases for `AccountSignError`. The \"sign-and-execute\" surface is\n *  the canonical entry point; the impersonation refusal lives here\n *  so a synchronous throw maps cleanly onto an async catch boundary\n *  when callers wrap the resolved-account signer in `Effect.try`. */\nexport type AccountSignPhase =\n\t| 'build-tx'\n\t| 'sign'\n\t| 'submit'\n\t| 'await-finality'\n\t| 'dependent-package-not-found'\n\t| 'lease-acquire'\n\t| 'impersonation-bypass-attempt';\n\n/** Account sign/execute error — raised by the per-account signer's\n *  `signAndExecute` / `signTransaction` / `signPersonalMessage`\n *  surfaces.\n *\n *  Distilled-doc opportunity: today's implementation projects this to\n *  JSON specially. Promoting to the uniform-shape interface here lets\n *  the cause walker treat it like every other plugin's tagged error;\n *  the special JSON-projection case can go away. */\nexport interface AccountSignError {\n\treadonly _tag: 'AccountSignError';\n\treadonly phase: AccountSignPhase;\n\treadonly accountName: string;\n\treadonly address: string;\n\treadonly message: string;\n\treadonly cause?: unknown;\n}\n\nexport const accountSignError = (parts: Omit<AccountSignError, '_tag'>): AccountSignError => ({\n\t_tag: 'AccountSignError',\n\t...parts,\n});\n\n/** Account variant discriminator. Mirrors the user-facing\n *  `AccountOptions` shape's `kind:` field. */\nexport type AccountVariantKind =\n\t| 'ephemeral'\n\t| 'keystore'\n\t| 'env'\n\t| 'inline'\n\t| 'signer'\n\t| 'impersonate';\n\n/** Union of every error an Account-plugin caller may encounter. */\nexport type AccountError = AccountAcquireError | AccountSignError;\n\n/** Error tags this plugin contributes — surfaced to the cause walker\n *  via `PluginErrorContribution`. */\nexport const ACCOUNT_ERROR_TAGS: ReadonlyArray<AccountError['_tag']> = [\n\t'AccountAcquireError',\n\t'AccountSignError',\n] as const;\n"],"mappings":";AAiDA,MAAa,uBACZ,WAC0B;CAAE,MAAM;CAAuB,GAAG;CAAO;AAgCpE,MAAa,oBAAoB,WAA6D;CAC7F,MAAM;CACN,GAAG;CACH;;;AAiBD,MAAa,qBAA0D,CACtE,uBACA,mBACA"}
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../../src/plugins/account/errors.ts"],"sourcesContent":["// Account plugin — typed errors.\n//\n// Distilled-doc finding (12-account.md \"Acquisition vs signing error\n// split\" invariant): two error families must not be mixed. Acquisition\n// errors (keystore unreadable, faucet exhausted, scheme unsupported)\n// surface as `AccountAcquireError`; signing errors (gRPC failure,\n// finality wait, locked-shared-object) surface as `AccountSignError`.\n// Mixing them breaks downstream `catchTag` boundaries — the engine's\n// pretty-cause walker also dispatches on `_tag`, so any merger here\n// would force a renderer-side branch on `phase` instead.\n//\n// Effect v4: plain interface + `_tag` literal discriminator (no\n// subclassing). The architecture's per-plugin tagged-error convention\n// (12-account.md \"Promote the sign/execute error to the same\n// tagged-error class shape\") is honored here — both errors are\n// uniform-shape, the cause walker handles them by `_tag`.\n\n/** Phases for `AccountAcquireError`. Closed sum — adding a phase\n *  requires editing this list AND the cause-walker's display table. */\nexport type AccountAcquirePhase =\n\t| 'validate-name'\n\t| 'validate-funding'\n\t| 'load-keystore'\n\t| 'read-env'\n\t| 'decode-inline'\n\t| 'bind-signer'\n\t| 'bind-impersonation-slot'\n\t| 'generate-keypair'\n\t| 'persist-keypair'\n\t| 'read-persisted-keypair'\n\t| 'restrict-permissions'\n\t| 'derive-address'\n\t| 'unsupported-scheme'\n\t| 'await-chain-ready'\n\t| 'fund-default'\n\t| 'fund-cross-cutting'\n\t| 'register';\n\n/** Account acquisition error — raised by the variant resolvers and\n *  the funding pass. Carries the per-variant + per-phase column. */\nexport interface AccountAcquireError {\n\treadonly _tag: 'AccountAcquireError';\n\treadonly phase: AccountAcquirePhase;\n\treadonly accountName: string;\n\treadonly variant: AccountVariantKind;\n\treadonly message: string;\n\treadonly hint?: string;\n\treadonly cause?: unknown;\n}\n\nexport const accountAcquireError = (\n\tparts: Omit<AccountAcquireError, '_tag'>,\n): AccountAcquireError => ({ _tag: 'AccountAcquireError', ...parts });\n\n/** Phases for `AccountSignError`. Strictly transport / lifecycle\n *  failures along the sign-and-execute pipeline — `signAndExecute`\n *  itself returns a `SignAndExecuteResult` discriminated union for\n *  the on-chain outcome (success vs `FailedTransaction`), so\n *  on-chain failures are NOT in this phase set. The impersonation\n *  refusal lives here so a synchronous throw maps cleanly onto an\n *  async catch boundary when callers wrap the resolved-account\n *  signer in `Effect.try`.\n *\n *   - `build-tx`         — transaction serialisation threw before\n *                          signing.\n *   - `sign`             — the signer rejected / threw.\n *   - `submit`           — `executeTransaction` transport failure\n *                          (RPC unreachable, network error). The\n *                          response never arrived.\n *   - `no-digest`        — `executeTransaction` returned a response\n *                          that violates the SDK envelope contract\n *                          (`$kind` missing OR `Transaction.digest`\n *                          missing OR `FailedTransaction.digest`\n *                          missing). Protocol violation, not a\n *                          transport failure — kept distinct so\n *                          `'submit'` keeps a single failure-kind\n *                          (per §2 \"phases describe steps, not\n *                          failure kinds\").\n *   - `await-finality`   — `waitForTransaction` failed AFTER a\n *                          submit-success; the digest exists but the\n *                          finality wait broke.\n *   - `dependent-package-not-found`\n *   - `lease-acquire`\n *   - `impersonation-bypass-attempt`\n */\nexport type AccountSignPhase =\n\t| 'build-tx'\n\t| 'sign'\n\t| 'submit'\n\t| 'no-digest'\n\t| 'await-finality'\n\t| 'dependent-package-not-found'\n\t| 'lease-acquire'\n\t| 'impersonation-bypass-attempt';\n\n/** Account sign/execute error — raised by the per-account signer's\n *  `signAndExecute` / `signTransaction` / `signPersonalMessage`\n *  surfaces.\n *\n *  Distilled-doc opportunity: today's implementation projects this to\n *  JSON specially. Promoting to the uniform-shape interface here lets\n *  the cause walker treat it like every other plugin's tagged error;\n *  the special JSON-projection case can go away. */\nexport interface AccountSignError {\n\treadonly _tag: 'AccountSignError';\n\treadonly phase: AccountSignPhase;\n\treadonly accountName: string;\n\treadonly address: string;\n\treadonly message: string;\n\treadonly cause?: unknown;\n}\n\nexport const accountSignError = (parts: Omit<AccountSignError, '_tag'>): AccountSignError => ({\n\t_tag: 'AccountSignError',\n\t...parts,\n});\n\n/** Account variant discriminator. Mirrors the user-facing\n *  `AccountOptions` shape's `kind:` field. */\nexport type AccountVariantKind =\n\t| 'ephemeral'\n\t| 'keystore'\n\t| 'env'\n\t| 'inline'\n\t| 'signer'\n\t| 'impersonate';\n\n/** Union of every error an Account-plugin caller may encounter. */\nexport type AccountError = AccountAcquireError | AccountSignError;\n\n/** Error tags this plugin contributes — surfaced to the cause walker\n *  via `PluginErrorContribution`. */\nexport const ACCOUNT_ERROR_TAGS: ReadonlyArray<AccountError['_tag']> = [\n\t'AccountAcquireError',\n\t'AccountSignError',\n] as const;\n"],"mappings":";AAkDA,MAAa,uBACZ,WAC0B;CAAE,MAAM;CAAuB,GAAG;CAAO;AA4DpE,MAAa,oBAAoB,WAA6D;CAC7F,MAAM;CACN,GAAG;CACH;;;AAiBD,MAAa,qBAA0D,CACtE,uBACA,mBACA"}

package/dist/plugins/account/funding.d.mts

@@ -1,9 +1,10 @@
 import { AnyResourceRef, ResourceRef } from "../../substrate/plugin.mjs";
-import { CoinResourceId } from "../coin/index.mjs";
+import { AccountFundingRequest as AccountFundingRequest$1, AccountFundingStrategy as AccountFundingStrategy$1 } from "../../contracts/funding-strategy.mjs";
 import { AccountValue } from "./service.mjs";
 import { Effect } from "effect";
 
 //#region src/plugins/account/funding.d.ts
+type CoinResourceId<Sym extends string> = `coin:${Sym}`;
 /** Direct resource ref shape for a coin upstream. The user passes the
  *  result of `coin.fromPackage(...)` / `coin.known(...)` /
  *  `coin.builtin(...)` — NOT a bare string or discriminator. Generic
@@ -59,26 +60,35 @@ interface ProjectedFundingEntry {
   readonly amount: bigint;
 }
 type ProjectedFunding = ReadonlyArray<ProjectedFundingEntry>;
+/** Outcome marker carried on each `applied` entry — distinguishes a
+ *  faucet/strategy call that actually moved funds (`'funded'`) from
+ *  the short-circuit case where the existing balance already covered
+ *  the request (`'already-satisfied'`). Downstream projection turns
+ *  this into the `AccountRegistryFundingEntry.status` column so a
+ *  no-faucet-call entry is not mislabeled as "funded".
+ *
+ *  Distilled-doc invariant: the `applied` projection must reflect
+ *  what actually happened — not the user's request shape. */
+type AppliedFundingOutcome = 'funded' | 'already-satisfied';
+interface AppliedFundingEntry extends ProjectedFundingEntry {
+  readonly outcome: AppliedFundingOutcome;
+}
+type AppliedFunding = ReadonlyArray<AppliedFundingEntry>;
 interface AccountFundingResult {
   readonly requested: ProjectedFunding;
-  readonly applied: ProjectedFunding;
-}
-/** Request passed to account funding strategies. `amount` uses the
- *  funded coin's smallest unit. The resolved account handle is present
- *  so strategies without an admin signer can perform account-owned
- *  swaps while still sharing the central funding dispatcher. */
-interface AccountFundingRequest {
-  readonly address: string;
-  readonly amount: bigint;
-  readonly account: AccountValue;
-}
-interface AccountFundingStrategy<E = unknown> {
-  readonly request: (req: AccountFundingRequest) => Effect.Effect<void, E>;
-  /** True when the strategy calls `account.withTransactionSigner`.
-   *  The dispatcher must not acquire the same non-reentrant
-   *  per-address lease outside the strategy. */
-  readonly usesAccountSigner?: boolean;
+  readonly applied: AppliedFunding;
 }
+/** Account-bus projection of the substrate funding-request contract
+ *  (`contracts/funding-strategy.ts`). Narrows the contract's generic
+ *  account-handle slot to the concrete `AccountValue` this plugin
+ *  publishes; strategies inside account or in sibling plugins
+ *  (coin/walrus/deepbook) see the real handle type without re-stating
+ *  the substrate shape. */
+type AccountFundingRequest = AccountFundingRequest$1<AccountValue>;
+/** Account-bus projection of the substrate strategy contract. The
+ *  generic account-handle slot is fixed to `AccountValue` so
+ *  contributing plugins receive a typed account handle. */
+type AccountFundingStrategy<E = unknown> = AccountFundingStrategy$1<E, AccountValue>;
 /** The canonical builtin SUI coin type. Used by the funding dispatch
  *  to route SUI entries to the faucet strategy (same key as the
  *  default-funding pass), and by everything that needs to detect
@@ -90,5 +100,5 @@ declare const SUI_FULL_COIN_TYPE: "0x2::sui::SUI";
  *  is predictable. */
 declare const DEFAULT_EPHEMERAL_FUND_MIST = 1000000000n;
 //#endregion
-export { AccountFunding, AccountFundingCoinValue, AccountFundingEntry, AccountFundingRequest, AccountFundingResult, AccountFundingStrategy, CoinMember, CrossCuttingFundingEntry, CrossCuttingFundingProvider, DEFAULT_EPHEMERAL_FUND_MIST, ProjectedFunding, ProjectedFundingEntry, SUI_FULL_COIN_TYPE, SuiFundingEntry };
+export { AccountFunding, AccountFundingCoinValue, AccountFundingEntry, AccountFundingRequest, AccountFundingResult, AccountFundingStrategy, AppliedFunding, AppliedFundingEntry, AppliedFundingOutcome, CoinMember, CrossCuttingFundingEntry, CrossCuttingFundingProvider, DEFAULT_EPHEMERAL_FUND_MIST, ProjectedFunding, ProjectedFundingEntry, SUI_FULL_COIN_TYPE, SuiFundingEntry };
 //# sourceMappingURL=funding.d.mts.map

package/dist/plugins/account/funding.mjs

@@ -1,10 +1,19 @@
+import { BALANCE_POLL_PROFILE, makeBoundedSpacedSchedule } from "../../substrate/runtime/retry-policy.mjs";
 import { setCurrentPluginPhase } from "../../substrate/runtime/current-plugin.mjs";
 import { StrategyRegistryService } from "../../substrate/runtime/strategy-registry/service.mjs";
-import { faucetCapabilityFor } from "../../substrate/runtime/strategy-registry/faucet-capability-for.mjs";
+import { chainKeyedStrategyFor } from "../../substrate/runtime/strategy-registry/chain-keyed-strategy-for.mjs";
+import "../../substrate/runtime/strategy-registry/index.mjs";
+import { SuiSpans } from "../sui/spans.mjs";
+import { FAUCET_CAPABILITY_KEY_PREFIX } from "../faucet/dispatcher.mjs";
+import "../faucet/index.mjs";
+import "../sui/index.mjs";
+import { AccountSpans } from "./spans.mjs";
 import { accountAcquireError } from "./errors.mjs";
 import { withAddressLease } from "./lease.mjs";
-import { Duration, Effect } from "effect";
+import { fundingFailureError } from "../internal/funding-failure-error.mjs";
+import { Effect } from "effect";
 //#region src/plugins/account/funding.ts
+const skipsFinalityWait = (reader) => reader.skipFinalityWait === true;
 /** The canonical builtin SUI coin type. Used by the funding dispatch
 *  to route SUI entries to the faucet strategy (same key as the
 *  default-funding pass), and by everything that needs to detect
@@ -15,8 +24,6 @@ const SUI_FULL_COIN_TYPE = "0x2::sui::SUI";
 *  Documented at the user-facing factory so a bare `account('alice')`
 *  is predictable. */
 const DEFAULT_EPHEMERAL_FUND_MIST = 1000000000n;
-const FUNDING_SETTLEMENT_INTERVAL_MS = 250;
-const FUNDING_SETTLEMENT_TIMEOUT_MS = 3e4;
 /** Apply the default-funding pass for an ephemeral account.
 *
 *  Wiring: yields `StrategyRegistryService` (the R-channel from
@@ -26,27 +33,26 @@ const FUNDING_SETTLEMENT_TIMEOUT_MS = 3e4;
 *  the address lock around the wire call. */
 const fundEphemeralDefault = (parts) => Effect.gen(function* () {
 	if (parts.suiMode === "fork") yield* parts.emitAutoPromotionEvent();
-	if (parts.amountMist <= 0n) return;
+	if (parts.amountMist <= 0n) return "skipped";
 	yield* setCurrentPluginPhase("checking SUI funding");
 	const existingBalance = yield* readExistingBalance(parts.balanceReader, {
 		owner: parts.address,
 		coinType: SUI_FULL_COIN_TYPE
 	});
-	if (existingBalance !== null && existingBalance >= parts.amountMist) return;
-	const strategy = yield* faucetCapabilityFor(parts.chainId).pipe(Effect.catchTag("StrategyNotFoundError", (err) => Effect.fail(accountAcquireError({
+	if (existingBalance !== null && existingBalance >= parts.amountMist) return "already-satisfied";
+	const strategy = yield* chainKeyedStrategyFor(FAUCET_CAPABILITY_KEY_PREFIX, parts.chainId).pipe(Effect.catchTag("StrategyNotFoundError", (err) => Effect.fail(accountAcquireError({
 		phase: "fund-default",
 		accountName: parts.accountName,
 		variant: "ephemeral",
 		message: `Account '${parts.accountName}': no faucet strategy registered for chain '${parts.chainId}' (sui mode=${parts.suiMode}). Registered keys: [${err.registeredKeys.join(", ")}].`,
 		hint: parts.suiMode === "fork" ? "Fork networks have no HTTP faucet — compose a plugin that contributes defineFaucetStrategy(...) for this chain id." : "Ensure a sui() plugin with a faucet-bearing mode (local/live-testnet/live-devnet) is in the stack."
 	}))));
-	const wrapFaucetFailure = (cause) => Effect.fail(accountAcquireError({
+	const wrapFaucetFailure = (cause) => Effect.fail(fundingFailureError({
 		phase: "fund-default",
 		accountName: parts.accountName,
 		variant: "ephemeral",
-		message: `Account '${parts.accountName}': faucet strategy request failed for chain '${parts.chainId}' (tag=${cause._tag}).`,
-		cause,
-		hint: "See the cause chain — typical roots are the faucet container not yet ready (FaucetUnreachable), the wall-clock budget elapsed (FaucetExhausted), or the body returned Failure (FaucetBodyError)."
+		chainId: parts.chainId,
+		cause
 	}));
 	yield* setCurrentPluginPhase("funding SUI");
 	yield* withAddressLease(parts.broker, parts.accountName, parts.address, strategy.request({
@@ -69,16 +75,17 @@ const fundEphemeralDefault = (parts) => Effect.gen(function* () {
 		amount: parts.amountMist
 	});
 	yield* Effect.annotateCurrentSpan({
-		"account.name": parts.accountName,
-		"account.address": parts.address,
-		"fund.amount.mist": parts.amountMist.toString(),
-		"sui.chain": parts.chainId,
-		"sui.mode": parts.suiMode
+		[AccountSpans.name]: parts.accountName,
+		[AccountSpans.address]: parts.address,
+		[AccountSpans.fundAmountMist]: parts.amountMist.toString(),
+		[SuiSpans.chain]: parts.chainId,
+		[SuiSpans.mode]: parts.suiMode
 	});
+	return "funded";
 }).pipe(Effect.withSpan("devstack.plugin.account.fundEphemeralDefault", { attributes: {
-	"account.name": parts.accountName,
-	"account.address": parts.address,
-	"sui.mode": parts.suiMode
+	[AccountSpans.name]: parts.accountName,
+	[AccountSpans.address]: parts.address,
+	[SuiSpans.mode]: parts.suiMode
 } }));
 /** Apply the cross-cutting funding pass. Variant-agnostic — runs for
 *  every variant once the keypair / impersonation slot is bound and
@@ -112,39 +119,48 @@ const applyCrossCuttingFunding = (parts) => Effect.gen(function* () {
 			coinType: entry.fullCoinType
 		});
 		if (existingBalance !== null && existingBalance >= entry.amount) {
-			applied.push(entry);
+			applied.push({
+				...entry,
+				outcome: "already-satisfied"
+			});
 			continue;
 		}
 		const isSui = entry.fullCoinType === SUI_FULL_COIN_TYPE;
 		const coinKey = `coinType:${entry.fullCoinType}`;
-		const strategy = yield* (isSui ? faucetCapabilityFor(parts.chainId) : registry.get(coinKey)).pipe(Effect.catchTag("StrategyNotFoundError", (err) => isSui ? Effect.fail(accountAcquireError({
+		const key = isSui ? `faucet:request:${parts.chainId}` : coinKey;
+		const wrapCrossCuttingFailure = (cause) => fundingFailureError({
+			phase: "fund-cross-cutting",
+			accountName: parts.accountName,
+			variant: parts.variant,
+			key,
+			amount: entry.amount,
+			cause
+		});
+		let request;
+		let usesAccountSigner = false;
+		if (isSui) request = (yield* chainKeyedStrategyFor(FAUCET_CAPABILITY_KEY_PREFIX, parts.chainId).pipe(Effect.catchTag("StrategyNotFoundError", (err) => Effect.fail(accountAcquireError({
 			phase: "fund-cross-cutting",
 			accountName: parts.accountName,
 			variant: parts.variant,
 			message: `Account '${parts.accountName}': no SUI funding strategy registered for chain '${parts.chainId}'. Registered keys: [${err.registeredKeys.join(", ")}].`,
 			cause: err,
 			hint: "Ensure a sui() plugin with a faucet-bearing mode (local/live-testnet/live-devnet) is in the stack."
-		})) : Effect.succeed(null)));
-		if (strategy === null) continue;
-		const key = isSui ? `faucet:request:${parts.chainId}` : coinKey;
-		const wrapCrossCuttingFailure = (cause) => {
-			const tag = typeof cause === "object" && cause !== null && "_tag" in cause ? String(cause._tag) : "unknown";
-			return accountAcquireError({
-				phase: "fund-cross-cutting",
-				accountName: parts.accountName,
-				variant: parts.variant,
-				message: `Account '${parts.accountName}': cross-cutting funding failed for coin (key='${key}') amount=${entry.amount} (tag=${tag}).`,
-				cause,
-				hint: "Cross-cutting funding requires the matching strategy to be registered at the time of acquire — check the plugin that contributes this coin and any `via` dependency."
-			});
-		};
-		const request = strategy.request({
+		}))))).request({
 			address: parts.address,
-			amount: entry.amount,
-			account: parts.account
+			amount: entry.amount
 		}).pipe(Effect.mapError(wrapCrossCuttingFailure));
+		else {
+			const strategy = yield* registry.get(coinKey).pipe(Effect.catchTag("StrategyNotFoundError", () => Effect.succeed(null)));
+			if (strategy === null) continue;
+			usesAccountSigner = strategy.usesAccountSigner === true;
+			request = strategy.request({
+				address: parts.address,
+				amount: entry.amount,
+				account: parts.account
+			}).pipe(Effect.mapError(wrapCrossCuttingFailure));
+		}
 		yield* setCurrentPluginPhase(`funding ${entry.coin}`);
-		yield* strategy.usesAccountSigner === true ? request : withAddressLease(parts.broker, parts.accountName, parts.address, request);
+		yield* usesAccountSigner ? request : withAddressLease(parts.broker, parts.accountName, parts.address, request);
 		yield* setCurrentPluginPhase(`waiting for ${entry.coin} funding settlement`);
 		yield* waitForBalanceAtLeast({
 			balanceReader: parts.balanceReader,
@@ -156,41 +172,43 @@ const applyCrossCuttingFunding = (parts) => Effect.gen(function* () {
 			coinLabel: entry.coin,
 			amount: entry.amount
 		});
-		applied.push(entry);
+		applied.push({
+			...entry,
+			outcome: "funded"
+		});
 	}
 	yield* Effect.annotateCurrentSpan({
-		"account.name": parts.accountName,
-		"account.address": parts.address,
-		"fund.cross-cutting.count": parts.funding.length,
-		"sui.chain": parts.chainId
+		[AccountSpans.name]: parts.accountName,
+		[AccountSpans.address]: parts.address,
+		[AccountSpans.fundCrossCuttingCount]: parts.funding.length,
+		[SuiSpans.chain]: parts.chainId
 	});
 	return applied;
 }).pipe(Effect.withSpan("devstack.plugin.account.applyCrossCuttingFunding", { attributes: {
-	"account.name": parts.accountName,
-	"account.address": parts.address,
-	"fund.cross-cutting.entries": parts.funding.length
+	[AccountSpans.name]: parts.accountName,
+	[AccountSpans.address]: parts.address,
+	[AccountSpans.fundCrossCuttingEntries]: parts.funding.length
 } }));
-const readExistingBalance = (balanceReader, args) => balanceReader === void 0 ? Effect.succeed(null) : balanceReader.readBalance(args);
+const readExistingBalance = (balanceReader, args) => balanceReader.readBalance(args);
 const waitForBalanceAtLeast = (parts) => {
-	if (parts.balanceReader === void 0) return Effect.void;
+	const reader = parts.balanceReader;
+	if (skipsFinalityWait(reader)) return Effect.void;
 	return Effect.gen(function* () {
-		const startedAt = Date.now();
-		let lastBalance = null;
-		for (;;) {
-			lastBalance = yield* readExistingBalance(parts.balanceReader, {
-				owner: parts.owner,
-				coinType: parts.coinType
-			});
-			if (lastBalance !== null && lastBalance >= parts.amount) return;
-			if (Date.now() - startedAt >= FUNDING_SETTLEMENT_TIMEOUT_MS) return yield* Effect.fail(accountAcquireError({
-				phase: parts.phase,
-				accountName: parts.accountName,
-				variant: parts.variant,
-				message: `Account '${parts.accountName}': funding for ${parts.coinLabel} was accepted but balance did not reach ${parts.amount} before the settlement timeout (last=${lastBalance === null ? "<unavailable>" : lastBalance}).`,
-				hint: "The faucet or funding strategy returned before the funded coin became spendable. Check the funding strategy finality gate and Sui RPC health."
-			}));
-			yield* Effect.sleep(Duration.millis(FUNDING_SETTLEMENT_INTERVAL_MS));
-		}
+		const lastBalance = yield* readExistingBalance(reader, {
+			owner: parts.owner,
+			coinType: parts.coinType
+		}).pipe(Effect.repeat({
+			schedule: makeBoundedSpacedSchedule(BALANCE_POLL_PROFILE.intervalMs, BALANCE_POLL_PROFILE.timeoutMs),
+			until: (balance) => balance !== null && balance >= parts.amount
+		}));
+		if (lastBalance !== null && lastBalance >= parts.amount) return;
+		return yield* Effect.fail(accountAcquireError({
+			phase: parts.phase,
+			accountName: parts.accountName,
+			variant: parts.variant,
+			message: `Account '${parts.accountName}': funding for ${parts.coinLabel} was accepted but balance did not reach ${parts.amount} before the settlement timeout (last=${lastBalance === null ? "<unavailable>" : lastBalance}).`,
+			hint: "The faucet or funding strategy returned before the funded coin became spendable. Check the funding strategy finality gate and Sui RPC health."
+		}));
 	});
 };
 //#endregion

package/dist/plugins/account/funding.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"funding.mjs","names":[],"sources":["../../../src/plugins/account/funding.ts"],"sourcesContent":["// Account plugin — funding logic.\n//\n// Two funding paths converge here:\n//\n//   1. **Default funding** — applies to the `ephemeral` variant only.\n//      On non-fork networks: faucet POST via the SUI HTTP strategy\n//      auto-registered by Faucet (see 11-faucet.md). On fork networks:\n//      \"pay from a seed via impersonation\" because forks have no\n//      faucet. The auto-promotion is LOUD by default per the\n//      architecture's \"no silent surprises\" principle — we emit a\n//      `log.appended` event the first time a stack hits this path.\n//\n//   2. **Cross-cutting funding** — declared per-account via\n//      `AccountOptions.funding`. Applies to every variant.\n//      Dispatched through the ambient strategy registry. Missing\n//      strategy for non-SUI coins ⇒ silent noop (architecture-\n//      mandated test-ergonomics contract, distilled-doc invariant:\n//      \"Optional Faucet is a noop, not an error\"). Explicit SUI\n//      entries use the SUI faucet strategy and fail loudly when no\n//      faucet-bearing strategy exists.\n//\n// Distilled-doc invariant: per-address serialization — concurrent\n// funding requests for the same address MUST serialize. We share the\n// substrate `LeaseBroker` handle from `service.ts` and open a fresh\n// scope per wire call so the lease releases the moment that call\n// returns. Each cross-cutting iteration is its own scope: the broker\n// is non-reentrant by design, so a hypothetical loop holding a single\n// lease across iterations would deadlock the second one.\n\nimport { Duration, Effect } from 'effect';\n\nimport type { FaucetStrategy } from '../faucet/strategies/sui-local.ts';\nimport {\n\tfaucetCapabilityFor,\n\tStrategyRegistryService,\n} from '../../substrate/runtime/strategy-registry/index.ts';\nimport type { AnyResourceRef, ResourceRef } from '../../api/define-plugin.ts';\nimport type { LeaseBroker } from '../../substrate/runtime/lease-broker/index.ts';\nimport type { ChainId } from '../../substrate/brand.ts';\nimport type { CoinResourceId } from '../coin/index.ts';\nimport { setCurrentPluginPhase } from '../../substrate/runtime/current-plugin.ts';\n\nimport {\n\taccountAcquireError,\n\ttype AccountAcquireError,\n\ttype AccountVariantKind,\n} from './errors.ts';\nimport { withAddressLease } from './lease.ts';\nimport type { AccountValue } from './service.ts';\n\n/** Direct resource ref shape for a coin upstream. The user passes the\n *  result of `coin.fromPackage(...)` / `coin.known(...)` /\n *  `coin.builtin(...)` — NOT a bare string or discriminator. Generic\n *  over the literal symbol so the account's dependency tuple preserves\n *  each per-coin resource id (`coin:managed_coin/managed_coin`,\n *  `coin:wal`, ...).\n *\n *  Architecture (Direct Member Refs): cross-plugin references at the\n *  user-facing surface are plugin/resource refs directly — no opaque\n *  tag or string discriminator vocabulary. */\nexport interface AccountFundingCoinValue {\n\treadonly fullCoinType: string;\n\treadonly symbol?: string;\n}\n\nexport type CoinMember<Sym extends string = string> = ResourceRef<\n\tCoinResourceId<Sym>,\n\tAccountFundingCoinValue\n>;\n\n/** Optional dependency edge for the plugin that contributes the\n *  funding strategy. Coin refs force the coin metadata edge; `via`\n *  forces the strategy-provider edge (e.g. a known DeepBook\n *  deployment that contributes `coinType:<DEEP>`). */\nexport type CrossCuttingFundingProvider = AnyResourceRef | readonly AnyResourceRef[];\n\n/** Built-in SUI funding entry. This uses the same account funding\n *  list as arbitrary coins but avoids requiring `coin.builtin('sui')`\n *  for the normal SUI faucet path. */\nexport interface SuiFundingEntry {\n\treadonly coin: 'sui';\n\treadonly amount: number | bigint;\n}\n\n/** A single cross-cutting funding entry. `coin` is a direct member ref\n *  (the value returned by `coin.fromPackage(...)` etc.) — the account plugin\n *  threads it through `dependsOn` so the substrate's dep graph forces\n *  the publishing / discovery edge to land before funding.\n *\n *  Distilled-doc invariant (\"Strict upstream declaration\"): coin\n *  references cited by Account must force a dep edge. `via` is the\n *  same contract for the strategy contributor that can satisfy the\n *  funding request. */\nexport interface CrossCuttingFundingEntry<M extends CoinMember = CoinMember> {\n\treadonly coin: M;\n\treadonly amount: bigint;\n\treadonly via?: CrossCuttingFundingProvider;\n}\n\nexport type AccountFundingEntry<M extends CoinMember = CoinMember> =\n\t| SuiFundingEntry\n\t| CrossCuttingFundingEntry<M>;\n\nexport type AccountFunding = ReadonlyArray<AccountFundingEntry>;\n\n/** Internal projected shape — the acquire body in `account/index.ts`\n *  receives each funding entry's resolved `CoinValue`, reads\n *  `fullCoinType`, and passes the projected entries to\n *  `applyCrossCuttingFunding`. The funding pass never sees the raw\n *  member refs — keeps the strategy dispatch logic\n *  substrate-name-blind. */\nexport interface ProjectedFundingEntry {\n\treadonly coin: string;\n\treadonly fullCoinType: string;\n\treadonly amount: bigint;\n}\n\nexport type ProjectedFunding = ReadonlyArray<ProjectedFundingEntry>;\n\nexport interface AccountFundingResult {\n\treadonly requested: ProjectedFunding;\n\treadonly applied: ProjectedFunding;\n}\n\n/** Request passed to account funding strategies. `amount` uses the\n *  funded coin's smallest unit. The resolved account handle is present\n *  so strategies without an admin signer can perform account-owned\n *  swaps while still sharing the central funding dispatcher. */\nexport interface AccountFundingRequest {\n\treadonly address: string;\n\treadonly amount: bigint;\n\treadonly account: AccountValue;\n}\n\nexport interface AccountFundingStrategy<E = unknown> {\n\treadonly request: (req: AccountFundingRequest) => Effect.Effect<void, E>;\n\t/** True when the strategy calls `account.withTransactionSigner`.\n\t *  The dispatcher must not acquire the same non-reentrant\n\t *  per-address lease outside the strategy. */\n\treadonly usesAccountSigner?: boolean;\n}\n\nexport interface FundingBalanceReader {\n\treadonly readBalance: (args: {\n\t\treadonly owner: string;\n\t\treadonly coinType: string;\n\t}) => Effect.Effect<bigint | null>;\n}\n\n/** The canonical builtin SUI coin type. Used by the funding dispatch\n *  to route SUI entries to the faucet strategy (same key as the\n *  default-funding pass), and by everything that needs to detect\n *  \"this is the protocol-defined SUI\". Mirrors `BUILTIN_COINS.sui`\n *  in the coin plugin. */\nexport const SUI_FULL_COIN_TYPE = '0x2::sui::SUI' as const;\n\n/** Default funding amount for ephemeral accounts — 1 SUI in MIST.\n *  Documented at the user-facing factory so a bare `account('alice')`\n *  is predictable. */\nexport const DEFAULT_EPHEMERAL_FUND_MIST = 1_000_000_000n;\n\nconst FUNDING_SETTLEMENT_INTERVAL_MS = 250;\nconst FUNDING_SETTLEMENT_TIMEOUT_MS = 30_000;\n\n/** Inputs the default-funding pass needs from the per-acquire ctx. */\nexport interface FundEphemeralDefaultArgs {\n\treadonly accountName: string;\n\treadonly address: string;\n\treadonly amountMist: bigint;\n\treadonly suiMode: 'local' | 'local-rpc' | 'live' | 'fork';\n\t/** Resolved sui chain id — the substrate-level chain identity used\n\t *  to compose the faucet strategy's capability key\n\t *  (`faucet:request:<chainId>`). */\n\treadonly chainId: ChainId;\n\t/** Loud-by-default auto-promotion event (called on fork before the\n\t *  strategy is invoked, per the architecture's \"no silent surprises\"\n\t *  principle). */\n\treadonly emitAutoPromotionEvent: () => Effect.Effect<void>;\n\t/** Substrate lease-broker handle — funding opens a fresh scope per\n\t *  wire call and acquires the per-address lease so concurrent wire\n\t *  calls for the same address serialize at the chain boundary. */\n\treadonly broker: LeaseBroker;\n\treadonly balanceReader?: FundingBalanceReader;\n}\n\n/** Apply the default-funding pass for an ephemeral account.\n *\n *  Wiring: yields `StrategyRegistryService` (the R-channel from\n *  Round 7), looks up the faucet strategy registered by the Sui\n *  plugin under `faucet:request:<chainId>`, and dispatches a request\n *  through it. Per-address serialization is enforced by acquiring\n *  the address lock around the wire call. */\nexport const fundEphemeralDefault = (\n\tparts: FundEphemeralDefaultArgs,\n): Effect.Effect<void, AccountAcquireError, StrategyRegistryService> =>\n\tEffect.gen(function* () {\n\t\t// LOUD AUTO-PROMOTION — distilled-doc invariant: \"no silent\n\t\t// surprises\". Emit BEFORE attempting the dispatch so the user\n\t\t// sees the path change even if the wire call subsequently\n\t\t// fails. On fork we surface the path-change event; on non-fork\n\t\t// the strategy registered by Sui IS the canonical default and\n\t\t// no auto-promotion is needed.\n\t\tif (parts.suiMode === 'fork') {\n\t\t\tyield* parts.emitAutoPromotionEvent();\n\t\t}\n\n\t\t// Zero-amount short-circuit — both real strategies treat zero\n\t\t// as a no-op; doing the same here avoids a registry lookup +\n\t\t// span emission for the legitimately-no-funding case.\n\t\tif (parts.amountMist <= 0n) {\n\t\t\treturn;\n\t\t}\n\n\t\tyield* setCurrentPluginPhase('checking SUI funding');\n\t\tconst existingBalance = yield* readExistingBalance(parts.balanceReader, {\n\t\t\towner: parts.address,\n\t\t\tcoinType: SUI_FULL_COIN_TYPE,\n\t\t});\n\t\tif (existingBalance !== null && existingBalance >= parts.amountMist) {\n\t\t\treturn;\n\t\t}\n\n\t\t// Look up the strategy. Sui auto-registers a faucet strategy\n\t\t// on non-fork modes; fork-mode strategies have to be supplied\n\t\t// by the faucet plugin (with the fork admin closed over). If\n\t\t// nothing is registered we surface a typed, actionable error\n\t\t// pointing at the architecture's contract: ephemeral-on-non-\n\t\t// fork without a Faucet MUST fail at acquire time.\n\t\tconst strategy = yield* faucetCapabilityFor<FaucetStrategy>(parts.chainId).pipe(\n\t\t\tEffect.catchTag('StrategyNotFoundError', (err) =>\n\t\t\t\tEffect.fail(\n\t\t\t\t\taccountAcquireError({\n\t\t\t\t\t\tphase: 'fund-default',\n\t\t\t\t\t\taccountName: parts.accountName,\n\t\t\t\t\t\tvariant: 'ephemeral',\n\t\t\t\t\t\tmessage:\n\t\t\t\t\t\t\t`Account '${parts.accountName}': no faucet strategy registered for ` +\n\t\t\t\t\t\t\t`chain '${parts.chainId}' (sui mode=${parts.suiMode}). ` +\n\t\t\t\t\t\t\t`Registered keys: [${err.registeredKeys.join(', ')}].`,\n\t\t\t\t\t\thint:\n\t\t\t\t\t\t\tparts.suiMode === 'fork'\n\t\t\t\t\t\t\t\t? 'Fork networks have no HTTP faucet — compose a plugin that contributes defineFaucetStrategy(...) for this chain id.'\n\t\t\t\t\t\t\t\t: 'Ensure a sui() plugin with a faucet-bearing mode (local/live-testnet/live-devnet) is in the stack.',\n\t\t\t\t\t}),\n\t\t\t\t),\n\t\t\t),\n\t\t);\n\n\t\t// Per-address serialization around the wire call. The lease is\n\t\t// scope-bound and releases as soon as `request(...)` returns;\n\t\t// two concurrent funding requests for the same address — e.g.\n\t\t// ephemeral default + cross-cutting SUI top-up — interleave\n\t\t// deterministically via the broker's FIFO queue.\n\t\tconst wrapFaucetFailure = (cause: {\n\t\t\treadonly _tag: 'FaucetUnreachable' | 'FaucetExhausted' | 'FaucetBodyError';\n\t\t}) =>\n\t\t\tEffect.fail(\n\t\t\t\taccountAcquireError({\n\t\t\t\t\tphase: 'fund-default',\n\t\t\t\t\taccountName: parts.accountName,\n\t\t\t\t\tvariant: 'ephemeral',\n\t\t\t\t\tmessage:\n\t\t\t\t\t\t`Account '${parts.accountName}': faucet strategy request failed ` +\n\t\t\t\t\t\t`for chain '${parts.chainId}' (tag=${cause._tag}).`,\n\t\t\t\t\tcause,\n\t\t\t\t\thint:\n\t\t\t\t\t\t'See the cause chain — typical roots are the faucet container ' +\n\t\t\t\t\t\t'not yet ready (FaucetUnreachable), the wall-clock budget elapsed ' +\n\t\t\t\t\t\t'(FaucetExhausted), or the body returned Failure (FaucetBodyError).',\n\t\t\t\t}),\n\t\t\t);\n\t\tyield* setCurrentPluginPhase('funding SUI');\n\t\tyield* withAddressLease(\n\t\t\tparts.broker,\n\t\t\tparts.accountName,\n\t\t\tparts.address,\n\t\t\tstrategy.request({ address: parts.address, amount: parts.amountMist }).pipe(\n\t\t\t\tEffect.catchTags({\n\t\t\t\t\tFaucetUnreachable: wrapFaucetFailure,\n\t\t\t\t\tFaucetExhausted: wrapFaucetFailure,\n\t\t\t\t\tFaucetBodyError: wrapFaucetFailure,\n\t\t\t\t}),\n\t\t\t),\n\t\t);\n\t\tyield* setCurrentPluginPhase('waiting for SUI funding settlement');\n\t\tyield* waitForBalanceAtLeast({\n\t\t\tbalanceReader: parts.balanceReader,\n\t\t\taccountName: parts.accountName,\n\t\t\tvariant: 'ephemeral',\n\t\t\tphase: 'fund-default',\n\t\t\towner: parts.address,\n\t\t\tcoinType: SUI_FULL_COIN_TYPE,\n\t\t\tcoinLabel: 'SUI',\n\t\t\tamount: parts.amountMist,\n\t\t});\n\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t'account.name': parts.accountName,\n\t\t\t'account.address': parts.address,\n\t\t\t'fund.amount.mist': parts.amountMist.toString(),\n\t\t\t'sui.chain': parts.chainId,\n\t\t\t'sui.mode': parts.suiMode,\n\t\t});\n\t}).pipe(\n\t\tEffect.withSpan('devstack.plugin.account.fundEphemeralDefault', {\n\t\t\tattributes: {\n\t\t\t\t'account.name': parts.accountName,\n\t\t\t\t'account.address': parts.address,\n\t\t\t\t'sui.mode': parts.suiMode,\n\t\t\t},\n\t\t}),\n\t);\n\n/** Inputs the cross-cutting funding pass needs from the per-acquire ctx.\n *\n *  `funding` is the PROJECTED shape — the acquire body in\n *  `account/index.ts` receives each user-supplied `CoinMember` as a\n *  resolved dependency and projects to `{fullCoinType, amount}` BEFORE\n *  invoking this pass. Keeps the dispatch logic substrate-name-blind. */\nexport interface ApplyCrossCuttingFundingArgs {\n\treadonly accountName: string;\n\treadonly address: string;\n\treadonly variant: AccountVariantKind;\n\treadonly account: AccountValue;\n\treadonly funding: ProjectedFunding;\n\treadonly chainId: ChainId;\n\treadonly broker: LeaseBroker;\n\treadonly balanceReader?: FundingBalanceReader;\n}\n\n/** Apply the cross-cutting funding pass. Variant-agnostic — runs for\n *  every variant once the keypair / impersonation slot is bound and\n *  the address is known.\n *\n *  Distilled-doc invariant: \"Optional Faucet is a noop, not an\n *  error\". Absence of a registered strategy for a non-SUI coin's\n *  capability key short-circuits silently (the entry is dropped).\n *  Explicit SUI entries are stricter: they route through the active\n *  chain's faucet strategy and fail loudly when none is registered.\n *  This lets a test author opt INTO arbitrary-coin funding without\n *  forcing every surrounding network to satisfy every custom coin.\n *\n *  Wiring: SUI entries (`fullCoinType === '0x2::sui::SUI'`) dispatch\n *  through `faucet:request:<chainId>` (same key as the default pass);\n *  other entries dispatch through `coinType:<fullCoinType>` keys\n *  contributed by the respective Coin/Walrus/Seal plugins.\n *\n *  Entries are processed serially. Strategies that use the resolved\n *  account signer acquire the per-address lease internally; strategies\n *  that do not are wrapped by this dispatcher. */\nexport const applyCrossCuttingFunding = (\n\tparts: ApplyCrossCuttingFundingArgs,\n): Effect.Effect<ProjectedFunding, AccountAcquireError, StrategyRegistryService> =>\n\tEffect.gen(function* () {\n\t\tif (parts.funding.length === 0) {\n\t\t\treturn [];\n\t\t}\n\t\tconst registry = yield* StrategyRegistryService;\n\t\tconst applied: ProjectedFundingEntry[] = [];\n\n\t\tfor (const entry of parts.funding) {\n\t\t\tif (entry.amount <= 0n) {\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\tyield* setCurrentPluginPhase(`checking ${entry.coin} funding`);\n\t\t\tconst existingBalance = yield* readExistingBalance(parts.balanceReader, {\n\t\t\t\towner: parts.address,\n\t\t\t\tcoinType: entry.fullCoinType,\n\t\t\t});\n\t\t\tif (existingBalance !== null && existingBalance >= entry.amount) {\n\t\t\t\tapplied.push(entry);\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\t// Resolve the capability key from the projected coin type.\n\t\t\t//\n\t\t\t// SUI (`0x2::sui::SUI`) → reuse the faucet-request key so the\n\t\t\t// SUI auto-registered strategy fields the request (this\n\t\t\t// matches the default-funding pass and keeps the registry\n\t\t\t// surface uniform).\n\t\t\t//\n\t\t\t// Everything else → `coinType:<fullCoinType>` so user-defined\n\t\t\t// Coin plugins (and Walrus's exchange strategy keyed by\n\t\t\t// `coinType:<WAL fullCoinType>`) can contribute strategies\n\t\t\t// declaratively.\n\t\t\tconst isSui = entry.fullCoinType === SUI_FULL_COIN_TYPE;\n\t\t\tconst coinKey = `coinType:${entry.fullCoinType}` as const;\n\t\t\tconst lookup = isSui\n\t\t\t\t? faucetCapabilityFor<AccountFundingStrategy>(parts.chainId)\n\t\t\t\t: registry.get<typeof coinKey, AccountFundingStrategy>(coinKey);\n\n\t\t\t// Architecture-distilled: optional-faucet-is-noop for\n\t\t\t// arbitrary coins. Explicit SUI entries are the normal gas\n\t\t\t// faucet path, so missing strategy is actionable and loud.\n\t\t\tconst strategy = yield* lookup.pipe(\n\t\t\t\tEffect.catchTag('StrategyNotFoundError', (err) =>\n\t\t\t\t\tisSui\n\t\t\t\t\t\t? Effect.fail(\n\t\t\t\t\t\t\t\taccountAcquireError({\n\t\t\t\t\t\t\t\t\tphase: 'fund-cross-cutting',\n\t\t\t\t\t\t\t\t\taccountName: parts.accountName,\n\t\t\t\t\t\t\t\t\tvariant: parts.variant,\n\t\t\t\t\t\t\t\t\tmessage:\n\t\t\t\t\t\t\t\t\t\t`Account '${parts.accountName}': no SUI funding strategy registered ` +\n\t\t\t\t\t\t\t\t\t\t`for chain '${parts.chainId}'. Registered keys: [${err.registeredKeys.join(', ')}].`,\n\t\t\t\t\t\t\t\t\tcause: err,\n\t\t\t\t\t\t\t\t\thint: 'Ensure a sui() plugin with a faucet-bearing mode (local/live-testnet/live-devnet) is in the stack.',\n\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\t)\n\t\t\t\t\t\t: Effect.succeed(null as AccountFundingStrategy | null),\n\t\t\t\t),\n\t\t\t);\n\t\t\tif (strategy === null) {\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\tconst key = isSui ? (`faucet:request:${parts.chainId}` as const) : coinKey;\n\t\t\tconst wrapCrossCuttingFailure = (cause: unknown): AccountAcquireError => {\n\t\t\t\tconst tag =\n\t\t\t\t\ttypeof cause === 'object' && cause !== null && '_tag' in cause\n\t\t\t\t\t\t? String((cause as { readonly _tag?: unknown })._tag)\n\t\t\t\t\t\t: 'unknown';\n\t\t\t\treturn accountAcquireError({\n\t\t\t\t\tphase: 'fund-cross-cutting',\n\t\t\t\t\taccountName: parts.accountName,\n\t\t\t\t\tvariant: parts.variant,\n\t\t\t\t\tmessage:\n\t\t\t\t\t\t`Account '${parts.accountName}': cross-cutting funding ` +\n\t\t\t\t\t\t`failed for coin (key='${key}') amount=${entry.amount} ` +\n\t\t\t\t\t\t`(tag=${tag}).`,\n\t\t\t\t\tcause,\n\t\t\t\t\thint:\n\t\t\t\t\t\t'Cross-cutting funding requires the matching strategy ' +\n\t\t\t\t\t\t'to be registered at the time of acquire — check the ' +\n\t\t\t\t\t\t'plugin that contributes this coin and any `via` dependency.',\n\t\t\t\t});\n\t\t\t};\n\t\t\tconst request = strategy\n\t\t\t\t.request({ address: parts.address, amount: entry.amount, account: parts.account })\n\t\t\t\t.pipe(Effect.mapError(wrapCrossCuttingFailure));\n\t\t\tyield* setCurrentPluginPhase(`funding ${entry.coin}`);\n\t\t\tyield* strategy.usesAccountSigner === true\n\t\t\t\t? request\n\t\t\t\t: withAddressLease(parts.broker, parts.accountName, parts.address, request);\n\t\t\tyield* setCurrentPluginPhase(`waiting for ${entry.coin} funding settlement`);\n\t\t\tyield* waitForBalanceAtLeast({\n\t\t\t\tbalanceReader: parts.balanceReader,\n\t\t\t\taccountName: parts.accountName,\n\t\t\t\tvariant: parts.variant,\n\t\t\t\tphase: 'fund-cross-cutting',\n\t\t\t\towner: parts.address,\n\t\t\t\tcoinType: entry.fullCoinType,\n\t\t\t\tcoinLabel: entry.coin,\n\t\t\t\tamount: entry.amount,\n\t\t\t});\n\t\t\tapplied.push(entry);\n\t\t}\n\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t'account.name': parts.accountName,\n\t\t\t'account.address': parts.address,\n\t\t\t'fund.cross-cutting.count': parts.funding.length,\n\t\t\t'sui.chain': parts.chainId,\n\t\t});\n\t\treturn applied;\n\t}).pipe(\n\t\tEffect.withSpan('devstack.plugin.account.applyCrossCuttingFunding', {\n\t\t\tattributes: {\n\t\t\t\t'account.name': parts.accountName,\n\t\t\t\t'account.address': parts.address,\n\t\t\t\t'fund.cross-cutting.entries': parts.funding.length,\n\t\t\t},\n\t\t}),\n\t);\n\nconst readExistingBalance = (\n\tbalanceReader: FundingBalanceReader | undefined,\n\targs: {\n\t\treadonly owner: string;\n\t\treadonly coinType: string;\n\t},\n): Effect.Effect<bigint | null> =>\n\tbalanceReader === undefined ? Effect.succeed(null) : balanceReader.readBalance(args);\n\nconst waitForBalanceAtLeast = (parts: {\n\treadonly balanceReader: FundingBalanceReader | undefined;\n\treadonly accountName: string;\n\treadonly variant: AccountVariantKind;\n\treadonly phase: 'fund-default' | 'fund-cross-cutting';\n\treadonly owner: string;\n\treadonly coinType: string;\n\treadonly coinLabel: string;\n\treadonly amount: bigint;\n}): Effect.Effect<void, AccountAcquireError> => {\n\tif (parts.balanceReader === undefined) {\n\t\treturn Effect.void;\n\t}\n\treturn Effect.gen(function* () {\n\t\tconst startedAt = Date.now();\n\t\tlet lastBalance: bigint | null = null;\n\t\tfor (;;) {\n\t\t\tlastBalance = yield* readExistingBalance(parts.balanceReader, {\n\t\t\t\towner: parts.owner,\n\t\t\t\tcoinType: parts.coinType,\n\t\t\t});\n\t\t\tif (lastBalance !== null && lastBalance >= parts.amount) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (Date.now() - startedAt >= FUNDING_SETTLEMENT_TIMEOUT_MS) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\taccountAcquireError({\n\t\t\t\t\t\tphase: parts.phase,\n\t\t\t\t\t\taccountName: parts.accountName,\n\t\t\t\t\t\tvariant: parts.variant,\n\t\t\t\t\t\tmessage:\n\t\t\t\t\t\t\t`Account '${parts.accountName}': funding for ${parts.coinLabel} was accepted ` +\n\t\t\t\t\t\t\t`but balance did not reach ${parts.amount} before the settlement timeout ` +\n\t\t\t\t\t\t\t`(last=${lastBalance === null ? '<unavailable>' : lastBalance}).`,\n\t\t\t\t\t\thint:\n\t\t\t\t\t\t\t'The faucet or funding strategy returned before the funded coin became spendable. ' +\n\t\t\t\t\t\t\t'Check the funding strategy finality gate and Sui RPC health.',\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t}\n\t\t\tyield* Effect.sleep(Duration.millis(FUNDING_SETTLEMENT_INTERVAL_MS));\n\t\t}\n\t});\n};\n"],"mappings":"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"}
+{"version":3,"file":"funding.mjs","names":[],"sources":["../../../src/plugins/account/funding.ts"],"sourcesContent":["// Account plugin — funding logic.\n//\n// Two funding paths converge here:\n//\n//   1. **Default funding** — applies to the `ephemeral` variant only.\n//      On non-fork networks: faucet POST via the SUI HTTP strategy\n//      auto-registered by Faucet (see 11-faucet.md). On fork networks:\n//      \"pay from a seed via impersonation\" because forks have no\n//      faucet. The auto-promotion is LOUD by default per the\n//      architecture's \"no silent surprises\" principle — we emit a\n//      `log.appended` event the first time a stack hits this path.\n//\n//   2. **Cross-cutting funding** — declared per-account via\n//      `AccountOptions.funding`. Applies to every variant.\n//      Dispatched through the ambient strategy registry. Missing\n//      strategy for non-SUI coins ⇒ silent noop (architecture-\n//      mandated test-ergonomics contract, distilled-doc invariant:\n//      \"Optional Faucet is a noop, not an error\"). Explicit SUI\n//      entries use the SUI faucet strategy and fail loudly when no\n//      faucet-bearing strategy exists.\n//\n// Distilled-doc invariant: per-address serialization — concurrent\n// funding requests for the same address MUST serialize. We share the\n// substrate `LeaseBroker` handle from `service.ts` and open a fresh\n// scope per wire call so the lease releases the moment that call\n// returns. Each cross-cutting iteration is its own scope: the broker\n// is non-reentrant by design, so a hypothetical loop holding a single\n// lease across iterations would deadlock the second one.\n\nimport { Effect } from 'effect';\n\nimport { FAUCET_CAPABILITY_KEY_PREFIX, type FaucetStrategy } from '../faucet/index.ts';\nimport {\n\tchainKeyedStrategyFor,\n\tStrategyRegistryService,\n} from '../../substrate/runtime/strategy-registry/index.ts';\nimport type { AnyResourceRef, ResourceRef } from '../../api/define-plugin.ts';\nimport type { LeaseBroker } from '../../substrate/runtime/lease-broker/index.ts';\nimport type { ChainId } from '../../substrate/brand.ts';\nimport type {\n\tAccountFundingRequest as ContractAccountFundingRequest,\n\tAccountFundingStrategy as ContractAccountFundingStrategy,\n} from '../../contracts/funding-strategy.ts';\nimport { setCurrentPluginPhase } from '../../substrate/runtime/current-plugin.ts';\nimport {\n\tBALANCE_POLL_PROFILE,\n\tmakeBoundedSpacedSchedule,\n} from '../../substrate/runtime/retry-policy.ts';\n\nimport {\n\taccountAcquireError,\n\ttype AccountAcquireError,\n\ttype AccountVariantKind,\n} from './errors.ts';\nimport { withAddressLease } from './lease.ts';\nimport { fundingFailureError } from '../internal/funding-failure-error.ts';\nimport type { AccountValue } from './service.ts';\nimport { AccountSpans } from './spans.ts';\nimport { SuiSpans } from '../sui/index.ts';\n\n// `CoinResourceId` is the literal-typed resource id the coin plugin\n// publishes. Inlined here as `coin:${Sym}` so this file does NOT\n// cross-import the coin plugin — the substrate's compose-time dedup\n// works by string equality on the resource id, and the coin plugin's\n// `coinResourceId` constructor produces the same shape. This is the\n// per-Task-A \"inline the literal type alias\" decision (the literal\n// pattern is the contract; promoting it to a substrate type would\n// be more ceremony than the single string template warrants).\ntype CoinResourceId<Sym extends string> = `coin:${Sym}`;\n\n/** Direct resource ref shape for a coin upstream. The user passes the\n *  result of `coin.fromPackage(...)` / `coin.known(...)` /\n *  `coin.builtin(...)` — NOT a bare string or discriminator. Generic\n *  over the literal symbol so the account's dependency tuple preserves\n *  each per-coin resource id (`coin:managed_coin/managed_coin`,\n *  `coin:wal`, ...).\n *\n *  Architecture (Direct Member Refs): cross-plugin references at the\n *  user-facing surface are plugin/resource refs directly — no opaque\n *  tag or string discriminator vocabulary. */\nexport interface AccountFundingCoinValue {\n\treadonly fullCoinType: string;\n\treadonly symbol?: string;\n}\n\nexport type CoinMember<Sym extends string = string> = ResourceRef<\n\tCoinResourceId<Sym>,\n\tAccountFundingCoinValue\n>;\n\n/** Optional dependency edge for the plugin that contributes the\n *  funding strategy. Coin refs force the coin metadata edge; `via`\n *  forces the strategy-provider edge (e.g. a known DeepBook\n *  deployment that contributes `coinType:<DEEP>`). */\nexport type CrossCuttingFundingProvider = AnyResourceRef | readonly AnyResourceRef[];\n\n/** Built-in SUI funding entry. This uses the same account funding\n *  list as arbitrary coins but avoids requiring `coin.builtin('sui')`\n *  for the normal SUI faucet path. */\nexport interface SuiFundingEntry {\n\treadonly coin: 'sui';\n\treadonly amount: number | bigint;\n}\n\n/** A single cross-cutting funding entry. `coin` is a direct member ref\n *  (the value returned by `coin.fromPackage(...)` etc.) — the account plugin\n *  threads it through `dependsOn` so the substrate's dep graph forces\n *  the publishing / discovery edge to land before funding.\n *\n *  Distilled-doc invariant (\"Strict upstream declaration\"): coin\n *  references cited by Account must force a dep edge. `via` is the\n *  same contract for the strategy contributor that can satisfy the\n *  funding request. */\nexport interface CrossCuttingFundingEntry<M extends CoinMember = CoinMember> {\n\treadonly coin: M;\n\treadonly amount: bigint;\n\treadonly via?: CrossCuttingFundingProvider;\n}\n\nexport type AccountFundingEntry<M extends CoinMember = CoinMember> =\n\t| SuiFundingEntry\n\t| CrossCuttingFundingEntry<M>;\n\nexport type AccountFunding = ReadonlyArray<AccountFundingEntry>;\n\n/** Internal projected shape — the acquire body in `account/index.ts`\n *  receives each funding entry's resolved `CoinValue`, reads\n *  `fullCoinType`, and passes the projected entries to\n *  `applyCrossCuttingFunding`. The funding pass never sees the raw\n *  member refs — keeps the strategy dispatch logic\n *  substrate-name-blind. */\nexport interface ProjectedFundingEntry {\n\treadonly coin: string;\n\treadonly fullCoinType: string;\n\treadonly amount: bigint;\n}\n\nexport type ProjectedFunding = ReadonlyArray<ProjectedFundingEntry>;\n\n/** Outcome marker carried on each `applied` entry — distinguishes a\n *  faucet/strategy call that actually moved funds (`'funded'`) from\n *  the short-circuit case where the existing balance already covered\n *  the request (`'already-satisfied'`). Downstream projection turns\n *  this into the `AccountRegistryFundingEntry.status` column so a\n *  no-faucet-call entry is not mislabeled as \"funded\".\n *\n *  Distilled-doc invariant: the `applied` projection must reflect\n *  what actually happened — not the user's request shape. */\nexport type AppliedFundingOutcome = 'funded' | 'already-satisfied';\n\nexport interface AppliedFundingEntry extends ProjectedFundingEntry {\n\treadonly outcome: AppliedFundingOutcome;\n}\n\nexport type AppliedFunding = ReadonlyArray<AppliedFundingEntry>;\n\nexport interface AccountFundingResult {\n\treadonly requested: ProjectedFunding;\n\treadonly applied: AppliedFunding;\n}\n\n/** Account-bus projection of the substrate funding-request contract\n *  (`contracts/funding-strategy.ts`). Narrows the contract's generic\n *  account-handle slot to the concrete `AccountValue` this plugin\n *  publishes; strategies inside account or in sibling plugins\n *  (coin/walrus/deepbook) see the real handle type without re-stating\n *  the substrate shape. */\nexport type AccountFundingRequest = ContractAccountFundingRequest<AccountValue>;\n\n/** Account-bus projection of the substrate strategy contract. The\n *  generic account-handle slot is fixed to `AccountValue` so\n *  contributing plugins receive a typed account handle. */\nexport type AccountFundingStrategy<E = unknown> = ContractAccountFundingStrategy<E, AccountValue>;\n\nexport interface FundingBalanceReader {\n\treadonly readBalance: (args: {\n\t\treadonly owner: string;\n\t\treadonly coinType: string;\n\t}) => Effect.Effect<bigint | null>;\n}\n\n/** Sentinel brand identifying the test-only no-op reader. Surfaced as\n *  a separate `readonly skipFinalityWait?: true` discriminator on\n *  `NULL_BALANCE_READER` so the funding pass can short-circuit the\n *  finality wait deterministically WITHOUT exhausting the bounded\n *  poll schedule. Production readers MUST NOT set this. */\ninterface NullBalanceReader extends FundingBalanceReader {\n\treadonly skipFinalityWait: true;\n}\n\n/** Test-only no-op balance reader.\n *\n *  Production callers (`account/service.ts`) build a real reader from\n *  the live SDK via `makeFundingBalanceReader`; the funding pass\n *  REQUIRES a reader so the post-faucet finality wait is load-bearing\n *  on real wire calls. Tests that don't model the read/poll loop pass\n *  this sentinel to explicitly opt OUT of the wait — the absence of\n *  this opt-out previously hid as a silent `Effect.void` short-circuit\n *  on any production caller that forgot to wire the reader. */\nexport const NULL_BALANCE_READER: FundingBalanceReader = {\n\treadBalance: () => Effect.succeed(null),\n\tskipFinalityWait: true,\n} as NullBalanceReader;\n\nconst skipsFinalityWait = (reader: FundingBalanceReader): boolean =>\n\t(reader as NullBalanceReader).skipFinalityWait === true;\n\n/** The canonical builtin SUI coin type. Used by the funding dispatch\n *  to route SUI entries to the faucet strategy (same key as the\n *  default-funding pass), and by everything that needs to detect\n *  \"this is the protocol-defined SUI\". Mirrors `BUILTIN_COINS.sui`\n *  in the coin plugin. */\nexport const SUI_FULL_COIN_TYPE = '0x2::sui::SUI' as const;\n\n/** Default funding amount for ephemeral accounts — 1 SUI in MIST.\n *  Documented at the user-facing factory so a bare `account('alice')`\n *  is predictable. */\nexport const DEFAULT_EPHEMERAL_FUND_MIST = 1_000_000_000n;\n\n/** Inputs the default-funding pass needs from the per-acquire ctx. */\nexport interface FundEphemeralDefaultArgs {\n\treadonly accountName: string;\n\treadonly address: string;\n\treadonly amountMist: bigint;\n\treadonly suiMode: 'local' | 'local-rpc' | 'live' | 'fork';\n\t/** Resolved sui chain id — the substrate-level chain identity used\n\t *  to compose the faucet strategy's capability key\n\t *  (`faucet:request:<chainId>`). */\n\treadonly chainId: ChainId;\n\t/** Loud-by-default auto-promotion event (called on fork before the\n\t *  strategy is invoked, per the architecture's \"no silent surprises\"\n\t *  principle). */\n\treadonly emitAutoPromotionEvent: () => Effect.Effect<void>;\n\t/** Substrate lease-broker handle — funding opens a fresh scope per\n\t *  wire call and acquires the per-address lease so concurrent wire\n\t *  calls for the same address serialize at the chain boundary. */\n\treadonly broker: LeaseBroker;\n\t/** Required. Production callers build this from the SDK via\n\t *  `makeFundingBalanceReader`; tests that don't model the read/poll\n\t *  loop opt out explicitly with `NULL_BALANCE_READER`. The previous\n\t *  optional shape allowed a silent `Effect.void` short-circuit on\n\t *  the finality wait when callers forgot to wire it. */\n\treadonly balanceReader: FundingBalanceReader;\n}\n\n/** Outcome of `fundEphemeralDefault`. `'skipped'` covers the\n *  zero-amount no-op; `'already-satisfied'` covers the pre-existing-\n *  balance short-circuit (no faucet call); `'funded'` covers the\n *  successful wire path. Callers project this into the `applied`\n *  shape so the `funded`-vs-`already-satisfied` distinction survives\n *  to the registry projection. */\nexport type FundEphemeralDefaultOutcome = 'funded' | 'already-satisfied' | 'skipped';\n\n/** Apply the default-funding pass for an ephemeral account.\n *\n *  Wiring: yields `StrategyRegistryService` (the R-channel from\n *  Round 7), looks up the faucet strategy registered by the Sui\n *  plugin under `faucet:request:<chainId>`, and dispatches a request\n *  through it. Per-address serialization is enforced by acquiring\n *  the address lock around the wire call. */\nexport const fundEphemeralDefault = (\n\tparts: FundEphemeralDefaultArgs,\n): Effect.Effect<FundEphemeralDefaultOutcome, AccountAcquireError, StrategyRegistryService> =>\n\tEffect.gen(function* () {\n\t\t// LOUD AUTO-PROMOTION — distilled-doc invariant: \"no silent\n\t\t// surprises\". Emit BEFORE attempting the dispatch so the user\n\t\t// sees the path change even if the wire call subsequently\n\t\t// fails. On fork we surface the path-change event; on non-fork\n\t\t// the strategy registered by Sui IS the canonical default and\n\t\t// no auto-promotion is needed.\n\t\tif (parts.suiMode === 'fork') {\n\t\t\tyield* parts.emitAutoPromotionEvent();\n\t\t}\n\n\t\t// Zero-amount short-circuit — both real strategies treat zero\n\t\t// as a no-op; doing the same here avoids a registry lookup +\n\t\t// span emission for the legitimately-no-funding case.\n\t\tif (parts.amountMist <= 0n) {\n\t\t\treturn 'skipped' as const;\n\t\t}\n\n\t\tyield* setCurrentPluginPhase('checking SUI funding');\n\t\tconst existingBalance = yield* readExistingBalance(parts.balanceReader, {\n\t\t\towner: parts.address,\n\t\t\tcoinType: SUI_FULL_COIN_TYPE,\n\t\t});\n\t\tif (existingBalance !== null && existingBalance >= parts.amountMist) {\n\t\t\treturn 'already-satisfied' as const;\n\t\t}\n\n\t\t// Look up the strategy. Sui auto-registers a faucet strategy\n\t\t// on non-fork modes; fork-mode strategies have to be supplied\n\t\t// by the faucet plugin (with the fork admin closed over). If\n\t\t// nothing is registered we surface a typed, actionable error\n\t\t// pointing at the architecture's contract: ephemeral-on-non-\n\t\t// fork without a Faucet MUST fail at acquire time.\n\t\tconst strategy = yield* chainKeyedStrategyFor<FaucetStrategy>(\n\t\t\tFAUCET_CAPABILITY_KEY_PREFIX,\n\t\t\tparts.chainId,\n\t\t).pipe(\n\t\t\tEffect.catchTag('StrategyNotFoundError', (err) =>\n\t\t\t\tEffect.fail(\n\t\t\t\t\taccountAcquireError({\n\t\t\t\t\t\tphase: 'fund-default',\n\t\t\t\t\t\taccountName: parts.accountName,\n\t\t\t\t\t\tvariant: 'ephemeral',\n\t\t\t\t\t\tmessage:\n\t\t\t\t\t\t\t`Account '${parts.accountName}': no faucet strategy registered for ` +\n\t\t\t\t\t\t\t`chain '${parts.chainId}' (sui mode=${parts.suiMode}). ` +\n\t\t\t\t\t\t\t`Registered keys: [${err.registeredKeys.join(', ')}].`,\n\t\t\t\t\t\thint:\n\t\t\t\t\t\t\tparts.suiMode === 'fork'\n\t\t\t\t\t\t\t\t? 'Fork networks have no HTTP faucet — compose a plugin that contributes defineFaucetStrategy(...) for this chain id.'\n\t\t\t\t\t\t\t\t: 'Ensure a sui() plugin with a faucet-bearing mode (local/live-testnet/live-devnet) is in the stack.',\n\t\t\t\t\t}),\n\t\t\t\t),\n\t\t\t),\n\t\t);\n\n\t\t// Per-address serialization around the wire call. The lease is\n\t\t// scope-bound and releases as soon as `request(...)` returns;\n\t\t// two concurrent funding requests for the same address — e.g.\n\t\t// ephemeral default + cross-cutting SUI top-up — interleave\n\t\t// deterministically via the broker's FIFO queue.\n\t\tconst wrapFaucetFailure = (cause: {\n\t\t\treadonly _tag: 'FaucetUnreachable' | 'FaucetExhausted' | 'FaucetBodyError';\n\t\t}) =>\n\t\t\tEffect.fail(\n\t\t\t\tfundingFailureError({\n\t\t\t\t\tphase: 'fund-default',\n\t\t\t\t\taccountName: parts.accountName,\n\t\t\t\t\tvariant: 'ephemeral',\n\t\t\t\t\tchainId: parts.chainId,\n\t\t\t\t\tcause,\n\t\t\t\t}),\n\t\t\t);\n\t\tyield* setCurrentPluginPhase('funding SUI');\n\t\tyield* withAddressLease(\n\t\t\tparts.broker,\n\t\t\tparts.accountName,\n\t\t\tparts.address,\n\t\t\tstrategy.request({ address: parts.address, amount: parts.amountMist }).pipe(\n\t\t\t\tEffect.catchTags({\n\t\t\t\t\tFaucetUnreachable: wrapFaucetFailure,\n\t\t\t\t\tFaucetExhausted: wrapFaucetFailure,\n\t\t\t\t\tFaucetBodyError: wrapFaucetFailure,\n\t\t\t\t}),\n\t\t\t),\n\t\t);\n\t\tyield* setCurrentPluginPhase('waiting for SUI funding settlement');\n\t\tyield* waitForBalanceAtLeast({\n\t\t\tbalanceReader: parts.balanceReader,\n\t\t\taccountName: parts.accountName,\n\t\t\tvariant: 'ephemeral',\n\t\t\tphase: 'fund-default',\n\t\t\towner: parts.address,\n\t\t\tcoinType: SUI_FULL_COIN_TYPE,\n\t\t\tcoinLabel: 'SUI',\n\t\t\tamount: parts.amountMist,\n\t\t});\n\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t[AccountSpans.name]: parts.accountName,\n\t\t\t[AccountSpans.address]: parts.address,\n\t\t\t[AccountSpans.fundAmountMist]: parts.amountMist.toString(),\n\t\t\t[SuiSpans.chain]: parts.chainId,\n\t\t\t[SuiSpans.mode]: parts.suiMode,\n\t\t});\n\t\treturn 'funded' as const;\n\t}).pipe(\n\t\tEffect.withSpan('devstack.plugin.account.fundEphemeralDefault', {\n\t\t\tattributes: {\n\t\t\t\t[AccountSpans.name]: parts.accountName,\n\t\t\t\t[AccountSpans.address]: parts.address,\n\t\t\t\t[SuiSpans.mode]: parts.suiMode,\n\t\t\t},\n\t\t}),\n\t);\n\n/** Inputs the cross-cutting funding pass needs from the per-acquire ctx.\n *\n *  `funding` is the PROJECTED shape — the acquire body in\n *  `account/index.ts` receives each user-supplied `CoinMember` as a\n *  resolved dependency and projects to `{fullCoinType, amount}` BEFORE\n *  invoking this pass. Keeps the dispatch logic substrate-name-blind. */\nexport interface ApplyCrossCuttingFundingArgs {\n\treadonly accountName: string;\n\treadonly address: string;\n\treadonly variant: AccountVariantKind;\n\treadonly account: AccountValue;\n\treadonly funding: ProjectedFunding;\n\treadonly chainId: ChainId;\n\treadonly broker: LeaseBroker;\n\t/** Required. See `FundEphemeralDefaultArgs.balanceReader`. */\n\treadonly balanceReader: FundingBalanceReader;\n}\n\n/** Apply the cross-cutting funding pass. Variant-agnostic — runs for\n *  every variant once the keypair / impersonation slot is bound and\n *  the address is known.\n *\n *  Distilled-doc invariant: \"Optional Faucet is a noop, not an\n *  error\". Absence of a registered strategy for a non-SUI coin's\n *  capability key short-circuits silently (the entry is dropped).\n *  Explicit SUI entries are stricter: they route through the active\n *  chain's faucet strategy and fail loudly when none is registered.\n *  This lets a test author opt INTO arbitrary-coin funding without\n *  forcing every surrounding network to satisfy every custom coin.\n *\n *  Wiring: SUI entries (`fullCoinType === '0x2::sui::SUI'`) dispatch\n *  through `faucet:request:<chainId>` (same key as the default pass);\n *  other entries dispatch through `coinType:<fullCoinType>` keys\n *  contributed by the respective Coin/Walrus/Seal plugins.\n *\n *  Entries are processed serially. Strategies that use the resolved\n *  account signer acquire the per-address lease internally; strategies\n *  that do not are wrapped by this dispatcher. */\nexport const applyCrossCuttingFunding = (\n\tparts: ApplyCrossCuttingFundingArgs,\n): Effect.Effect<AppliedFunding, AccountAcquireError, StrategyRegistryService> =>\n\tEffect.gen(function* () {\n\t\tif (parts.funding.length === 0) {\n\t\t\treturn [];\n\t\t}\n\t\tconst registry = yield* StrategyRegistryService;\n\t\tconst applied: AppliedFundingEntry[] = [];\n\n\t\tfor (const entry of parts.funding) {\n\t\t\tif (entry.amount <= 0n) {\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\tyield* setCurrentPluginPhase(`checking ${entry.coin} funding`);\n\t\t\tconst existingBalance = yield* readExistingBalance(parts.balanceReader, {\n\t\t\t\towner: parts.address,\n\t\t\t\tcoinType: entry.fullCoinType,\n\t\t\t});\n\t\t\tif (existingBalance !== null && existingBalance >= entry.amount) {\n\t\t\t\tapplied.push({ ...entry, outcome: 'already-satisfied' });\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\t// Resolve the capability key from the projected coin type.\n\t\t\t//\n\t\t\t// SUI (`0x2::sui::SUI`) → reuse the faucet-request key so the\n\t\t\t// SUI auto-registered strategy fields the request (this\n\t\t\t// matches the default-funding pass and keeps the registry\n\t\t\t// surface uniform). The faucet contract takes\n\t\t\t// `{address, amount}` only (it never sees the resolved\n\t\t\t// account handle) — kept as its own helper so the typing is\n\t\t\t// honest at the dispatch site.\n\t\t\t//\n\t\t\t// Everything else → `coinType:<fullCoinType>` so user-defined\n\t\t\t// Coin plugins (and Walrus's exchange strategy keyed by\n\t\t\t// `coinType:<WAL fullCoinType>`) can contribute strategies\n\t\t\t// declaratively. These satisfy `AccountFundingStrategy` and\n\t\t\t// receive the resolved account handle in the request.\n\t\t\tconst isSui = entry.fullCoinType === SUI_FULL_COIN_TYPE;\n\t\t\tconst coinKey = `coinType:${entry.fullCoinType}` as const;\n\t\t\tconst key = isSui ? (`faucet:request:${parts.chainId}` as const) : coinKey;\n\n\t\t\tconst wrapCrossCuttingFailure = (cause: unknown): AccountAcquireError =>\n\t\t\t\tfundingFailureError({\n\t\t\t\t\tphase: 'fund-cross-cutting',\n\t\t\t\t\taccountName: parts.accountName,\n\t\t\t\t\tvariant: parts.variant,\n\t\t\t\t\tkey,\n\t\t\t\t\tamount: entry.amount,\n\t\t\t\t\tcause,\n\t\t\t\t});\n\n\t\t\tlet request: Effect.Effect<void, AccountAcquireError>;\n\t\t\tlet usesAccountSigner = false;\n\t\t\tif (isSui) {\n\t\t\t\t// FaucetStrategy lookup — request shape is `{address, amount}`.\n\t\t\t\t// Architecture-distilled: explicit SUI entries are the\n\t\t\t\t// normal gas faucet path, so missing strategy is\n\t\t\t\t// actionable and loud (no silent drop).\n\t\t\t\tconst strategy = yield* chainKeyedStrategyFor<FaucetStrategy>(\n\t\t\t\t\tFAUCET_CAPABILITY_KEY_PREFIX,\n\t\t\t\t\tparts.chainId,\n\t\t\t\t).pipe(\n\t\t\t\t\tEffect.catchTag('StrategyNotFoundError', (err) =>\n\t\t\t\t\t\tEffect.fail(\n\t\t\t\t\t\t\taccountAcquireError({\n\t\t\t\t\t\t\t\tphase: 'fund-cross-cutting',\n\t\t\t\t\t\t\t\taccountName: parts.accountName,\n\t\t\t\t\t\t\t\tvariant: parts.variant,\n\t\t\t\t\t\t\t\tmessage:\n\t\t\t\t\t\t\t\t\t`Account '${parts.accountName}': no SUI funding strategy registered ` +\n\t\t\t\t\t\t\t\t\t`for chain '${parts.chainId}'. Registered keys: [${err.registeredKeys.join(', ')}].`,\n\t\t\t\t\t\t\t\tcause: err,\n\t\t\t\t\t\t\t\thint: 'Ensure a sui() plugin with a faucet-bearing mode (local/live-testnet/live-devnet) is in the stack.',\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t),\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t\trequest = strategy\n\t\t\t\t\t.request({ address: parts.address, amount: entry.amount })\n\t\t\t\t\t.pipe(Effect.mapError(wrapCrossCuttingFailure));\n\t\t\t} else {\n\t\t\t\t// AccountFundingStrategy lookup — request shape is\n\t\t\t\t// `{address, amount, account}`. Architecture-distilled:\n\t\t\t\t// optional-faucet-is-noop for arbitrary coins — missing\n\t\t\t\t// registration short-circuits silently rather than\n\t\t\t\t// failing the acquire.\n\t\t\t\tconst strategy = yield* registry\n\t\t\t\t\t.get<typeof coinKey, AccountFundingStrategy>(coinKey)\n\t\t\t\t\t.pipe(\n\t\t\t\t\t\tEffect.catchTag('StrategyNotFoundError', () =>\n\t\t\t\t\t\t\tEffect.succeed(null as AccountFundingStrategy | null),\n\t\t\t\t\t\t),\n\t\t\t\t\t);\n\t\t\t\tif (strategy === null) {\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tusesAccountSigner = strategy.usesAccountSigner === true;\n\t\t\t\trequest = strategy\n\t\t\t\t\t.request({ address: parts.address, amount: entry.amount, account: parts.account })\n\t\t\t\t\t.pipe(Effect.mapError(wrapCrossCuttingFailure));\n\t\t\t}\n\n\t\t\tyield* setCurrentPluginPhase(`funding ${entry.coin}`);\n\t\t\tyield* usesAccountSigner\n\t\t\t\t? request\n\t\t\t\t: withAddressLease(parts.broker, parts.accountName, parts.address, request);\n\t\t\tyield* setCurrentPluginPhase(`waiting for ${entry.coin} funding settlement`);\n\t\t\tyield* waitForBalanceAtLeast({\n\t\t\t\tbalanceReader: parts.balanceReader,\n\t\t\t\taccountName: parts.accountName,\n\t\t\t\tvariant: parts.variant,\n\t\t\t\tphase: 'fund-cross-cutting',\n\t\t\t\towner: parts.address,\n\t\t\t\tcoinType: entry.fullCoinType,\n\t\t\t\tcoinLabel: entry.coin,\n\t\t\t\tamount: entry.amount,\n\t\t\t});\n\t\t\tapplied.push({ ...entry, outcome: 'funded' });\n\t\t}\n\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t[AccountSpans.name]: parts.accountName,\n\t\t\t[AccountSpans.address]: parts.address,\n\t\t\t[AccountSpans.fundCrossCuttingCount]: parts.funding.length,\n\t\t\t[SuiSpans.chain]: parts.chainId,\n\t\t});\n\t\treturn applied;\n\t}).pipe(\n\t\tEffect.withSpan('devstack.plugin.account.applyCrossCuttingFunding', {\n\t\t\tattributes: {\n\t\t\t\t[AccountSpans.name]: parts.accountName,\n\t\t\t\t[AccountSpans.address]: parts.address,\n\t\t\t\t[AccountSpans.fundCrossCuttingEntries]: parts.funding.length,\n\t\t\t},\n\t\t}),\n\t);\n\nconst readExistingBalance = (\n\tbalanceReader: FundingBalanceReader,\n\targs: {\n\t\treadonly owner: string;\n\t\treadonly coinType: string;\n\t},\n): Effect.Effect<bigint | null> => balanceReader.readBalance(args);\n\nconst waitForBalanceAtLeast = (parts: {\n\treadonly balanceReader: FundingBalanceReader;\n\treadonly accountName: string;\n\treadonly variant: AccountVariantKind;\n\treadonly phase: 'fund-default' | 'fund-cross-cutting';\n\treadonly owner: string;\n\treadonly coinType: string;\n\treadonly coinLabel: string;\n\treadonly amount: bigint;\n}): Effect.Effect<void, AccountAcquireError> => {\n\tconst reader = parts.balanceReader;\n\t// Test-only opt-out — the `NULL_BALANCE_READER` sentinel explicitly\n\t// declares \"this caller doesn't model the read/poll loop\". Production\n\t// readers never set `skipFinalityWait`, so the wait stays load-bearing\n\t// on real wire calls.\n\tif (skipsFinalityWait(reader)) {\n\t\treturn Effect.void;\n\t}\n\treturn Effect.gen(function* () {\n\t\tconst read = readExistingBalance(reader, {\n\t\t\towner: parts.owner,\n\t\t\tcoinType: parts.coinType,\n\t\t});\n\t\tconst lastBalance = yield* read.pipe(\n\t\t\tEffect.repeat({\n\t\t\t\tschedule: makeBoundedSpacedSchedule(\n\t\t\t\t\tBALANCE_POLL_PROFILE.intervalMs,\n\t\t\t\t\tBALANCE_POLL_PROFILE.timeoutMs,\n\t\t\t\t),\n\t\t\t\tuntil: (balance) => balance !== null && balance >= parts.amount,\n\t\t\t}),\n\t\t);\n\t\tif (lastBalance !== null && lastBalance >= parts.amount) {\n\t\t\treturn;\n\t\t}\n\t\treturn yield* Effect.fail(\n\t\t\taccountAcquireError({\n\t\t\t\tphase: parts.phase,\n\t\t\t\taccountName: parts.accountName,\n\t\t\t\tvariant: parts.variant,\n\t\t\t\tmessage:\n\t\t\t\t\t`Account '${parts.accountName}': funding for ${parts.coinLabel} was accepted ` +\n\t\t\t\t\t`but balance did not reach ${parts.amount} before the settlement timeout ` +\n\t\t\t\t\t`(last=${lastBalance === null ? '<unavailable>' : lastBalance}).`,\n\t\t\t\thint:\n\t\t\t\t\t'The faucet or funding strategy returned before the funded coin became spendable. ' +\n\t\t\t\t\t'Check the funding strategy finality gate and Sui RPC health.',\n\t\t\t}),\n\t\t);\n\t});\n};\n"],"mappings":"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"}

package/dist/plugins/account/index.d.mts

@@ -3,12 +3,11 @@ import { ProjectionDecl } from "../../contracts/projection.mjs";
 import { SnapshotableDecl } from "../../contracts/snapshotable.mjs";
 import { StrategyContributorDecl } from "../../contracts/strategy-contributor.mjs";
 import { AnyResourceRef, Plugin, ResourceRef } from "../../substrate/plugin.mjs";
-import { SeedObjectsAccumulator } from "../sui/seed-objects.mjs";
 import { SuiClient } from "../sui/mode/shared.mjs";
 import { SuiOptions } from "../sui/mode/spec.mjs";
 import { AccountAcquireError, AccountAcquirePhase, AccountError, AccountSignError, AccountSignPhase, AccountVariantKind } from "./errors.mjs";
-import { AccountOptions, AccountValue, TxResult } from "./service.mjs";
-import { AccountFunding, AccountFundingCoinValue, AccountFundingEntry, AccountFundingRequest, AccountFundingResult, AccountFundingStrategy, CoinMember, CrossCuttingFundingEntry, CrossCuttingFundingProvider, DEFAULT_EPHEMERAL_FUND_MIST, ProjectedFunding, ProjectedFundingEntry, SUI_FULL_COIN_TYPE, SuiFundingEntry } from "./funding.mjs";
+import { AccountOptions, AccountValue, SignAndExecuteResult, TxResult } from "./service.mjs";
+import { AccountFunding, AccountFundingCoinValue, AccountFundingEntry, AccountFundingRequest, AccountFundingResult, AccountFundingStrategy, AppliedFunding, AppliedFundingEntry, AppliedFundingOutcome, CoinMember, CrossCuttingFundingEntry, CrossCuttingFundingProvider, DEFAULT_EPHEMERAL_FUND_MIST, ProjectedFunding, ProjectedFundingEntry, SUI_FULL_COIN_TYPE, SuiFundingEntry } from "./funding.mjs";
 import { AccountRegistryEntry, AccountRegistryFunding } from "./registry.mjs";
 import { AccountBindings } from "./codegen.mjs";
 import { ResolvedKeypair, SignatureScheme } from "./keypair.mjs";
@@ -47,7 +46,6 @@ type FundingEntryProviderDependencies<Entry> = Entry extends {
 type FundingProviderDependencies<Entries extends readonly unknown[]> = Entries extends readonly [infer Head, ...infer Tail] ? readonly [...FundingEntryProviderDependencies<Head>, ...FundingProviderDependencies<Tail>] : readonly [];
 declare const account: <const N extends string, const Funding extends AccountFunding = readonly []>(name: N, opts?: AccountOptions<Funding>) => Plugin<`account/${N}`, AccountValue, readonly [ResourceRef<"sui", SuiClient & {
   readonly mode: SuiOptions["mode"];
-  readonly seedObjects: SeedObjectsAccumulator;
 }>, ...FundingCoinDependencies<Funding>, ...FundingProviderDependencies<Funding>], readonly [SnapshotableDecl, CodegenableDecl<`account/${N}`>, StrategyContributorDecl<`account:${N}`, AccountRegistryEntry>, ProjectionDecl]>;
 //#endregion
 export { AccountResourceId, account };