@mysten-incubation/devstack 0.0.0

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

@@ -0,0 +1,60 @@
+import { suiPluginError } from "../errors.mjs";
+import { assembleSuiClient, buildWaitForTransactionsReady, fetchChainId, makeResolvedNetwork, noopWaitForTransactionsReady } from "./shared-boot.mjs";
+import { Duration, Effect } from "effect";
+import { SuiGrpcClient } from "@mysten/sui/grpc";
+//#region src/plugins/sui/mode/external.ts
+/** Default chain-id fetch timeout for caller-owned local RPCs. The wire
+*  latency is the dominant cost; 30s is the documented ceiling. */
+const DEFAULT_EXTERNAL_CHAIN_ID_TIMEOUT = Duration.seconds(30);
+/** Build the local-RPC-mode boot Effect. No container, no sidecar,
+*  no build image. Just probe chain id + wire `waitForTransactionsReady`
+*  conditional on `faucetUrl`. */
+const bootLocalRpcMode = (opts) => Effect.gen(function* () {
+	const sdkClient = yield* Effect.try({
+		try: () => new SuiGrpcClient({
+			baseUrl: opts.rpcUrl,
+			network: "localnet"
+		}),
+		catch: (cause) => suiPluginError("chain-id-fetch", `sui local-rpc mode: SuiGrpcClient construction failed for rpcUrl=${opts.rpcUrl}: ${stringifyCause(cause)}`, cause)
+	});
+	const chain = opts.chain ?? (yield* fetchChainId(sdkClient, {
+		timeout: opts.readyTimeout ?? DEFAULT_EXTERNAL_CHAIN_ID_TIMEOUT,
+		span: "devstack.plugin.sui.localRpc.fetchChainId"
+	}));
+	const waitForTransactionsReady = opts.faucetUrl !== void 0 ? yield* buildWaitForTransactionsReady(opts.faucetUrl) : noopWaitForTransactionsReady;
+	const { client } = assembleSuiClient({
+		sdkClient,
+		chain,
+		rpcUrl: opts.rpcUrl,
+		...opts.faucetUrl !== void 0 ? { faucetUrl: opts.faucetUrl } : {},
+		...opts.graphqlUrl !== void 0 ? { graphqlUrl: opts.graphqlUrl } : {},
+		waitForTransactionsReady
+	});
+	return {
+		resolved: makeResolvedNetwork({
+			mode: "local-rpc",
+			chain,
+			rpc: opts.rpcUrl,
+			source: "config",
+			...opts.faucetUrl !== void 0 ? { faucet: opts.faucetUrl } : {},
+			...opts.graphqlUrl !== void 0 ? { graphql: opts.graphqlUrl } : {}
+		}),
+		client
+	};
+}).pipe(Effect.withSpan("devstack.plugin.sui.localRpc.boot", { attributes: {
+	"devstack.plugin": "sui",
+	"sui.mode": "local-rpc"
+} }));
+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);
+	}
+};
+//#endregion
+export { bootLocalRpcMode };
+
+//# sourceMappingURL=external.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"external.mjs","names":[],"sources":["../../../../src/plugins/sui/mode/external.ts"],"sourcesContent":["// Sui plugin — local caller-owned RPC mode.\n//\n// Caller already has a Sui process running and supplies the RPC URL\n// (optionally faucet and GraphQL). Used in CI, custom-runtime\n// experiments, and \"wrap my own sui localnet\" scenarios.\n//\n// What's hard:\n//   - The entire container + sidecar + build-container pipeline\n//     must be skipped cleanly. No image build, no docker network,\n//     no SuiBuildImage wired in.\n//   - Downstream consumers must still get the same endpoint shape,\n//     the same chain id, and a working `waitForTransactionsReady`\n//     when a faucet URL is supplied.\n//   - The chain-id fetch IS the only readiness sentinel; must have\n//     a bounded timeout.\n//\n// Local-RPC mode contributes a `NetworkResolver` and a `ChainProbe`\n// but does NOT contribute a `Snapshotable`-managed container or a\n// `Routable` entrypoint (the caller's own router fronts the RPC).\n//\n// Boot sequence:\n//\n//   1. Construct an `@mysten/sui/grpc` `SuiGrpcClient` against the\n//      caller-supplied `rpcUrl`. `network: 'localnet'` is the\n//      semantically-correct discriminator — external IS a local-mode\n//      sub-shape, not a public-net target.\n//   2. Fetch the chain identifier with a bounded timeout — the only\n//      readiness sentinel for this mode.\n//   3. Build `waitForTransactionsReady`:\n//        - If `faucetUrl` is supplied, wire the real HTTP probe\n//          (same code path as local mode).\n//        - Otherwise, the gate is a trivially-succeeding no-op\n//          (callers that need funds must arrange them externally).\n//   4. Assemble the resolved `SuiClient` and return it alongside the\n//      `ResolvedSuiNetwork` projection (consumed by the codegen +\n//      network-resolver contributions at the barrel).\n\nimport { Duration, Effect, type Scope } from 'effect';\n\nimport { SuiGrpcClient } from '@mysten/sui/grpc';\n\nimport { suiPluginError, type SuiPluginError } from '../errors.ts';\nimport type { ResolvedSuiNetwork } from '../network-resolver.ts';\nimport type { SuiClient } from './shared.ts';\nimport {\n\tassembleSuiClient,\n\tbuildWaitForTransactionsReady,\n\tfetchChainId,\n\tmakeResolvedNetwork,\n\tnoopWaitForTransactionsReady,\n} from './shared-boot.ts';\nimport type { SuiLocalRpcOptions } from './spec.ts';\n\n/** Default chain-id fetch timeout for caller-owned local RPCs. The wire\n *  latency is the dominant cost; 30s is the documented ceiling. */\nexport const DEFAULT_EXTERNAL_CHAIN_ID_TIMEOUT = Duration.seconds(30);\n\n/** Resolved local-RPC-mode boot artifacts. */\nexport interface LocalRpcModeBootResult {\n\treadonly resolved: ResolvedSuiNetwork;\n\treadonly client: SuiClient;\n}\n\n/** Build the local-RPC-mode boot Effect. No container, no sidecar,\n *  no build image. Just probe chain id + wire `waitForTransactionsReady`\n *  conditional on `faucetUrl`. */\nexport const bootLocalRpcMode = (\n\topts: SuiLocalRpcOptions,\n): Effect.Effect<LocalRpcModeBootResult, SuiPluginError, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\t// ----- 1. Construct the grpc client ----------------------------------\n\t\t// `network: 'localnet'` is semantically correct: external is a\n\t\t// substrate-level `'local'` sub-mode (caller's own localnet); the\n\t\t// SDK uses `network` for MVR / wallet-standard hints which the\n\t\t// caller-provided RPC won't honor anyway.\n\t\tconst sdkClient = yield* Effect.try({\n\t\t\ttry: () =>\n\t\t\t\tnew SuiGrpcClient({\n\t\t\t\t\tbaseUrl: opts.rpcUrl,\n\t\t\t\t\tnetwork: 'localnet',\n\t\t\t\t}),\n\t\t\tcatch: (cause): SuiPluginError =>\n\t\t\t\tsuiPluginError(\n\t\t\t\t\t'chain-id-fetch',\n\t\t\t\t\t`sui local-rpc mode: SuiGrpcClient construction failed for rpcUrl=${opts.rpcUrl}: ${stringifyCause(cause)}`,\n\t\t\t\t\tcause,\n\t\t\t\t),\n\t\t});\n\n\t\t// ----- 2. Resolve chain id -------------------------------------------\n\t\tconst chain =\n\t\t\topts.chain ??\n\t\t\t(yield* fetchChainId(sdkClient, {\n\t\t\t\ttimeout: opts.readyTimeout ?? DEFAULT_EXTERNAL_CHAIN_ID_TIMEOUT,\n\t\t\t\tspan: 'devstack.plugin.sui.localRpc.fetchChainId',\n\t\t\t}));\n\n\t\t// ----- 3. Build waitForTransactionsReady -----------------------------\n\t\t// Faucet-bearing: real HTTP probe. Faucet-less: no-op (caller\n\t\t// must arrange funding out-of-band).\n\t\tconst waitForTransactionsReady =\n\t\t\topts.faucetUrl !== undefined\n\t\t\t\t? yield* buildWaitForTransactionsReady(opts.faucetUrl)\n\t\t\t\t: noopWaitForTransactionsReady;\n\n\t\t// ----- 4. Assemble + return ------------------------------------------\n\t\tconst { client } = assembleSuiClient({\n\t\t\tsdkClient,\n\t\t\tchain,\n\t\t\trpcUrl: opts.rpcUrl,\n\t\t\t...(opts.faucetUrl !== undefined ? { faucetUrl: opts.faucetUrl } : {}),\n\t\t\t...(opts.graphqlUrl !== undefined ? { graphqlUrl: opts.graphqlUrl } : {}),\n\t\t\twaitForTransactionsReady,\n\t\t});\n\t\tconst resolved = makeResolvedNetwork({\n\t\t\tmode: 'local-rpc',\n\t\t\tchain,\n\t\t\trpc: opts.rpcUrl,\n\t\t\tsource: 'config',\n\t\t\t...(opts.faucetUrl !== undefined ? { faucet: opts.faucetUrl } : {}),\n\t\t\t...(opts.graphqlUrl !== undefined ? { graphql: opts.graphqlUrl } : {}),\n\t\t});\n\n\t\treturn { resolved, client };\n\t}).pipe(\n\t\tEffect.withSpan('devstack.plugin.sui.localRpc.boot', {\n\t\t\tattributes: { 'devstack.plugin': 'sui', 'sui.mode': 'local-rpc' },\n\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":";;;;;;;AAuDA,MAAa,oCAAoC,SAAS,QAAQ,GAAG;;;;AAWrE,MAAa,oBACZ,SAEA,OAAO,IAAI,aAAa;CAMvB,MAAM,YAAY,OAAO,OAAO,IAAI;EACnC,WACC,IAAI,cAAc;GACjB,SAAS,KAAK;GACd,SAAS;GACT,CAAC;EACH,QAAQ,UACP,eACC,kBACA,oEAAoE,KAAK,OAAO,IAAI,eAAe,MAAM,IACzG,MACA;EACF,CAAC;CAGF,MAAM,QACL,KAAK,UACJ,OAAO,aAAa,WAAW;EAC/B,SAAS,KAAK,gBAAgB;EAC9B,MAAM;EACN,CAAC;CAKH,MAAM,2BACL,KAAK,cAAc,KAAA,IAChB,OAAO,8BAA8B,KAAK,UAAU,GACpD;CAGJ,MAAM,EAAE,WAAW,kBAAkB;EACpC;EACA;EACA,QAAQ,KAAK;EACb,GAAI,KAAK,cAAc,KAAA,IAAY,EAAE,WAAW,KAAK,WAAW,GAAG,EAAE;EACrE,GAAI,KAAK,eAAe,KAAA,IAAY,EAAE,YAAY,KAAK,YAAY,GAAG,EAAE;EACxE;EACA,CAAC;AAUF,QAAO;EAAE,UATQ,oBAAoB;GACpC,MAAM;GACN;GACA,KAAK,KAAK;GACV,QAAQ;GACR,GAAI,KAAK,cAAc,KAAA,IAAY,EAAE,QAAQ,KAAK,WAAW,GAAG,EAAE;GAClE,GAAI,KAAK,eAAe,KAAA,IAAY,EAAE,SAAS,KAAK,YAAY,GAAG,EAAE;GACrE,CAEgB;EAAE;EAAQ;EAC1B,CAAC,KACF,OAAO,SAAS,qCAAqC,EACpD,YAAY;CAAE,mBAAmB;CAAO,YAAY;CAAa,EACjE,CAAC,CACF;AAEF,MAAM,kBAAkB,UAA2B;AAClD,KAAI,iBAAiB,MAAO,QAAO,MAAM;AACzC,KAAI,OAAO,UAAU,SAAU,QAAO;AACtC,KAAI;AACH,SAAO,KAAK,UAAU,MAAM;SACrB;AACP,SAAO,OAAO,MAAM"}

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

@@ -0,0 +1,283 @@
+import { renderUrl, routerHostname } from "../../../orchestrators/router/hostname.mjs";
+import { ProbeTimeoutError, waitForProbe } from "../../../substrate/runtime/probes.mjs";
+import { suiPluginError } from "../errors.mjs";
+import { toDockerHostGatewayUrl } from "./shared.mjs";
+import { assembleSuiClient, fetchChainId, makeResolvedNetwork, noopWaitForTransactionsReady } from "./shared-boot.mjs";
+import { ensureManagedContainer } from "../../../substrate/runtime/managed-container.mjs";
+import { resolveAutoTickIntervalMs, runAutoTickClock } from "../auto-tick.mjs";
+import { SUI_RPC_ENTRYPOINT_PORT } from "../routable.mjs";
+import { wrapWithForkGuard } from "../fork-orchestration.mjs";
+import { verifyForkImpersonationSender } from "../fork-transaction.mjs";
+import { DEFAULT_SUI_CLI_VERSION } from "../../../substrate/runtime/sui-move-build/index.mjs";
+import { Duration, Effect } from "effect";
+import { createHash } from "node:crypto";
+import { join, resolve } from "node:path";
+import { SuiGrpcClient } from "@mysten/sui/grpc";
+import { mkdir } from "node:fs/promises";
+import { normalizeSuiAddress, normalizeSuiObjectId } from "@mysten/sui/utils";
+//#region src/plugins/sui/mode/fork.ts
+/** Default ready-probe timeout for fork-mode cold start. */
+const DEFAULT_FORK_READY_TIMEOUT = Duration.seconds(180);
+/** Default Sui repository revision used by the bundled `sui-fork` image build. */
+const DEFAULT_SUI_FORK_REV = "62ee6ada958cd61b3c8a4466dd33c9aba3cdff8a";
+const DEFAULT_FORK_HOST_RPC_PORT = 51002;
+const DOCKER_PUBLISH_HOST = "0.0.0.0";
+const CONTAINER_RPC_PORT = SUI_RPC_ENTRYPOINT_PORT;
+const FORK_CONTAINER_DATA_DIR = "/var/lib/sui-fork";
+const PROBE_ATTEMPT_TIMEOUT_MS = 3e3;
+const bootForkMode = (runtime, identity, portBroker, paths, opts) => Effect.gen(function* () {
+	const autoTickIntervalMs = resolveAutoTickIntervalMs(opts.autoTick);
+	const image = yield* resolveForkImage(runtime, opts);
+	const dataDir = yield* ensureForkDataDir(paths, opts);
+	const { handle, ports } = yield* ensureForkContainer({
+		runtime,
+		portBroker,
+		image,
+		labels: {
+			app: identity.app,
+			stack: identity.stack,
+			plugin: "sui",
+			role: "fork-validator"
+		},
+		containerName: `devstack-${identity.app}-${identity.stack}-sui-fork`,
+		dataDir,
+		opts
+	});
+	const directRpcUrl = `http://127.0.0.1:${pickPublishedPort(ports, handle.ports).hostPort}`;
+	const rpcUrl = yield* routedSuiRpcUrl(identity);
+	const sdkClient = new SuiGrpcClient({
+		baseUrl: directRpcUrl,
+		network: opts.upstream
+	});
+	const status = yield* waitForForkReady(sdkClient, opts.readyTimeout ?? DEFAULT_FORK_READY_TIMEOUT).pipe(Effect.annotateLogs({ "sui.container": handle.name }));
+	const chain = yield* fetchChainId(sdkClient, { span: "devstack.plugin.sui.fork.fetchChainId" });
+	const fork = makeForkAdminSurface(sdkClient);
+	const assembled = assembleSuiClient({
+		sdkClient,
+		chain,
+		rpcUrl,
+		waitForTransactionsReady: noopWaitForTransactionsReady,
+		buildImage: image,
+		hostGateway: {
+			rpcUrl: toDockerHostGatewayUrl(directRpcUrl),
+			faucetUrl: null,
+			graphqlUrl: null
+		}
+	});
+	const client = {
+		...assembled.client,
+		sdk: wrapWithForkGuard(assembled.sdkShim),
+		fork
+	};
+	if (autoTickIntervalMs !== void 0) yield* runAutoTickClock(fork, autoTickIntervalMs);
+	return {
+		resolved: makeResolvedNetwork({
+			mode: "fork",
+			chain,
+			rpc: rpcUrl,
+			source: "default",
+			checkpoint: status.forkedAtCheckpoint,
+			forkUpstream: opts.upstream
+		}),
+		client,
+		autoTickIntervalMs
+	};
+}).pipe(Effect.withSpan("devstack.plugin.sui.fork.boot", { attributes: { "devstack.plugin": "sui" } }));
+const suiForkImageBuildContext = (rev = DEFAULT_SUI_FORK_REV) => ({
+	contextPath: new URL("../../../../images/", import.meta.url).pathname,
+	dockerfile: "sui-fork/Dockerfile",
+	buildArgs: {
+		SUI_FORK_REV: rev,
+		SUI_CLI_VERSION: DEFAULT_SUI_CLI_VERSION
+	}
+});
+const resolveForkImage = (runtime, opts) => Effect.gen(function* () {
+	if (opts.image && "pull" in opts.image) {
+		const pullRef = opts.image.pull;
+		if (runtime.pullImage === void 0) return yield* Effect.fail(suiPluginError("image-build", `sui fork mode cannot pull image '${pullRef}' because the configured container runtime does not expose image pulls.`));
+		return yield* runtime.pullImage(pullRef).pipe(Effect.mapError((cause) => suiPluginError("image-build", `sui fork mode failed to pull image '${pullRef}': ${cause.reason}: ${cause.detail}`, cause)));
+	}
+	const rev = opts.version ?? "62ee6ada958cd61b3c8a4466dd33c9aba3cdff8a";
+	const buildCtx = opts.image && "build" in opts.image ? {
+		contextPath: opts.image.build.context,
+		dockerfile: opts.image.build.dockerfile ?? "Dockerfile",
+		buildArgs: {
+			SUI_FORK_REV: rev,
+			SUI_CLI_VERSION: DEFAULT_SUI_CLI_VERSION
+		}
+	} : suiForkImageBuildContext(rev);
+	return yield* runtime.ensureImage(buildCtx).pipe(Effect.mapError((cause) => suiPluginError("image-build", `sui fork image build failed: ${cause.reason}: ${cause.detail}`, cause)));
+}).pipe(Effect.withSpan("devstack.plugin.sui.fork.resolveImage"));
+const ensureForkContainer = (params) => Effect.gen(function* () {
+	const reusable = params.opts.ports === void 0 ? yield* findReusableForkPort(params.runtime, params.labels, params.containerName) : void 0;
+	const ports = reusable === void 0 ? [yield* allocateForkRpcPort(params.portBroker, params.opts.ports)] : [reusable];
+	const reconciliation = reusable === void 0 && params.opts.ports !== void 0 ? "exact" : "adopt-existing";
+	const command = forkStartCommand(params.opts);
+	return {
+		handle: yield* ensureManagedContainer({
+			runtime: params.runtime,
+			labels: params.labels,
+			spec: {
+				name: params.containerName,
+				image: params.image,
+				recreate: "on-config-change",
+				configHash: forkContainerConfigHash(params.opts, params.dataDir, command),
+				stopGraceSeconds: 30,
+				ports,
+				portBindingReconciliation: reconciliation,
+				mounts: [{
+					source: params.dataDir,
+					target: FORK_CONTAINER_DATA_DIR
+				}],
+				command
+			},
+			mapError: (cause) => cause
+		}).pipe(Effect.mapError((cause) => suiPluginError("container-start", `sui-fork container failed: ${cause.reason}: ${cause.detail}`, cause))),
+		ports
+	};
+});
+const forkStartCommand = (opts) => {
+	const seed = normalizeForkSeed(opts);
+	const command = [
+		"start",
+		"--network",
+		opts.upstream,
+		"--data-dir",
+		FORK_CONTAINER_DATA_DIR,
+		"--rpc-addr",
+		`0.0.0.0:${CONTAINER_RPC_PORT}`
+	];
+	if (opts.checkpoint !== void 0) command.push("--checkpoint", String(opts.checkpoint));
+	for (const address of seed.addresses) command.push("--address", address);
+	for (const objectId of seed.objects) command.push("--object", objectId);
+	return command;
+};
+const normalizeForkSeed = (opts) => ({
+	addresses: [...new Set((opts.seed?.addresses ?? []).map((address) => normalizeSuiAddress(address)))].sort(),
+	objects: [...new Set((opts.seed?.objects ?? []).map((objectId) => normalizeSuiObjectId(objectId)))].sort()
+});
+const forkContainerConfigHash = (opts, dataDir, command) => createHash("sha256").update(JSON.stringify({
+	dataDir,
+	command,
+	version: opts.version ?? "62ee6ada958cd61b3c8a4466dd33c9aba3cdff8a",
+	ports: opts.ports ?? null
+})).digest("hex");
+const allocateForkRpcPort = (portBroker, override) => {
+	const overridePort = override?.[CONTAINER_RPC_PORT];
+	if (overridePort !== void 0) return Effect.succeed(portPublish(CONTAINER_RPC_PORT, overridePort));
+	return portBroker.allocate({
+		kind: "rpc",
+		preferredPort: DEFAULT_FORK_HOST_RPC_PORT,
+		probeHost: DOCKER_PUBLISH_HOST
+	}).pipe(Effect.catchTag("PortBrokerError", (cause) => cause.reason === "preferred-busy" ? portBroker.allocate({
+		kind: "rpc",
+		probeHost: DOCKER_PUBLISH_HOST
+	}) : Effect.fail(cause)), Effect.map((allocated) => portPublish(CONTAINER_RPC_PORT, allocated.port)), Effect.mapError((cause) => suiPluginError("port-allocate", `sui fork mode: failed to allocate RPC host port: ${cause.detail}`, cause)));
+};
+const findReusableForkPort = (runtime, labels, containerName) => runtime.inspectByLabels(labels).pipe(Effect.map((handles) => handles.find((handle) => handle.name === containerName)?.ports?.find((port) => port.containerPort === CONTAINER_RPC_PORT)), Effect.mapError((cause) => suiPluginError("container-start", `sui fork mode: failed to inspect existing fork container: ${cause.reason}: ${cause.detail}`, cause)));
+const pickPublishedPort = (requested, actual) => actual?.find((port) => port.containerPort === CONTAINER_RPC_PORT) ?? requested.find((port) => port.containerPort === CONTAINER_RPC_PORT) ?? portPublish(CONTAINER_RPC_PORT, 51002);
+const portPublish = (containerPort, hostPort) => ({
+	containerPort,
+	hostPort,
+	hostIp: DOCKER_PUBLISH_HOST
+});
+const forkDataDirKey = (opts) => createHash("sha256").update(JSON.stringify({
+	upstream: opts.upstream,
+	checkpoint: opts.checkpoint ?? null,
+	version: opts.version ?? "62ee6ada958cd61b3c8a4466dd33c9aba3cdff8a",
+	seed: normalizeForkSeed(opts)
+})).digest("hex").slice(0, 16);
+const ensureForkDataDir = (paths, opts) => {
+	const dataDir = resolve(join(paths.stackRoot, "sui-fork", forkDataDirKey(opts)));
+	return Effect.tryPromise({
+		try: async () => {
+			await mkdir(dataDir, {
+				recursive: true,
+				mode: 448
+			});
+			return dataDir;
+		},
+		catch: (cause) => suiPluginError("fork-data-dir", `sui fork mode: failed to create data directory ${dataDir}: ${stringifyCause(cause)}`, cause)
+	});
+};
+const waitForForkReady = (sdkClient, readyTimeout) => Effect.gen(function* () {
+	const readyTimeoutMs = Duration.toMillis(readyTimeout);
+	yield* waitForProbe({
+		label: "sui.fork.rpc",
+		timeoutMs: readyTimeoutMs,
+		intervalMs: 1e3,
+		attemptTimeoutMs: PROBE_ATTEMPT_TIMEOUT_MS,
+		probe: () => readForkStatus(sdkClient).pipe(Effect.as(true))
+	}).pipe(Effect.mapError((cause) => cause instanceof ProbeTimeoutError ? suiPluginError("fork-status-probe", `sui fork mode: ForkingService.GetStatus did not become ready within ${readyTimeoutMs}ms.`, cause.lastError ?? cause.lastNotReady ?? cause) : suiPluginError("fork-status-probe", `sui fork mode: ForkingService.GetStatus probe failed: ${stringifyCause(cause)}`, cause)));
+	return yield* readForkStatus(sdkClient);
+}).pipe(Effect.withSpan("devstack.plugin.sui.fork.waitForReady"));
+const makeForkAdminSurface = (sdkClient) => ({
+	status: readForkStatus(sdkClient).pipe(Effect.map(({ checkpoint, clock }) => ({
+		checkpoint,
+		clock
+	}))),
+	advanceClock: (intervalMs) => Effect.tryPromise({
+		try: () => sdkClient.forkingService.advanceClock({ durationMs: BigInt(intervalMs) }).response,
+		catch: (cause) => suiPluginError("fork-advance-clock", `sui fork mode: advanceClock(${intervalMs}) failed: ${stringifyCause(cause)}`, cause)
+	}).pipe(Effect.asVoid),
+	advanceCheckpoint: Effect.tryPromise({
+		try: () => sdkClient.forkingService.advanceCheckpoint({}).response,
+		catch: (cause) => suiPluginError("fork-advance-checkpoint", `sui fork mode: advanceCheckpoint failed: ${stringifyCause(cause)}`, cause)
+	}).pipe(Effect.asVoid),
+	impersonate: (sender, tx) => Effect.gen(function* () {
+		if (!(tx instanceof Uint8Array)) return yield* Effect.fail(suiPluginError("fork-impersonate", `sui fork mode: impersonate(${sender}) expected serialized transaction bytes.`));
+		yield* verifyForkImpersonationSender(sender, tx);
+		const raw = yield* Effect.tryPromise({
+			try: () => sdkClient.executeTransaction({
+				transaction: tx,
+				signatures: [],
+				include: {
+					effects: true,
+					objectTypes: true
+				}
+			}),
+			catch: (cause) => suiPluginError("fork-impersonate", `sui fork mode: impersonate(${sender}) failed: ${stringifyCause(cause)}`, cause)
+		});
+		const digest = extractExecuteDigest(raw);
+		if (digest === void 0) return yield* Effect.fail(suiPluginError("fork-impersonate", `sui fork mode: impersonate(${sender}) returned no transaction digest.`, raw));
+		return {
+			digest,
+			success: !isFailedTransaction(raw),
+			raw
+		};
+	})
+});
+const readForkStatus = (sdkClient) => Effect.tryPromise({
+	try: async () => {
+		const response = await sdkClient.forkingService.getStatus({}).response;
+		return {
+			checkpoint: response.checkpointSequenceNumber.toString(),
+			clock: Number(response.timestampMs),
+			forkedAtCheckpoint: response.forkedAtCheckpoint.toString()
+		};
+	},
+	catch: (cause) => suiPluginError("fork-status-probe", `sui fork mode: GetStatus failed: ${stringifyCause(cause)}`, cause)
+});
+const routedSuiRpcUrl = (identity) => routerHostname(identity, "rpc").pipe(Effect.map((hostname) => renderUrl({
+	protocol: "http",
+	hostname,
+	port: SUI_RPC_ENTRYPOINT_PORT
+})), Effect.mapError((cause) => suiPluginError("container-start", `sui fork mode: failed to construct router RPC URL: ${cause.detail}`, cause)));
+const extractExecuteDigest = (raw) => {
+	const env = raw;
+	return env.$kind === "FailedTransaction" ? env.FailedTransaction?.digest : env.Transaction?.digest;
+};
+const isFailedTransaction = (raw) => raw.$kind === "FailedTransaction";
+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);
+	}
+};
+//#endregion
+export { bootForkMode };
+
+//# sourceMappingURL=fork.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fork.mjs","names":["sharedFetchChainId"],"sources":["../../../../src/plugins/sui/mode/fork.ts"],"sourcesContent":["// Sui plugin — fork mode.\n\nimport { createHash } from 'node:crypto';\nimport { mkdir } from 'node:fs/promises';\nimport { join, resolve } from 'node:path';\n\nimport { Duration, Effect, type Scope } from 'effect';\n\nimport { SuiGrpcClient } from '@mysten/sui/grpc';\nimport { normalizeSuiAddress, normalizeSuiObjectId } from '@mysten/sui/utils';\n\nimport type {\n\tContainerHandle,\n\tContainerPortPublish,\n\tContainerRuntime,\n\tContainerRuntimeError,\n\tImageRef,\n\tPortBindingReconciliation,\n} from '../../../contracts/container-runtime.ts';\nimport type { ContainerLabelTuple } from '../../../contracts/snapshotable.ts';\nimport type { Identity } from '../../../substrate/identity.ts';\nimport { ensureManagedContainer } from '../../../substrate/runtime/managed-container.ts';\nimport type { StackPaths } from '../../../substrate/runtime/paths.ts';\nimport type { AllocatedPort, PortBroker } from '../../../substrate/runtime/port-broker/index.ts';\nimport { ProbeTimeoutError, waitForProbe } from '../../../substrate/runtime/probes.ts';\nimport { renderUrl, routerHostname } from '../../../orchestrators/router/hostname.ts';\nimport { resolveAutoTickIntervalMs, runAutoTickClock } from '../auto-tick.ts';\nimport { suiPluginError, type SeedManifestMismatchError, type SuiPluginError } from '../errors.ts';\nimport type { ResolvedSuiNetwork } from '../network-resolver.ts';\nimport { SUI_RPC_ENDPOINT_NAME, SUI_RPC_ENTRYPOINT_PORT } from '../routable.ts';\nimport { wrapWithForkGuard } from '../fork-orchestration.ts';\nimport { verifyForkImpersonationSender } from '../fork-transaction.ts';\nimport { DEFAULT_SUI_CLI_VERSION } from '../../../substrate/runtime/sui-move-build/index.ts';\nimport type { ForkAdminSurface, SuiClient } from './shared.ts';\nimport { toDockerHostGatewayUrl } from './shared.ts';\nimport {\n\tassembleSuiClient,\n\tfetchChainId as sharedFetchChainId,\n\tmakeResolvedNetwork,\n\tnoopWaitForTransactionsReady,\n} from './shared-boot.ts';\nimport type { SuiForkOptions } from './spec.ts';\n\n/** Default ready-probe timeout for fork-mode cold start. */\nexport const DEFAULT_FORK_READY_TIMEOUT = Duration.seconds(180);\n\n/** Default Sui repository revision used by the bundled `sui-fork` image build. */\nexport const DEFAULT_SUI_FORK_REV = '62ee6ada958cd61b3c8a4466dd33c9aba3cdff8a';\n\n/** Map upstream literal to the canonical \"live\" chain id known by wallet-standard / MVR. */\nexport const FORK_UPSTREAM_TO_KNOWN_NETWORK = {\n\tmainnet: 'sui:mainnet',\n\ttestnet: 'sui:testnet',\n\tdevnet: 'sui:devnet',\n} as const;\n\nexport const DEFAULT_FORK_HOST_RPC_PORT = 51002;\nexport const FORK_VALIDATOR_STOP_GRACE_SECONDS = 30;\n\nconst DOCKER_PUBLISH_HOST = '0.0.0.0' as const;\nconst CONTAINER_RPC_PORT = SUI_RPC_ENTRYPOINT_PORT;\nconst FORK_CONTAINER_DATA_DIR = '/var/lib/sui-fork';\nconst PROBE_ATTEMPT_TIMEOUT_MS = 3_000;\n\n/** Resolved fork-mode boot artifacts. */\nexport interface ForkModeBootResult {\n\treadonly resolved: ResolvedSuiNetwork;\n\treadonly client: SuiClient;\n\treadonly autoTickIntervalMs: number | undefined;\n}\n\nexport const bootForkMode = (\n\truntime: ContainerRuntime,\n\tidentity: Identity,\n\tportBroker: PortBroker,\n\tpaths: StackPaths,\n\topts: SuiForkOptions,\n): Effect.Effect<ForkModeBootResult, SuiPluginError | SeedManifestMismatchError, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\tconst autoTickIntervalMs = resolveAutoTickIntervalMs(opts.autoTick);\n\t\tconst image = yield* resolveForkImage(runtime, opts);\n\t\tconst dataDir = yield* ensureForkDataDir(paths, opts);\n\n\t\tconst labels: ContainerLabelTuple = {\n\t\t\tapp: identity.app,\n\t\t\tstack: identity.stack,\n\t\t\tplugin: 'sui',\n\t\t\trole: 'fork-validator',\n\t\t};\n\t\tconst containerName = `devstack-${identity.app}-${identity.stack}-sui-fork`;\n\t\tconst { handle, ports } = yield* ensureForkContainer({\n\t\t\truntime,\n\t\t\tportBroker,\n\t\t\timage,\n\t\t\tlabels,\n\t\t\tcontainerName,\n\t\t\tdataDir,\n\t\t\topts,\n\t\t});\n\n\t\tconst published = pickPublishedPort(ports, handle.ports);\n\t\tconst directRpcUrl = `http://127.0.0.1:${published.hostPort}`;\n\t\tconst rpcUrl = yield* routedSuiRpcUrl(identity);\n\t\tconst sdkClient = new SuiGrpcClient({ baseUrl: directRpcUrl, network: opts.upstream });\n\t\tconst readyTimeout = opts.readyTimeout ?? DEFAULT_FORK_READY_TIMEOUT;\n\n\t\tconst status = yield* waitForForkReady(sdkClient, readyTimeout).pipe(\n\t\t\tEffect.annotateLogs({ 'sui.container': handle.name }),\n\t\t);\n\t\tconst chain = yield* sharedFetchChainId(sdkClient, {\n\t\t\tspan: 'devstack.plugin.sui.fork.fetchChainId',\n\t\t});\n\n\t\tconst fork = makeForkAdminSurface(sdkClient);\n\t\tconst assembled = assembleSuiClient({\n\t\t\tsdkClient,\n\t\t\tchain,\n\t\t\trpcUrl,\n\t\t\twaitForTransactionsReady: noopWaitForTransactionsReady,\n\t\t\tbuildImage: image,\n\t\t\thostGateway: {\n\t\t\t\trpcUrl: toDockerHostGatewayUrl(directRpcUrl),\n\t\t\t\tfaucetUrl: null,\n\t\t\t\tgraphqlUrl: null,\n\t\t\t},\n\t\t});\n\t\tconst client: SuiClient = {\n\t\t\t...assembled.client,\n\t\t\tsdk: wrapWithForkGuard(assembled.sdkShim),\n\t\t\tfork,\n\t\t};\n\n\t\tif (autoTickIntervalMs !== undefined) {\n\t\t\tyield* runAutoTickClock(fork, autoTickIntervalMs);\n\t\t}\n\n\t\treturn {\n\t\t\tresolved: makeResolvedNetwork({\n\t\t\t\tmode: 'fork',\n\t\t\t\tchain,\n\t\t\t\trpc: rpcUrl,\n\t\t\t\tsource: 'default',\n\t\t\t\tcheckpoint: status.forkedAtCheckpoint,\n\t\t\t\tforkUpstream: opts.upstream,\n\t\t\t}),\n\t\t\tclient,\n\t\t\tautoTickIntervalMs,\n\t\t};\n\t}).pipe(\n\t\tEffect.withSpan('devstack.plugin.sui.fork.boot', { attributes: { 'devstack.plugin': 'sui' } }),\n\t);\n\nexport const suiForkImageBuildContext = (rev = DEFAULT_SUI_FORK_REV) => ({\n\tcontextPath: new URL('../../../../images/', import.meta.url).pathname,\n\tdockerfile: 'sui-fork/Dockerfile',\n\tbuildArgs: { SUI_FORK_REV: rev, SUI_CLI_VERSION: DEFAULT_SUI_CLI_VERSION },\n});\n\nexport const resolveForkImage = (\n\truntime: ContainerRuntime,\n\topts: SuiForkOptions,\n): Effect.Effect<ImageRef, SuiPluginError> =>\n\tEffect.gen(function* () {\n\t\tif (opts.image && 'pull' in opts.image) {\n\t\t\tconst pullRef = opts.image.pull;\n\t\t\tif (runtime.pullImage === undefined) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tsuiPluginError(\n\t\t\t\t\t\t'image-build',\n\t\t\t\t\t\t`sui fork mode cannot pull image '${pullRef}' because the configured container runtime does not expose image pulls.`,\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn yield* runtime\n\t\t\t\t.pullImage(pullRef)\n\t\t\t\t.pipe(\n\t\t\t\t\tEffect.mapError((cause) =>\n\t\t\t\t\t\tsuiPluginError(\n\t\t\t\t\t\t\t'image-build',\n\t\t\t\t\t\t\t`sui fork mode failed to pull image '${pullRef}': ${cause.reason}: ${cause.detail}`,\n\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t),\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t}\n\t\tconst rev = opts.version ?? DEFAULT_SUI_FORK_REV;\n\t\tconst buildCtx =\n\t\t\topts.image && 'build' in opts.image\n\t\t\t\t? {\n\t\t\t\t\t\tcontextPath: opts.image.build.context,\n\t\t\t\t\t\tdockerfile: opts.image.build.dockerfile ?? 'Dockerfile',\n\t\t\t\t\t\tbuildArgs: { SUI_FORK_REV: rev, SUI_CLI_VERSION: DEFAULT_SUI_CLI_VERSION },\n\t\t\t\t\t}\n\t\t\t\t: suiForkImageBuildContext(rev);\n\t\treturn yield* runtime\n\t\t\t.ensureImage(buildCtx)\n\t\t\t.pipe(\n\t\t\t\tEffect.mapError((cause) =>\n\t\t\t\t\tsuiPluginError(\n\t\t\t\t\t\t'image-build',\n\t\t\t\t\t\t`sui fork image build failed: ${cause.reason}: ${cause.detail}`,\n\t\t\t\t\t\tcause,\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t);\n\t}).pipe(Effect.withSpan('devstack.plugin.sui.fork.resolveImage'));\n\ninterface ForkContainerResult {\n\treadonly handle: ContainerHandle;\n\treadonly ports: ReadonlyArray<ContainerPortPublish>;\n}\n\nconst ensureForkContainer = (params: {\n\treadonly runtime: ContainerRuntime;\n\treadonly portBroker: PortBroker;\n\treadonly image: ImageRef;\n\treadonly labels: ContainerLabelTuple;\n\treadonly containerName: string;\n\treadonly dataDir: string;\n\treadonly opts: SuiForkOptions;\n}): Effect.Effect<ForkContainerResult, SuiPluginError, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\tconst reusable =\n\t\t\tparams.opts.ports === undefined\n\t\t\t\t? yield* findReusableForkPort(params.runtime, params.labels, params.containerName)\n\t\t\t\t: undefined;\n\t\tconst ports =\n\t\t\treusable === undefined\n\t\t\t\t? [yield* allocateForkRpcPort(params.portBroker, params.opts.ports)]\n\t\t\t\t: [reusable];\n\t\tconst reconciliation: PortBindingReconciliation =\n\t\t\treusable === undefined && params.opts.ports !== undefined ? 'exact' : 'adopt-existing';\n\t\tconst command = forkStartCommand(params.opts);\n\t\tconst handle = yield* ensureManagedContainer({\n\t\t\truntime: params.runtime,\n\t\t\tlabels: params.labels,\n\t\t\tspec: {\n\t\t\t\tname: params.containerName,\n\t\t\t\timage: params.image,\n\t\t\t\trecreate: 'on-config-change',\n\t\t\t\tconfigHash: forkContainerConfigHash(params.opts, params.dataDir, command),\n\t\t\t\tstopGraceSeconds: FORK_VALIDATOR_STOP_GRACE_SECONDS,\n\t\t\t\tports,\n\t\t\t\tportBindingReconciliation: reconciliation,\n\t\t\t\tmounts: [{ source: params.dataDir, target: FORK_CONTAINER_DATA_DIR }],\n\t\t\t\tcommand,\n\t\t\t},\n\t\t\tmapError: (cause) => cause,\n\t\t}).pipe(\n\t\t\tEffect.mapError((cause: ContainerRuntimeError) =>\n\t\t\t\tsuiPluginError(\n\t\t\t\t\t'container-start',\n\t\t\t\t\t`sui-fork container failed: ${cause.reason}: ${cause.detail}`,\n\t\t\t\t\tcause,\n\t\t\t\t),\n\t\t\t),\n\t\t);\n\t\treturn { handle, ports };\n\t});\n\nexport const forkStartCommand = (opts: SuiForkOptions): ReadonlyArray<string> => {\n\tconst seed = normalizeForkSeed(opts);\n\tconst command = [\n\t\t'start',\n\t\t'--network',\n\t\topts.upstream,\n\t\t'--data-dir',\n\t\tFORK_CONTAINER_DATA_DIR,\n\t\t'--rpc-addr',\n\t\t`0.0.0.0:${CONTAINER_RPC_PORT}`,\n\t];\n\tif (opts.checkpoint !== undefined) {\n\t\tcommand.push('--checkpoint', String(opts.checkpoint));\n\t}\n\tfor (const address of seed.addresses) {\n\t\tcommand.push('--address', address);\n\t}\n\tfor (const objectId of seed.objects) {\n\t\tcommand.push('--object', objectId);\n\t}\n\treturn command;\n};\n\nconst normalizeForkSeed = (opts: SuiForkOptions) => ({\n\taddresses: [\n\t\t...new Set((opts.seed?.addresses ?? []).map((address) => normalizeSuiAddress(address))),\n\t].sort(),\n\tobjects: [\n\t\t...new Set((opts.seed?.objects ?? []).map((objectId) => normalizeSuiObjectId(objectId))),\n\t].sort(),\n});\n\nconst forkContainerConfigHash = (\n\topts: SuiForkOptions,\n\tdataDir: string,\n\tcommand: ReadonlyArray<string>,\n): string =>\n\tcreateHash('sha256')\n\t\t.update(\n\t\t\tJSON.stringify({\n\t\t\t\tdataDir,\n\t\t\t\tcommand,\n\t\t\t\tversion: opts.version ?? DEFAULT_SUI_FORK_REV,\n\t\t\t\tports: opts.ports ?? null,\n\t\t\t}),\n\t\t)\n\t\t.digest('hex');\n\nconst allocateForkRpcPort = (\n\tportBroker: PortBroker,\n\toverride: Readonly<Record<number, number>> | undefined,\n): Effect.Effect<ContainerPortPublish, SuiPluginError, Scope.Scope> => {\n\tconst overridePort = override?.[CONTAINER_RPC_PORT];\n\tif (overridePort !== undefined) {\n\t\treturn Effect.succeed(portPublish(CONTAINER_RPC_PORT, overridePort));\n\t}\n\treturn portBroker\n\t\t.allocate({\n\t\t\tkind: 'rpc',\n\t\t\tpreferredPort: DEFAULT_FORK_HOST_RPC_PORT,\n\t\t\tprobeHost: DOCKER_PUBLISH_HOST,\n\t\t})\n\t\t.pipe(\n\t\t\tEffect.catchTag('PortBrokerError', (cause) =>\n\t\t\t\tcause.reason === 'preferred-busy'\n\t\t\t\t\t? portBroker.allocate({ kind: 'rpc', probeHost: DOCKER_PUBLISH_HOST })\n\t\t\t\t\t: Effect.fail(cause),\n\t\t\t),\n\t\t\tEffect.map((allocated: AllocatedPort) => portPublish(CONTAINER_RPC_PORT, allocated.port)),\n\t\t\tEffect.mapError((cause) =>\n\t\t\t\tsuiPluginError(\n\t\t\t\t\t'port-allocate',\n\t\t\t\t\t`sui fork mode: failed to allocate RPC host port: ${cause.detail}`,\n\t\t\t\t\tcause,\n\t\t\t\t),\n\t\t\t),\n\t\t);\n};\n\nconst findReusableForkPort = (\n\truntime: ContainerRuntime,\n\tlabels: ContainerLabelTuple,\n\tcontainerName: string,\n): Effect.Effect<ContainerPortPublish | undefined, SuiPluginError> =>\n\truntime.inspectByLabels(labels).pipe(\n\t\tEffect.map((handles) =>\n\t\t\thandles\n\t\t\t\t.find((handle) => handle.name === containerName)\n\t\t\t\t?.ports?.find((port) => port.containerPort === CONTAINER_RPC_PORT),\n\t\t),\n\t\tEffect.mapError((cause) =>\n\t\t\tsuiPluginError(\n\t\t\t\t'container-start',\n\t\t\t\t`sui fork mode: failed to inspect existing fork container: ${cause.reason}: ${cause.detail}`,\n\t\t\t\tcause,\n\t\t\t),\n\t\t),\n\t);\n\nconst pickPublishedPort = (\n\trequested: ReadonlyArray<ContainerPortPublish>,\n\tactual: ReadonlyArray<ContainerPortPublish> | undefined,\n): ContainerPortPublish =>\n\tactual?.find((port) => port.containerPort === CONTAINER_RPC_PORT) ??\n\trequested.find((port) => port.containerPort === CONTAINER_RPC_PORT) ??\n\tportPublish(CONTAINER_RPC_PORT, DEFAULT_FORK_HOST_RPC_PORT);\n\nconst portPublish = (containerPort: number, hostPort: number): ContainerPortPublish => ({\n\tcontainerPort,\n\thostPort,\n\thostIp: DOCKER_PUBLISH_HOST,\n});\n\nexport const forkDataDirKey = (opts: SuiForkOptions): string =>\n\tcreateHash('sha256')\n\t\t.update(\n\t\t\tJSON.stringify({\n\t\t\t\tupstream: opts.upstream,\n\t\t\t\tcheckpoint: opts.checkpoint ?? null,\n\t\t\t\tversion: opts.version ?? DEFAULT_SUI_FORK_REV,\n\t\t\t\tseed: normalizeForkSeed(opts),\n\t\t\t}),\n\t\t)\n\t\t.digest('hex')\n\t\t.slice(0, 16);\n\nconst ensureForkDataDir = (\n\tpaths: StackPaths,\n\topts: SuiForkOptions,\n): Effect.Effect<string, SuiPluginError> => {\n\tconst dataDir = resolve(join(paths.stackRoot, 'sui-fork', forkDataDirKey(opts)));\n\treturn Effect.tryPromise({\n\t\ttry: async () => {\n\t\t\tawait mkdir(dataDir, { recursive: true, mode: 0o700 });\n\t\t\treturn dataDir;\n\t\t},\n\t\tcatch: (cause) =>\n\t\t\tsuiPluginError(\n\t\t\t\t'fork-data-dir',\n\t\t\t\t`sui fork mode: failed to create data directory ${dataDir}: ${stringifyCause(cause)}`,\n\t\t\t\tcause,\n\t\t\t),\n\t});\n};\n\ninterface ForkStatus {\n\treadonly checkpoint: string;\n\treadonly clock: number;\n\treadonly forkedAtCheckpoint: string;\n}\n\nconst waitForForkReady = (\n\tsdkClient: SuiGrpcClient,\n\treadyTimeout: Duration.Duration,\n): Effect.Effect<ForkStatus, SuiPluginError> =>\n\tEffect.gen(function* () {\n\t\tconst readyTimeoutMs = Duration.toMillis(readyTimeout);\n\t\tyield* waitForProbe({\n\t\t\tlabel: 'sui.fork.rpc',\n\t\t\ttimeoutMs: readyTimeoutMs,\n\t\t\tintervalMs: 1_000,\n\t\t\tattemptTimeoutMs: PROBE_ATTEMPT_TIMEOUT_MS,\n\t\t\tprobe: () => readForkStatus(sdkClient).pipe(Effect.as(true)),\n\t\t}).pipe(\n\t\t\tEffect.mapError((cause) =>\n\t\t\t\tcause instanceof ProbeTimeoutError\n\t\t\t\t\t? suiPluginError(\n\t\t\t\t\t\t\t'fork-status-probe',\n\t\t\t\t\t\t\t`sui fork mode: ForkingService.GetStatus did not become ready within ${readyTimeoutMs}ms.`,\n\t\t\t\t\t\t\tcause.lastError ?? cause.lastNotReady ?? cause,\n\t\t\t\t\t\t)\n\t\t\t\t\t: suiPluginError(\n\t\t\t\t\t\t\t'fork-status-probe',\n\t\t\t\t\t\t\t`sui fork mode: ForkingService.GetStatus probe failed: ${stringifyCause(cause)}`,\n\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t),\n\t\t\t),\n\t\t);\n\t\treturn yield* readForkStatus(sdkClient);\n\t}).pipe(Effect.withSpan('devstack.plugin.sui.fork.waitForReady'));\n\nconst makeForkAdminSurface = (sdkClient: SuiGrpcClient): ForkAdminSurface => ({\n\tstatus: readForkStatus(sdkClient).pipe(\n\t\tEffect.map(({ checkpoint, clock }) => ({ checkpoint, clock })),\n\t),\n\tadvanceClock: (intervalMs) =>\n\t\tEffect.tryPromise({\n\t\t\ttry: () => sdkClient.forkingService.advanceClock({ durationMs: BigInt(intervalMs) }).response,\n\t\t\tcatch: (cause) =>\n\t\t\t\tsuiPluginError(\n\t\t\t\t\t'fork-advance-clock',\n\t\t\t\t\t`sui fork mode: advanceClock(${intervalMs}) failed: ${stringifyCause(cause)}`,\n\t\t\t\t\tcause,\n\t\t\t\t),\n\t\t}).pipe(Effect.asVoid),\n\tadvanceCheckpoint: Effect.tryPromise({\n\t\ttry: () => sdkClient.forkingService.advanceCheckpoint({}).response,\n\t\tcatch: (cause) =>\n\t\t\tsuiPluginError(\n\t\t\t\t'fork-advance-checkpoint',\n\t\t\t\t`sui fork mode: advanceCheckpoint failed: ${stringifyCause(cause)}`,\n\t\t\t\tcause,\n\t\t\t),\n\t}).pipe(Effect.asVoid),\n\timpersonate: (sender, tx) =>\n\t\tEffect.gen(function* () {\n\t\t\tif (!(tx instanceof Uint8Array)) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tsuiPluginError(\n\t\t\t\t\t\t'fork-impersonate',\n\t\t\t\t\t\t`sui fork mode: impersonate(${sender}) expected serialized transaction bytes.`,\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t}\n\t\t\tyield* verifyForkImpersonationSender(sender, tx);\n\t\t\tconst raw = yield* Effect.tryPromise({\n\t\t\t\ttry: () =>\n\t\t\t\t\tsdkClient.executeTransaction({\n\t\t\t\t\t\ttransaction: tx,\n\t\t\t\t\t\tsignatures: [],\n\t\t\t\t\t\tinclude: { effects: true, objectTypes: true },\n\t\t\t\t\t}),\n\t\t\t\tcatch: (cause) =>\n\t\t\t\t\tsuiPluginError(\n\t\t\t\t\t\t'fork-impersonate',\n\t\t\t\t\t\t`sui fork mode: impersonate(${sender}) failed: ${stringifyCause(cause)}`,\n\t\t\t\t\t\tcause,\n\t\t\t\t\t),\n\t\t\t});\n\t\t\tconst digest = extractExecuteDigest(raw);\n\t\t\tif (digest === undefined) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tsuiPluginError(\n\t\t\t\t\t\t'fork-impersonate',\n\t\t\t\t\t\t`sui fork mode: impersonate(${sender}) returned no transaction digest.`,\n\t\t\t\t\t\traw,\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn { digest, success: !isFailedTransaction(raw), raw };\n\t\t}),\n});\n\nconst readForkStatus = (sdkClient: SuiGrpcClient): Effect.Effect<ForkStatus, SuiPluginError> =>\n\tEffect.tryPromise({\n\t\ttry: async () => {\n\t\t\tconst response = await sdkClient.forkingService.getStatus({}).response;\n\t\t\treturn {\n\t\t\t\tcheckpoint: response.checkpointSequenceNumber.toString(),\n\t\t\t\tclock: Number(response.timestampMs),\n\t\t\t\tforkedAtCheckpoint: response.forkedAtCheckpoint.toString(),\n\t\t\t};\n\t\t},\n\t\tcatch: (cause) =>\n\t\t\tsuiPluginError(\n\t\t\t\t'fork-status-probe',\n\t\t\t\t`sui fork mode: GetStatus failed: ${stringifyCause(cause)}`,\n\t\t\t\tcause,\n\t\t\t),\n\t});\n\nconst routedSuiRpcUrl = (identity: Identity): Effect.Effect<string, SuiPluginError> =>\n\trouterHostname(identity, SUI_RPC_ENDPOINT_NAME).pipe(\n\t\tEffect.map((hostname) =>\n\t\t\trenderUrl({ protocol: 'http', hostname, port: SUI_RPC_ENTRYPOINT_PORT }),\n\t\t),\n\t\tEffect.mapError((cause) =>\n\t\t\tsuiPluginError(\n\t\t\t\t'container-start',\n\t\t\t\t`sui fork mode: failed to construct router RPC URL: ${cause.detail}`,\n\t\t\t\tcause,\n\t\t\t),\n\t\t),\n\t);\n\nconst extractExecuteDigest = (raw: unknown): string | undefined => {\n\tconst env = raw as {\n\t\treadonly $kind?: 'Transaction' | 'FailedTransaction';\n\t\treadonly Transaction?: { readonly digest?: string };\n\t\treadonly FailedTransaction?: { readonly digest?: string };\n\t};\n\treturn env.$kind === 'FailedTransaction'\n\t\t? env.FailedTransaction?.digest\n\t\t: env.Transaction?.digest;\n};\n\nconst isFailedTransaction = (raw: unknown): boolean =>\n\t(raw as { readonly $kind?: string }).$kind === 'FailedTransaction';\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/live.mjs

@@ -0,0 +1,103 @@
+import { suiPluginError } from "../errors.mjs";
+import { assembleSuiClient, buildWaitForTransactionsReady, fetchChainId, makeResolvedNetwork, noopWaitForTransactionsReady } from "./shared-boot.mjs";
+import { Duration, Effect } from "effect";
+import { SuiGrpcClient } from "@mysten/sui/grpc";
+//#region src/plugins/sui/mode/live.ts
+/** Default chain-id fetch timeout for live RPCs. */
+const DEFAULT_LIVE_CHAIN_ID_TIMEOUT = Duration.seconds(30);
+/** Default RPC endpoints per known network. `custom` requires the
+*  caller to supply `rpcUrl`. */
+const LIVE_DEFAULTS = {
+	testnet: {
+		rpcUrl: "https://fullnode.testnet.sui.io:443",
+		faucetUrl: "https://faucet.testnet.sui.io",
+		graphqlUrl: "https://sui-testnet.mystenlabs.com/graphql"
+	},
+	mainnet: {
+		rpcUrl: "https://fullnode.mainnet.sui.io:443",
+		faucetUrl: void 0,
+		graphqlUrl: "https://sui-mainnet.mystenlabs.com/graphql"
+	},
+	devnet: {
+		rpcUrl: "https://fullnode.devnet.sui.io:443",
+		faucetUrl: "https://faucet.devnet.sui.io",
+		graphqlUrl: void 0
+	}
+};
+/** Resolve endpoints from caller overrides + the known-network table.
+*  Order: caller-provided wins; otherwise the LIVE_DEFAULTS row for
+*  the requested network. `custom` MUST carry an explicit `rpcUrl`. */
+const resolveEndpoints = (opts) => {
+	if (opts.network === "custom") {
+		if (opts.rpcUrl === void 0) return Effect.fail(suiPluginError("chain-id-fetch", "sui live mode: network='custom' requires opts.rpcUrl. Use suiFor(network).live.custom({rpcUrl: ...}) or pass network='testnet'|'mainnet'|'devnet' to use the built-in defaults."));
+		return Effect.succeed({
+			rpcUrl: opts.rpcUrl,
+			faucetUrl: opts.faucetUrl,
+			graphqlUrl: opts.graphqlUrl,
+			sdkNetwork: "localnet"
+		});
+	}
+	const defaults = LIVE_DEFAULTS[opts.network];
+	return Effect.succeed({
+		rpcUrl: opts.rpcUrl ?? defaults.rpcUrl,
+		faucetUrl: opts.faucetUrl ?? defaults.faucetUrl,
+		graphqlUrl: opts.graphqlUrl ?? defaults.graphqlUrl,
+		sdkNetwork: opts.network
+	});
+};
+/** Build the live-mode boot Effect. */
+const bootLiveMode = (opts) => Effect.gen(function* () {
+	const endpoints = yield* resolveEndpoints(opts);
+	yield* Effect.annotateCurrentSpan({
+		"sui.live.network": opts.network,
+		"sui.live.rpcUrl": endpoints.rpcUrl,
+		"sui.live.faucetUrl": endpoints.faucetUrl ?? "<none>"
+	});
+	const sdkClient = yield* Effect.try({
+		try: () => new SuiGrpcClient({
+			baseUrl: endpoints.rpcUrl,
+			network: endpoints.sdkNetwork
+		}),
+		catch: (cause) => suiPluginError("chain-id-fetch", `sui live mode: SuiGrpcClient construction failed for rpcUrl=${endpoints.rpcUrl}: ${stringifyCause(cause)}`, cause)
+	});
+	const chain = opts.chain ?? (yield* fetchChainId(sdkClient, {
+		timeout: opts.readyTimeout ?? DEFAULT_LIVE_CHAIN_ID_TIMEOUT,
+		span: "devstack.plugin.sui.live.fetchChainId"
+	}));
+	const waitForTransactionsReady = endpoints.faucetUrl !== void 0 ? yield* buildWaitForTransactionsReady(endpoints.faucetUrl) : noopWaitForTransactionsReady;
+	const { client } = assembleSuiClient({
+		sdkClient,
+		chain,
+		rpcUrl: endpoints.rpcUrl,
+		...endpoints.faucetUrl !== void 0 ? { faucetUrl: endpoints.faucetUrl } : {},
+		...endpoints.graphqlUrl !== void 0 ? { graphqlUrl: endpoints.graphqlUrl } : {},
+		waitForTransactionsReady
+	});
+	return {
+		resolved: makeResolvedNetwork({
+			mode: "live",
+			chain,
+			rpc: endpoints.rpcUrl,
+			source: opts.rpcUrl === void 0 && opts.faucetUrl === void 0 && opts.graphqlUrl === void 0 ? "default" : "config",
+			...endpoints.faucetUrl !== void 0 ? { faucet: endpoints.faucetUrl } : {},
+			...endpoints.graphqlUrl !== void 0 ? { graphql: endpoints.graphqlUrl } : {}
+		}),
+		client
+	};
+}).pipe(Effect.withSpan("devstack.plugin.sui.live.boot", { attributes: {
+	"devstack.plugin": "sui",
+	"sui.mode": "live"
+} }));
+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);
+	}
+};
+//#endregion
+export { bootLiveMode };
+
+//# sourceMappingURL=live.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"live.mjs","names":[],"sources":["../../../../src/plugins/sui/mode/live.ts"],"sourcesContent":["// Sui plugin — live mode (testnet / mainnet / devnet / custom).\n//\n// Wraps a public or caller-provided Sui RPC. Testnet has a faucet;\n// mainnet has none; custom may or may not.\n//\n// What's hard:\n//   - No ready probe is meaningful (the public chain is always\n//     up); chain-id fetch IS the only sentinel with a bounded\n//     timeout.\n//   - Faucet-less networks (mainnet) need a \"no-op\" funds-ready\n//     gate so downstream callers don't have to branch.\n//   - The KnownPackage substrate contributions are wired here so\n//     wallet-standard / MVR / known-deployment lookups find the\n//     right published ids.\n//\n// Live mode contributes a `NetworkResolver`, a `ChainProbe`, and a\n// `Codegenable` — but NO managed container, NO `Routable`, and the\n// build container is forced to the host CLI path (no in-stack\n// build image). The latter is flagged in the distilled-doc Open\n// questions as a candidate to revisit.\n//\n// Boot sequence:\n//\n//   1. Resolve `rpcUrl` / `faucetUrl` / `graphqlUrl` from caller\n//      overrides, then fall back to `LIVE_DEFAULTS` for known nets.\n//      `custom` requires `rpcUrl` — surface a typed refusal if\n//      omitted.\n//   2. Construct `SuiGrpcClient` against the resolved URL with the\n//      matching `network:` discriminator (so MVR / wallet-standard\n//      hints route correctly).\n//   3. Fetch chain id (the only readiness sentinel for live).\n//   4. Build `waitForTransactionsReady`:\n//        - mainnet: trivially-succeeding no-op (no faucet exists).\n//        - testnet/devnet/custom-with-faucet: real HTTP probe.\n//        - custom-without-faucet: no-op.\n\nimport { Duration, Effect, type Scope } from 'effect';\n\nimport { SuiGrpcClient } from '@mysten/sui/grpc';\n\nimport { suiPluginError, type SuiPluginError } from '../errors.ts';\nimport type { ResolvedSuiNetwork } from '../network-resolver.ts';\nimport type { SuiClient } from './shared.ts';\nimport {\n\tassembleSuiClient,\n\tbuildWaitForTransactionsReady,\n\tfetchChainId,\n\tmakeResolvedNetwork,\n\tnoopWaitForTransactionsReady,\n} from './shared-boot.ts';\nimport type { SuiLiveOptions } from './spec.ts';\n\n/** Default chain-id fetch timeout for live RPCs. */\nexport const DEFAULT_LIVE_CHAIN_ID_TIMEOUT = Duration.seconds(30);\n\n/** Default RPC endpoints per known network. `custom` requires the\n *  caller to supply `rpcUrl`. */\nexport const LIVE_DEFAULTS = {\n\ttestnet: {\n\t\trpcUrl: 'https://fullnode.testnet.sui.io:443',\n\t\tfaucetUrl: 'https://faucet.testnet.sui.io',\n\t\tgraphqlUrl: 'https://sui-testnet.mystenlabs.com/graphql',\n\t},\n\tmainnet: {\n\t\trpcUrl: 'https://fullnode.mainnet.sui.io:443',\n\t\tfaucetUrl: undefined as string | undefined,\n\t\tgraphqlUrl: 'https://sui-mainnet.mystenlabs.com/graphql',\n\t},\n\tdevnet: {\n\t\trpcUrl: 'https://fullnode.devnet.sui.io:443',\n\t\tfaucetUrl: 'https://faucet.devnet.sui.io',\n\t\tgraphqlUrl: undefined as string | undefined,\n\t},\n} as const;\n\n/** Resolved live-mode boot artifacts. */\nexport interface LiveModeBootResult {\n\treadonly resolved: ResolvedSuiNetwork;\n\treadonly client: SuiClient;\n}\n\ninterface ResolvedLiveEndpoints {\n\treadonly rpcUrl: string;\n\treadonly faucetUrl: string | undefined;\n\treadonly graphqlUrl: string | undefined;\n\treadonly sdkNetwork: 'mainnet' | 'testnet' | 'devnet' | 'localnet';\n}\n\n/** Resolve endpoints from caller overrides + the known-network table.\n *  Order: caller-provided wins; otherwise the LIVE_DEFAULTS row for\n *  the requested network. `custom` MUST carry an explicit `rpcUrl`. */\nconst resolveEndpoints = (\n\topts: SuiLiveOptions,\n): Effect.Effect<ResolvedLiveEndpoints, SuiPluginError> => {\n\tif (opts.network === 'custom') {\n\t\tif (opts.rpcUrl === undefined) {\n\t\t\treturn Effect.fail(\n\t\t\t\tsuiPluginError(\n\t\t\t\t\t'chain-id-fetch',\n\t\t\t\t\t`sui live mode: network='custom' requires opts.rpcUrl. ` +\n\t\t\t\t\t\t`Use suiFor(network).live.custom({rpcUrl: ...}) or pass network='testnet'|'mainnet'|'devnet' to use the built-in defaults.`,\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\t\treturn Effect.succeed({\n\t\t\trpcUrl: opts.rpcUrl,\n\t\t\tfaucetUrl: opts.faucetUrl,\n\t\t\tgraphqlUrl: opts.graphqlUrl,\n\t\t\t// SDK accepts arbitrary strings under the `(string & {})`\n\t\t\t// branch; `localnet` is the closest semantic for a custom\n\t\t\t// caller-defined live target.\n\t\t\tsdkNetwork: 'localnet',\n\t\t});\n\t}\n\tconst defaults = LIVE_DEFAULTS[opts.network];\n\treturn Effect.succeed({\n\t\trpcUrl: opts.rpcUrl ?? defaults.rpcUrl,\n\t\tfaucetUrl: opts.faucetUrl ?? defaults.faucetUrl,\n\t\tgraphqlUrl: opts.graphqlUrl ?? defaults.graphqlUrl,\n\t\tsdkNetwork: opts.network,\n\t});\n};\n\n/** Build the live-mode boot Effect. */\nexport const bootLiveMode = (\n\topts: SuiLiveOptions,\n): Effect.Effect<LiveModeBootResult, SuiPluginError, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\t// ----- 1. Resolve endpoints ------------------------------------------\n\t\tconst endpoints = yield* resolveEndpoints(opts);\n\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t'sui.live.network': opts.network,\n\t\t\t'sui.live.rpcUrl': endpoints.rpcUrl,\n\t\t\t'sui.live.faucetUrl': endpoints.faucetUrl ?? '<none>',\n\t\t});\n\n\t\t// ----- 2. Construct the grpc client ----------------------------------\n\t\tconst sdkClient = yield* Effect.try({\n\t\t\ttry: () =>\n\t\t\t\tnew SuiGrpcClient({\n\t\t\t\t\tbaseUrl: endpoints.rpcUrl,\n\t\t\t\t\tnetwork: endpoints.sdkNetwork,\n\t\t\t\t}),\n\t\t\tcatch: (cause): SuiPluginError =>\n\t\t\t\tsuiPluginError(\n\t\t\t\t\t'chain-id-fetch',\n\t\t\t\t\t`sui live mode: SuiGrpcClient construction failed for rpcUrl=${endpoints.rpcUrl}: ${stringifyCause(cause)}`,\n\t\t\t\t\tcause,\n\t\t\t\t),\n\t\t});\n\n\t\t// ----- 3. Resolve chain id -------------------------------------------\n\t\tconst chain =\n\t\t\topts.chain ??\n\t\t\t(yield* fetchChainId(sdkClient, {\n\t\t\t\ttimeout: opts.readyTimeout ?? DEFAULT_LIVE_CHAIN_ID_TIMEOUT,\n\t\t\t\tspan: 'devstack.plugin.sui.live.fetchChainId',\n\t\t\t}));\n\n\t\t// ----- 4. Build waitForTransactionsReady -----------------------------\n\t\t// Mainnet: no faucet exists, gate is a no-op. testnet/devnet/\n\t\t// custom-with-faucet: real HTTP probe (rate-limited by upstream,\n\t\t// but the wire shape is identical to localnet).\n\t\tconst waitForTransactionsReady =\n\t\t\tendpoints.faucetUrl !== undefined\n\t\t\t\t? yield* buildWaitForTransactionsReady(endpoints.faucetUrl)\n\t\t\t\t: noopWaitForTransactionsReady;\n\n\t\t// ----- 5. Assemble + return ------------------------------------------\n\t\tconst { client } = assembleSuiClient({\n\t\t\tsdkClient,\n\t\t\tchain,\n\t\t\trpcUrl: endpoints.rpcUrl,\n\t\t\t...(endpoints.faucetUrl !== undefined ? { faucetUrl: endpoints.faucetUrl } : {}),\n\t\t\t...(endpoints.graphqlUrl !== undefined ? { graphqlUrl: endpoints.graphqlUrl } : {}),\n\t\t\twaitForTransactionsReady,\n\t\t});\n\t\tconst resolved = makeResolvedNetwork({\n\t\t\tmode: 'live',\n\t\t\tchain,\n\t\t\trpc: endpoints.rpcUrl,\n\t\t\t// `source: 'default'` when we pulled from LIVE_DEFAULTS;\n\t\t\t// `'config'` when the caller passed an override. The\n\t\t\t// distinction matters for the doctor's \"where did this\n\t\t\t// value come from\" surface.\n\t\t\tsource:\n\t\t\t\topts.rpcUrl === undefined && opts.faucetUrl === undefined && opts.graphqlUrl === undefined\n\t\t\t\t\t? 'default'\n\t\t\t\t\t: 'config',\n\t\t\t...(endpoints.faucetUrl !== undefined ? { faucet: endpoints.faucetUrl } : {}),\n\t\t\t...(endpoints.graphqlUrl !== undefined ? { graphql: endpoints.graphqlUrl } : {}),\n\t\t});\n\n\t\treturn { resolved, client };\n\t}).pipe(\n\t\tEffect.withSpan('devstack.plugin.sui.live.boot', {\n\t\t\tattributes: { 'devstack.plugin': 'sui', 'sui.mode': 'live' },\n\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":";;;;;;AAqDA,MAAa,gCAAgC,SAAS,QAAQ,GAAG;;;AAIjE,MAAa,gBAAgB;CAC5B,SAAS;EACR,QAAQ;EACR,WAAW;EACX,YAAY;EACZ;CACD,SAAS;EACR,QAAQ;EACR,WAAW,KAAA;EACX,YAAY;EACZ;CACD,QAAQ;EACP,QAAQ;EACR,WAAW;EACX,YAAY,KAAA;EACZ;CACD;;;;AAkBD,MAAM,oBACL,SAC0D;AAC1D,KAAI,KAAK,YAAY,UAAU;AAC9B,MAAI,KAAK,WAAW,KAAA,EACnB,QAAO,OAAO,KACb,eACC,kBACA,kLAEA,CACD;AAEF,SAAO,OAAO,QAAQ;GACrB,QAAQ,KAAK;GACb,WAAW,KAAK;GAChB,YAAY,KAAK;GAIjB,YAAY;GACZ,CAAC;;CAEH,MAAM,WAAW,cAAc,KAAK;AACpC,QAAO,OAAO,QAAQ;EACrB,QAAQ,KAAK,UAAU,SAAS;EAChC,WAAW,KAAK,aAAa,SAAS;EACtC,YAAY,KAAK,cAAc,SAAS;EACxC,YAAY,KAAK;EACjB,CAAC;;;AAIH,MAAa,gBACZ,SAEA,OAAO,IAAI,aAAa;CAEvB,MAAM,YAAY,OAAO,iBAAiB,KAAK;AAE/C,QAAO,OAAO,oBAAoB;EACjC,oBAAoB,KAAK;EACzB,mBAAmB,UAAU;EAC7B,sBAAsB,UAAU,aAAa;EAC7C,CAAC;CAGF,MAAM,YAAY,OAAO,OAAO,IAAI;EACnC,WACC,IAAI,cAAc;GACjB,SAAS,UAAU;GACnB,SAAS,UAAU;GACnB,CAAC;EACH,QAAQ,UACP,eACC,kBACA,+DAA+D,UAAU,OAAO,IAAI,eAAe,MAAM,IACzG,MACA;EACF,CAAC;CAGF,MAAM,QACL,KAAK,UACJ,OAAO,aAAa,WAAW;EAC/B,SAAS,KAAK,gBAAgB;EAC9B,MAAM;EACN,CAAC;CAMH,MAAM,2BACL,UAAU,cAAc,KAAA,IACrB,OAAO,8BAA8B,UAAU,UAAU,GACzD;CAGJ,MAAM,EAAE,WAAW,kBAAkB;EACpC;EACA;EACA,QAAQ,UAAU;EAClB,GAAI,UAAU,cAAc,KAAA,IAAY,EAAE,WAAW,UAAU,WAAW,GAAG,EAAE;EAC/E,GAAI,UAAU,eAAe,KAAA,IAAY,EAAE,YAAY,UAAU,YAAY,GAAG,EAAE;EAClF;EACA,CAAC;AAiBF,QAAO;EAAE,UAhBQ,oBAAoB;GACpC,MAAM;GACN;GACA,KAAK,UAAU;GAKf,QACC,KAAK,WAAW,KAAA,KAAa,KAAK,cAAc,KAAA,KAAa,KAAK,eAAe,KAAA,IAC9E,YACA;GACJ,GAAI,UAAU,cAAc,KAAA,IAAY,EAAE,QAAQ,UAAU,WAAW,GAAG,EAAE;GAC5E,GAAI,UAAU,eAAe,KAAA,IAAY,EAAE,SAAS,UAAU,YAAY,GAAG,EAAE;GAC/E,CAEgB;EAAE;EAAQ;EAC1B,CAAC,KACF,OAAO,SAAS,iCAAiC,EAChD,YAAY;CAAE,mBAAmB;CAAO,YAAY;CAAQ,EAC5D,CAAC,CACF;AAEF,MAAM,kBAAkB,UAA2B;AAClD,KAAI,iBAAiB,MAAO,QAAO,MAAM;AACzC,KAAI,OAAO,UAAU,SAAU,QAAO;AACtC,KAAI;AACH,SAAO,KAAK,UAAU,MAAM;SACrB;AACP,SAAO,OAAO,MAAM"}