@mysten-incubation/devstack 0.0.1 → 0.1.0

package/dist/plugins/sui/fork-orchestration.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"fork-orchestration.mjs","names":[],"sources":["../../../src/plugins/sui/fork-orchestration.ts"],"sourcesContent":["// Fork-mode orchestration helpers.\n//\n// Owns the runtime SDK guard for surfaces the sui-fork binary panics\n// on. The data-dir lock + seed-manifest meta gate live in the\n// fork-mode builder once that wiring lands; they belong to the same\n// file once they have real implementations to anchor on.\n\nimport { forkUnsupportedError, type ForkUnsupportedError } from './errors.ts';\n\n/** Lock-holder identity persisted alongside the data-dir lock file.\n *  Two fork acquires against the same data dir surface this; one\n *  wins, the other gets an actionable error. */\nexport interface ForkLockHolder {\n\treadonly pid: number;\n\treadonly host: string;\n\treadonly instanceId: string;\n\treadonly startedAt: number;\n}\n\n/** On-disk seed-manifest snapshot. */\nexport interface ForkMeta {\n\treadonly version: number;\n\treadonly createdAt: number;\n\treadonly upstream: string;\n\treadonly checkpoint?: string;\n\t/** Lowercased + sorted (architecture invariant: configHash MUST\n\t *  be stable across orderings). */\n\treadonly seedAddresses: ReadonlyArray<string>;\n\t/** Lowercased + sorted, same invariant. */\n\treadonly seedObjects: ReadonlyArray<string>;\n\t/** Digest of the above four fields. `autoTickMs` is NOT folded\n\t *  in (architecture invariant). */\n\treadonly configHash: string;\n\treadonly runtime?: { readonly autoTickMs?: number };\n}\n\n/** Surfaces that the sui-fork binary explicitly panics on. New\n *  upstream additions fail OPEN by default — architecture\n *  invariant. */\nexport const FORK_UNSUPPORTED_SURFACES: ReadonlyArray<string> = [\n\t// `client.core.*` methods that hit `simulate_transaction` /\n\t// balance-derivation paths the fork binary doesn't implement.\n\t'getBalance',\n\t'listBalances',\n\t'getCoinInfo',\n] as const;\n\n/** Wrap a Sui SDK shim with the fork guard. Property access for a\n *  blocklisted surface SYNCHRONOUSLY throws — the wire call never\n *  happens, so the fork binary stays up. */\nexport type ForkGuardedSdk<Sdk extends { readonly core: object }> = Omit<Sdk, 'core'> & {\n\treadonly core: Sdk['core'];\n};\n\nexport const wrapWithForkGuard = <Sdk extends { readonly core: object }>(\n\tsdk: Sdk,\n): ForkGuardedSdk<Sdk> => {\n\tconst guardedCore = new Proxy(sdk.core as Record<string, unknown>, {\n\t\tget(target, prop, receiver) {\n\t\t\tif (typeof prop === 'string' && FORK_UNSUPPORTED_SURFACES.includes(prop)) {\n\t\t\t\tconst err: ForkUnsupportedError = forkUnsupportedError(\n\t\t\t\t\t`client.core.${prop}`,\n\t\t\t\t\t'fork mode does not implement this SDK surface — use the impersonation helper ' +\n\t\t\t\t\t\t'or read state via ChainProbe.',\n\t\t\t\t);\n\t\t\t\tthrow err;\n\t\t\t}\n\t\t\treturn Reflect.get(target, prop, receiver);\n\t\t},\n\t}) as Sdk['core'];\n\t// Preserve all SDK fields (e.g. SuiSdkShim's opaque `client` for\n\t// Transaction.build) — only the `core` proxy intercepts; siblings\n\t// like `client` flow through unchanged.\n\treturn { ...sdk, core: guardedCore };\n};\n"],"mappings":";;;;;AAuCA,MAAa,4BAAmD;CAG/D;CACA;CACA;CACA;AASD,MAAa,qBACZ,QACyB;CACzB,MAAM,cAAc,IAAI,MAAM,IAAI,MAAiC,EAClE,IAAI,QAAQ,MAAM,UAAU;AAC3B,MAAI,OAAO,SAAS,YAAY,0BAA0B,SAAS,KAAK,CAMvE,OALkC,qBACjC,eAAe,QACf,6GAGQ;AAEV,SAAO,QAAQ,IAAI,QAAQ,MAAM,SAAS;IAE3C,CAAC;AAIF,QAAO;EAAE,GAAG;EAAK,MAAM;EAAa"}
+{"version":3,"file":"fork-orchestration.mjs","names":["nodeHostname"],"sources":["../../../src/plugins/sui/fork-orchestration.ts"],"sourcesContent":["// Fork-mode orchestration helpers.\n//\n// Owns the runtime SDK guard for surfaces the sui-fork binary panics\n// on, plus the data-dir mutual-exclusion holder protocol (acquire /\n// heartbeat / release) that serializes two stacks against the same\n// `<stackRoot>/sui-fork/<key>` data dir — concurrent writers to a\n// single fork data dir corrupt the binary's RocksDB.\n\nimport { readFileSync, unlinkSync } from 'node:fs';\nimport { join } from 'node:path';\nimport { hostname as nodeHostname } from 'node:os';\n\nimport { Effect, Schedule, Schema, type Scope } from 'effect';\n\nimport { atomicWriteJsonSync } from '../../substrate/runtime/atomic-write.ts';\nimport {\n\tacquireStackLock,\n\tisPidAlive,\n\tprocessStartTime,\n} from '../../substrate/runtime/cross-process/index.ts';\nimport { selfPid } from '../../substrate/runtime/cross-process/self-pid.ts';\nimport { mintRandomSuffix } from '../../substrate/runtime/random-suffix.ts';\nimport { SpanAttr } from '../../substrate/runtime/observability/spans.ts';\nimport { parseVersionedDocumentBodyOrNull } from '../../substrate/versioned-doc-sync.ts';\nimport {\n\tforkUnsupportedError,\n\tsuiPluginError,\n\ttype ForkUnsupportedError,\n\ttype SuiPluginError,\n} from './errors.ts';\n\n/** Lock-holder identity persisted alongside the data-dir lock file.\n *  Two fork acquires against the same data dir surface this; one\n *  wins, the other gets an actionable error. */\nexport interface ForkLockHolder {\n\treadonly pid: number;\n\treadonly host: string;\n\treadonly instanceId: string;\n\treadonly startedAt: number;\n\t/** FNV-1a hash of `ps -o lstart` for `pid`, captured at claim time\n\t *  via the SAME `processStartTime` probe roster/liveness use. Lets\n\t *  same-host liveness distinguish a LIVE holder from a recycled-PID\n\t *  impostor (a crashed-then-reused pid). `null` when the platform\n\t *  couldn't probe — treated conservatively (see `isForkHolderAlive`),\n\t *  matching roster's `isOwnEntry` / `checkHolderLiveness` null policy. */\n\treadonly startTime: number | null;\n}\n\n// -----------------------------------------------------------------------------\n// Data-dir mutual-exclusion holder protocol\n// -----------------------------------------------------------------------------\n//\n// `acquireStackLock` is a HOLD-BRIEFLY primitive (it reclaims after\n// ~30s of staleness, so it must NOT be held for the fork's lifetime —\n// cross-process § \"the lock is held BRIEFLY\"). So the long-lived claim\n// on a fork data dir is a HOLDER FILE, mirroring the roster's\n// heartbeat + (pid, host) liveness pattern: we take the brief OS lock\n// only to serialize the read-holder → liveness-check → write-holder\n// critical section, then release it. A scope-bound fiber refreshes\n// `startedAt` on a cadence comfortably under the staleness window so\n// peers see we are alive; a finalizer removes the holder on teardown.\n\n/** Heartbeat cadence — refresh `startedAt` every 10s. Matches the\n *  roster's `heartbeatIntervalMillis`. The heartbeat keeps the holder's\n *  `startedAt`/`startTime` fresh for diagnostics and so a peer that DOES\n *  later add a foreign-host liveness signal has recent data; with the\n *  current conservative foreign-host policy (always-alive) it is not a\n *  reclaim gate, mirroring the roster heartbeat fiber. */\nconst FORK_HOLDER_HEARTBEAT_INTERVAL_MILLIS = 10_000;\n\n/** Brief acquire timeout for the holder critical section. The OS lock\n *  is held only across a read → liveness-check → write, never across\n *  I/O — a tight budget keeps peers reacting quickly to a release. */\nconst FORK_HOLDER_LOCK_TIMEOUT_MILLIS = 5_000;\n\n// No `version` field by design. `parseVersionedDocumentBodyOrNull`\n// decodes the raw body against this schema and treats ANY decode miss\n// (including a future shape change) as `null` ⇒ \"no live holder\",\n// which the acquire path handles by reclaiming. Because the holder file\n// is transient (it lives inside the data dir and a wipe removes it —\n// see `forkHolderPath` below), a leftover old-shape body self-heals on\n// the next acquire rather than blocking it. This mirrors stack-lock's\n// precedent for short-lived holder files; persistent docs that must\n// survive a format change use `versionedDocSchema` with a bumped\n// version stamp instead.\nconst ForkLockHolderSchema = Schema.Struct({\n\tpid: Schema.Number,\n\thost: Schema.String,\n\tinstanceId: Schema.String,\n\tstartedAt: Schema.Number,\n\tstartTime: Schema.NullOr(Schema.Number),\n});\n\n/** Holder file lives inside the data dir so it travels with the dir's\n *  lifecycle (wipe removes it). */\nexport const forkHolderPath = (dataDir: string): string => join(dataDir, 'holder.json');\n\n/** Is an existing holder alive? Mirrors `liveness.checkHolderLiveness`\n *  exactly (the `RosterHolder` shape doesn't fit — that carries\n *  `hostname`/`heartbeatAt`, not our `host`/`startedAt` — so we\n *  replicate its logic against the `ForkLockHolder` fields):\n *\n *   - Foreign-host → ALWAYS ALIVE. Cross-host pid comparison is\n *     meaningless, and comparing our `Date.now()` to the holder's\n *     `startedAt` (a different host's clock) is clock-skew-unsafe — a\n *     >~20s skew on an NFS root could reclaim a LIVE foreign holder and\n *     produce dual-writer RocksDB corruption. The NFS-safe trade is to\n *     never auto-reclaim a foreign holder; a truly-abandoned one needs\n *     manual cleanup (`rm <dataDir>/holder.json`).\n *   - Same-host → pid must be live AND its start-time must match, so a\n *     crashed-then-recycled pid (an abandoned dir whose pid the kernel\n *     handed to an unrelated process) no longer reads as \"in use\".\n *\n *  A `null` start-time on either side is handled conservatively the\n *  same way roster does — ALIVE — because we have nothing to dispute\n *  the recorded identity with (mismatching a probed stamp against a\n *  recorded `null`, or vice versa, would falsely harvest a live\n *  holder). */\nconst isForkHolderAlive = (holder: ForkLockHolder): boolean => {\n\tif (holder.host !== nodeHostname()) return true;\n\tif (!isPidAlive(holder.pid)) return false;\n\tconst probedStart = processStartTime(holder.pid);\n\tif (probedStart === null) return true;\n\tif (holder.startTime === null) return true;\n\treturn probedStart === holder.startTime;\n};\n\nconst readForkHolder = (path: string): ForkLockHolder | null =>\n\tparseVersionedDocumentBodyOrNull(\n\t\tsafeReadHolderRaw(path),\n\t\tForkLockHolderSchema,\n\t\t'sui-fork.holder',\n\t);\n\n/** Read the holder file's bytes, returning `''` (→ parses to null) on\n *  any I/O error. A missing/unreadable holder means \"no live claim\";\n *  the caller writes its own. Sync read is correct here — we are\n *  inside the brief OS-lock critical section, same non-yielding\n *  discipline as the cross-process roster reader. */\nconst safeReadHolderRaw = (path: string): string => {\n\ttry {\n\t\treturn readFileSync(path, 'utf8');\n\t} catch {\n\t\treturn '';\n\t}\n};\n\nconst ownForkHolder = (): ForkLockHolder => {\n\tconst pid = selfPid();\n\treturn {\n\t\tpid,\n\t\thost: nodeHostname(),\n\t\tinstanceId: mintRandomSuffix(8),\n\t\tstartedAt: Date.now(),\n\t\t// Same probe roster/liveness record at claim time — a `null`\n\t\t// (exotic platform / transient `ps` error) propagates verbatim so\n\t\t// the conservative null branch in `isForkHolderAlive` applies.\n\t\tstartTime: processStartTime(pid),\n\t};\n};\n\n/** Run `body` under a BRIEFLY-held `stack.lock`. The lock serializes\n *  the holder file's read → liveness-check → write critical section so\n *  two claimers never both decide the dir is free. Released the moment\n *  `body` completes — never held across the fork's lifetime. */\nconst underStackLock = <A>(\n\tstackLockFile: string,\n\tholderPath: string,\n\tbody: Effect.Effect<A, SuiPluginError>,\n): Effect.Effect<A, SuiPluginError> =>\n\tEffect.scoped(\n\t\tEffect.gen(function* () {\n\t\t\tyield* acquireStackLock(stackLockFile, FORK_HOLDER_LOCK_TIMEOUT_MILLIS).pipe(\n\t\t\t\tEffect.mapError((cause) =>\n\t\t\t\t\tsuiPluginError(\n\t\t\t\t\t\t'fork-lock',\n\t\t\t\t\t\t`sui fork mode: failed to acquire stack lock for data dir ${holderPath}: ${cause._tag}`,\n\t\t\t\t\t\tcause,\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t);\n\t\t\treturn yield* body;\n\t\t}),\n\t);\n\n/** The brief critical section: under `stack.lock`, read any existing\n *  holder; if a LIVE one is present, fail with an actionable error;\n *  otherwise claim by writing our own holder atomically. Returns the\n *  holder we wrote so the heartbeat fiber can refresh it. */\nconst claimForkHolder = (\n\tstackLockFile: string,\n\tholderPath: string,\n): Effect.Effect<ForkLockHolder, SuiPluginError> =>\n\tunderStackLock(\n\t\tstackLockFile,\n\t\tholderPath,\n\t\tEffect.gen(function* () {\n\t\t\tconst existing = readForkHolder(holderPath);\n\t\t\tif (existing !== null && isForkHolderAlive(existing)) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tsuiPluginError(\n\t\t\t\t\t\t'fork-lock',\n\t\t\t\t\t\t`sui fork mode: fork data dir ${holderPath} is in use by pid ${existing.pid} on ` +\n\t\t\t\t\t\t\t`${existing.host}; stop that stack or use a different fork key.`,\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst self = ownForkHolder();\n\t\t\tyield* writeForkHolder(holderPath, self);\n\t\t\treturn self;\n\t\t}),\n\t);\n\n/** Heartbeat: under the brief lock, re-stamp `startedAt` IF the holder\n *  on disk is still ours. A peer that reclaimed us (same-host recycled-\n *  pid takeover) owns the file now; we must not clobber its claim, so a\n *  mismatched `instanceId` makes this a no-op. */\nconst refreshForkHolder = (\n\tstackLockFile: string,\n\tholderPath: string,\n\tself: ForkLockHolder,\n): Effect.Effect<void, SuiPluginError> =>\n\tunderStackLock(\n\t\tstackLockFile,\n\t\tholderPath,\n\t\tEffect.gen(function* () {\n\t\t\tconst current = readForkHolder(holderPath);\n\t\t\tif (current !== null && current.instanceId !== self.instanceId) return;\n\t\t\tyield* writeForkHolder(holderPath, { ...self, startedAt: Date.now() });\n\t\t}),\n\t);\n\n/** Scope-finalizer release: unlink the holder file ONLY if it is still\n *  ours. A finalizer that unconditionally `unlinkSync`d by path would,\n *  after a legitimate same-host reclaim (our pid crashed-and-recycled,\n *  a peer took over), delete the PEER's holder and unprotect a dir the\n *  peer is actively writing. Re-reading and matching `instanceId` makes\n *  the release a no-op once we no longer own the file. A missing/\n *  unreadable holder is already-gone — also a no-op. Best-effort: a\n *  crash that skips this is recovered by the next peer's same-host\n *  liveness check. */\nconst releaseOwnForkHolder = (holderPath: string, self: ForkLockHolder): void => {\n\tconst current = readForkHolder(holderPath);\n\tif (current !== null && current.instanceId !== self.instanceId) return;\n\ttry {\n\t\tunlinkSync(holderPath);\n\t} catch {\n\t\t// Already gone — ok.\n\t}\n};\n\nconst writeForkHolder = (\n\tpath: string,\n\tholder: ForkLockHolder,\n): Effect.Effect<void, SuiPluginError> =>\n\tEffect.try({\n\t\ttry: () => atomicWriteJsonSync(path, holder),\n\t\tcatch: (cause) =>\n\t\t\tsuiPluginError(\n\t\t\t\t'fork-lock',\n\t\t\t\t`sui fork mode: failed to write fork data-dir holder ${path}.`,\n\t\t\t\tcause,\n\t\t\t),\n\t});\n\n/**\n * Acquire the data-dir holder for the lifetime of the surrounding\n * scope.\n *\n *   1. Briefly take `stack.lock`, read any existing holder, fail if a\n *      live peer holds it, else write our own holder. Release the OS\n *      lock immediately (the claim outlives the lock).\n *   2. Fork a scope-bound heartbeat fiber that re-takes the brief lock\n *      every `FORK_HOLDER_HEARTBEAT_INTERVAL_MILLIS` and refreshes\n *      `startedAt` (only while the file is still ours). A heartbeat\n *      failure is non-fatal — log and retry next tick (same policy as\n *      the roster heartbeat fiber).\n *   3. Register a finalizer that removes our holder file on scope\n *      close (wipe / restart / Ctrl-C) — but ONLY if the on-disk holder\n *      is still ours, so a legitimate peer reclaim is never clobbered.\n *      A crash that skips the finalizer is recovered same-host by the\n *      next peer's liveness check (foreign-host needs manual cleanup —\n *      the NFS-safe trade in `isForkHolderAlive`).\n */\nexport const acquireForkDataDirHolder = (\n\tstackLockFile: string,\n\tdataDir: string,\n): Effect.Effect<ForkLockHolder, SuiPluginError, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\tconst holderPath = forkHolderPath(dataDir);\n\t\tconst self = yield* claimForkHolder(stackLockFile, holderPath);\n\t\tyield* Effect.addFinalizer(() => Effect.sync(() => releaseOwnForkHolder(holderPath, self)));\n\t\tconst refresh = refreshForkHolder(stackLockFile, holderPath, self).pipe(\n\t\t\tEffect.catch((err) =>\n\t\t\t\tEffect.logWarning('sui fork data-dir holder heartbeat failed; next tick will retry').pipe(\n\t\t\t\t\tEffect.annotateLogs({\n\t\t\t\t\t\t[SpanAttr.phase]: err.phase,\n\t\t\t\t\t\t[SpanAttr.errorMessage]: err.message,\n\t\t\t\t\t}),\n\t\t\t\t),\n\t\t\t),\n\t\t);\n\t\tyield* refresh.pipe(\n\t\t\tEffect.repeat(Schedule.spaced(`${FORK_HOLDER_HEARTBEAT_INTERVAL_MILLIS} millis`)),\n\t\t\tEffect.forkScoped,\n\t\t);\n\t\treturn self;\n\t}).pipe(Effect.withSpan('devstack.plugin.sui.fork.acquireDataDirHolder'));\n\n/** Surfaces that the sui-fork binary explicitly panics on. New\n *  upstream additions fail OPEN by default — architecture\n *  invariant. */\nexport const FORK_UNSUPPORTED_SURFACES: ReadonlyArray<string> = [\n\t// `client.core.*` methods that hit `simulate_transaction` /\n\t// balance-derivation paths the fork binary doesn't implement.\n\t'getBalance',\n\t'listBalances',\n\t'getCoinInfo',\n] as const;\n\n/** Wrap a Sui SDK shim with the fork guard. Property access for a\n *  blocklisted surface SYNCHRONOUSLY throws — the wire call never\n *  happens, so the fork binary stays up. */\nexport const wrapWithForkGuard = <Sdk extends { readonly core: object }>(sdk: Sdk): Sdk => {\n\tconst guardedCore = new Proxy(sdk.core as Record<string, unknown>, {\n\t\tget(target, prop, receiver) {\n\t\t\tif (typeof prop === 'string' && FORK_UNSUPPORTED_SURFACES.includes(prop)) {\n\t\t\t\tconst err: ForkUnsupportedError = forkUnsupportedError(\n\t\t\t\t\t`client.core.${prop}`,\n\t\t\t\t\t'fork mode does not implement this SDK surface — use the impersonation helper ' +\n\t\t\t\t\t\t'or read state via ChainProbe.',\n\t\t\t\t);\n\t\t\t\tthrow err;\n\t\t\t}\n\t\t\treturn Reflect.get(target, prop, receiver);\n\t\t},\n\t}) as Sdk['core'];\n\t// Preserve all SDK fields (e.g. SuiSdkShim's opaque `client` for\n\t// Transaction.build) — only the `core` proxy intercepts; siblings\n\t// like `client` flow through unchanged.\n\treturn { ...sdk, core: guardedCore };\n};\n"],"mappings":"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"}

package/dist/plugins/sui/fork-transaction.d.mts

@@ -0,0 +1,2 @@
+import { Effect } from "effect";
+import { Transaction } from "@mysten/sui/transactions";

package/dist/plugins/sui/fork-transaction.mjs

@@ -1,10 +1,46 @@
 import { suiPluginError } from "./errors.mjs";
+import { formatUnknownError } from "../../substrate/runtime/format-unknown-error.mjs";
 import { Effect } from "effect";
 import { normalizeSuiAddress } from "@mysten/sui/utils";
 import { Inputs, TransactionDataBuilder } from "@mysten/sui/transactions";
 //#region src/plugins/sui/fork-transaction.ts
-const FORK_IMPERSONATION_GAS_BUDGET = 1000000000n;
+const FORK_IMPERSONATION_GAS_BUDGET = 100000000n;
 const FORK_IMPERSONATION_GAS_PRICE = 1000n;
+/** Canonical SUI gas coin type used to filter `listCoins` when picking
+*  a gas/funding coin. Kept local so the sui plugin needn't depend on
+*  the account plugin's `SUI_FULL_COIN_TYPE`. */
+const SUI_GAS_COIN_TYPE = "0x2::sui::SUI";
+/** `listCoins` page size while scanning for a sufficient coin. */
+const FORK_COIN_PAGE_SIZE = 50;
+/** Paginate `owner`'s SUI coins and return the first whose balance covers
+*  `minBalanceMist` (with that balance), or `undefined` if none across all
+*  pages. `listCoins` is paginated and NOT balance-ordered, so a sufficient
+*  coin can sit behind dust on a later page — we must page, never sample
+*  page 1. Shared by gas selection and the fork faucet. */
+const firstSufficientSuiCoin = async (client, owner, minBalanceMist) => {
+	let cursor = null;
+	do {
+		const page = await client.listCoins({
+			owner,
+			coinType: SUI_GAS_COIN_TYPE,
+			cursor,
+			limit: FORK_COIN_PAGE_SIZE
+		});
+		for (const candidate of page.objects) {
+			if (candidate.balance === void 0) continue;
+			const balanceMist = BigInt(candidate.balance);
+			if (balanceMist >= minBalanceMist) return {
+				coin: {
+					objectId: candidate.objectId,
+					version: String(candidate.version),
+					digest: candidate.digest
+				},
+				balanceMist
+			};
+		}
+		cursor = page.hasNextPage === true ? page.cursor ?? null : null;
+	} while (cursor !== null);
+};
 const prepareForkImpersonationTransaction = (tx, sender, gasPayment) => {
 	tx.setSender(sender);
 	tx.setGasBudget(FORK_IMPERSONATION_GAS_BUDGET);
@@ -13,16 +49,20 @@ const prepareForkImpersonationTransaction = (tx, sender, gasPayment) => {
 	tx.setGasPayment([...gasPayment]);
 	if (tx.getData().expiration == null) tx.setExpiration({ None: true });
 };
-const buildForkImpersonationTransactionBytes = (tx, sender, client) => Effect.tryPromise({
+const buildForkImpersonationTransactionBytes = (tx, sender, client, gasCoin) => Effect.tryPromise({
 	try: async () => {
-		prepareForkImpersonationTransaction(tx, sender, await selectForkImpersonationGasPayment(client, sender));
+		prepareForkImpersonationTransaction(tx, sender, gasCoin !== void 0 ? [gasCoin] : await selectForkImpersonationGasPayment(client, sender));
 		await tx.prepareForSerialization({});
 		const data = tx.getData();
 		data.inputs = await Promise.all(data.inputs.map((input) => resolveForkInput(input, client)));
 		return TransactionDataBuilder.restore(data).build();
 	},
-	catch: (cause) => suiPluginError("fork-impersonate", `sui fork mode: failed to build fork impersonation transaction for ${sender}: ${stringifyCause(cause)}`, cause)
+	catch: (cause) => {
+		if (isSuiPluginError(cause)) return cause;
+		return suiPluginError("fork-impersonate", `sui fork mode: failed to build fork impersonation transaction for ${sender}: ${formatUnknownError(cause)}`, cause);
+	}
 });
+const isSuiPluginError = (value) => typeof value === "object" && value !== null && value._tag === "SuiPluginError";
 const resolveForkInput = async (input, client) => {
 	if (input.UnresolvedObject === void 0) return input;
 	const unresolved = input.UnresolvedObject;
@@ -51,9 +91,16 @@ const resolveForkInput = async (input, client) => {
 };
 const objectFromGetObjectResponse = (response) => {
 	const object = response.object;
-	if (typeof object !== "object" || object === null) throw new Error(`getObject returned no object: ${JSON.stringify(response)}`);
+	if (typeof object !== "object" || object === null) throw suiPluginError("fork-impersonate", "sui fork mode: getObject returned no object", { responseKeys: describeKeys(response) });
 	const candidate = object;
-	if (typeof candidate.objectId !== "string" || typeof candidate.version !== "string" || typeof candidate.digest !== "string") throw new Error(`getObject returned incomplete object ref: ${JSON.stringify(response)}`);
+	if (typeof candidate.objectId !== "string" || typeof candidate.version !== "string" || typeof candidate.digest !== "string") throw suiPluginError("fork-impersonate", "sui fork mode: getObject returned incomplete object ref", {
+		objectKeys: describeKeys(object),
+		missing: {
+			objectId: typeof candidate.objectId !== "string",
+			version: typeof candidate.version !== "string",
+			digest: typeof candidate.digest !== "string"
+		}
+	});
 	return {
 		objectId: candidate.objectId,
 		version: candidate.version,
@@ -62,35 +109,52 @@ const objectFromGetObjectResponse = (response) => {
 	};
 };
 const selectForkImpersonationGasPayment = async (client, sender) => {
-	const coin = (await client.listCoins({
-		owner: sender,
-		limit: 1
-	})).objects[0];
-	if (coin === void 0) throw new Error(`no SUI gas coins found for ${sender}`);
-	return [{
-		objectId: coin.objectId,
-		version: String(coin.version),
-		digest: coin.digest
-	}];
+	const found = await firstSufficientSuiCoin(client, sender, FORK_IMPERSONATION_GAS_BUDGET);
+	if (found === void 0) throw suiPluginError("fork-impersonate", `sui fork mode: no SUI coin >= ${FORK_IMPERSONATION_GAS_BUDGET} MIST (gas budget) found for ${sender}.`, {
+		sender,
+		requiredMist: FORK_IMPERSONATION_GAS_BUDGET.toString()
+	});
+	return [found.coin];
 };
+/** Find a SUI coin owned by `owner` that covers `minBalanceMist`, for use as
+*  BOTH gas payment and the `splitCoins(tx.gas, …)` funding source in a fork
+*  faucet transfer. Paginates the coin set (a sufficient coin can sit behind
+*  dust on a later page) and returns the first that qualifies. Fails with an
+*  actionable `SuiPluginError` when none exists — reused at boot to validate a
+*  configured whale before any funding runs. */
+const selectSufficientForkCoin = (client, owner, minBalanceMist) => Effect.tryPromise({
+	try: async () => {
+		const found = await firstSufficientSuiCoin(client, owner, minBalanceMist);
+		if (found === void 0) throw suiPluginError("fork-impersonate", `sui fork mode: no SUI coin >= ${minBalanceMist} MIST (request + gas budget) found for ${owner}. Use a fork faucet whale with a larger single coin, or fund a smaller amount.`, {
+			owner,
+			requiredMist: minBalanceMist.toString()
+		});
+		return found;
+	},
+	catch: (cause) => {
+		if (isSuiPluginError(cause)) return cause;
+		return suiPluginError("fork-impersonate", `sui fork mode: failed to select a SUI coin for ${owner}: ${formatUnknownError(cause)}`, cause);
+	}
+});
 const verifyForkImpersonationSender = (sender, txBytes) => Effect.try({
 	try: () => {
 		const actual = TransactionDataBuilder.fromBytes(txBytes).snapshot().sender;
-		if (actual == null) throw new Error("transaction has no sender");
-		if (normalizeSuiAddress(actual) !== normalizeSuiAddress(sender)) throw new Error(`transaction sender ${actual} does not match impersonated sender ${sender}`);
+		if (actual == null) throw suiPluginError("fork-impersonate", "sui fork mode: refused impersonation transaction — transaction has no sender", { expectedSender: sender });
+		if (normalizeSuiAddress(actual) !== normalizeSuiAddress(sender)) throw suiPluginError("fork-impersonate", "sui fork mode: refused impersonation transaction — sender mismatch", {
+			expectedSender: sender,
+			actualSender: actual
+		});
 	},
-	catch: (cause) => suiPluginError("fork-impersonate", `sui fork mode: refused impersonation transaction: ${stringifyCause(cause)}`, cause)
-});
-const stringifyCause = (cause) => {
-	if (cause instanceof Error) return cause.message;
-	if (typeof cause === "string") return cause;
-	try {
-		return JSON.stringify(cause);
-	} catch {
-		return String(cause);
+	catch: (cause) => {
+		if (isSuiPluginError(cause)) return cause;
+		return suiPluginError("fork-impersonate", `sui fork mode: refused impersonation transaction: ${formatUnknownError(cause)}`, cause);
 	}
+});
+const describeKeys = (value) => {
+	if (typeof value !== "object" || value === null) return [];
+	return Object.keys(value);
 };
 //#endregion
-export { buildForkImpersonationTransactionBytes, verifyForkImpersonationSender };
+export { FORK_IMPERSONATION_GAS_BUDGET, FORK_IMPERSONATION_GAS_PRICE, buildForkImpersonationTransactionBytes, prepareForkImpersonationTransaction, selectSufficientForkCoin, verifyForkImpersonationSender };
 
 //# sourceMappingURL=fork-transaction.mjs.map

package/dist/plugins/sui/fork-transaction.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"fork-transaction.mjs","names":[],"sources":["../../../src/plugins/sui/fork-transaction.ts"],"sourcesContent":["import { Effect } from 'effect';\n\nimport {\n\tInputs,\n\tTransaction,\n\tTransactionDataBuilder,\n\ttype CallArg,\n} from '@mysten/sui/transactions';\nimport { normalizeSuiAddress } from '@mysten/sui/utils';\n\nimport { suiPluginError, type SuiPluginError } from './errors.ts';\n\nexport const FORK_IMPERSONATION_GAS_BUDGET = 1_000_000_000n;\nexport const FORK_IMPERSONATION_GAS_PRICE = 1_000n;\n\ninterface ForkImpersonationGasClient {\n\treadonly getObject: (input: { readonly objectId: string }) => Promise<unknown>;\n\treadonly listCoins: (input: {\n\t\treadonly owner: string;\n\t\treadonly coinType?: string;\n\t\treadonly limit?: number;\n\t}) => Promise<{\n\t\treadonly objects: ReadonlyArray<{\n\t\t\treadonly objectId: string;\n\t\t\treadonly version: string | number | bigint;\n\t\t\treadonly digest: string;\n\t\t\treadonly balance?: string | number | bigint;\n\t\t}>;\n\t}>;\n}\n\nexport const prepareForkImpersonationTransaction = (\n\ttx: Transaction,\n\tsender: string,\n\tgasPayment: ReadonlyArray<{\n\t\treadonly objectId: string;\n\t\treadonly version: string;\n\t\treadonly digest: string;\n\t}>,\n): void => {\n\ttx.setSender(sender);\n\n\ttx.setGasBudget(FORK_IMPERSONATION_GAS_BUDGET);\n\ttx.setGasPrice(FORK_IMPERSONATION_GAS_PRICE);\n\ttx.setGasOwner(sender);\n\ttx.setGasPayment([...gasPayment]);\n\n\tconst data = tx.getData();\n\tif (data.expiration == null) tx.setExpiration({ None: true });\n};\n\nexport const buildForkImpersonationTransactionBytes = (\n\ttx: Transaction,\n\tsender: string,\n\tclient: ForkImpersonationGasClient,\n): Effect.Effect<Uint8Array, SuiPluginError> =>\n\tEffect.tryPromise({\n\t\ttry: async () => {\n\t\t\tconst gasPayment = await selectForkImpersonationGasPayment(client, sender);\n\t\t\tprepareForkImpersonationTransaction(tx, sender, gasPayment);\n\t\t\tawait tx.prepareForSerialization({});\n\t\t\tconst data = tx.getData();\n\t\t\tdata.inputs = await Promise.all(data.inputs.map((input) => resolveForkInput(input, client)));\n\t\t\treturn TransactionDataBuilder.restore(data).build();\n\t\t},\n\t\tcatch: (cause) =>\n\t\t\tsuiPluginError(\n\t\t\t\t'fork-impersonate',\n\t\t\t\t`sui fork mode: failed to build fork impersonation transaction for ${sender}: ${stringifyCause(cause)}`,\n\t\t\t\tcause,\n\t\t\t),\n\t});\n\nconst resolveForkInput = async (\n\tinput: CallArg,\n\tclient: ForkImpersonationGasClient,\n): Promise<CallArg> => {\n\tif (input.UnresolvedObject === undefined) return input;\n\tconst unresolved = input.UnresolvedObject;\n\tif (unresolved.initialSharedVersion != null) {\n\t\treturn Inputs.SharedObjectRef({\n\t\t\tobjectId: unresolved.objectId,\n\t\t\tinitialSharedVersion: unresolved.initialSharedVersion,\n\t\t\tmutable: unresolved.mutable ?? true,\n\t\t});\n\t}\n\tif (unresolved.version != null && unresolved.digest != null) {\n\t\treturn Inputs.ObjectRef({\n\t\t\tobjectId: unresolved.objectId,\n\t\t\tversion: unresolved.version,\n\t\t\tdigest: unresolved.digest,\n\t\t});\n\t}\n\n\tconst object = objectFromGetObjectResponse(\n\t\tawait client.getObject({ objectId: unresolved.objectId }),\n\t);\n\tconst owner = object.owner;\n\tif (owner?.$kind === 'Shared' && owner.Shared !== undefined) {\n\t\treturn Inputs.SharedObjectRef({\n\t\t\tobjectId: object.objectId,\n\t\t\tinitialSharedVersion: owner.Shared.initialSharedVersion,\n\t\t\tmutable: unresolved.mutable ?? true,\n\t\t});\n\t}\n\treturn Inputs.ObjectRef({\n\t\tobjectId: object.objectId,\n\t\tversion: object.version,\n\t\tdigest: object.digest,\n\t});\n};\n\nconst objectFromGetObjectResponse = (\n\tresponse: unknown,\n): {\n\treadonly objectId: string;\n\treadonly version: string;\n\treadonly digest: string;\n\treadonly owner?: {\n\t\treadonly $kind?: string;\n\t\treadonly Shared?: { readonly initialSharedVersion: string };\n\t};\n} => {\n\tconst object = (response as { readonly object?: unknown }).object;\n\tif (typeof object !== 'object' || object === null) {\n\t\tthrow new Error(`getObject returned no object: ${JSON.stringify(response)}`);\n\t}\n\tconst candidate = object as {\n\t\treadonly objectId?: unknown;\n\t\treadonly version?: unknown;\n\t\treadonly digest?: unknown;\n\t\treadonly owner?: {\n\t\t\treadonly $kind?: string;\n\t\t\treadonly Shared?: { readonly initialSharedVersion: string };\n\t\t};\n\t};\n\tif (\n\t\ttypeof candidate.objectId !== 'string' ||\n\t\ttypeof candidate.version !== 'string' ||\n\t\ttypeof candidate.digest !== 'string'\n\t) {\n\t\tthrow new Error(`getObject returned incomplete object ref: ${JSON.stringify(response)}`);\n\t}\n\treturn {\n\t\tobjectId: candidate.objectId,\n\t\tversion: candidate.version,\n\t\tdigest: candidate.digest,\n\t\towner: candidate.owner,\n\t};\n};\n\nconst selectForkImpersonationGasPayment = async (\n\tclient: ForkImpersonationGasClient,\n\tsender: string,\n): Promise<\n\tReadonlyArray<{ readonly objectId: string; readonly version: string; readonly digest: string }>\n> => {\n\tconst response = await client.listCoins({ owner: sender, limit: 1 });\n\tconst coin = response.objects[0];\n\tif (coin === undefined) {\n\t\tthrow new Error(`no SUI gas coins found for ${sender}`);\n\t}\n\treturn [\n\t\t{\n\t\t\tobjectId: coin.objectId,\n\t\t\tversion: String(coin.version),\n\t\t\tdigest: coin.digest,\n\t\t},\n\t];\n};\n\nexport const verifyForkImpersonationSender = (\n\tsender: string,\n\ttxBytes: Uint8Array,\n): Effect.Effect<void, SuiPluginError> =>\n\tEffect.try({\n\t\ttry: () => {\n\t\t\tconst actual = TransactionDataBuilder.fromBytes(txBytes).snapshot().sender;\n\t\t\tif (actual == null) {\n\t\t\t\tthrow new Error('transaction has no sender');\n\t\t\t}\n\t\t\tif (normalizeSuiAddress(actual) !== normalizeSuiAddress(sender)) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`transaction sender ${actual} does not match impersonated sender ${sender}`,\n\t\t\t\t);\n\t\t\t}\n\t\t},\n\t\tcatch: (cause) =>\n\t\t\tsuiPluginError(\n\t\t\t\t'fork-impersonate',\n\t\t\t\t`sui fork mode: refused impersonation transaction: ${stringifyCause(cause)}`,\n\t\t\t\tcause,\n\t\t\t),\n\t});\n\nconst stringifyCause = (cause: unknown): string => {\n\tif (cause instanceof Error) return cause.message;\n\tif (typeof cause === 'string') return cause;\n\ttry {\n\t\treturn JSON.stringify(cause);\n\t} catch {\n\t\treturn String(cause);\n\t}\n};\n"],"mappings":"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"}
+{"version":3,"file":"fork-transaction.mjs","names":[],"sources":["../../../src/plugins/sui/fork-transaction.ts"],"sourcesContent":["import { Effect } from 'effect';\n\nimport {\n\tInputs,\n\tTransaction,\n\tTransactionDataBuilder,\n\ttype CallArg,\n} from '@mysten/sui/transactions';\nimport { normalizeSuiAddress } from '@mysten/sui/utils';\n\nimport { suiPluginError, type SuiPluginError } from './errors.ts';\nimport { formatUnknownError } from '../../substrate/runtime/format-unknown-error.ts';\n\n// 0.1 SUI. Deliberately well below the faucet's default per-account fund\n// (1 SUI) so a faucet-funded account keeps headroom to move value:\n// `setGasBudget` reserves the whole gas coin, so a budget equal to the\n// coin balance leaves nothing for `splitCoins(tx.gas, …)` / transfers\n// (InsufficientCoinBalance). 0.1 SUI still covers package publishes.\nexport const FORK_IMPERSONATION_GAS_BUDGET = 100_000_000n;\nexport const FORK_IMPERSONATION_GAS_PRICE = 1_000n;\n\n/** Canonical SUI gas coin type used to filter `listCoins` when picking\n *  a gas/funding coin. Kept local so the sui plugin needn't depend on\n *  the account plugin's `SUI_FULL_COIN_TYPE`. */\nconst SUI_GAS_COIN_TYPE = '0x2::sui::SUI';\n\n/** `listCoins` page size while scanning for a sufficient coin. */\nconst FORK_COIN_PAGE_SIZE = 50;\n\n/** An object ref usable as gas payment for an impersonation transaction. */\nexport interface ForkGasCoin {\n\treadonly objectId: string;\n\treadonly version: string;\n\treadonly digest: string;\n}\n\nexport interface ForkImpersonationGasClient {\n\treadonly getObject: (input: { readonly objectId: string }) => Promise<unknown>;\n\treadonly listCoins: (input: {\n\t\treadonly owner: string;\n\t\treadonly coinType?: string;\n\t\treadonly limit?: number;\n\t\treadonly cursor?: string | null;\n\t}) => Promise<{\n\t\treadonly objects: ReadonlyArray<{\n\t\t\treadonly objectId: string;\n\t\t\treadonly version: string | number | bigint;\n\t\t\treadonly digest: string;\n\t\t\treadonly balance?: string | number | bigint;\n\t\t}>;\n\t\treadonly hasNextPage?: boolean;\n\t\treadonly cursor?: string | null;\n\t}>;\n}\n\n/** Paginate `owner`'s SUI coins and return the first whose balance covers\n *  `minBalanceMist` (with that balance), or `undefined` if none across all\n *  pages. `listCoins` is paginated and NOT balance-ordered, so a sufficient\n *  coin can sit behind dust on a later page — we must page, never sample\n *  page 1. Shared by gas selection and the fork faucet. */\nconst firstSufficientSuiCoin = async (\n\tclient: ForkImpersonationGasClient,\n\towner: string,\n\tminBalanceMist: bigint,\n): Promise<{ readonly coin: ForkGasCoin; readonly balanceMist: bigint } | undefined> => {\n\tlet cursor: string | null = null;\n\tdo {\n\t\tconst page = await client.listCoins({\n\t\t\towner,\n\t\t\tcoinType: SUI_GAS_COIN_TYPE,\n\t\t\tcursor,\n\t\t\tlimit: FORK_COIN_PAGE_SIZE,\n\t\t});\n\t\tfor (const candidate of page.objects) {\n\t\t\tif (candidate.balance === undefined) continue;\n\t\t\tconst balanceMist = BigInt(candidate.balance);\n\t\t\tif (balanceMist >= minBalanceMist) {\n\t\t\t\treturn {\n\t\t\t\t\tcoin: {\n\t\t\t\t\t\tobjectId: candidate.objectId,\n\t\t\t\t\t\tversion: String(candidate.version),\n\t\t\t\t\t\tdigest: candidate.digest,\n\t\t\t\t\t},\n\t\t\t\t\tbalanceMist,\n\t\t\t\t};\n\t\t\t}\n\t\t}\n\t\tcursor = page.hasNextPage === true ? (page.cursor ?? null) : null;\n\t} while (cursor !== null);\n\treturn undefined;\n};\n\nexport const prepareForkImpersonationTransaction = (\n\ttx: Transaction,\n\tsender: string,\n\tgasPayment: ReadonlyArray<{\n\t\treadonly objectId: string;\n\t\treadonly version: string;\n\t\treadonly digest: string;\n\t}>,\n): void => {\n\ttx.setSender(sender);\n\n\ttx.setGasBudget(FORK_IMPERSONATION_GAS_BUDGET);\n\ttx.setGasPrice(FORK_IMPERSONATION_GAS_PRICE);\n\ttx.setGasOwner(sender);\n\ttx.setGasPayment([...gasPayment]);\n\n\tconst data = tx.getData();\n\tif (data.expiration == null) tx.setExpiration({ None: true });\n};\n\nexport const buildForkImpersonationTransactionBytes = (\n\ttx: Transaction,\n\tsender: string,\n\tclient: ForkImpersonationGasClient,\n\t/** Pre-selected gas coin. When omitted, the first coin owned by\n\t *  `sender` is used (legacy behaviour). The fork faucet passes the\n\t *  whale's gas coin via {@link selectSufficientForkCoin} so a\n\t *  `splitCoins(tx.gas, …)` funding transfer has enough balance. */\n\tgasCoin?: ForkGasCoin,\n): Effect.Effect<Uint8Array, SuiPluginError> =>\n\tEffect.tryPromise({\n\t\ttry: async () => {\n\t\t\tconst gasPayment =\n\t\t\t\tgasCoin !== undefined ? [gasCoin] : await selectForkImpersonationGasPayment(client, sender);\n\t\t\tprepareForkImpersonationTransaction(tx, sender, gasPayment);\n\t\t\tawait tx.prepareForSerialization({});\n\t\t\tconst data = tx.getData();\n\t\t\tdata.inputs = await Promise.all(data.inputs.map((input) => resolveForkInput(input, client)));\n\t\t\treturn TransactionDataBuilder.restore(data).build();\n\t\t},\n\t\tcatch: (cause) => {\n\t\t\t// Pass through pre-tagged SuiPluginError (thrown by inner\n\t\t\t// helpers with structured response fields) so we don't\n\t\t\t// double-wrap or stringify-leak the response payload.\n\t\t\tif (isSuiPluginError(cause)) return cause;\n\t\t\treturn suiPluginError(\n\t\t\t\t'fork-impersonate',\n\t\t\t\t`sui fork mode: failed to build fork impersonation transaction for ${sender}: ${formatUnknownError(cause)}`,\n\t\t\t\tcause,\n\t\t\t);\n\t\t},\n\t});\n\nconst isSuiPluginError = (value: unknown): value is SuiPluginError =>\n\ttypeof value === 'object' &&\n\tvalue !== null &&\n\t(value as { _tag?: unknown })._tag === 'SuiPluginError';\n\nconst resolveForkInput = async (\n\tinput: CallArg,\n\tclient: ForkImpersonationGasClient,\n): Promise<CallArg> => {\n\tif (input.UnresolvedObject === undefined) return input;\n\tconst unresolved = input.UnresolvedObject;\n\tif (unresolved.initialSharedVersion != null) {\n\t\treturn Inputs.SharedObjectRef({\n\t\t\tobjectId: unresolved.objectId,\n\t\t\tinitialSharedVersion: unresolved.initialSharedVersion,\n\t\t\tmutable: unresolved.mutable ?? true,\n\t\t});\n\t}\n\tif (unresolved.version != null && unresolved.digest != null) {\n\t\treturn Inputs.ObjectRef({\n\t\t\tobjectId: unresolved.objectId,\n\t\t\tversion: unresolved.version,\n\t\t\tdigest: unresolved.digest,\n\t\t});\n\t}\n\n\tconst object = objectFromGetObjectResponse(\n\t\tawait client.getObject({ objectId: unresolved.objectId }),\n\t);\n\tconst owner = object.owner;\n\tif (owner?.$kind === 'Shared' && owner.Shared !== undefined) {\n\t\treturn Inputs.SharedObjectRef({\n\t\t\tobjectId: object.objectId,\n\t\t\tinitialSharedVersion: owner.Shared.initialSharedVersion,\n\t\t\tmutable: unresolved.mutable ?? true,\n\t\t});\n\t}\n\treturn Inputs.ObjectRef({\n\t\tobjectId: object.objectId,\n\t\tversion: object.version,\n\t\tdigest: object.digest,\n\t});\n};\n\nconst objectFromGetObjectResponse = (\n\tresponse: unknown,\n): {\n\treadonly objectId: string;\n\treadonly version: string;\n\treadonly digest: string;\n\treadonly owner?: {\n\t\treadonly $kind?: string;\n\t\treadonly Shared?: { readonly initialSharedVersion: string };\n\t};\n} => {\n\tconst object = (response as { readonly object?: unknown }).object;\n\tif (typeof object !== 'object' || object === null) {\n\t\tthrow suiPluginError('fork-impersonate', 'sui fork mode: getObject returned no object', {\n\t\t\tresponseKeys: describeKeys(response),\n\t\t});\n\t}\n\tconst candidate = object as {\n\t\treadonly objectId?: unknown;\n\t\treadonly version?: unknown;\n\t\treadonly digest?: unknown;\n\t\treadonly owner?: {\n\t\t\treadonly $kind?: string;\n\t\t\treadonly Shared?: { readonly initialSharedVersion: string };\n\t\t};\n\t};\n\tif (\n\t\ttypeof candidate.objectId !== 'string' ||\n\t\ttypeof candidate.version !== 'string' ||\n\t\ttypeof candidate.digest !== 'string'\n\t) {\n\t\tthrow suiPluginError(\n\t\t\t'fork-impersonate',\n\t\t\t'sui fork mode: getObject returned incomplete object ref',\n\t\t\t{\n\t\t\t\tobjectKeys: describeKeys(object),\n\t\t\t\tmissing: {\n\t\t\t\t\tobjectId: typeof candidate.objectId !== 'string',\n\t\t\t\t\tversion: typeof candidate.version !== 'string',\n\t\t\t\t\tdigest: typeof candidate.digest !== 'string',\n\t\t\t\t},\n\t\t\t},\n\t\t);\n\t}\n\treturn {\n\t\tobjectId: candidate.objectId,\n\t\tversion: candidate.version,\n\t\tdigest: candidate.digest,\n\t\towner: candidate.owner,\n\t};\n};\n\nconst selectForkImpersonationGasPayment = async (\n\tclient: ForkImpersonationGasClient,\n\tsender: string,\n): Promise<\n\tReadonlyArray<{ readonly objectId: string; readonly version: string; readonly digest: string }>\n> => {\n\t// The gas coin must cover the impersonation gas budget. Pick the first SUI\n\t// coin that does (paginating past dust) — not blindly `objects[0]`, which on\n\t// an account holding change coins may be below the budget → InsufficientGas\n\t// even though a larger coin exists.\n\tconst found = await firstSufficientSuiCoin(client, sender, FORK_IMPERSONATION_GAS_BUDGET);\n\tif (found === undefined) {\n\t\tthrow suiPluginError(\n\t\t\t'fork-impersonate',\n\t\t\t`sui fork mode: no SUI coin >= ${FORK_IMPERSONATION_GAS_BUDGET} MIST (gas budget) found for ${sender}.`,\n\t\t\t{ sender, requiredMist: FORK_IMPERSONATION_GAS_BUDGET.toString() },\n\t\t);\n\t}\n\treturn [found.coin];\n};\n\n/** Find a SUI coin owned by `owner` that covers `minBalanceMist`, for use as\n *  BOTH gas payment and the `splitCoins(tx.gas, …)` funding source in a fork\n *  faucet transfer. Paginates the coin set (a sufficient coin can sit behind\n *  dust on a later page) and returns the first that qualifies. Fails with an\n *  actionable `SuiPluginError` when none exists — reused at boot to validate a\n *  configured whale before any funding runs. */\nexport const selectSufficientForkCoin = (\n\tclient: ForkImpersonationGasClient,\n\towner: string,\n\tminBalanceMist: bigint,\n): Effect.Effect<{ readonly coin: ForkGasCoin; readonly balanceMist: bigint }, SuiPluginError> =>\n\tEffect.tryPromise({\n\t\ttry: async () => {\n\t\t\tconst found = await firstSufficientSuiCoin(client, owner, minBalanceMist);\n\t\t\tif (found === undefined) {\n\t\t\t\tthrow suiPluginError(\n\t\t\t\t\t'fork-impersonate',\n\t\t\t\t\t`sui fork mode: no SUI coin >= ${minBalanceMist} MIST (request + gas budget) found for ` +\n\t\t\t\t\t\t`${owner}. Use a fork faucet whale with a larger single coin, or fund a smaller amount.`,\n\t\t\t\t\t{ owner, requiredMist: minBalanceMist.toString() },\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn found;\n\t\t},\n\t\tcatch: (cause) => {\n\t\t\tif (isSuiPluginError(cause)) return cause;\n\t\t\treturn suiPluginError(\n\t\t\t\t'fork-impersonate',\n\t\t\t\t`sui fork mode: failed to select a SUI coin for ${owner}: ${formatUnknownError(cause)}`,\n\t\t\t\tcause,\n\t\t\t);\n\t\t},\n\t});\n\nexport const verifyForkImpersonationSender = (\n\tsender: string,\n\ttxBytes: Uint8Array,\n): Effect.Effect<void, SuiPluginError> =>\n\tEffect.try({\n\t\ttry: () => {\n\t\t\tconst actual = TransactionDataBuilder.fromBytes(txBytes).snapshot().sender;\n\t\t\tif (actual == null) {\n\t\t\t\tthrow suiPluginError(\n\t\t\t\t\t'fork-impersonate',\n\t\t\t\t\t'sui fork mode: refused impersonation transaction — transaction has no sender',\n\t\t\t\t\t{ expectedSender: sender },\n\t\t\t\t);\n\t\t\t}\n\t\t\tif (normalizeSuiAddress(actual) !== normalizeSuiAddress(sender)) {\n\t\t\t\tthrow suiPluginError(\n\t\t\t\t\t'fork-impersonate',\n\t\t\t\t\t'sui fork mode: refused impersonation transaction — sender mismatch',\n\t\t\t\t\t{ expectedSender: sender, actualSender: actual },\n\t\t\t\t);\n\t\t\t}\n\t\t},\n\t\tcatch: (cause) => {\n\t\t\tif (isSuiPluginError(cause)) return cause;\n\t\t\treturn suiPluginError(\n\t\t\t\t'fork-impersonate',\n\t\t\t\t`sui fork mode: refused impersonation transaction: ${formatUnknownError(cause)}`,\n\t\t\t\tcause,\n\t\t\t);\n\t\t},\n\t});\n\nconst describeKeys = (value: unknown): ReadonlyArray<string> => {\n\tif (typeof value !== 'object' || value === null) return [];\n\treturn Object.keys(value);\n};\n"],"mappings":"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"}

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

@@ -1,5 +1,5 @@
-import { ChainId } from "../../substrate/brand.mjs";
 import { CodegenableDecl } from "../../contracts/codegenable.mjs";
+import { ChainId } from "../../substrate/brand.mjs";
 import { RoutableDecl } from "../../contracts/routable.mjs";
 import { SnapshotableDecl } from "../../contracts/snapshotable.mjs";
 import { StrategyContributorDecl } from "../../contracts/strategy-contributor.mjs";
@@ -8,27 +8,19 @@ import { ImageRef } from "../../contracts/container-runtime.mjs";
 import { ModeNamespace } from "../../api/mode-narrowed-factory.mjs";
 import { ChainProbe, ChainProbeError, ChainProbeMode } from "../../contracts/chain-probe.mjs";
 import { SuiProbeKey, SuiSdkShim } from "./chain-probe.mjs";
-import { LeaseBroker } from "../../substrate/runtime/lease-broker/service.mjs";
-import { FaucetStrategy } from "../faucet/strategies/sui-local.mjs";
-import { SeedObjectsAccumulator } from "./seed-objects.mjs";
-import { ForkUnsupportedError, SeedManifestMismatchError, SuiCliError, SuiConfigError, SuiError, SuiFundsReadyError, SuiPluginError } from "./errors.mjs";
+import { FaucetStrategy } from "../faucet/dispatcher.mjs";
+import { ForkUnsupportedError, SuiCliError, SuiConfigError, SuiError, SuiPluginError } from "./errors.mjs";
 import { ForkAdminSurface, SuiClient, WaitForTransactionsReady } from "./mode/shared.mjs";
 import { SuiForkOptions, SuiLiveOptions, SuiLocalOptions, SuiLocalRpcOptions, SuiOptions, SuiPluginMode } from "./mode/spec.mjs";
-import { FundsReadyError, FundsReadyStrategy } from "../../contracts/network-resolver.mjs";
 import { ResolvedSuiNetwork } from "./network-resolver.mjs";
 import { SuiNetworkBindings } from "./codegen.mjs";
-import { Effect } from "effect";
-
 //#region src/plugins/sui/index.d.ts
-declare const fundingFaucetLeaseBrokerSymbol: unique symbol;
-/** The Sui plugin's resource identity. The id is `'sui'` (singular). */
 /** Local Sui shorthand. Network/env selection belongs to the CLI or
  *  `defineDevstackWith(...)`; plain `sui()` always means an in-stack
  *  local validator. */
 declare const sui: (opts?: SuiOptions) => Plugin<"sui", {
-  mode: "local" | "local-rpc" | "live" | "fork";
-  seedObjects: SeedObjectsAccumulator;
-  [fundingFaucetLeaseBrokerSymbol]: LeaseBroker;
+  mode: "local" | "live" | "fork" | "local-rpc";
+  fundingFaucetStrategy: FaucetStrategy | null;
   sdk: SuiSdkShim;
   rpcUrl: string;
   faucetUrl: string | null;
@@ -49,9 +41,7 @@ declare const sui: (opts?: SuiOptions) => Plugin<"sui", {
   capabilityKey: `faucet:request:${ChainId}`;
   strategy: FaucetStrategy;
   autoMounted: true;
-} | StrategyContributorDecl<"gate:funds-ready", {
-  readonly waitFundsReady: Effect.Effect<void, SuiPluginError>;
-}> | StrategyContributorDecl<"sui:seed-objects", SeedObjectsAccumulator>)[]]>;
+})[]]>;
 /** Mode-narrowed factory namespace.
  *
  *  Usage:
@@ -65,9 +55,8 @@ declare const sui: (opts?: SuiOptions) => Plugin<"sui", {
 declare const suiFor: ModeNamespace<{
   local: {
     local: (opts?: Omit<SuiLocalOptions, "mode">) => Plugin<"sui", {
-      mode: "local" | "local-rpc" | "live" | "fork";
-      seedObjects: SeedObjectsAccumulator;
-      [fundingFaucetLeaseBrokerSymbol]: LeaseBroker;
+      mode: "local" | "live" | "fork" | "local-rpc";
+      fundingFaucetStrategy: FaucetStrategy | null;
       sdk: SuiSdkShim;
       rpcUrl: string;
       faucetUrl: string | null;
@@ -88,13 +77,10 @@ declare const suiFor: ModeNamespace<{
       capabilityKey: `faucet:request:${ChainId}`;
       strategy: FaucetStrategy;
       autoMounted: true;
-    } | StrategyContributorDecl<"gate:funds-ready", {
-      readonly waitFundsReady: Effect.Effect<void, SuiPluginError>;
-    }> | StrategyContributorDecl<"sui:seed-objects", SeedObjectsAccumulator>)[]]>;
+    })[]]>;
     localRpc: (opts: Omit<SuiLocalRpcOptions, "mode">) => Plugin<"sui", {
-      mode: "local" | "local-rpc" | "live" | "fork";
-      seedObjects: SeedObjectsAccumulator;
-      [fundingFaucetLeaseBrokerSymbol]: LeaseBroker;
+      mode: "local" | "live" | "fork" | "local-rpc";
+      fundingFaucetStrategy: FaucetStrategy | null;
       sdk: SuiSdkShim;
       rpcUrl: string;
       faucetUrl: string | null;
@@ -115,15 +101,12 @@ declare const suiFor: ModeNamespace<{
       capabilityKey: `faucet:request:${ChainId}`;
       strategy: FaucetStrategy;
       autoMounted: true;
-    } | StrategyContributorDecl<"gate:funds-ready", {
-      readonly waitFundsReady: Effect.Effect<void, SuiPluginError>;
-    }> | StrategyContributorDecl<"sui:seed-objects", SeedObjectsAccumulator>)[]]>;
+    })[]]>;
   };
   live: {
     testnet: (opts?: Omit<SuiLiveOptions, "mode" | "network">) => Plugin<"sui", {
-      mode: "local" | "local-rpc" | "live" | "fork";
-      seedObjects: SeedObjectsAccumulator;
-      [fundingFaucetLeaseBrokerSymbol]: LeaseBroker;
+      mode: "local" | "live" | "fork" | "local-rpc";
+      fundingFaucetStrategy: FaucetStrategy | null;
       sdk: SuiSdkShim;
       rpcUrl: string;
       faucetUrl: string | null;
@@ -144,13 +127,10 @@ declare const suiFor: ModeNamespace<{
       capabilityKey: `faucet:request:${ChainId}`;
       strategy: FaucetStrategy;
       autoMounted: true;
-    } | StrategyContributorDecl<"gate:funds-ready", {
-      readonly waitFundsReady: Effect.Effect<void, SuiPluginError>;
-    }> | StrategyContributorDecl<"sui:seed-objects", SeedObjectsAccumulator>)[]]>;
+    })[]]>;
     mainnet: (opts?: Omit<SuiLiveOptions, "mode" | "network">) => Plugin<"sui", {
-      mode: "local" | "local-rpc" | "live" | "fork";
-      seedObjects: SeedObjectsAccumulator;
-      [fundingFaucetLeaseBrokerSymbol]: LeaseBroker;
+      mode: "local" | "live" | "fork" | "local-rpc";
+      fundingFaucetStrategy: FaucetStrategy | null;
       sdk: SuiSdkShim;
       rpcUrl: string;
       faucetUrl: string | null;
@@ -171,13 +151,10 @@ declare const suiFor: ModeNamespace<{
       capabilityKey: `faucet:request:${ChainId}`;
       strategy: FaucetStrategy;
       autoMounted: true;
-    } | StrategyContributorDecl<"gate:funds-ready", {
-      readonly waitFundsReady: Effect.Effect<void, SuiPluginError>;
-    }> | StrategyContributorDecl<"sui:seed-objects", SeedObjectsAccumulator>)[]]>;
+    })[]]>;
     devnet: (opts?: Omit<SuiLiveOptions, "mode" | "network">) => Plugin<"sui", {
-      mode: "local" | "local-rpc" | "live" | "fork";
-      seedObjects: SeedObjectsAccumulator;
-      [fundingFaucetLeaseBrokerSymbol]: LeaseBroker;
+      mode: "local" | "live" | "fork" | "local-rpc";
+      fundingFaucetStrategy: FaucetStrategy | null;
       sdk: SuiSdkShim;
       rpcUrl: string;
       faucetUrl: string | null;
@@ -198,13 +175,10 @@ declare const suiFor: ModeNamespace<{
       capabilityKey: `faucet:request:${ChainId}`;
       strategy: FaucetStrategy;
       autoMounted: true;
-    } | StrategyContributorDecl<"gate:funds-ready", {
-      readonly waitFundsReady: Effect.Effect<void, SuiPluginError>;
-    }> | StrategyContributorDecl<"sui:seed-objects", SeedObjectsAccumulator>)[]]>;
+    })[]]>;
     custom: (opts: Omit<SuiLiveOptions, "mode" | "network">) => Plugin<"sui", {
-      mode: "local" | "local-rpc" | "live" | "fork";
-      seedObjects: SeedObjectsAccumulator;
-      [fundingFaucetLeaseBrokerSymbol]: LeaseBroker;
+      mode: "local" | "live" | "fork" | "local-rpc";
+      fundingFaucetStrategy: FaucetStrategy | null;
       sdk: SuiSdkShim;
       rpcUrl: string;
       faucetUrl: string | null;
@@ -225,15 +199,12 @@ declare const suiFor: ModeNamespace<{
       capabilityKey: `faucet:request:${ChainId}`;
       strategy: FaucetStrategy;
       autoMounted: true;
-    } | StrategyContributorDecl<"gate:funds-ready", {
-      readonly waitFundsReady: Effect.Effect<void, SuiPluginError>;
-    }> | StrategyContributorDecl<"sui:seed-objects", SeedObjectsAccumulator>)[]]>;
+    })[]]>;
   };
   fork: {
     mainnet: (opts?: Omit<SuiForkOptions, "mode" | "upstream">) => Plugin<"sui", {
-      mode: "local" | "local-rpc" | "live" | "fork";
-      seedObjects: SeedObjectsAccumulator;
-      [fundingFaucetLeaseBrokerSymbol]: LeaseBroker;
+      mode: "local" | "live" | "fork" | "local-rpc";
+      fundingFaucetStrategy: FaucetStrategy | null;
       sdk: SuiSdkShim;
       rpcUrl: string;
       faucetUrl: string | null;
@@ -254,13 +225,10 @@ declare const suiFor: ModeNamespace<{
       capabilityKey: `faucet:request:${ChainId}`;
       strategy: FaucetStrategy;
       autoMounted: true;
-    } | StrategyContributorDecl<"gate:funds-ready", {
-      readonly waitFundsReady: Effect.Effect<void, SuiPluginError>;
-    }> | StrategyContributorDecl<"sui:seed-objects", SeedObjectsAccumulator>)[]]>;
+    })[]]>;
     testnet: (opts?: Omit<SuiForkOptions, "mode" | "upstream">) => Plugin<"sui", {
-      mode: "local" | "local-rpc" | "live" | "fork";
-      seedObjects: SeedObjectsAccumulator;
-      [fundingFaucetLeaseBrokerSymbol]: LeaseBroker;
+      mode: "local" | "live" | "fork" | "local-rpc";
+      fundingFaucetStrategy: FaucetStrategy | null;
       sdk: SuiSdkShim;
       rpcUrl: string;
       faucetUrl: string | null;
@@ -281,13 +249,10 @@ declare const suiFor: ModeNamespace<{
       capabilityKey: `faucet:request:${ChainId}`;
       strategy: FaucetStrategy;
       autoMounted: true;
-    } | StrategyContributorDecl<"gate:funds-ready", {
-      readonly waitFundsReady: Effect.Effect<void, SuiPluginError>;
-    }> | StrategyContributorDecl<"sui:seed-objects", SeedObjectsAccumulator>)[]]>;
+    })[]]>;
     devnet: (opts?: Omit<SuiForkOptions, "mode" | "upstream">) => Plugin<"sui", {
-      mode: "local" | "local-rpc" | "live" | "fork";
-      seedObjects: SeedObjectsAccumulator;
-      [fundingFaucetLeaseBrokerSymbol]: LeaseBroker;
+      mode: "local" | "live" | "fork" | "local-rpc";
+      fundingFaucetStrategy: FaucetStrategy | null;
       sdk: SuiSdkShim;
       rpcUrl: string;
       faucetUrl: string | null;
@@ -308,9 +273,7 @@ declare const suiFor: ModeNamespace<{
       capabilityKey: `faucet:request:${ChainId}`;
       strategy: FaucetStrategy;
       autoMounted: true;
-    } | StrategyContributorDecl<"gate:funds-ready", {
-      readonly waitFundsReady: Effect.Effect<void, SuiPluginError>;
-    }> | StrategyContributorDecl<"sui:seed-objects", SeedObjectsAccumulator>)[]]>;
+    })[]]>;
   };
 }>;
 //#endregion

package/dist/plugins/sui/index.mjs

@@ -1,31 +1,76 @@
 import { definePlugin, resource } from "../../substrate/plugin.mjs";
-import { pluginErrorContributions } from "../../api/plugin-errors.mjs";
+import "../../api/define-plugin.mjs";
 import { IdentityContext, StackPathsService } from "../../substrate/runtime/paths.mjs";
-import { PortBrokerService } from "../../substrate/runtime/port-broker/service.mjs";
-import { defineModeNamespace } from "../../api/mode-narrowed-factory.mjs";
-import { FUNDS_READY_GATE_KEY } from "../../contracts/network-resolver.mjs";
-import { chainProbeCapabilityKey } from "../../contracts/chain-probe.mjs";
 import { ContainerRuntimeService } from "../../runtime/docker/service.mjs";
 import { LeaseBrokerService } from "../../substrate/runtime/lease-broker/service.mjs";
+import "../../substrate/runtime/lease-broker/index.mjs";
+import { PortBrokerService } from "../../substrate/runtime/port-broker/service.mjs";
+import "../../substrate/runtime/port-broker/index.mjs";
+import { chainProbeCapabilityKey } from "../../contracts/chain-probe.mjs";
+import { makeSuiForkRoutables, makeSuiLocalRoutables } from "./routable.mjs";
+import { pluginErrorContributions } from "../../api/plugin-errors.mjs";
+import { defineModeNamespace } from "../../api/mode-narrowed-factory.mjs";
 import { makeCodegenable } from "./codegen.mjs";
 import { makeSnapshotable } from "./snapshot.mjs";
-import { SEED_OBJECTS_CAPABILITY_KEY, makeSeedObjectsAccumulator } from "./seed-objects.mjs";
 import { SUI_ERROR_TAGS } from "./errors.mjs";
-import { makeSuiForkRoutables, makeSuiLocalRoutables } from "./routable.mjs";
+import "./spans.mjs";
 import "./fork-orchestration.mjs";
+import { selectSufficientForkCoin } from "./fork-transaction.mjs";
+import { FORK_FAUCET_WHALE_MIN_COIN_MIST, resolveForkWhale } from "./mode/fork.mjs";
 import { bootSuiService } from "./service.mjs";
 import { faucetCapabilityKey } from "../faucet/dispatcher.mjs";
-import { suiLocalStrategy } from "../faucet/strategies/sui-local.mjs";
+import "../faucet/index.mjs";
+import { suiLocalStrategy } from "./local-faucet-strategy.mjs";
+import { suiForkFaucetStrategy } from "./fork-faucet-strategy.mjs";
+import "./chain-build-container.mjs";
 import { Effect } from "effect";
 //#region src/plugins/sui/index.ts
-const fundingFaucetLeaseBrokerSymbol = Symbol("@mysten-incubation/devstack/sui/fundingFaucetLeaseBroker");
 /** The Sui plugin's resource identity. The id is `'sui'` (singular). */
 const suiResource = resource("sui");
 const suiErrorContributions = pluginErrorContributions(SUI_ERROR_TAGS);
+/** Build the funds-ready faucet strategy for the resolved network, or
+*  `null` when the network has none. Local/live wrap the HTTP faucet;
+*  fork mode impersonates a whale (resolved + validated here). */
+const resolveFundingFaucetStrategy = (opts, client, broker) => {
+	if (opts.mode === "fork") return resolveForkFaucetStrategy(opts, client, broker);
+	if (client.fundingFaucetUrl === null) return Effect.succeed(null);
+	return Effect.succeed(suiLocalStrategy({
+		faucetUrl: client.fundingFaucetUrl,
+		serialization: {
+			broker,
+			key: `sui-faucet:${client.chain}`,
+			owner: `sui-faucet:${client.chain}`
+		}
+	}));
+};
+/** Fork-mode faucet: resolve the whale, validate it holds a large enough
+*  SUI coin, then build the impersonation strategy. A whale the user set
+*  explicitly that fails validation hard-fails the boot; a per-upstream
+*  default whale only warns and disables the faucet so the fork still
+*  comes up (account funding then surfaces the "no faucet strategy"
+*  error only if something actually needs SUI). */
+const resolveForkFaucetStrategy = (opts, client, broker) => Effect.gen(function* () {
+	const resolved = resolveForkWhale(opts);
+	const fork = client.fork;
+	if (resolved === null || fork === null) return null;
+	const strategy = suiForkFaucetStrategy({
+		whale: resolved.whale,
+		fork,
+		sdk: client.sdk,
+		perRequestCapMist: resolved.perRequestCapMist,
+		serialization: {
+			broker,
+			key: `sui-fork-faucet:${client.chain}`,
+			owner: `sui-fork-faucet:${client.chain}`
+		}
+	});
+	return yield* selectSufficientForkCoin(client.sdk.core, resolved.whale, FORK_FAUCET_WHALE_MIN_COIN_MIST).pipe(Effect.as(strategy), Effect.catchTag("SuiPluginError", (cause) => resolved.explicit ? Effect.fail(cause) : Effect.logWarning(`sui fork mode: default faucet whale ${resolved.whale} is unusable (${cause.message}); disabling the fork faucet. Set faucet.whale to override.`).pipe(Effect.as(null))));
+});
 const buildPlugin = (opts) => {
 	return definePlugin({
 		id: suiResource.id,
 		role: "service",
+		section: "service",
 		start: () => Effect.gen(function* () {
 			const runtime = yield* ContainerRuntimeService;
 			const identity = yield* IdentityContext;
@@ -33,12 +78,11 @@ const buildPlugin = (opts) => {
 			const portBroker = yield* PortBrokerService;
 			const fundingFaucetLeaseBroker = yield* LeaseBrokerService;
 			const { client } = yield* bootSuiService(runtime, identity, portBroker, paths, opts);
-			const seedObjects = yield* makeSeedObjectsAccumulator();
+			const fundingFaucetStrategy = yield* resolveFundingFaucetStrategy(opts, client, fundingFaucetLeaseBroker);
 			return {
 				...client,
 				mode: opts.mode,
-				seedObjects,
-				[fundingFaucetLeaseBrokerSymbol]: fundingFaucetLeaseBroker
+				fundingFaucetStrategy
 			};
 		}),
 		capabilities: ({ value, runtime }) => makePluginCapabilities(opts, value, runtime),
@@ -70,29 +114,10 @@ const makePluginCapabilities = (opts, resolved, acquireCtx) => {
 		strategy: resolved.chainProbe,
 		autoMounted: true
 	};
-	const fundsReadyContribution = {
-		kind: "strategy-contributor",
-		capabilityKey: FUNDS_READY_GATE_KEY,
-		strategy: { waitFundsReady: resolved.waitForTransactionsReady.wait },
-		autoMounted: true
-	};
-	const seedObjectsContribution = {
-		kind: "strategy-contributor",
-		capabilityKey: SEED_OBJECTS_CAPABILITY_KEY,
-		strategy: resolved.seedObjects,
-		autoMounted: true
-	};
-	const faucetContribution = resolved.fundingFaucetUrl === null ? [] : [{
+	const faucetContribution = resolvedRuntime.fundingFaucetStrategy === null ? [] : [{
 		kind: "strategy-contributor",
 		capabilityKey: faucetCapabilityKey(realChain),
-		strategy: suiLocalStrategy({
-			faucetUrl: resolved.fundingFaucetUrl,
-			serialization: {
-				broker: resolvedRuntime[fundingFaucetLeaseBrokerSymbol],
-				key: `sui-faucet:${realChain}`,
-				owner: `sui-faucet:${realChain}`
-			}
-		}),
+		strategy: resolvedRuntime.fundingFaucetStrategy,
 		autoMounted: true
 	}];
 	const localRoutables = opts.mode === "local" ? makeSuiLocalRoutables({
@@ -105,8 +130,6 @@ const makePluginCapabilities = (opts, resolved, acquireCtx) => {
 		codegen,
 		chainProbeContribution,
 		...faucetContribution,
-		fundsReadyContribution,
-		seedObjectsContribution,
 		...localRoutables,
 		...forkRoutables
 	];