@mysten-incubation/devstack 0.0.0

package/dist/plugins/sui/mode/shared-boot.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-boot.mjs","names":["brandChainId"],"sources":["../../../../src/plugins/sui/mode/shared-boot.ts"],"sourcesContent":["// Sui plugin — boot helpers shared across local / external / live modes.\n//\n// What lives here (and why):\n//\n//   - `fetchChainId(client, opts?)` — bounded chain-id probe. The\n//     only readiness sentinel for external + live; local treats it\n//     as the chain-id capture step after the multi-probe gate has\n//     succeeded.\n//   - `buildWaitForTransactionsReady(faucetUrl, opts?)` — memoised\n//     funds-ready gate for faucet-bearing networks. `Effect.cached`\n//     with a manual-invalidation surface (the distilled-doc\n//     opportunity called out in `mode/shared.ts`).\n//   - `noopWaitForTransactionsReady` — trivially-succeeding gate for\n//     faucet-less networks (live mainnet, fork).\n//   - `assembleSuiClient(...)` — collapses the boilerplate that\n//     local/local-rpc/live all repeat (sdk shim + chainProbe + the\n//     `fork: null` discriminator).\n//\n// Why not jam this into `mode/local.ts`: external + live can't\n// import from `local.ts` without dragging the container-runtime\n// import path along; the helpers below are wire-only and have NO\n// substrate-context dependencies.\n\nimport { Duration, Effect, Ref, type Scope } from 'effect';\n\nimport type { SuiGrpcClient } from '@mysten/sui/grpc';\n\nimport type { ChainProbe } from '../../../contracts/chain-probe.ts';\nimport { chainId as brandChainId } from '../../../substrate/brand.ts';\nimport { waitForHttpEndpoint } from '../../../substrate/runtime/http-probe.ts';\nimport { makeSuiChainProbe, type SuiSdkShim, type SuiProbeKey } from '../chain-probe.ts';\nimport { suiPluginError, type SuiPluginError } from '../errors.ts';\nimport type { ResolvedSuiNetwork } from '../network-resolver.ts';\nimport { toDockerHostGatewayUrl, type SuiClient, type WaitForTransactionsReady } from './shared.ts';\n\n// ---------------------------------------------------------------------------\n// Chain-id fetch — bounded, typed-error\n// ---------------------------------------------------------------------------\n\n/** Default chain-id fetch timeout. The wire latency is the dominant\n *  cost on real RPCs; 30 s is the documented ceiling. */\nexport const DEFAULT_CHAIN_ID_TIMEOUT = Duration.seconds(30);\n\n/** Fetch the chain identifier off a constructed grpc client. The\n *  result is the bare string that downstream cache layers fold into\n *  their state-store keys. */\nexport const fetchChainId = (\n\tsdkClient: SuiGrpcClient,\n\topts?: { readonly timeout?: Duration.Duration; readonly span?: string },\n): Effect.Effect<string, SuiPluginError> => {\n\tconst timeout = opts?.timeout ?? DEFAULT_CHAIN_ID_TIMEOUT;\n\tconst timeoutMs = Duration.toMillis(timeout);\n\treturn Effect.tryPromise({\n\t\ttry: (signal) =>\n\t\t\tsdkClient.ledgerService\n\t\t\t\t.getServiceInfo({}, { abort: signal, timeout: timeoutMs })\n\t\t\t\t.response.then((response) => {\n\t\t\t\t\tif (!response.chainId) {\n\t\t\t\t\t\tthrow new Error('Chain identifier not found in service info');\n\t\t\t\t\t}\n\t\t\t\t\treturn response.chainId;\n\t\t\t\t}),\n\t\tcatch: (cause): SuiPluginError =>\n\t\t\tsuiPluginError(\n\t\t\t\t'chain-id-fetch',\n\t\t\t\t`sui chain-id fetch failed: ${stringifyCause(cause)}`,\n\t\t\t\tcause,\n\t\t\t),\n\t}).pipe(\n\t\tEffect.timeoutOrElse({\n\t\t\tduration: timeout,\n\t\t\torElse: (): Effect.Effect<string, SuiPluginError> =>\n\t\t\t\tEffect.fail(\n\t\t\t\t\tsuiPluginError(\n\t\t\t\t\t\t'chain-id-fetch',\n\t\t\t\t\t\t`sui chain-id fetch did not respond within ${timeoutMs}ms`,\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t}),\n\t\tEffect.tap((id: string) => Effect.annotateCurrentSpan({ 'sui.chain': id })),\n\t\tEffect.withSpan(opts?.span ?? 'devstack.plugin.sui.fetchChainId'),\n\t);\n};\n\n// ---------------------------------------------------------------------------\n// waitForTransactionsReady — memoised, with manual invalidation\n// ---------------------------------------------------------------------------\n\n/** Per-attempt and total budget for the `waitForTransactionsReady`\n *  retry loop. The 2 s spacing matches the upstream sui-faucet's\n *  internal cadence; the 90 s ceiling matches the v3 service's\n *  documented wall-clock. */\nconst FUNDS_READY_RETRY_SPACING = Duration.seconds(2);\nconst FUNDS_READY_TIMEOUT = Duration.seconds(90);\n\n/** Per-fetch deadline for the faucet probe POST. Bounded short so\n *  the outer retry loop hammers quickly. */\nconst PROBE_FETCH_TIMEOUT_MS = 3000;\n\n/** Probe recipient for the faucet funds-ready check. A literal\n *  zero-balance address so the real call doesn't pollute caller wallets;\n *  any well-formed address works. */\nconst FAUCET_PROBE_RECIPIENT = '0x0000000000000000000000000000000000000000000000000000000000000001';\n\n/**\n * Build the funds-transferable gate against a real HTTP faucet.\n * Memoised — first successful resolution sticks for the scope; the\n * manual `invalidate` surface clears the memo so long-running\n * supervisors can re-probe without a full restart.\n */\nexport const buildWaitForTransactionsReady = (\n\tfaucetUrl: string,\n\topts?: {\n\t\treadonly retrySpacing?: Duration.Duration;\n\t\treadonly timeout?: Duration.Duration;\n\t},\n): Effect.Effect<WaitForTransactionsReady, never, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\tconst retrySpacing = opts?.retrySpacing ?? FUNDS_READY_RETRY_SPACING;\n\t\tconst timeout = opts?.timeout ?? FUNDS_READY_TIMEOUT;\n\t\tconst ref = yield* Ref.make<Effect.Effect<void, SuiPluginError> | null>(null);\n\n\t\tconst makeProbe = (): Effect.Effect<void, SuiPluginError> =>\n\t\t\twaitForHttpEndpoint({\n\t\t\t\tendpoint: `${faucetUrl}/v2/gas`,\n\t\t\t\ttimeoutMs: Duration.toMillis(timeout),\n\t\t\t\tintervalMs: Duration.toMillis(retrySpacing),\n\t\t\t\trequestTimeoutMs: PROBE_FETCH_TIMEOUT_MS,\n\t\t\t\trequestInit: {\n\t\t\t\t\tmethod: 'POST',\n\t\t\t\t\theaders: { 'content-type': 'application/json' },\n\t\t\t\t\tbody: JSON.stringify({\n\t\t\t\t\t\tFixedAmountRequest: { recipient: FAUCET_PROBE_RECIPIENT },\n\t\t\t\t\t}),\n\t\t\t\t},\n\t\t\t\tvalidate: async (response) => {\n\t\t\t\t\tif (!response.ok) throw new Error(`faucet HTTP ${response.status}`);\n\t\t\t\t\tconst body = (await response.json()) as { status?: unknown };\n\t\t\t\t\tconst status = body.status;\n\t\t\t\t\tif (typeof status === 'object' && status !== null && 'Failure' in status) {\n\t\t\t\t\t\tconst failure = (status as { Failure: unknown }).Failure;\n\t\t\t\t\t\tthrow new Error(`faucet body: Failure ${JSON.stringify(failure)}`);\n\t\t\t\t\t}\n\t\t\t\t\treturn true;\n\t\t\t\t},\n\t\t\t}).pipe(\n\t\t\t\tEffect.mapError(\n\t\t\t\t\t(cause): SuiPluginError =>\n\t\t\t\t\t\tsuiPluginError(\n\t\t\t\t\t\t\t'wait-funds-ready',\n\t\t\t\t\t\t\t`sui faucet at ${faucetUrl} did not become funds-transferable within ` +\n\t\t\t\t\t\t\t\t`${Duration.toMillis(timeout)}ms (still returning body-level Failure or 5xx): ` +\n\t\t\t\t\t\t\t\tstringifyCause(cause),\n\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t);\n\n\t\tconst getOrInit: Effect.Effect<Effect.Effect<void, SuiPluginError>> = Effect.gen(function* () {\n\t\t\tconst existing = yield* Ref.get(ref);\n\t\t\tif (existing !== null) return existing;\n\t\t\tconst cached = yield* Effect.cached(makeProbe());\n\t\t\tyield* Ref.set(ref, cached);\n\t\t\treturn cached;\n\t\t});\n\n\t\treturn {\n\t\t\twait: getOrInit.pipe(Effect.flatMap((eff) => eff)),\n\t\t\tinvalidate: Ref.set(ref, null),\n\t\t};\n\t});\n\n/** Trivially-succeeding gate. Used by faucet-less networks (live\n *  mainnet, fork — fork funds via impersonation, not HTTP). */\nexport const noopWaitForTransactionsReady: WaitForTransactionsReady = {\n\twait: Effect.void,\n\tinvalidate: Effect.void,\n};\n\nconst SUI_RPC_READ_TIMEOUT_MS = 10_000;\n\nconst postJsonRpc = async <A>(\n\trpcUrl: string,\n\tmethod: string,\n\tparams: ReadonlyArray<unknown>,\n): Promise<A> => {\n\tconst controller = new AbortController();\n\tconst timeout = setTimeout(() => controller.abort(), SUI_RPC_READ_TIMEOUT_MS);\n\ttimeout.unref?.();\n\ttry {\n\t\tconst response = await fetch(rpcUrl, {\n\t\t\tmethod: 'POST',\n\t\t\theaders: { 'content-type': 'application/json' },\n\t\t\tbody: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),\n\t\t\tsignal: controller.signal,\n\t\t});\n\t\tif (!response.ok) throw new Error(`Sui RPC HTTP ${response.status}`);\n\t\tconst payload = (await response.json()) as {\n\t\t\treadonly result?: A;\n\t\t\treadonly error?: { readonly message?: string };\n\t\t};\n\t\tif (payload.error !== undefined) {\n\t\t\tthrow new Error(payload.error.message ?? JSON.stringify(payload.error));\n\t\t}\n\t\tif (payload.result === undefined) throw new Error(`Sui RPC ${method} returned no result`);\n\t\treturn payload.result;\n\t} finally {\n\t\tclearTimeout(timeout);\n\t}\n};\n\nconst normalizeJsonOwner = (owner: unknown): unknown => {\n\tif (owner === 'Immutable') return { $kind: 'Immutable', Immutable: true };\n\tif (typeof owner !== 'object' || owner === null) return { $kind: 'Unknown', Unknown: owner };\n\tconst record = owner as {\n\t\treadonly AddressOwner?: unknown;\n\t\treadonly ObjectOwner?: unknown;\n\t\treadonly Shared?: {\n\t\t\treadonly initial_shared_version?: unknown;\n\t\t\treadonly initialSharedVersion?: unknown;\n\t\t};\n\t\treadonly ConsensusAddressOwner?: unknown;\n\t};\n\tif (typeof record.AddressOwner === 'string') {\n\t\treturn { $kind: 'AddressOwner', AddressOwner: record.AddressOwner };\n\t}\n\tif (record.ObjectOwner !== undefined) {\n\t\treturn { $kind: 'Parent', Parent: record.ObjectOwner };\n\t}\n\tif (record.Shared !== undefined) {\n\t\tconst initialSharedVersion =\n\t\t\trecord.Shared.initialSharedVersion ?? record.Shared.initial_shared_version;\n\t\treturn {\n\t\t\t$kind: 'Shared',\n\t\t\tShared: { initialSharedVersion: String(initialSharedVersion) },\n\t\t};\n\t}\n\tif (record.ConsensusAddressOwner !== undefined) {\n\t\treturn { $kind: 'ConsensusAddressOwner', ConsensusAddressOwner: record.ConsensusAddressOwner };\n\t}\n\treturn { $kind: 'Unknown', Unknown: owner };\n};\n\nconst getObjectViaJsonRpc = async (\n\trpcUrl: string,\n\targs: {\n\t\treadonly objectId: string;\n\t\treadonly include?: {\n\t\t\treadonly content?: boolean;\n\t\t\treadonly json?: boolean;\n\t\t};\n\t},\n): Promise<unknown> => {\n\tconst showContent = args.include?.content === true || args.include?.json === true;\n\tconst result = await postJsonRpc<{\n\t\treadonly data?: {\n\t\t\treadonly objectId?: string;\n\t\t\treadonly version?: string | number;\n\t\t\treadonly type?: string;\n\t\t\treadonly owner?: unknown;\n\t\t\treadonly content?: {\n\t\t\t\treadonly fields?: unknown;\n\t\t\t};\n\t\t};\n\t}>('' + rpcUrl, 'sui_getObject', [\n\t\targs.objectId,\n\t\t{ showType: true, showOwner: true, showContent },\n\t]);\n\tconst data = result.data;\n\tif (data?.objectId === undefined) throw new Error(`object ${args.objectId} not found`);\n\tconst object = {\n\t\tobjectId: data.objectId,\n\t\tversion: String(data.version ?? ''),\n\t\ttype: data.type ?? 'unknown',\n\t\towner: normalizeJsonOwner(data.owner),\n\t\t...(args.include?.json === true ? { json: data.content?.fields } : {}),\n\t\t...(args.include?.content === true ? { content: data.content } : {}),\n\t};\n\treturn { ...object, object };\n};\n\n// ---------------------------------------------------------------------------\n// SuiClient assembly — collapses the per-mode boilerplate\n// ---------------------------------------------------------------------------\n\n/** Build the `SuiSdkShim` over a constructed grpc client.\n *  Account/Coin/Wallet read through this seam, so we expose\n *  `executeTransaction` + `waitForTransaction` in addition to the\n *  read methods needed by the chain probe. */\nexport const makeSdkShim = (sdkClient: SuiGrpcClient, rpcUrl: string): SuiSdkShim => ({\n\tcore: {\n\t\tgetObject: (args) => getObjectViaJsonRpc(rpcUrl, args),\n\t\tgetTransaction: (args) => sdkClient.core.getTransaction(args),\n\t\tgetBalance: (args) => sdkClient.core.getBalance(args),\n\t\tlistCoins: (args) => sdkClient.core.listCoins(args),\n\t\t// Extended surfaces — used by the account plugin's sign + execute\n\t\t// closure. Local mode keeps the `sdkClient.executeTransaction` /\n\t\t// `sdkClient.waitForTransaction` instance methods reachable on\n\t\t// the shim so consumers don't have to know about the grpc client\n\t\t// constructor. The SDK accepts a mutable `signatures: string[]`\n\t\t// shape; the shim's readonly signature is widened with a copy at\n\t\t// the boundary.\n\t\texecuteTransaction: (args) =>\n\t\t\tsdkClient.executeTransaction({\n\t\t\t\ttransaction: args.transaction,\n\t\t\t\tsignatures: [...args.signatures],\n\t\t\t\t...(args.include !== undefined ? { include: args.include } : {}),\n\t\t\t}),\n\t\twaitForTransaction: (args) =>\n\t\t\tsdkClient.waitForTransaction({\n\t\t\t\tdigest: args.digest,\n\t\t\t\t...(args.timeout !== undefined ? { timeout: args.timeout } : {}),\n\t\t\t}),\n\t},\n\t// Opaque client passthrough — the Package plugin's publish-tx\n\t// builder hands this to `Transaction.build({ client })`. The shim\n\t// layer doesn't type-narrow it; downstream consumers cast at the\n\t// `tx.build` call site (mirrors coin/mint.ts).\n\tclient: sdkClient,\n});\n\n/** Assemble a `SuiClient` from the per-mode building blocks. The\n *  `fork: null` discriminator is invariant for non-fork modes; the\n *  fork builder constructs its own client with the admin surface.\n *\n *  `chain` is accepted as a bare string and branded to `ChainId` at\n *  this single boundary — every consumer downstream reads the\n *  branded shape so capability-key constructors (`chainProbe…`,\n *  `faucet…`) accept it without a cast. */\nexport const assembleSuiClient = (parts: {\n\treadonly sdkClient: SuiGrpcClient;\n\treadonly chain: string;\n\treadonly rpcUrl: string;\n\treadonly sdkRpcUrl?: string;\n\treadonly faucetUrl?: string;\n\treadonly fundingFaucetUrl?: string;\n\treadonly graphqlUrl?: string;\n\treadonly waitForTransactionsReady: WaitForTransactionsReady;\n\t/** Image ref consumed by package's path (b) (`docker run --rm`)\n\t *  build path. `null` for modes that have no in-stack image\n\t *  (external + live). */\n\treadonly buildImage?: import('../../../contracts/container-runtime.ts').ImageRef | null;\n\t/** Container-reachable mirrors. Local mode resolves public URLs\n\t *  through the router but sibling containers still need direct\n\t *  host-gateway URLs during boot. */\n\treadonly hostGateway?: SuiClient['hostGateway'];\n}): {\n\treadonly client: SuiClient;\n\treadonly sdkShim: SuiSdkShim;\n\treadonly chainProbe: ChainProbe<SuiProbeKey>;\n} => {\n\tconst sdkShim = makeSdkShim(parts.sdkClient, parts.sdkRpcUrl ?? parts.rpcUrl);\n\tconst chainProbe = makeSuiChainProbe(sdkShim, parts.chain);\n\tconst client: SuiClient = {\n\t\tsdk: sdkShim,\n\t\trpcUrl: parts.rpcUrl,\n\t\tfaucetUrl: parts.faucetUrl ?? null,\n\t\tfundingFaucetUrl: parts.fundingFaucetUrl ?? parts.faucetUrl ?? null,\n\t\tgraphqlUrl: parts.graphqlUrl ?? null,\n\t\thostGateway: parts.hostGateway ?? {\n\t\t\trpcUrl: toDockerHostGatewayUrl(parts.rpcUrl),\n\t\t\tfaucetUrl: parts.faucetUrl === undefined ? null : toDockerHostGatewayUrl(parts.faucetUrl),\n\t\t\tgraphqlUrl: parts.graphqlUrl === undefined ? null : toDockerHostGatewayUrl(parts.graphqlUrl),\n\t\t},\n\t\tchain: brandChainId(parts.chain),\n\t\twaitForTransactionsReady: parts.waitForTransactionsReady,\n\t\tchainProbe,\n\t\tfork: null,\n\t\tbuildImage: parts.buildImage ?? null,\n\t};\n\treturn { client, sdkShim, chainProbe };\n};\n\n/** Shape the resolved network record the boot builders all hand\n *  back. The substrate-network mapping is uniform per mode. Brands\n *  the raw chain string at this boundary so consumers downstream\n *  (codegen, capabilities, walrus/seal deps) read a `ChainId` and\n *  don't re-wrap. */\nexport const makeResolvedNetwork = (parts: {\n\treadonly mode: ResolvedSuiNetwork['mode'];\n\treadonly chain: string;\n\treadonly rpc: string;\n\treadonly faucet?: string;\n\treadonly graphql?: string;\n\treadonly source: ResolvedSuiNetwork['source'];\n\treadonly checkpoint?: string;\n\treadonly forkUpstream?: ResolvedSuiNetwork['forkUpstream'];\n}): ResolvedSuiNetwork => ({\n\tmode: parts.mode,\n\tchain: brandChainId(parts.chain),\n\trpc: parts.rpc,\n\tsource: parts.source,\n\t...(parts.faucet !== undefined ? { faucet: parts.faucet } : {}),\n\t...(parts.graphql !== undefined ? { graphql: parts.graphql } : {}),\n\t...(parts.checkpoint !== undefined ? { checkpoint: parts.checkpoint } : {}),\n\t...(parts.forkUpstream !== undefined ? { forkUpstream: parts.forkUpstream } : {}),\n});\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\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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"}

package/dist/plugins/sui/mode/shared.d.mts

@@ -0,0 +1,103 @@
+import { ChainId } from "../../../substrate/brand.mjs";
+import { ImageRef } from "../../../contracts/container-runtime.mjs";
+import { ChainProbe } from "../../../contracts/chain-probe.mjs";
+import { SuiProbeKey, SuiSdkShim } from "../chain-probe.mjs";
+import { SuiPluginError } from "../errors.mjs";
+import { Effect } from "effect";
+
+//#region src/plugins/sui/mode/shared.d.ts
+/** Funds-ready strategy contributed by Sui. Mode-aware:
+ *
+ *   - local container — first call POSTs a real funding tx against
+ *     the faucet, retrying on body-level {Failure} during the
+ *     post-RPC / pre-fund window. Memoised after first success.
+ *   - external w/ faucet — same as local container.
+ *   - live testnet — same, but no retry needed (the public faucet
+ *     is rate-limited differently).
+ *   - live mainnet / faucet-less — trivially-succeeding no-op.
+ *     (Architecture: "no-faucet network has a trivially-succeeding
+ *     funds-ready gate" is a first-class property of the mode.)
+ *   - fork — trivially-succeeding (impersonation funds, not
+ *     faucet).
+ *
+ *  Distilled-doc opportunity: `Effect.cached` caches the first-call
+ *  failure for the whole scope; add a manual-invalidation surface
+ *  so a fork restart can re-probe. The shape below leaves room for
+ *  that knob. */
+interface WaitForTransactionsReady {
+  readonly wait: Effect.Effect<void, SuiPluginError>;
+  /** Manual invalidation — clears the memoised result. The default
+   *  built-in invalidates on plugin restart; this surface lets
+   *  long-running supervisors invalidate without a full restart. */
+  readonly invalidate: Effect.Effect<void>;
+}
+/** Fork admin surface — mode-narrowed. Only the fork-mode factory's
+ *  resolved value carries this; local/local-rpc/live values have a
+ *  type-level `null`.
+ *
+ *  Distilled-doc opportunity: today's `Fiber` handle is discarded
+ *  at the auto-tick call site; the `autoTickHandle` field below
+ *  preserves it for a future cadence-change surface. */
+interface ForkAdminSurface {
+  readonly status: Effect.Effect<{
+    readonly checkpoint: string;
+    readonly clock: number;
+  }, SuiPluginError>;
+  readonly advanceClock: (intervalMs: number) => Effect.Effect<void, SuiPluginError>;
+  readonly advanceCheckpoint: Effect.Effect<void, SuiPluginError>;
+  readonly impersonate: (sender: string, tx: unknown) => Effect.Effect<{
+    readonly digest: string;
+    readonly success: boolean;
+    readonly raw: unknown;
+  }, SuiPluginError>;
+}
+/** The resolved value Sui publishes via its resource id. */
+interface SuiClient {
+  /** The SDK shim. Fork mode wraps this with the property-access
+   *  blocklist (`fork-orchestration.wrapWithForkGuard`). */
+  readonly sdk: SuiSdkShim;
+  /** Host-reachable RPC URL for this resolved network. Local mode
+   *  surfaces the router-fronted URL; direct boot/probe ports are
+   *  available through `hostGateway` for sibling containers. */
+  readonly rpcUrl: string;
+  /** Host-reachable faucet base URL when this network has a faucet. */
+  readonly faucetUrl: string | null;
+  /** Faucet URL used by account funding strategies. Local mode keeps
+   *  this on the direct validator port used by the funds-ready gate. */
+  readonly fundingFaucetUrl: string | null;
+  /** Host-reachable GraphQL URL when the mode exposes one. */
+  readonly graphqlUrl: string | null;
+  /** Container-reachable mirrors of the host URLs. Loopback hosts are
+   *  rewritten to `host.docker.internal`; public URLs pass through. */
+  readonly hostGateway: {
+    readonly rpcUrl: string;
+    readonly faucetUrl: string | null;
+    readonly graphqlUrl: string | null;
+  };
+  /** Chain identity — downstream cache primitives fold this into
+   *  their state-store keys so on-chain artifacts re-derive when
+   *  the chain is wiped. Branded so consumers can hand it directly
+   *  to `chainProbeCapabilityKey(chain)` / `faucetCapabilityKey(chain)`
+   *  without a cast. */
+  readonly chain: ChainId;
+  /** Mode-aware funds-transferable gate; trivially-succeeding on
+   *  faucet-less networks. */
+  readonly waitForTransactionsReady: WaitForTransactionsReady;
+  /** Schema-validated read surface. Folded into every consumer's
+   *  context via `chain-probe:<chainId>` strategy lookup. */
+  readonly chainProbe: ChainProbe<SuiProbeKey>;
+  /** Fork-mode-only admin sub-surface. `null` for non-fork
+   *  modes; the mode-narrowed factory namespace narrows this at
+   *  the type level so consumers don't have to nullcheck. */
+  readonly fork: ForkAdminSurface | null;
+  /** Container image ref the Sui plugin built/pulled for its
+   *  validator. Surfaced so cross-service consumers (Package's
+   *  Move build, codegen's `summary` invocation) can spawn a
+   *  one-shot container running the SAME sui binary without
+   *  re-resolving the image. `null` for modes that have no
+   *  in-stack container (external + live). */
+  readonly buildImage: ImageRef | null;
+}
+//#endregion
+export { ForkAdminSurface, SuiClient, WaitForTransactionsReady };
+//# sourceMappingURL=shared.d.mts.map

package/dist/plugins/sui/mode/shared.mjs

@@ -0,0 +1,12 @@
+import "effect";
+//#region src/plugins/sui/mode/shared.ts
+const toDockerHostGatewayUrl = (url) => {
+	const parsed = new URL(url);
+	if (parsed.hostname === "127.0.0.1" || parsed.hostname === "localhost" || parsed.hostname === "0.0.0.0" || parsed.hostname === "::1" || parsed.hostname === "[::1]") parsed.hostname = "host.docker.internal";
+	const rendered = parsed.toString();
+	return parsed.pathname === "/" && parsed.search === "" && parsed.hash === "" ? rendered.slice(0, -1) : rendered;
+};
+//#endregion
+export { toDockerHostGatewayUrl };
+
+//# sourceMappingURL=shared.mjs.map

package/dist/plugins/sui/mode/shared.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.mjs","names":[],"sources":["../../../../src/plugins/sui/mode/shared.ts"],"sourcesContent":["// Shared shapes across mode builders.\n//\n// `SuiClient` is the resolved-value the plugin's `provides` tag\n// publishes — every consumer (Account, Coin, Wallet, Faucet,\n// Package, Codegen, Walrus/Seal/Deepbook fork variants) reads\n// THIS shape.\n//\n// Why one shape: distilled-doc finding — Sui's factory + builder\n// file is ~2000 LOC because the four per-network builders share\n// boilerplate (publish endpoints + fetch chain id + publish state)\n// but their bodies diverge in mode-specific ways. The redesign\n// bakes the seam in: the resolved value is uniform, the boot path\n// is mode-specific, and the admin surfaces narrow at the type\n// level (fork has `Sui.fork.advanceClock`; live does not).\n\nimport { Effect } from 'effect';\n\nimport type { SuiPluginError } from '../errors.ts';\nimport type { SuiSdkShim } from '../chain-probe.ts';\nimport type { ChainProbe } from '../../../contracts/chain-probe.ts';\nimport type { ImageRef } from '../../../contracts/container-runtime.ts';\nimport type { SuiProbeKey } from '../chain-probe.ts';\nimport type { ChainId } from '../../../substrate/brand.ts';\n\n/** Funds-ready strategy contributed by Sui. Mode-aware:\n *\n *   - local container — first call POSTs a real funding tx against\n *     the faucet, retrying on body-level {Failure} during the\n *     post-RPC / pre-fund window. Memoised after first success.\n *   - external w/ faucet — same as local container.\n *   - live testnet — same, but no retry needed (the public faucet\n *     is rate-limited differently).\n *   - live mainnet / faucet-less — trivially-succeeding no-op.\n *     (Architecture: \"no-faucet network has a trivially-succeeding\n *     funds-ready gate\" is a first-class property of the mode.)\n *   - fork — trivially-succeeding (impersonation funds, not\n *     faucet).\n *\n *  Distilled-doc opportunity: `Effect.cached` caches the first-call\n *  failure for the whole scope; add a manual-invalidation surface\n *  so a fork restart can re-probe. The shape below leaves room for\n *  that knob. */\nexport interface WaitForTransactionsReady {\n\treadonly wait: Effect.Effect<void, SuiPluginError>;\n\t/** Manual invalidation — clears the memoised result. The default\n\t *  built-in invalidates on plugin restart; this surface lets\n\t *  long-running supervisors invalidate without a full restart. */\n\treadonly invalidate: Effect.Effect<void>;\n}\n\n/** Fork admin surface — mode-narrowed. Only the fork-mode factory's\n *  resolved value carries this; local/local-rpc/live values have a\n *  type-level `null`.\n *\n *  Distilled-doc opportunity: today's `Fiber` handle is discarded\n *  at the auto-tick call site; the `autoTickHandle` field below\n *  preserves it for a future cadence-change surface. */\nexport interface ForkAdminSurface {\n\treadonly status: Effect.Effect<\n\t\t{ readonly checkpoint: string; readonly clock: number },\n\t\tSuiPluginError\n\t>;\n\treadonly advanceClock: (intervalMs: number) => Effect.Effect<void, SuiPluginError>;\n\treadonly advanceCheckpoint: Effect.Effect<void, SuiPluginError>;\n\treadonly impersonate: (\n\t\tsender: string,\n\t\ttx: unknown,\n\t) => Effect.Effect<\n\t\t{ readonly digest: string; readonly success: boolean; readonly raw: unknown },\n\t\tSuiPluginError\n\t>;\n}\n\n/** The resolved value Sui publishes via its resource id. */\nexport interface SuiClient {\n\t/** The SDK shim. Fork mode wraps this with the property-access\n\t *  blocklist (`fork-orchestration.wrapWithForkGuard`). */\n\treadonly sdk: SuiSdkShim;\n\t/** Host-reachable RPC URL for this resolved network. Local mode\n\t *  surfaces the router-fronted URL; direct boot/probe ports are\n\t *  available through `hostGateway` for sibling containers. */\n\treadonly rpcUrl: string;\n\t/** Host-reachable faucet base URL when this network has a faucet. */\n\treadonly faucetUrl: string | null;\n\t/** Faucet URL used by account funding strategies. Local mode keeps\n\t *  this on the direct validator port used by the funds-ready gate. */\n\treadonly fundingFaucetUrl: string | null;\n\t/** Host-reachable GraphQL URL when the mode exposes one. */\n\treadonly graphqlUrl: string | null;\n\t/** Container-reachable mirrors of the host URLs. Loopback hosts are\n\t *  rewritten to `host.docker.internal`; public URLs pass through. */\n\treadonly hostGateway: {\n\t\treadonly rpcUrl: string;\n\t\treadonly faucetUrl: string | null;\n\t\treadonly graphqlUrl: string | null;\n\t};\n\t/** Chain identity — downstream cache primitives fold this into\n\t *  their state-store keys so on-chain artifacts re-derive when\n\t *  the chain is wiped. Branded so consumers can hand it directly\n\t *  to `chainProbeCapabilityKey(chain)` / `faucetCapabilityKey(chain)`\n\t *  without a cast. */\n\treadonly chain: ChainId;\n\t/** Mode-aware funds-transferable gate; trivially-succeeding on\n\t *  faucet-less networks. */\n\treadonly waitForTransactionsReady: WaitForTransactionsReady;\n\t/** Schema-validated read surface. Folded into every consumer's\n\t *  context via `chain-probe:<chainId>` strategy lookup. */\n\treadonly chainProbe: ChainProbe<SuiProbeKey>;\n\t/** Fork-mode-only admin sub-surface. `null` for non-fork\n\t *  modes; the mode-narrowed factory namespace narrows this at\n\t *  the type level so consumers don't have to nullcheck. */\n\treadonly fork: ForkAdminSurface | null;\n\t/** Container image ref the Sui plugin built/pulled for its\n\t *  validator. Surfaced so cross-service consumers (Package's\n\t *  Move build, codegen's `summary` invocation) can spawn a\n\t *  one-shot container running the SAME sui binary without\n\t *  re-resolving the image. `null` for modes that have no\n\t *  in-stack container (external + live). */\n\treadonly buildImage: ImageRef | null;\n}\n\nexport const toDockerHostGatewayUrl = (url: string): string => {\n\tconst parsed = new URL(url);\n\tif (\n\t\tparsed.hostname === '127.0.0.1' ||\n\t\tparsed.hostname === 'localhost' ||\n\t\tparsed.hostname === '0.0.0.0' ||\n\t\tparsed.hostname === '::1' ||\n\t\tparsed.hostname === '[::1]'\n\t) {\n\t\tparsed.hostname = 'host.docker.internal';\n\t}\n\tconst rendered = parsed.toString();\n\treturn parsed.pathname === '/' && parsed.search === '' && parsed.hash === ''\n\t\t? rendered.slice(0, -1)\n\t\t: rendered;\n};\n"],"mappings":";;AAyHA,MAAa,0BAA0B,QAAwB;CAC9D,MAAM,SAAS,IAAI,IAAI,IAAI;AAC3B,KACC,OAAO,aAAa,eACpB,OAAO,aAAa,eACpB,OAAO,aAAa,aACpB,OAAO,aAAa,SACpB,OAAO,aAAa,QAEpB,QAAO,WAAW;CAEnB,MAAM,WAAW,OAAO,UAAU;AAClC,QAAO,OAAO,aAAa,OAAO,OAAO,WAAW,MAAM,OAAO,SAAS,KACvE,SAAS,MAAM,GAAG,GAAG,GACrB"}

package/dist/plugins/sui/mode/spec.d.mts

@@ -0,0 +1,94 @@
+import { Duration } from "effect";
+
+//#region src/plugins/sui/mode/spec.d.ts
+/** Internal mode discriminator. Distinct from the substrate's
+ *  `NetworkMode` because we surface a degenerate `local-rpc`
+ *  sub-mode (caller-supplied RPC URL — no container needed) under
+ *  the substrate-level `'local'` branch. */
+type SuiPluginMode = 'local' | 'local-rpc' | 'live' | 'fork';
+/** Common Sui plugin options. Mode-specific identity pins live on the
+ *  modes that actually accept caller-supplied endpoints. */
+interface SuiCommonOptions {
+  /** Ready-probe timeout. Per-mode defaults are mode-specific. */
+  readonly readyTimeout?: Duration.Duration;
+}
+/** Local container mode — in-stack validator + faucet + GraphQL +
+ *  postgres indexer. */
+interface SuiLocalOptions extends SuiCommonOptions {
+  readonly mode: 'local';
+  /** Image override — `{pull}` skips the build; `{build}` uses
+   *  the bundled Dockerfile + a content-hashed tag. */
+  readonly image?: {
+    readonly pull: string;
+  } | {
+    readonly build: {
+      readonly context: string;
+      readonly dockerfile?: string;
+    };
+  };
+  /** Sui binary version (default in mode/local.ts). */
+  readonly version?: string;
+  /** Optional direct host port mapping keyed by container port. When
+   *  supplied, the mapping is exact: Sui does not reassign missing
+   *  or busy host ports through the PortBroker. Omit this field to
+   *  use brokered private host-port defaults for RPC/faucet/GraphQL
+   *  and reassign on collision. Router entrypoints own the public
+   *  9000/9123/9125 ports. */
+  readonly ports?: Readonly<Record<number, number>>;
+}
+/** Local RPC mode — caller already has a Sui process; we
+ *  wrap it. NO container, NO postgres sidecar, NO build image. */
+interface SuiLocalRpcOptions extends SuiCommonOptions {
+  readonly mode: 'local-rpc';
+  readonly rpcUrl: string;
+  readonly faucetUrl?: string;
+  readonly graphqlUrl?: string;
+  /** Optional chain id pin for caller-owned endpoints. Omit to
+   *  probe the RPC endpoint. */
+  readonly chain?: string;
+}
+/** Live testnet / mainnet / custom-RPC mode. */
+interface SuiLiveOptions extends SuiCommonOptions {
+  readonly mode: 'live';
+  /** Discriminator for known-network defaulting; `custom` requires
+   *  rpcUrl. */
+  readonly network: 'testnet' | 'mainnet' | 'devnet' | 'custom';
+  readonly rpcUrl?: string;
+  readonly faucetUrl?: string;
+  readonly graphqlUrl?: string;
+  /** Optional chain id pin for custom/caller-owned live endpoints.
+   *  Omit to probe the RPC endpoint. */
+  readonly chain?: string;
+}
+/** Fork mode — sui-fork binary mirroring a real chain at a
+ *  checkpoint. */
+interface SuiForkOptions extends SuiCommonOptions {
+  readonly mode: 'fork';
+  readonly upstream: 'mainnet' | 'testnet' | 'devnet';
+  readonly checkpoint?: number;
+  readonly image?: {
+    readonly pull: string;
+  } | {
+    readonly build: {
+      readonly context: string;
+      readonly dockerfile?: string;
+    };
+  };
+  /** Pinned Git revision of the Sui repository used to build `sui-fork`. */
+  readonly version?: string;
+  /** Optional direct host port mapping keyed by container port. */
+  readonly ports?: Readonly<Record<number, number>>;
+  readonly seed?: {
+    readonly addresses?: ReadonlyArray<string>;
+    readonly objects?: ReadonlyArray<string>;
+  };
+  /** Auto-tick clock cadence (or off). */
+  readonly autoTick?: boolean | {
+    readonly intervalMs: number;
+  };
+}
+/** The discriminated union of all four mode option records. */
+type SuiOptions = SuiLocalOptions | SuiLocalRpcOptions | SuiLiveOptions | SuiForkOptions;
+//#endregion
+export { SuiForkOptions, SuiLiveOptions, SuiLocalOptions, SuiLocalRpcOptions, SuiOptions, SuiPluginMode };
+//# sourceMappingURL=spec.d.mts.map

package/dist/plugins/sui/network-resolver.d.mts

@@ -0,0 +1,23 @@
+import { ChainId } from "../../substrate/brand.mjs";
+import { SuiPluginMode } from "./mode/spec.mjs";
+//#region src/plugins/sui/network-resolver.d.ts
+/** Plugin-internal shape — the resolved mode's identity, populated
+ *  by the mode-specific builder. The resolver below projects this
+ *  into the substrate's `NetworkConfig`. */
+interface ResolvedSuiNetwork {
+  readonly mode: SuiPluginMode;
+  /** Branded chain identity — assembled by the mode builders so
+   *  downstream lookups (chain-probe / faucet capability keys) and
+   *  the `NetworkConfig` projection both accept it without a re-wrap. */
+  readonly chain: ChainId;
+  readonly rpc: string;
+  readonly faucet?: string;
+  readonly graphql?: string;
+  readonly source: 'cli' | 'env' | 'config' | 'default';
+  /** Fork-only: upstream + checkpoint pin. */
+  readonly checkpoint?: string;
+  readonly forkUpstream?: 'mainnet' | 'testnet' | 'devnet';
+}
+//#endregion
+export { ResolvedSuiNetwork };
+//# sourceMappingURL=network-resolver.d.mts.map

package/dist/plugins/sui/routable.mjs

@@ -0,0 +1,88 @@
+const SUI_FAUCET_ENDPOINT_NAME = "faucet";
+const SUI_GRAPHQL_ENDPOINT_NAME = "graphql";
+const SUI_RPC_ENTRYPOINT_PORT = 9e3;
+const SUI_FAUCET_ENTRYPOINT_PORT = 9123;
+const SUI_GRAPHQL_ENTRYPOINT_PORT = 9125;
+const SUI_ENTRYPOINTS = [
+	{
+		name: "rpc",
+		port: SUI_RPC_ENTRYPOINT_PORT,
+		protocol: "http"
+	},
+	{
+		name: SUI_FAUCET_ENDPOINT_NAME,
+		port: SUI_FAUCET_ENTRYPOINT_PORT,
+		protocol: "http"
+	},
+	{
+		name: SUI_GRAPHQL_ENDPOINT_NAME,
+		port: SUI_GRAPHQL_ENTRYPOINT_PORT,
+		protocol: "http"
+	}
+];
+const makeSuiLocalRoutables = (parts) => [
+	{
+		kind: "routable",
+		endpointName: "rpc",
+		dispatchId: {
+			serviceKey: "sui.local",
+			role: "rpc"
+		},
+		upstream: {
+			type: "container",
+			containerName: parts.containerName,
+			containerPort: SUI_RPC_ENTRYPOINT_PORT
+		},
+		cors: true,
+		wireProtocol: "http"
+	},
+	{
+		kind: "routable",
+		endpointName: SUI_FAUCET_ENDPOINT_NAME,
+		dispatchId: {
+			serviceKey: "sui.local",
+			role: SUI_FAUCET_ENDPOINT_NAME
+		},
+		upstream: {
+			type: "container",
+			containerName: parts.containerName,
+			containerPort: SUI_FAUCET_ENTRYPOINT_PORT
+		},
+		cors: true,
+		wireProtocol: "http"
+	},
+	...parts.includeGraphql ? [{
+		kind: "routable",
+		endpointName: SUI_GRAPHQL_ENDPOINT_NAME,
+		dispatchId: {
+			serviceKey: "sui.local",
+			role: SUI_GRAPHQL_ENDPOINT_NAME
+		},
+		upstream: {
+			type: "container",
+			containerName: parts.containerName,
+			containerPort: SUI_GRAPHQL_ENTRYPOINT_PORT
+		},
+		cors: true,
+		wireProtocol: "http"
+	}] : []
+];
+const makeSuiForkRoutables = (parts) => [{
+	kind: "routable",
+	endpointName: "rpc",
+	dispatchId: {
+		serviceKey: "sui.fork",
+		role: "rpc"
+	},
+	upstream: {
+		type: "container",
+		containerName: parts.containerName,
+		containerPort: SUI_RPC_ENTRYPOINT_PORT
+	},
+	cors: true,
+	wireProtocol: "http"
+}];
+//#endregion
+export { SUI_ENTRYPOINTS, SUI_FAUCET_ENDPOINT_NAME, SUI_FAUCET_ENTRYPOINT_PORT, SUI_GRAPHQL_ENDPOINT_NAME, SUI_GRAPHQL_ENTRYPOINT_PORT, SUI_RPC_ENTRYPOINT_PORT, makeSuiForkRoutables, makeSuiLocalRoutables };
+
+//# sourceMappingURL=routable.mjs.map

package/dist/plugins/sui/routable.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"routable.mjs","names":[],"sources":["../../../src/plugins/sui/routable.ts"],"sourcesContent":["import type { EntrypointDecl, RoutableDecl } from '../../contracts/routable.ts';\n\nexport const SUI_RPC_ENDPOINT_NAME = 'rpc' as const;\nexport const SUI_FAUCET_ENDPOINT_NAME = 'faucet' as const;\nexport const SUI_GRAPHQL_ENDPOINT_NAME = 'graphql' as const;\n\nexport const SUI_RPC_ENTRYPOINT_PORT = 9000;\nexport const SUI_FAUCET_ENTRYPOINT_PORT = 9123;\nexport const SUI_GRAPHQL_ENTRYPOINT_PORT = 9125;\n\nexport const SUI_ENTRYPOINTS: ReadonlyArray<EntrypointDecl> = [\n\t{ name: SUI_RPC_ENDPOINT_NAME, port: SUI_RPC_ENTRYPOINT_PORT, protocol: 'http' },\n\t{ name: SUI_FAUCET_ENDPOINT_NAME, port: SUI_FAUCET_ENTRYPOINT_PORT, protocol: 'http' },\n\t{ name: SUI_GRAPHQL_ENDPOINT_NAME, port: SUI_GRAPHQL_ENTRYPOINT_PORT, protocol: 'http' },\n];\n\nexport const makeSuiLocalRoutables = (parts: {\n\treadonly containerName: string;\n\treadonly includeGraphql: boolean;\n}): ReadonlyArray<RoutableDecl> => [\n\t{\n\t\tkind: 'routable',\n\t\tendpointName: SUI_RPC_ENDPOINT_NAME,\n\t\tdispatchId: {\n\t\t\tserviceKey: 'sui.local',\n\t\t\trole: SUI_RPC_ENDPOINT_NAME,\n\t\t},\n\t\tupstream: {\n\t\t\ttype: 'container',\n\t\t\tcontainerName: parts.containerName,\n\t\t\tcontainerPort: SUI_RPC_ENTRYPOINT_PORT,\n\t\t},\n\t\tcors: true,\n\t\twireProtocol: 'http',\n\t},\n\t{\n\t\tkind: 'routable',\n\t\tendpointName: SUI_FAUCET_ENDPOINT_NAME,\n\t\tdispatchId: {\n\t\t\tserviceKey: 'sui.local',\n\t\t\trole: SUI_FAUCET_ENDPOINT_NAME,\n\t\t},\n\t\tupstream: {\n\t\t\ttype: 'container',\n\t\t\tcontainerName: parts.containerName,\n\t\t\tcontainerPort: SUI_FAUCET_ENTRYPOINT_PORT,\n\t\t},\n\t\tcors: true,\n\t\twireProtocol: 'http',\n\t},\n\t...(parts.includeGraphql\n\t\t? [\n\t\t\t\t{\n\t\t\t\t\tkind: 'routable',\n\t\t\t\t\tendpointName: SUI_GRAPHQL_ENDPOINT_NAME,\n\t\t\t\t\tdispatchId: {\n\t\t\t\t\t\tserviceKey: 'sui.local',\n\t\t\t\t\t\trole: SUI_GRAPHQL_ENDPOINT_NAME,\n\t\t\t\t\t},\n\t\t\t\t\tupstream: {\n\t\t\t\t\t\ttype: 'container',\n\t\t\t\t\t\tcontainerName: parts.containerName,\n\t\t\t\t\t\tcontainerPort: SUI_GRAPHQL_ENTRYPOINT_PORT,\n\t\t\t\t\t},\n\t\t\t\t\tcors: true,\n\t\t\t\t\twireProtocol: 'http',\n\t\t\t\t} satisfies RoutableDecl,\n\t\t\t]\n\t\t: []),\n];\n\nexport const makeSuiForkRoutables = (parts: {\n\treadonly containerName: string;\n}): ReadonlyArray<RoutableDecl> => [\n\t{\n\t\tkind: 'routable',\n\t\tendpointName: SUI_RPC_ENDPOINT_NAME,\n\t\tdispatchId: {\n\t\t\tserviceKey: 'sui.fork',\n\t\t\trole: SUI_RPC_ENDPOINT_NAME,\n\t\t},\n\t\tupstream: {\n\t\t\ttype: 'container',\n\t\t\tcontainerName: parts.containerName,\n\t\t\tcontainerPort: SUI_RPC_ENTRYPOINT_PORT,\n\t\t},\n\t\tcors: true,\n\t\twireProtocol: 'http',\n\t},\n];\n"],"mappings":"AAGA,MAAa,2BAA2B;AACxC,MAAa,4BAA4B;AAEzC,MAAa,0BAA0B;AACvC,MAAa,6BAA6B;AAC1C,MAAa,8BAA8B;AAE3C,MAAa,kBAAiD;CAC7D;EAAE,MAAA;EAA6B,MAAM;EAAyB,UAAU;EAAQ;CAChF;EAAE,MAAM;EAA0B,MAAM;EAA4B,UAAU;EAAQ;CACtF;EAAE,MAAM;EAA2B,MAAM;EAA6B,UAAU;EAAQ;CACxF;AAED,MAAa,yBAAyB,UAGH;CAClC;EACC,MAAM;EACN,cAAA;EACA,YAAY;GACX,YAAY;GACZ,MAAA;GACA;EACD,UAAU;GACT,MAAM;GACN,eAAe,MAAM;GACrB,eAAe;GACf;EACD,MAAM;EACN,cAAc;EACd;CACD;EACC,MAAM;EACN,cAAc;EACd,YAAY;GACX,YAAY;GACZ,MAAM;GACN;EACD,UAAU;GACT,MAAM;GACN,eAAe,MAAM;GACrB,eAAe;GACf;EACD,MAAM;EACN,cAAc;EACd;CACD,GAAI,MAAM,iBACP,CACA;EACC,MAAM;EACN,cAAc;EACd,YAAY;GACX,YAAY;GACZ,MAAM;GACN;EACD,UAAU;GACT,MAAM;GACN,eAAe,MAAM;GACrB,eAAe;GACf;EACD,MAAM;EACN,cAAc;EACd,CACD,GACA,EAAE;CACL;AAED,MAAa,wBAAwB,UAEF,CAClC;CACC,MAAM;CACN,cAAA;CACA,YAAY;EACX,YAAY;EACZ,MAAA;EACA;CACD,UAAU;EACT,MAAM;EACN,eAAe,MAAM;EACrB,eAAe;EACf;CACD,MAAM;CACN,cAAc;CACd,CACD"}

package/dist/plugins/sui/seed-objects.d.mts

@@ -0,0 +1,18 @@
+import { Effect } from "effect";
+
+//#region src/plugins/sui/seed-objects.d.ts
+/** Plugin-instance-scoped accumulator. Constructed inside the
+ *  Sui plugin's `acquire` body; the lifetime is the plugin's scope. */
+interface SeedObjectsAccumulator {
+  /** Merge a set of seed object ids. KnownPackage declarations
+   *  call this during their own acquire — Sui's fork builder
+   *  reads the accumulated set AFTER scheduler ordering puts
+   *  KnownPackage upstream of the fork container. */
+  readonly contribute: (objects: ReadonlyArray<string>) => Effect.Effect<void>;
+  /** Snapshot the accumulated set. Called by fork's acquire when
+   *  composing the `--object` seed flags. */
+  readonly snapshot: Effect.Effect<ReadonlyArray<string>>;
+}
+//#endregion
+export { SeedObjectsAccumulator };
+//# sourceMappingURL=seed-objects.d.mts.map

package/dist/plugins/sui/seed-objects.mjs

@@ -0,0 +1,25 @@
+import { Effect, Ref } from "effect";
+//#region src/plugins/sui/seed-objects.ts
+/** Capability key the StrategyContributor registry dispatches on.
+*  KnownPackage declarations look this up; Sui's fork mode
+*  contributes it from inside acquire. */
+const SEED_OBJECTS_CAPABILITY_KEY = "sui:seed-objects";
+/** Construct a fresh accumulator. Each Sui plugin instance gets
+*  one — the substrate's scope-boundary handles isolation across
+*  parallel stacks. */
+const makeSeedObjectsAccumulator = () => Effect.gen(function* () {
+	const ref = yield* Ref.make([]);
+	const contribute = (objects) => Ref.update(ref, (prev) => {
+		const set = new Set(prev);
+		for (const o of objects) set.add(o.toLowerCase());
+		return Array.from(set).sort();
+	});
+	return {
+		contribute,
+		snapshot: Ref.get(ref)
+	};
+});
+//#endregion
+export { SEED_OBJECTS_CAPABILITY_KEY, makeSeedObjectsAccumulator };
+
+//# sourceMappingURL=seed-objects.mjs.map

package/dist/plugins/sui/seed-objects.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-objects.mjs","names":[],"sources":["../../../src/plugins/sui/seed-objects.ts"],"sourcesContent":["// Fork-mode seed-objects accumulator.\n//\n// Distilled-doc finding (5-sui § Opportunities): today's code uses\n// a module-scope `Set<string>` with an explicit\n// `clearKnownPackageSeedObjects()` contract between composes. That\n// is a foot-gun — tests that compose more than once must remember\n// to clear; the responsibility sits with the user, not the\n// framework.\n//\n// Fix: confine the accumulator to plugin-instance state. Each\n// `sui()` factory call constructs a fresh `SeedObjectsAccumulator`\n// inside its acquire body's scope; KnownPackage declarations\n// elsewhere in the stack discover it via the StrategyContributor\n// registry (`sui:seed-objects`).\n//\n// The substrate-redesign substrate-violations document already\n// flags module-scope mutable state as forbidden; this file is the\n// implementation of the cure.\n\nimport { Effect, Ref } from 'effect';\n\n/** Plugin-instance-scoped accumulator. Constructed inside the\n *  Sui plugin's `acquire` body; the lifetime is the plugin's scope. */\nexport interface SeedObjectsAccumulator {\n\t/** Merge a set of seed object ids. KnownPackage declarations\n\t *  call this during their own acquire — Sui's fork builder\n\t *  reads the accumulated set AFTER scheduler ordering puts\n\t *  KnownPackage upstream of the fork container. */\n\treadonly contribute: (objects: ReadonlyArray<string>) => Effect.Effect<void>;\n\t/** Snapshot the accumulated set. Called by fork's acquire when\n\t *  composing the `--object` seed flags. */\n\treadonly snapshot: Effect.Effect<ReadonlyArray<string>>;\n}\n\n/** Capability key the StrategyContributor registry dispatches on.\n *  KnownPackage declarations look this up; Sui's fork mode\n *  contributes it from inside acquire. */\nexport const SEED_OBJECTS_CAPABILITY_KEY = 'sui:seed-objects' as const;\n\n/** Construct a fresh accumulator. Each Sui plugin instance gets\n *  one — the substrate's scope-boundary handles isolation across\n *  parallel stacks. */\nexport const makeSeedObjectsAccumulator = (): Effect.Effect<SeedObjectsAccumulator> =>\n\tEffect.gen(function* () {\n\t\tconst ref = yield* Ref.make<ReadonlyArray<string>>([]);\n\n\t\tconst contribute = (objects: ReadonlyArray<string>): Effect.Effect<void> =>\n\t\t\tRef.update(ref, (prev) => {\n\t\t\t\t// Stable union — sorted + lowercased so the configHash\n\t\t\t\t// is invariant under contribution order (architecture\n\t\t\t\t// § sui § Invariants).\n\t\t\t\tconst set = new Set(prev);\n\t\t\t\tfor (const o of objects) set.add(o.toLowerCase());\n\t\t\t\treturn Array.from(set).sort();\n\t\t\t});\n\n\t\tconst snapshot = Ref.get(ref);\n\n\t\treturn { contribute, snapshot };\n\t});\n"],"mappings":";;;;;AAqCA,MAAa,8BAA8B;;;;AAK3C,MAAa,mCACZ,OAAO,IAAI,aAAa;CACvB,MAAM,MAAM,OAAO,IAAI,KAA4B,EAAE,CAAC;CAEtD,MAAM,cAAc,YACnB,IAAI,OAAO,MAAM,SAAS;EAIzB,MAAM,MAAM,IAAI,IAAI,KAAK;AACzB,OAAK,MAAM,KAAK,QAAS,KAAI,IAAI,EAAE,aAAa,CAAC;AACjD,SAAO,MAAM,KAAK,IAAI,CAAC,MAAM;GAC5B;AAIH,QAAO;EAAE;EAAY,UAFJ,IAAI,IAAI,IAEI;EAAE;EAC9B"}

package/dist/plugins/sui/service.mjs

@@ -0,0 +1,38 @@
+import { bootLocalRpcMode } from "./mode/external.mjs";
+import { bootForkMode } from "./mode/fork.mjs";
+import { bootLiveMode } from "./mode/live.mjs";
+import { bootLocalMode } from "./mode/local.mjs";
+import { Effect } from "effect";
+//#region src/plugins/sui/service.ts
+/** Dispatch on the typed mode and return the mode's boot artifacts.
+*
+*  The `ContainerRuntime` is consumed by container-bearing modes
+*  only (local + fork); external + live get `null` and a typed
+*  refusal would surface if they tried to use it.
+*
+*  Stub: the per-mode builders are all stubs; the orchestrator
+*  here is the only fully-wired piece. */
+const bootSuiService = (runtime, identity, portBroker, paths, opts) => {
+	switch (opts.mode) {
+		case "local": return bootLocalMode(runtime, identity, portBroker, opts).pipe(Effect.map(({ resolved, client }) => ({
+			resolved,
+			client
+		})));
+		case "local-rpc": return bootLocalRpcMode(opts).pipe(Effect.map(({ resolved, client }) => ({
+			resolved,
+			client
+		})));
+		case "live": return bootLiveMode(opts).pipe(Effect.map(({ resolved, client }) => ({
+			resolved,
+			client
+		})));
+		case "fork": return bootForkMode(runtime, identity, portBroker, paths, opts).pipe(Effect.map(({ resolved, client }) => ({
+			resolved,
+			client
+		})));
+	}
+};
+//#endregion
+export { bootSuiService };
+
+//# sourceMappingURL=service.mjs.map

package/dist/plugins/sui/service.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.mjs","names":[],"sources":["../../../src/plugins/sui/service.ts"],"sourcesContent":["// Sui plugin — service body.\n//\n// Architecture: the four modes are NOT four separate plugins. They\n// are one plugin with internal mode dispatch. The factory at the\n// barrel (`index.ts`) constructs a `SuiOptions` discriminator from\n// typed options; the `acquire` body below dispatches on `opts.mode`\n// and assembles the mode-appropriate subsystems.\n//\n// What this file does:\n//\n//   1. Receive resolved `SuiOptions`.\n//   2. Dispatch to the right `bootXxxMode` builder.\n//   3. Assemble the mode-aware `SuiClient` (the resolved value).\n//\n// What it does NOT do:\n//\n//   - Provision the build container — `chain-build-container.ts`\n//     owns that; the plugin acquires it ONLY when needed (Move\n//     publish or codegen) via the ArtifactPublisher seam.\n//   - Wire the StrategyContributor capabilities — that's the\n//     barrel's job; the body just returns the resolved value.\n\nimport { Effect, type Scope } from 'effect';\n\nimport type { SeedManifestMismatchError, SuiPluginError } from './errors.ts';\nimport type { ResolvedSuiNetwork } from './network-resolver.ts';\nimport type { SuiClient } from './mode/shared.ts';\nimport type { SuiOptions } from './mode/spec.ts';\nimport { bootLocalRpcMode } from './mode/external.ts';\nimport { bootForkMode } from './mode/fork.ts';\nimport { bootLiveMode } from './mode/live.ts';\nimport { bootLocalMode } from './mode/local.ts';\nimport type { ContainerRuntime } from '../../contracts/container-runtime.ts';\nimport type { Identity } from '../../substrate/identity.ts';\nimport type { StackPaths } from '../../substrate/runtime/paths.ts';\nimport type { PortBroker } from '../../substrate/runtime/port-broker/index.ts';\n\n/** Bundled result of one acquire — resolved metadata + the user-facing\n *  client. The barrel projects this into the Sui resource value; the\n *  resolved metadata feeds the Codegenable + NetworkResolver contributions. */\nexport interface SuiBootResult {\n\treadonly resolved: ResolvedSuiNetwork;\n\treadonly client: SuiClient;\n}\n\n/** Dispatch on the typed mode and return the mode's boot artifacts.\n *\n *  The `ContainerRuntime` is consumed by container-bearing modes\n *  only (local + fork); external + live get `null` and a typed\n *  refusal would surface if they tried to use it.\n *\n *  Stub: the per-mode builders are all stubs; the orchestrator\n *  here is the only fully-wired piece. */\nexport const bootSuiService = (\n\truntime: ContainerRuntime,\n\tidentity: Identity,\n\tportBroker: PortBroker,\n\tpaths: StackPaths,\n\topts: SuiOptions,\n): Effect.Effect<SuiBootResult, SuiPluginError | SeedManifestMismatchError, Scope.Scope> => {\n\tswitch (opts.mode) {\n\t\tcase 'local':\n\t\t\treturn bootLocalMode(runtime, identity, portBroker, opts).pipe(\n\t\t\t\tEffect.map(({ resolved, client }) => ({ resolved, client })),\n\t\t\t);\n\t\tcase 'local-rpc':\n\t\t\treturn bootLocalRpcMode(opts).pipe(\n\t\t\t\tEffect.map(({ resolved, client }) => ({ resolved, client })),\n\t\t\t);\n\t\tcase 'live':\n\t\t\treturn bootLiveMode(opts).pipe(Effect.map(({ resolved, client }) => ({ resolved, client })));\n\t\tcase 'fork':\n\t\t\treturn bootForkMode(runtime, identity, portBroker, paths, opts).pipe(\n\t\t\t\tEffect.map(({ resolved, client }) => ({ resolved, client })),\n\t\t\t);\n\t}\n};\n"],"mappings":";;;;;;;;;;;;;;AAqDA,MAAa,kBACZ,SACA,UACA,YACA,OACA,SAC2F;AAC3F,SAAQ,KAAK,MAAb;EACC,KAAK,QACJ,QAAO,cAAc,SAAS,UAAU,YAAY,KAAK,CAAC,KACzD,OAAO,KAAK,EAAE,UAAU,cAAc;GAAE;GAAU;GAAQ,EAAE,CAC5D;EACF,KAAK,YACJ,QAAO,iBAAiB,KAAK,CAAC,KAC7B,OAAO,KAAK,EAAE,UAAU,cAAc;GAAE;GAAU;GAAQ,EAAE,CAC5D;EACF,KAAK,OACJ,QAAO,aAAa,KAAK,CAAC,KAAK,OAAO,KAAK,EAAE,UAAU,cAAc;GAAE;GAAU;GAAQ,EAAE,CAAC;EAC7F,KAAK,OACJ,QAAO,aAAa,SAAS,UAAU,YAAY,OAAO,KAAK,CAAC,KAC/D,OAAO,KAAK,EAAE,UAAU,cAAc;GAAE;GAAU;GAAQ,EAAE,CAC5D"}

package/dist/plugins/sui/snapshot.mjs

@@ -0,0 +1,53 @@
+import { Effect } from "effect";
+//#region src/plugins/sui/snapshot.ts
+/** Build the Snapshotable contribution for a resolved mode + chain id.
+*
+*  Identity guard data lives in `preRestore`: the substrate compares
+*  the snapshot's stored chain identity against the resolver's
+*  current answer; a mismatch refuses BEFORE any destructive
+*  mutation. */
+const makeSnapshotable = (mode, app, stack, chain) => {
+	const labels = (role) => ({
+		app,
+		stack,
+		plugin: "sui",
+		role
+	});
+	switch (mode) {
+		case "local": return {
+			kind: "snapshotable",
+			subtrees: [],
+			managedContainers: [labels("validator"), labels("postgres")],
+			missingTolerance: "fine",
+			preRestore: Effect.succeed({
+				kind: "sui-chain",
+				chain
+			}),
+			postRestore: Effect.void
+		};
+		case "local-rpc":
+		case "live": return {
+			kind: "snapshotable",
+			subtrees: [],
+			missingTolerance: "fine",
+			preRestore: Effect.succeed({
+				kind: "sui-chain",
+				chain
+			})
+		};
+		case "fork": return {
+			kind: "snapshotable",
+			subtrees: ["sui-fork/"],
+			managedContainers: [labels("fork-validator")],
+			missingTolerance: "fine",
+			preRestore: Effect.succeed({
+				kind: "sui-chain",
+				chain
+			})
+		};
+	}
+};
+//#endregion
+export { makeSnapshotable };
+
+//# sourceMappingURL=snapshot.mjs.map

package/dist/plugins/sui/snapshot.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.mjs","names":[],"sources":["../../../src/plugins/sui/snapshot.ts"],"sourcesContent":["// Sui plugin — Snapshotable contribution.\n//\n// Architecture §3: the snapshot orchestrator captures and restores\n// without naming the plugin. Sui's contribution is mode-aware:\n//\n//   - local mode  — chain state (localnet validator) MUST live in\n//                   the writable container layer (NOT a named\n//                   volume), so `docker commit` captures it. Same\n//                   for the postgres indexer (PGDATA relocated off\n//                   the inherited VOLUME path).\n//\n//   - external    — no container, no snapshot. The `SnapshotableDecl`\n//                   has `missingTolerance: 'fine'` so restore against\n//                   a snapshot taken in local mode is a clean no-op.\n//\n//   - live        — same as external; no snapshot.\n//\n//   - fork        — data dir is a bind-mount; snapshot capture is\n//                   handled separately by the snapshot orchestrator.\n//                   This file emits the bind-mount subtree as the\n//                   capture descriptor.\n//\n// Chain identity (chainId + per-mode cluster id) is the canonical\n// identity-guard contribution from this plugin. The substrate's\n// pre-restore hook reads it; identity mismatch refuses the restore.\n\nimport { Effect } from 'effect';\n\nimport type { ContainerLabelTuple, SnapshotableDecl } from '../../contracts/snapshotable.ts';\nimport type { SuiPluginMode } from './mode/spec.ts';\n\n/** Build the Snapshotable contribution for a resolved mode + chain id.\n *\n *  Identity guard data lives in `preRestore`: the substrate compares\n *  the snapshot's stored chain identity against the resolver's\n *  current answer; a mismatch refuses BEFORE any destructive\n *  mutation. */\nexport const makeSnapshotable = (\n\tmode: SuiPluginMode,\n\tapp: string,\n\tstack: string,\n\tchain: string,\n): SnapshotableDecl => {\n\tconst labels = (role: string): ContainerLabelTuple => ({\n\t\tapp,\n\t\tstack,\n\t\tplugin: 'sui',\n\t\trole,\n\t});\n\n\tswitch (mode) {\n\t\tcase 'local': {\n\t\t\t// Validator's writable layer + postgres indexer's writable\n\t\t\t// layer. The runtime adapter pauses both before commit;\n\t\t\t// architecture default grace is \"pause container\".\n\t\t\treturn {\n\t\t\t\tkind: 'snapshotable',\n\t\t\t\t// Chain state lives in the writable container layer\n\t\t\t\t// — declared via `managedContainers`, not subtrees.\n\t\t\t\tsubtrees: [],\n\t\t\t\tmanagedContainers: [labels('validator'), labels('postgres')],\n\t\t\t\tmissingTolerance: 'fine',\n\t\t\t\tpreRestore: Effect.succeed({ kind: 'sui-chain', chain }),\n\t\t\t\tpostRestore: Effect.void,\n\t\t\t};\n\t\t}\n\t\tcase 'local-rpc':\n\t\tcase 'live': {\n\t\t\t// No container, no capture. The decl still exists so the\n\t\t\t// identity guard fires on restore (e.g. restoring a local\n\t\t\t// snapshot while the resolver says \"live testnet\" — the\n\t\t\t// identity-guard refuses).\n\t\t\treturn {\n\t\t\t\tkind: 'snapshotable',\n\t\t\t\tsubtrees: [],\n\t\t\t\tmissingTolerance: 'fine',\n\t\t\t\tpreRestore: Effect.succeed({ kind: 'sui-chain', chain }),\n\t\t\t};\n\t\t}\n\t\tcase 'fork': {\n\t\t\t// Data dir + meta are bind-mounted host paths; the\n\t\t\t// orchestrator walks the declared subtree. The fork\n\t\t\t// container itself is also captured (writable layer for\n\t\t\t// dep + cache state).\n\t\t\treturn {\n\t\t\t\tkind: 'snapshotable',\n\t\t\t\tsubtrees: ['sui-fork/'],\n\t\t\t\tmanagedContainers: [labels('fork-validator')],\n\t\t\t\tmissingTolerance: 'fine',\n\t\t\t\tpreRestore: Effect.succeed({ kind: 'sui-chain', chain }),\n\t\t\t};\n\t\t}\n\t}\n};\n"],"mappings":";;;;;;;;AAqCA,MAAa,oBACZ,MACA,KACA,OACA,UACsB;CACtB,MAAM,UAAU,UAAuC;EACtD;EACA;EACA,QAAQ;EACR;EACA;AAED,SAAQ,MAAR;EACC,KAAK,QAIJ,QAAO;GACN,MAAM;GAGN,UAAU,EAAE;GACZ,mBAAmB,CAAC,OAAO,YAAY,EAAE,OAAO,WAAW,CAAC;GAC5D,kBAAkB;GAClB,YAAY,OAAO,QAAQ;IAAE,MAAM;IAAa;IAAO,CAAC;GACxD,aAAa,OAAO;GACpB;EAEF,KAAK;EACL,KAAK,OAKJ,QAAO;GACN,MAAM;GACN,UAAU,EAAE;GACZ,kBAAkB;GAClB,YAAY,OAAO,QAAQ;IAAE,MAAM;IAAa;IAAO,CAAC;GACxD;EAEF,KAAK,OAKJ,QAAO;GACN,MAAM;GACN,UAAU,CAAC,YAAY;GACvB,mBAAmB,CAAC,OAAO,iBAAiB,CAAC;GAC7C,kBAAkB;GAClB,YAAY,OAAO,QAAQ;IAAE,MAAM;IAAa;IAAO,CAAC;GACxD"}

package/dist/plugins/wallet/codegen.d.mts

@@ -0,0 +1,33 @@
+//#region src/plugins/wallet/codegen.d.ts
+/** The typed shape `dapp-kit/config.ts` exports. Downstream consumers
+ *  (the user-app's dapp-kit boot code) import and consume this.
+ *
+ *  Field shape mirrors what `DevstackSignerAdapter` needs:
+ *
+ *    - `walletUrl`     : the wallet HTTP server's URL (router-fronted
+ *                        host form when available, direct-loopback
+ *                        fallback otherwise).
+ *    - `pairUrl`       : `walletUrl` + `/#token=<32-hex>` (single
+ *                        source of truth for the token).
+ *    - `protocolPaths` : path constants the adapter reads. Mirrored
+ *                        here so the adapter doesn't depend on a
+ *                        separate import.
+ *    - `chain`         : Sui chain id the wallet's accounts are
+ *                        scoped to. Surfaced so dapp-kit can pin its
+ *                        active chain.
+ */
+interface DappKitConfigBindings {
+  readonly walletUrl: string;
+  readonly pairUrl: string;
+  readonly chain: string;
+  readonly protocolPaths: {
+    readonly health: string;
+    readonly accounts: string;
+    readonly signTransaction: string;
+    readonly signPersonalMessage: string;
+    readonly execute: string;
+  };
+}
+//#endregion
+export { DappKitConfigBindings };
+//# sourceMappingURL=codegen.d.mts.map

package/dist/plugins/wallet/codegen.mjs

@@ -0,0 +1,34 @@
+import { redactToken } from "./pairing.mjs";
+import { Effect } from "effect";
+//#region src/plugins/wallet/codegen.ts
+/**
+* Construct the Codegenable contribution.
+*
+*  Emits `dapp-kit/config.ts` with `sensitive: true` → the orchestrator
+*  writes the file with `0o600` and gitignores it. The emitted shape
+*  carries the unredacted pair URL; the side-channel token file is
+*  also `0o600`.
+*
+*  The `resolved` arg is supplied AFTER acquire (the substrate's
+*  "resolve-once" memo). At factory time the barrel passes a
+*  placeholder so the type plumbing works; at codegen time the
+*  substrate re-evaluates with the resolved values.
+*/
+const makeWalletCodegen = (resolved) => ({
+	kind: "codegenable",
+	emitterName: "dapp-kit-config",
+	outputPath: "dapp-kit/config.ts",
+	sensitive: true,
+	emit: (ctx) => Effect.gen(function* () {
+		yield* Effect.annotateCurrentSpan({
+			"wallet.codegen.pairUrl": redactToken(resolved.pairUrl),
+			"wallet.codegen.walletUrl": resolved.walletUrl
+		});
+		ctx.exportConst("dappKitConfig", resolved);
+		return ctx.done();
+	})
+});
+//#endregion
+export { makeWalletCodegen };
+
+//# sourceMappingURL=codegen.mjs.map