@mysten-incubation/devstack 0.0.0

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

@@ -0,0 +1,293 @@
+import { renderUrl, routerHostname } from "../../../orchestrators/router/hostname.mjs";
+import { suiPluginError } from "../errors.mjs";
+import { waitForHttpEndpoint } from "../../../substrate/runtime/http-probe.mjs";
+import { toDockerHostGatewayUrl } from "./shared.mjs";
+import { assembleSuiClient, buildWaitForTransactionsReady, fetchChainId, makeResolvedNetwork } from "./shared-boot.mjs";
+import { ensureManagedContainer } from "../../../substrate/runtime/managed-container.mjs";
+import { noopClockAdvancer } from "../auto-tick.mjs";
+import { SUI_FAUCET_ENDPOINT_NAME, SUI_FAUCET_ENTRYPOINT_PORT, SUI_GRAPHQL_ENDPOINT_NAME, SUI_GRAPHQL_ENTRYPOINT_PORT, SUI_RPC_ENTRYPOINT_PORT } from "../routable.mjs";
+import { DEFAULT_SUI_CLI_VERSION, suiCliImageBuildContext } from "../../../substrate/runtime/sui-move-build/index.mjs";
+import { setCurrentPluginPhase } from "../../../substrate/runtime/current-plugin.mjs";
+import { Duration, Effect } from "effect";
+import { SuiGrpcClient } from "@mysten/sui/grpc";
+//#region src/plugins/sui/mode/local.ts
+/** Default ready-probe timeout for localnet. The validator's cold
+*  start runs genesis + faucet bootstrap; 60 s is the documented
+*  ceiling. */
+const DEFAULT_LOCAL_READY_TIMEOUT = Duration.seconds(60);
+/** Default sui validator binary version pinned by the vendored
+*  `images/sui/` Dockerfile. The build arg `SUI_VERSION` is threaded
+*  through to the release-tarball URL. Bump in lockstep with matching
+*  Walrus / Seal versions (else the Move package ABIs drift). */
+const DEFAULT_SUI_VERSION = DEFAULT_SUI_CLI_VERSION;
+const CONTAINER_RPC_PORT = SUI_RPC_ENTRYPOINT_PORT;
+const CONTAINER_FAUCET_PORT = SUI_FAUCET_ENTRYPOINT_PORT;
+const CONTAINER_GRAPHQL_PORT = SUI_GRAPHQL_ENTRYPOINT_PORT;
+const DEFAULT_HOST_RPC_PORT = 51e3;
+const DEFAULT_HOST_FAUCET_PORT = 5e4;
+const DEFAULT_HOST_GRAPHQL_PORT = 51001;
+const DOCKER_PUBLISH_HOST = "0.0.0.0";
+/** Per-fetch deadline for the ready-probe HTTP calls. Without it a
+*  hung fetch would block the outer ready deadline with no signal
+*  about which probe wedged. */
+const PROBE_FETCH_TIMEOUT_MS = 3e3;
+/**
+* Build the local-mode boot Effect.
+*
+* `identity` is threaded in by the caller (the plugin barrel's acquire
+* body, which has access to the substrate's `IdentityContext` via the
+* outer composition layer); the body uses it to stamp the canonical
+* container label tuple so sweep / inventory are name-blind.
+*
+* `{pull}`, `{build}`, and vendored-build image branches are wired.
+*/
+const bootLocalMode = (runtime, identity, portBroker, opts) => Effect.gen(function* () {
+	yield* setCurrentPluginPhase("resolving Sui local image");
+	const image = yield* resolveImage(runtime, opts);
+	yield* setCurrentPluginPhase("creating Sui validator container");
+	const { handle, ports } = yield* ensureLocalValidatorContainer(runtime, portBroker, image, {
+		app: identity.app,
+		stack: identity.stack,
+		plugin: "sui",
+		role: "validator"
+	}, `devstack-${identity.app}-${identity.stack}-sui-validator`, opts);
+	const publishedPorts = resolvePublishedPortMapping(ports, handle.ports);
+	const directRpcUrl = `http://127.0.0.1:${publishedPorts[0].hostPort}`;
+	const directFaucetUrl = `http://127.0.0.1:${publishedPorts[1].hostPort}`;
+	const directGraphqlUrl = `http://127.0.0.1:${publishedPorts[2].hostPort}`;
+	const rpcUrl = yield* routedSuiUrl(identity, "rpc", SUI_RPC_ENTRYPOINT_PORT);
+	const faucetUrl = yield* routedSuiUrl(identity, SUI_FAUCET_ENDPOINT_NAME, SUI_FAUCET_ENTRYPOINT_PORT);
+	const graphqlUrl = yield* routedSuiUrl(identity, SUI_GRAPHQL_ENDPOINT_NAME, SUI_GRAPHQL_ENTRYPOINT_PORT);
+	const readyTimeout = opts.readyTimeout ?? DEFAULT_LOCAL_READY_TIMEOUT;
+	yield* setCurrentPluginPhase("waiting for Sui RPC, faucet, and GraphQL");
+	yield* waitForReady(directRpcUrl, directFaucetUrl, directGraphqlUrl, readyTimeout).pipe(Effect.annotateLogs({ "sui.container": handle.name }));
+	const sdkClient = new SuiGrpcClient({
+		baseUrl: directRpcUrl,
+		network: "localnet"
+	});
+	yield* setCurrentPluginPhase("fetching Sui chain id");
+	const chain = yield* fetchChainId(sdkClient, { span: "devstack.plugin.sui.local.fetchChainId" });
+	yield* setCurrentPluginPhase("preparing Sui funds-ready gate");
+	const { client } = assembleSuiClient({
+		sdkClient,
+		chain,
+		rpcUrl,
+		sdkRpcUrl: directRpcUrl,
+		faucetUrl,
+		fundingFaucetUrl: directFaucetUrl,
+		graphqlUrl,
+		waitForTransactionsReady: yield* buildWaitForTransactionsReady(directFaucetUrl),
+		buildImage: image,
+		hostGateway: {
+			rpcUrl: toDockerHostGatewayUrl(directRpcUrl),
+			faucetUrl: toDockerHostGatewayUrl(directFaucetUrl),
+			graphqlUrl: toDockerHostGatewayUrl(directGraphqlUrl)
+		}
+	});
+	return {
+		resolved: makeResolvedNetwork({
+			mode: "local",
+			chain,
+			rpc: rpcUrl,
+			faucet: faucetUrl,
+			graphql: graphqlUrl,
+			source: "default"
+		}),
+		client,
+		clockAdvancer: noopClockAdvancer
+	};
+}).pipe(Effect.withSpan("devstack.plugin.sui.local.boot", { attributes: { "devstack.plugin": "sui" } }));
+const resolveImage = (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 local 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 local mode failed to pull image '${pullRef}': ${cause.reason}: ${cause.detail}`, cause)));
+	}
+	const version = opts.version ?? DEFAULT_SUI_VERSION;
+	const buildCtx = opts.image && "build" in opts.image ? {
+		contextPath: opts.image.build.context,
+		dockerfile: opts.image.build.dockerfile ?? "Dockerfile",
+		buildArgs: { SUI_VERSION: version }
+	} : suiCliImageBuildContext(version);
+	return yield* runtime.ensureImage(buildCtx).pipe(Effect.mapError((cause) => suiPluginError("image-build", `sui image build failed: ${cause.reason}: ${cause.detail}`, cause)));
+}).pipe(Effect.withSpan("devstack.plugin.sui.local.resolveImage"));
+const ensureLocalValidatorContainer = (runtime, portBroker, image, labels, containerName, opts) => Effect.gen(function* () {
+	const reusablePorts = opts.ports === void 0 ? yield* findReusablePortMapping(runtime, labels, containerName) : void 0;
+	if (reusablePorts !== void 0) return yield* ensureLocalValidatorContainerAttempt({
+		runtime,
+		portBroker,
+		image,
+		labels,
+		containerName,
+		opts,
+		ports: reusablePorts,
+		attempt: 0,
+		reconciliation: "adopt-existing"
+	});
+	return yield* ensureLocalValidatorContainerWithFreshPorts({
+		runtime,
+		portBroker,
+		image,
+		labels,
+		containerName,
+		opts,
+		attempt: 0,
+		reconciliation: opts.ports ? "exact" : "adopt-existing"
+	});
+});
+const ensureLocalValidatorContainerWithFreshPorts = (params) => Effect.gen(function* () {
+	const mapping = yield* resolvePortMappingWithRelease(params.portBroker, params.opts.ports);
+	return yield* ensureLocalValidatorContainerAttempt({
+		...params,
+		ports: mapping.ports,
+		releasePorts: mapping.release
+	});
+});
+const ensureLocalValidatorContainerAttempt = (params) => ensureManagedContainer({
+	runtime: params.runtime,
+	labels: params.labels,
+	spec: {
+		name: params.containerName,
+		image: params.image,
+		recreate: "on-failure",
+		stopGraceSeconds: 30,
+		ports: params.ports,
+		portBindingReconciliation: params.reconciliation
+	},
+	mapError: (cause) => cause
+}).pipe(Effect.map((handle) => ({
+	handle,
+	ports: params.ports
+})), Effect.catch((cause) => {
+	if (params.opts.ports === void 0 && cause.reason === "publish-port-conflict" && params.attempt < 3) return (params.releasePorts ?? Effect.void).pipe(Effect.andThen(ensureLocalValidatorContainerWithFreshPorts({
+		...params,
+		attempt: params.attempt + 1,
+		reconciliation: "exact"
+	})));
+	return Effect.fail(suiPluginError("container-start", `sui-validator container failed: ${cause.reason}: ${cause.detail}`, cause));
+}));
+const resolvePortMappingWithRelease = (portBroker, override) => {
+	const pick = (containerPort, fallback) => {
+		if (!override) return fallback;
+		const hit = override[containerPort];
+		return typeof hit === "number" ? hit : fallback;
+	};
+	if (override) return Effect.succeed({
+		ports: [
+			portPublish(CONTAINER_RPC_PORT, pick(CONTAINER_RPC_PORT, DEFAULT_HOST_RPC_PORT)),
+			portPublish(CONTAINER_FAUCET_PORT, pick(CONTAINER_FAUCET_PORT, DEFAULT_HOST_FAUCET_PORT)),
+			portPublish(CONTAINER_GRAPHQL_PORT, pick(CONTAINER_GRAPHQL_PORT, DEFAULT_HOST_GRAPHQL_PORT))
+		],
+		release: Effect.void
+	});
+	return Effect.gen(function* () {
+		const rpc = yield* allocatePort(portBroker, "rpc", DEFAULT_HOST_RPC_PORT, "rpc");
+		const faucet = yield* allocatePort(portBroker, "http", DEFAULT_HOST_FAUCET_PORT, "faucet");
+		const graphql = yield* allocatePort(portBroker, "rpc", DEFAULT_HOST_GRAPHQL_PORT, "graphql");
+		return {
+			ports: [
+				portPublish(CONTAINER_RPC_PORT, rpc.port),
+				portPublish(CONTAINER_FAUCET_PORT, faucet.port),
+				portPublish(CONTAINER_GRAPHQL_PORT, graphql.port)
+			],
+			release: Effect.all([
+				rpc.release,
+				faucet.release,
+				graphql.release
+			], { discard: true })
+		};
+	});
+};
+const resolvePublishedPortMapping = (requested, actual) => [
+	pickPublishedPort(requested, actual, CONTAINER_RPC_PORT, DEFAULT_HOST_RPC_PORT),
+	pickPublishedPort(requested, actual, CONTAINER_FAUCET_PORT, DEFAULT_HOST_FAUCET_PORT),
+	pickPublishedPort(requested, actual, CONTAINER_GRAPHQL_PORT, DEFAULT_HOST_GRAPHQL_PORT)
+];
+const pickPublishedPort = (requested, actual, containerPort, fallbackHostPort) => actual?.find((port) => port.containerPort === containerPort) ?? requested.find((port) => port.containerPort === containerPort) ?? portPublish(containerPort, fallbackHostPort);
+const selectReusablePortMapping = (handles, containerName) => {
+	const ports = handles.find((handle) => handle.name === containerName)?.ports;
+	if (!hasSuiPortMapping(ports)) return void 0;
+	return resolvePublishedPortMapping([], ports);
+};
+const findReusablePortMapping = (runtime, labels, containerName) => runtime.inspectByLabels(labels).pipe(Effect.map((handles) => selectReusablePortMapping(handles, containerName)), Effect.mapError((cause) => suiPluginError("container-start", `sui local mode: failed to inspect existing validator container: ${cause.reason}: ${cause.detail}`, cause)));
+const hasSuiPortMapping = (ports) => ports !== void 0 && ports.some((port) => port.containerPort === CONTAINER_RPC_PORT) && ports.some((port) => port.containerPort === CONTAINER_FAUCET_PORT) && ports.some((port) => port.containerPort === CONTAINER_GRAPHQL_PORT);
+const portPublish = (containerPort, hostPort) => ({
+	containerPort,
+	hostPort,
+	hostIp: DOCKER_PUBLISH_HOST
+});
+const allocatePort = (portBroker, kind, preferredPort, label) => {
+	const allocate = (hint) => portBroker.allocate({
+		kind,
+		...hint === void 0 ? {} : { preferredPort: hint },
+		probeHost: DOCKER_PUBLISH_HOST
+	}).pipe(Effect.catchTag("PortBrokerError", (cause) => hint !== void 0 && cause.reason === "preferred-busy" ? portBroker.allocate({
+		kind,
+		probeHost: DOCKER_PUBLISH_HOST
+	}) : Effect.fail(cause)), Effect.mapError((cause) => suiPluginError("port-allocate", `sui local mode: failed to allocate ${label} host port (preferred ${hint ?? "auto"}): ${cause.detail}`, cause)));
+	return allocate(preferredPort);
+};
+/** Coordinated readiness gate. Both RPC + faucet must respond within
+*  the outer deadline; each probe has its own per-fetch deadline so a
+*  wedged endpoint surfaces by name. */
+const waitForReady = (rpcUrl, faucetUrl, graphqlUrl, readyTimeout) => Effect.gen(function* () {
+	const readyTimeoutMs = Duration.toMillis(readyTimeout);
+	const rpcProbe = waitForHttpEndpoint({
+		endpoint: rpcUrl,
+		timeoutMs: readyTimeoutMs,
+		intervalMs: 1e3,
+		requestTimeoutMs: PROBE_FETCH_TIMEOUT_MS,
+		requestInit: {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({
+				jsonrpc: "2.0",
+				id: 1,
+				method: "sui_getLatestCheckpointSequenceNumber",
+				params: []
+			})
+		},
+		validate: async (response) => {
+			if (!response.ok) return false;
+			const body = await response.json();
+			return typeof body.result === "string" || typeof body.result === "number";
+		}
+	}).pipe(Effect.mapError((cause) => suiPluginError("rpc-probe", `sui local mode: RPC endpoint ${rpcUrl} did not become ready within ${readyTimeoutMs}ms: ${stringifyCause(cause)}`, cause)), Effect.withSpan("devstack.plugin.sui.local.probe.rpc"));
+	const faucetProbe = waitForHttpEndpoint({
+		endpoint: faucetUrl,
+		timeoutMs: readyTimeoutMs,
+		intervalMs: 1e3,
+		requestTimeoutMs: PROBE_FETCH_TIMEOUT_MS,
+		validate: (response) => response.status < 500
+	}).pipe(Effect.mapError((cause) => suiPluginError("faucet-probe", `sui local mode: faucet endpoint ${faucetUrl} did not become ready within ${readyTimeoutMs}ms: ${stringifyCause(cause)}`, cause)), Effect.withSpan("devstack.plugin.sui.local.probe.faucet"));
+	const graphqlProbe = waitForHttpEndpoint({
+		endpoint: graphqlUrl,
+		timeoutMs: readyTimeoutMs,
+		intervalMs: 1e3,
+		requestTimeoutMs: PROBE_FETCH_TIMEOUT_MS,
+		validate: (response) => response.status < 500
+	}).pipe(Effect.mapError((cause) => suiPluginError("graphql-probe", `sui local mode: GraphQL endpoint ${graphqlUrl} did not become ready within ${readyTimeoutMs}ms: ${stringifyCause(cause)}`, cause)), Effect.withSpan("devstack.plugin.sui.local.probe.graphql"));
+	yield* Effect.all([
+		rpcProbe,
+		faucetProbe,
+		graphqlProbe
+	], { concurrency: "unbounded" }).pipe(Effect.asVoid);
+}).pipe(Effect.withSpan("devstack.plugin.sui.local.waitForReady"));
+const routedSuiUrl = (identity, endpointName, port) => routerHostname(identity, endpointName).pipe(Effect.map((hostname) => renderUrl({
+	protocol: "http",
+	hostname,
+	port
+})), Effect.mapError((cause) => suiPluginError("container-start", `sui local mode: failed to construct router URL for ${endpointName}: ${cause.detail}`, cause)));
+const stringifyCause = (cause) => {
+	if (cause instanceof Error) return cause.message;
+	if (typeof cause === "string") return cause;
+	try {
+		return JSON.stringify(cause);
+	} catch {
+		return String(cause);
+	}
+};
+//#endregion
+export { bootLocalMode };
+
+//# sourceMappingURL=local.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"local.mjs","names":["sharedFetchChainId"],"sources":["../../../../src/plugins/sui/mode/local.ts"],"sourcesContent":["// Sui plugin — local-container mode.\n//\n// In-stack Sui validator + faucet, running in the supervised docker\n// stack. Used during normal dev loops when the developer wants fresh,\n// fast, throwaway chain state with a working faucet.\n//\n// Boot sequence (load-bearing order):\n//\n//   1. Resolve image — vendored Dockerfile build via the\n//      ContainerRuntime contract (caller `image` override honoured for\n//      `{build}`; `{pull}` is deferred — see stub list in the README).\n//   2. Allocate + ensure container — `sui start --with-faucet=0.0.0.0:9123\n//      --with-graphql=0.0.0.0:9125` with direct host port-publishing\n//      for internal boot probes. User-facing URLs are router-fronted\n//      named hosts; the direct host ports intentionally live in the\n//      high private windows so they do not collide with router\n//      entrypoints.\n//      RecreatePolicy is `on-failure` so the writable layer (chain\n//      state at `/root/.sui`) survives clean stop/start cycles, but an\n//      unclean SIGKILL/137 exit recreates instead of resuming a suspect\n//      RocksDB/checkpoint state. The image's entrypoint forwards SIGINT\n//      to a non-PID-1 sui child so clean shutdown (RocksDB checkpoint\n//      drain → exit 0/130) is the normal case.\n//   3. Ready probe — RPC `getChainIdentifier`, faucet `GET /`, and\n//      GraphQL HTTP liveness. Per-fetch deadline + outer deadline.\n//   4. Fetch chain id from the now-responsive client (bounded timeout).\n//   5. Build `waitForTransactionsReady` — `Effect.cached` against a\n//      real faucet funding tx; first failure caches for the scope.\n//      Manual `invalidate` clears the memo.\n//   6. Return resolved `SuiClient`. Auto-tick is the no-op advancer\n//      (localnet drives its own consensus).\n//\n// Faucet socket-level readiness does NOT imply funds-transferability.\n// The first `waitForTransactionsReady.wait` POSTs a real funding tx,\n// retrying on body-level `{Failure}` responses during the post-RPC /\n// pre-fund window.\n//\n// What this body deliberately defers:\n//   - Postgres indexer sidecar — GraphQL is enabled by `sui start` and\n//     routed as a first-class endpoint, but no separate postgres\n//     lifecycle is supervised here.\n//   - Snapshot capture — the framework exists in the plugin's\n//     snapshot.ts; this body produces the running container that the\n//     orchestrator captures.\n\nimport { Duration, Effect, type Scope } from 'effect';\n\nimport { SuiGrpcClient } from '@mysten/sui/grpc';\n\nimport type {\n\tContainerHandle,\n\tContainerRuntime,\n\tContainerRuntimeError,\n\tImageRef,\n\tContainerPortPublish,\n\tPortBindingReconciliation,\n} from '../../../contracts/container-runtime.ts';\nimport type { ContainerLabelTuple } from '../../../contracts/snapshotable.ts';\nimport type { Identity } from '../../../substrate/identity.ts';\nimport type {\n\tAllocatedPort,\n\tPortBroker,\n\tPortKind,\n} from '../../../substrate/runtime/port-broker/index.ts';\nimport { waitForHttpEndpoint } from '../../../substrate/runtime/http-probe.ts';\nimport { setCurrentPluginPhase } from '../../../substrate/runtime/current-plugin.ts';\nimport { ensureManagedContainer } from '../../../substrate/runtime/managed-container.ts';\nimport { renderUrl, routerHostname } from '../../../orchestrators/router/hostname.ts';\nimport {\n\tDEFAULT_SUI_CLI_VERSION,\n\tsuiCliImageBuildContext,\n} from '../../../substrate/runtime/sui-move-build/index.ts';\nimport { noopClockAdvancer } from '../auto-tick.ts';\nimport { suiPluginError, type SuiPluginError } from '../errors.ts';\nimport type { ResolvedSuiNetwork } from '../network-resolver.ts';\nimport {\n\tSUI_FAUCET_ENTRYPOINT_PORT,\n\tSUI_FAUCET_ENDPOINT_NAME,\n\tSUI_GRAPHQL_ENDPOINT_NAME,\n\tSUI_GRAPHQL_ENTRYPOINT_PORT,\n\tSUI_RPC_ENDPOINT_NAME,\n\tSUI_RPC_ENTRYPOINT_PORT,\n} from '../routable.ts';\nimport type { SuiClient } from './shared.ts';\nimport { toDockerHostGatewayUrl } from './shared.ts';\nimport {\n\tassembleSuiClient,\n\tbuildWaitForTransactionsReady,\n\tfetchChainId as sharedFetchChainId,\n\tmakeResolvedNetwork,\n} from './shared-boot.ts';\nimport type { SuiLocalOptions } from './spec.ts';\n\n/** Default ready-probe timeout for localnet. The validator's cold\n *  start runs genesis + faucet bootstrap; 60 s is the documented\n *  ceiling. */\nexport const DEFAULT_LOCAL_READY_TIMEOUT = Duration.seconds(60);\n\n/** Default sui validator binary version pinned by the vendored\n *  `images/sui/` Dockerfile. The build arg `SUI_VERSION` is threaded\n *  through to the release-tarball URL. Bump in lockstep with matching\n *  Walrus / Seal versions (else the Move package ABIs drift). */\nexport const DEFAULT_SUI_VERSION = DEFAULT_SUI_CLI_VERSION;\n\n// In-container ports the sui binary binds on. These match the router\n// entrypoint ports; direct host publishes below use different high\n// ports so Traefik owns the public listener ports.\nconst CONTAINER_RPC_PORT = SUI_RPC_ENTRYPOINT_PORT;\nconst CONTAINER_FAUCET_PORT = SUI_FAUCET_ENTRYPOINT_PORT;\nconst CONTAINER_GRAPHQL_PORT = SUI_GRAPHQL_ENTRYPOINT_PORT;\n\n// Default host ports. Without `opts.ports`, these are preferences\n// brokered against the kernel before Docker publishes them.\nexport const DEFAULT_HOST_RPC_PORT = 51000;\nexport const DEFAULT_HOST_FAUCET_PORT = 50000;\nexport const DEFAULT_HOST_GRAPHQL_PORT = 51001;\nconst DOCKER_PUBLISH_HOST = '0.0.0.0' as const;\nexport const MAX_DOCKER_PUBLISH_PORT_RETRIES = 3;\nexport const LOCAL_VALIDATOR_STOP_GRACE_SECONDS = 30;\n\n/** Per-fetch deadline for the ready-probe HTTP calls. Without it a\n *  hung fetch would block the outer ready deadline with no signal\n *  about which probe wedged. */\nconst PROBE_FETCH_TIMEOUT_MS = 3000;\n\n/** Resolved local-mode boot artifacts. */\nexport interface LocalModeBootResult {\n\treadonly resolved: ResolvedSuiNetwork;\n\treadonly client: SuiClient;\n\treadonly clockAdvancer: typeof noopClockAdvancer;\n}\n\n/**\n * Build the local-mode boot Effect.\n *\n * `identity` is threaded in by the caller (the plugin barrel's acquire\n * body, which has access to the substrate's `IdentityContext` via the\n * outer composition layer); the body uses it to stamp the canonical\n * container label tuple so sweep / inventory are name-blind.\n *\n * `{pull}`, `{build}`, and vendored-build image branches are wired.\n */\nexport const bootLocalMode = (\n\truntime: ContainerRuntime,\n\tidentity: Identity,\n\tportBroker: PortBroker,\n\topts: SuiLocalOptions,\n): Effect.Effect<LocalModeBootResult, SuiPluginError, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\t// ----- 1. Resolve image ---------------------------------------------\n\t\tyield* setCurrentPluginPhase('resolving Sui local image');\n\t\tconst image = yield* resolveImage(runtime, opts);\n\n\t\t// ----- 2. Allocate ports + ensure container --------------------------\n\t\tyield* setCurrentPluginPhase('creating Sui validator container');\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: 'validator',\n\t\t};\n\t\tconst containerName = `devstack-${identity.app}-${identity.stack}-sui-validator`;\n\t\tconst { handle, ports } = yield* ensureLocalValidatorContainer(\n\t\t\truntime,\n\t\t\tportBroker,\n\t\t\timage,\n\t\t\tlabels,\n\t\t\tcontainerName,\n\t\t\topts,\n\t\t);\n\n\t\t// ----- 3. Ready probes ----------------------------------------------\n\t\tconst publishedPorts = resolvePublishedPortMapping(ports, handle.ports);\n\t\tconst directRpcUrl = `http://127.0.0.1:${publishedPorts[0]!.hostPort}`;\n\t\tconst directFaucetUrl = `http://127.0.0.1:${publishedPorts[1]!.hostPort}`;\n\t\tconst directGraphqlUrl = `http://127.0.0.1:${publishedPorts[2]!.hostPort}`;\n\t\tconst rpcUrl = yield* routedSuiUrl(identity, SUI_RPC_ENDPOINT_NAME, SUI_RPC_ENTRYPOINT_PORT);\n\t\tconst faucetUrl = yield* routedSuiUrl(\n\t\t\tidentity,\n\t\t\tSUI_FAUCET_ENDPOINT_NAME,\n\t\t\tSUI_FAUCET_ENTRYPOINT_PORT,\n\t\t);\n\t\tconst graphqlUrl = yield* routedSuiUrl(\n\t\t\tidentity,\n\t\t\tSUI_GRAPHQL_ENDPOINT_NAME,\n\t\t\tSUI_GRAPHQL_ENTRYPOINT_PORT,\n\t\t);\n\t\tconst readyTimeout = opts.readyTimeout ?? DEFAULT_LOCAL_READY_TIMEOUT;\n\n\t\tyield* setCurrentPluginPhase('waiting for Sui RPC, faucet, and GraphQL');\n\t\tyield* waitForReady(directRpcUrl, directFaucetUrl, directGraphqlUrl, readyTimeout).pipe(\n\t\t\tEffect.annotateLogs({ 'sui.container': handle.name }),\n\t\t);\n\n\t\tconst sdkClient = new SuiGrpcClient({ baseUrl: directRpcUrl, network: 'localnet' });\n\n\t\t// ----- 4. Resolve chain id ------------------------------------------\n\t\tyield* setCurrentPluginPhase('fetching Sui chain id');\n\t\tconst chain = yield* sharedFetchChainId(sdkClient, {\n\t\t\tspan: 'devstack.plugin.sui.local.fetchChainId',\n\t\t});\n\n\t\t// ----- 5. waitForTransactionsReady (memoised) -----------------------\n\t\tyield* setCurrentPluginPhase('preparing Sui funds-ready gate');\n\t\tconst waitForTransactionsReady = yield* buildWaitForTransactionsReady(directFaucetUrl);\n\n\t\t// ----- 6. Assemble resolved SuiClient -------------------------------\n\t\t// Surface `buildImage` so package's path-(b) `docker run --rm`\n\t\t// build path can spawn a one-shot sui-cli container using the\n\t\t// SAME image we built/resolved here. Without this the package\n\t\t// plugin would have to re-resolve the image, doubling the\n\t\t// build-context hash work and risking digest drift.\n\t\tconst { client } = assembleSuiClient({\n\t\t\tsdkClient,\n\t\t\tchain,\n\t\t\trpcUrl,\n\t\t\tsdkRpcUrl: directRpcUrl,\n\t\t\tfaucetUrl,\n\t\t\tfundingFaucetUrl: directFaucetUrl,\n\t\t\tgraphqlUrl,\n\t\t\twaitForTransactionsReady,\n\t\t\tbuildImage: image,\n\t\t\thostGateway: {\n\t\t\t\trpcUrl: toDockerHostGatewayUrl(directRpcUrl),\n\t\t\t\tfaucetUrl: toDockerHostGatewayUrl(directFaucetUrl),\n\t\t\t\tgraphqlUrl: toDockerHostGatewayUrl(directGraphqlUrl),\n\t\t\t},\n\t\t});\n\t\tconst resolved = makeResolvedNetwork({\n\t\t\tmode: 'local',\n\t\t\tchain,\n\t\t\trpc: rpcUrl,\n\t\t\tfaucet: faucetUrl,\n\t\t\tgraphql: graphqlUrl,\n\t\t\tsource: 'default',\n\t\t});\n\t\treturn {\n\t\t\tresolved,\n\t\t\tclient,\n\t\t\tclockAdvancer: noopClockAdvancer,\n\t\t};\n\t}).pipe(\n\t\tEffect.withSpan('devstack.plugin.sui.local.boot', { attributes: { 'devstack.plugin': 'sui' } }),\n\t);\n\n// ---------------------------------------------------------------------------\n// Image resolution — vendored Dockerfile build via `ContainerRuntime`\n// ---------------------------------------------------------------------------\n\nexport const resolveImage = (\n\truntime: ContainerRuntime,\n\topts: SuiLocalOptions,\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 local 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 local 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 version = opts.version ?? DEFAULT_SUI_VERSION;\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_VERSION: version },\n\t\t\t\t\t}\n\t\t\t\t: suiCliImageBuildContext(version);\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 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.local.resolveImage'));\n\ninterface LocalValidatorContainerResult {\n\treadonly handle: ContainerHandle;\n\treadonly ports: ReadonlyArray<ContainerPortPublish>;\n}\n\ninterface ResolvedPortMapping {\n\treadonly ports: ReadonlyArray<ContainerPortPublish>;\n\treadonly release: Effect.Effect<void>;\n}\n\nexport const ensureLocalValidatorContainer = (\n\truntime: ContainerRuntime,\n\tportBroker: PortBroker,\n\timage: ImageRef,\n\tlabels: ContainerLabelTuple,\n\tcontainerName: string,\n\topts: SuiLocalOptions,\n): Effect.Effect<LocalValidatorContainerResult, SuiPluginError, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\tconst reusablePorts =\n\t\t\topts.ports === undefined\n\t\t\t\t? yield* findReusablePortMapping(runtime, labels, containerName)\n\t\t\t\t: undefined;\n\t\tif (reusablePorts !== undefined) {\n\t\t\treturn yield* ensureLocalValidatorContainerAttempt({\n\t\t\t\truntime,\n\t\t\t\tportBroker,\n\t\t\t\timage,\n\t\t\t\tlabels,\n\t\t\t\tcontainerName,\n\t\t\t\topts,\n\t\t\t\tports: reusablePorts,\n\t\t\t\tattempt: 0,\n\t\t\t\treconciliation: 'adopt-existing',\n\t\t\t});\n\t\t}\n\t\treturn yield* ensureLocalValidatorContainerWithFreshPorts({\n\t\t\truntime,\n\t\t\tportBroker,\n\t\t\timage,\n\t\t\tlabels,\n\t\t\tcontainerName,\n\t\t\topts,\n\t\t\tattempt: 0,\n\t\t\treconciliation: opts.ports ? 'exact' : 'adopt-existing',\n\t\t});\n\t});\n\ninterface EnsureLocalValidatorContainerBase {\n\treadonly runtime: ContainerRuntime;\n\treadonly portBroker: PortBroker;\n\treadonly image: ImageRef;\n\treadonly labels: ContainerLabelTuple;\n\treadonly containerName: string;\n\treadonly opts: SuiLocalOptions;\n}\n\nconst ensureLocalValidatorContainerWithFreshPorts = (\n\tparams: EnsureLocalValidatorContainerBase & {\n\t\treadonly attempt: number;\n\t\treadonly reconciliation: PortBindingReconciliation;\n\t},\n): Effect.Effect<LocalValidatorContainerResult, SuiPluginError, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\tconst mapping = yield* resolvePortMappingWithRelease(params.portBroker, params.opts.ports);\n\t\treturn yield* ensureLocalValidatorContainerAttempt({\n\t\t\t...params,\n\t\t\tports: mapping.ports,\n\t\t\treleasePorts: mapping.release,\n\t\t});\n\t});\n\nconst ensureLocalValidatorContainerAttempt = (\n\tparams: EnsureLocalValidatorContainerBase & {\n\t\treadonly ports: ReadonlyArray<ContainerPortPublish>;\n\t\treadonly releasePorts?: Effect.Effect<void>;\n\t\treadonly attempt: number;\n\t\treadonly reconciliation: PortBindingReconciliation;\n\t},\n): Effect.Effect<LocalValidatorContainerResult, SuiPluginError, Scope.Scope> =>\n\tensureManagedContainer({\n\t\truntime: params.runtime,\n\t\tlabels: params.labels,\n\t\tspec: {\n\t\t\tname: params.containerName,\n\t\t\timage: params.image,\n\t\t\t// Keep the writable layer only after clean exits. If Docker\n\t\t\t// escalates a previous stop to SIGKILL (137), resume can hang\n\t\t\t// in RocksDB/checkpoint recovery with no RPC/faucet probes.\n\t\t\t// `on-failure` routes that stale layer to recreate while still\n\t\t\t// warm-resuming normal exit 0 / 130 stops. The longer grace\n\t\t\t// gives the entrypoint's SIGINT forwarding time to drain.\n\t\t\trecreate: 'on-failure',\n\t\t\tstopGraceSeconds: LOCAL_VALIDATOR_STOP_GRACE_SECONDS,\n\t\t\tports: params.ports,\n\t\t\tportBindingReconciliation: params.reconciliation,\n\t\t},\n\t\tmapError: (cause) => cause,\n\t}).pipe(\n\t\tEffect.map((handle) => ({ handle, ports: params.ports })),\n\t\tEffect.catch((cause: ContainerRuntimeError) => {\n\t\t\tif (\n\t\t\t\tparams.opts.ports === undefined &&\n\t\t\t\tcause.reason === 'publish-port-conflict' &&\n\t\t\t\tparams.attempt < MAX_DOCKER_PUBLISH_PORT_RETRIES\n\t\t\t) {\n\t\t\t\treturn (params.releasePorts ?? Effect.void).pipe(\n\t\t\t\t\tEffect.andThen(\n\t\t\t\t\t\tensureLocalValidatorContainerWithFreshPorts({\n\t\t\t\t\t\t\t...params,\n\t\t\t\t\t\t\tattempt: params.attempt + 1,\n\t\t\t\t\t\t\treconciliation: 'exact',\n\t\t\t\t\t\t}),\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn Effect.fail(\n\t\t\t\tsuiPluginError(\n\t\t\t\t\t'container-start',\n\t\t\t\t\t`sui-validator 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);\n\n// ---------------------------------------------------------------------------\n// Port mapping — host:container pairs\n// ---------------------------------------------------------------------------\n\nexport const resolvePortMapping = (\n\tportBroker: PortBroker,\n\toverride: Readonly<Record<number, number>> | undefined,\n): Effect.Effect<ReadonlyArray<ContainerPortPublish>, SuiPluginError, Scope.Scope> =>\n\tresolvePortMappingWithRelease(portBroker, override).pipe(Effect.map((mapping) => mapping.ports));\n\nconst resolvePortMappingWithRelease = (\n\tportBroker: PortBroker,\n\toverride: Readonly<Record<number, number>> | undefined,\n): Effect.Effect<ResolvedPortMapping, SuiPluginError, Scope.Scope> => {\n\tconst pick = (containerPort: number, fallback: number): number => {\n\t\tif (!override) return fallback;\n\t\tconst hit = override[containerPort];\n\t\treturn typeof hit === 'number' ? hit : fallback;\n\t};\n\tif (override) {\n\t\treturn Effect.succeed({\n\t\t\tports: [\n\t\t\t\tportPublish(CONTAINER_RPC_PORT, pick(CONTAINER_RPC_PORT, DEFAULT_HOST_RPC_PORT)),\n\t\t\t\tportPublish(CONTAINER_FAUCET_PORT, pick(CONTAINER_FAUCET_PORT, DEFAULT_HOST_FAUCET_PORT)),\n\t\t\t\tportPublish(\n\t\t\t\t\tCONTAINER_GRAPHQL_PORT,\n\t\t\t\t\tpick(CONTAINER_GRAPHQL_PORT, DEFAULT_HOST_GRAPHQL_PORT),\n\t\t\t\t),\n\t\t\t],\n\t\t\trelease: Effect.void,\n\t\t});\n\t}\n\treturn Effect.gen(function* () {\n\t\tconst rpc = yield* allocatePort(portBroker, 'rpc', DEFAULT_HOST_RPC_PORT, 'rpc');\n\t\tconst faucet = yield* allocatePort(portBroker, 'http', DEFAULT_HOST_FAUCET_PORT, 'faucet');\n\t\tconst graphql = yield* allocatePort(portBroker, 'rpc', DEFAULT_HOST_GRAPHQL_PORT, 'graphql');\n\t\treturn {\n\t\t\tports: [\n\t\t\t\tportPublish(CONTAINER_RPC_PORT, rpc.port),\n\t\t\t\tportPublish(CONTAINER_FAUCET_PORT, faucet.port),\n\t\t\t\tportPublish(CONTAINER_GRAPHQL_PORT, graphql.port),\n\t\t\t],\n\t\t\trelease: Effect.all([rpc.release, faucet.release, graphql.release], { discard: true }),\n\t\t};\n\t});\n};\n\nexport const resolvePublishedPortMapping = (\n\trequested: ReadonlyArray<ContainerPortPublish>,\n\tactual: ReadonlyArray<ContainerPortPublish> | undefined,\n): ReadonlyArray<ContainerPortPublish> => [\n\tpickPublishedPort(requested, actual, CONTAINER_RPC_PORT, DEFAULT_HOST_RPC_PORT),\n\tpickPublishedPort(requested, actual, CONTAINER_FAUCET_PORT, DEFAULT_HOST_FAUCET_PORT),\n\tpickPublishedPort(requested, actual, CONTAINER_GRAPHQL_PORT, DEFAULT_HOST_GRAPHQL_PORT),\n];\n\nconst pickPublishedPort = (\n\trequested: ReadonlyArray<ContainerPortPublish>,\n\tactual: ReadonlyArray<ContainerPortPublish> | undefined,\n\tcontainerPort: number,\n\tfallbackHostPort: number,\n): ContainerPortPublish =>\n\tactual?.find((port) => port.containerPort === containerPort) ??\n\trequested.find((port) => port.containerPort === containerPort) ??\n\tportPublish(containerPort, fallbackHostPort);\n\nexport const selectReusablePortMapping = (\n\thandles: ReadonlyArray<ContainerHandle>,\n\tcontainerName: string,\n): ReadonlyArray<ContainerPortPublish> | undefined => {\n\tconst ports = handles.find((handle) => handle.name === containerName)?.ports;\n\tif (!hasSuiPortMapping(ports)) return undefined;\n\treturn resolvePublishedPortMapping([], ports);\n};\n\nconst findReusablePortMapping = (\n\truntime: ContainerRuntime,\n\tlabels: ContainerLabelTuple,\n\tcontainerName: string,\n): Effect.Effect<ReadonlyArray<ContainerPortPublish> | undefined, SuiPluginError> =>\n\truntime.inspectByLabels(labels).pipe(\n\t\tEffect.map((handles) => selectReusablePortMapping(handles, containerName)),\n\t\tEffect.mapError((cause) =>\n\t\t\tsuiPluginError(\n\t\t\t\t'container-start',\n\t\t\t\t`sui local mode: failed to inspect existing validator container: ${cause.reason}: ${cause.detail}`,\n\t\t\t\tcause,\n\t\t\t),\n\t\t),\n\t);\n\nconst hasSuiPortMapping = (\n\tports: ReadonlyArray<ContainerPortPublish> | undefined,\n): ports is ReadonlyArray<ContainerPortPublish> =>\n\tports !== undefined &&\n\tports.some((port) => port.containerPort === CONTAINER_RPC_PORT) &&\n\tports.some((port) => port.containerPort === CONTAINER_FAUCET_PORT) &&\n\tports.some((port) => port.containerPort === CONTAINER_GRAPHQL_PORT);\n\nconst portPublish = (containerPort: number, hostPort: number): ContainerPortPublish => ({\n\tcontainerPort,\n\thostPort,\n\thostIp: DOCKER_PUBLISH_HOST,\n});\n\nconst allocatePort = (\n\tportBroker: PortBroker,\n\tkind: PortKind,\n\tpreferredPort: number | undefined,\n\tlabel: 'rpc' | 'faucet' | 'graphql',\n): Effect.Effect<AllocatedPort, SuiPluginError, Scope.Scope> => {\n\tconst allocate = (\n\t\thint: number | undefined,\n\t): Effect.Effect<AllocatedPort, SuiPluginError, Scope.Scope> =>\n\t\tportBroker\n\t\t\t.allocate({\n\t\t\t\tkind,\n\t\t\t\t...(hint === undefined ? {} : { preferredPort: hint }),\n\t\t\t\tprobeHost: DOCKER_PUBLISH_HOST,\n\t\t\t})\n\t\t\t.pipe(\n\t\t\t\tEffect.catchTag('PortBrokerError', (cause) =>\n\t\t\t\t\thint !== undefined && cause.reason === 'preferred-busy'\n\t\t\t\t\t\t? portBroker.allocate({ kind, probeHost: DOCKER_PUBLISH_HOST })\n\t\t\t\t\t\t: Effect.fail(cause),\n\t\t\t\t),\n\t\t\t\tEffect.mapError((cause) =>\n\t\t\t\t\tsuiPluginError(\n\t\t\t\t\t\t'port-allocate',\n\t\t\t\t\t\t`sui local mode: failed to allocate ${label} host port ` +\n\t\t\t\t\t\t\t`(preferred ${hint ?? 'auto'}): ${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\treturn allocate(preferredPort);\n};\n\n// ---------------------------------------------------------------------------\n// Ready-probe coordination\n// ---------------------------------------------------------------------------\n\n/** Coordinated readiness gate. Both RPC + faucet must respond within\n *  the outer deadline; each probe has its own per-fetch deadline so a\n *  wedged endpoint surfaces by name. */\nconst waitForReady = (\n\trpcUrl: string,\n\tfaucetUrl: string,\n\tgraphqlUrl: string,\n\treadyTimeout: Duration.Duration,\n): Effect.Effect<void, SuiPluginError> =>\n\tEffect.gen(function* () {\n\t\tconst readyTimeoutMs = Duration.toMillis(readyTimeout);\n\t\tconst rpcProbe: Effect.Effect<void, SuiPluginError> = waitForHttpEndpoint({\n\t\t\tendpoint: rpcUrl,\n\t\t\ttimeoutMs: readyTimeoutMs,\n\t\t\tintervalMs: 1_000,\n\t\t\trequestTimeoutMs: PROBE_FETCH_TIMEOUT_MS,\n\t\t\trequestInit: {\n\t\t\t\tmethod: 'POST',\n\t\t\t\theaders: { 'content-type': 'application/json' },\n\t\t\t\tbody: JSON.stringify({\n\t\t\t\t\tjsonrpc: '2.0',\n\t\t\t\t\tid: 1,\n\t\t\t\t\tmethod: 'sui_getLatestCheckpointSequenceNumber',\n\t\t\t\t\tparams: [],\n\t\t\t\t}),\n\t\t\t},\n\t\t\tvalidate: async (response) => {\n\t\t\t\tif (!response.ok) return false;\n\t\t\t\tconst body = (await response.json()) as { readonly result?: unknown };\n\t\t\t\treturn typeof body.result === 'string' || typeof body.result === 'number';\n\t\t\t},\n\t\t}).pipe(\n\t\t\tEffect.mapError(\n\t\t\t\t(cause): SuiPluginError =>\n\t\t\t\t\tsuiPluginError(\n\t\t\t\t\t\t'rpc-probe',\n\t\t\t\t\t\t`sui local mode: RPC endpoint ${rpcUrl} did not become ready within ` +\n\t\t\t\t\t\t\t`${readyTimeoutMs}ms: ${stringifyCause(cause)}`,\n\t\t\t\t\t\tcause,\n\t\t\t\t\t),\n\t\t\t),\n\t\t\tEffect.withSpan('devstack.plugin.sui.local.probe.rpc'),\n\t\t);\n\n\t\t// Faucet socket-level liveness — `GET /` returns \"OK\" as soon as\n\t\t// the HTTP server is bound. We do NOT POST `/v2/gas` here; that's\n\t\t// the funds-ready probe, which is paid for lazily on first call.\n\t\tconst faucetProbe: Effect.Effect<void, SuiPluginError> = waitForHttpEndpoint({\n\t\t\tendpoint: faucetUrl,\n\t\t\ttimeoutMs: readyTimeoutMs,\n\t\t\tintervalMs: 1_000,\n\t\t\trequestTimeoutMs: PROBE_FETCH_TIMEOUT_MS,\n\t\t\tvalidate: (response) => response.status < 500,\n\t\t}).pipe(\n\t\t\tEffect.mapError(\n\t\t\t\t(cause): SuiPluginError =>\n\t\t\t\t\tsuiPluginError(\n\t\t\t\t\t\t'faucet-probe',\n\t\t\t\t\t\t`sui local mode: faucet endpoint ${faucetUrl} did not become ready within ` +\n\t\t\t\t\t\t\t`${readyTimeoutMs}ms: ${stringifyCause(cause)}`,\n\t\t\t\t\t\tcause,\n\t\t\t\t\t),\n\t\t\t),\n\t\t\tEffect.withSpan('devstack.plugin.sui.local.probe.faucet'),\n\t\t);\n\n\t\tconst graphqlProbe: Effect.Effect<void, SuiPluginError> = waitForHttpEndpoint({\n\t\t\tendpoint: graphqlUrl,\n\t\t\ttimeoutMs: readyTimeoutMs,\n\t\t\tintervalMs: 1_000,\n\t\t\trequestTimeoutMs: PROBE_FETCH_TIMEOUT_MS,\n\t\t\tvalidate: (response) => response.status < 500,\n\t\t}).pipe(\n\t\t\tEffect.mapError(\n\t\t\t\t(cause): SuiPluginError =>\n\t\t\t\t\tsuiPluginError(\n\t\t\t\t\t\t'graphql-probe',\n\t\t\t\t\t\t`sui local mode: GraphQL endpoint ${graphqlUrl} did not become ready within ` +\n\t\t\t\t\t\t\t`${readyTimeoutMs}ms: ${stringifyCause(cause)}`,\n\t\t\t\t\t\tcause,\n\t\t\t\t\t),\n\t\t\t),\n\t\t\tEffect.withSpan('devstack.plugin.sui.local.probe.graphql'),\n\t\t);\n\n\t\tyield* Effect.all([rpcProbe, faucetProbe, graphqlProbe], { concurrency: 'unbounded' }).pipe(\n\t\t\tEffect.asVoid,\n\t\t);\n\t}).pipe(Effect.withSpan('devstack.plugin.sui.local.waitForReady'));\n\n// Chain-id fetch + waitForTransactionsReady builders live in\n// `shared-boot.ts` — see imports at the top of this file.\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\nconst routedSuiUrl = (\n\tidentity: Identity,\n\tendpointName: string,\n\tport: number,\n): Effect.Effect<string, SuiPluginError> =>\n\trouterHostname(identity, endpointName).pipe(\n\t\tEffect.map((hostname) => renderUrl({ protocol: 'http', hostname, port })),\n\t\tEffect.mapError((cause) =>\n\t\t\tsuiPluginError(\n\t\t\t\t'container-start',\n\t\t\t\t`sui local mode: failed to construct router URL for ${endpointName}: ${cause.detail}`,\n\t\t\t\tcause,\n\t\t\t),\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":"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"}

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

@@ -0,0 +1,254 @@
+import { chainId } from "../../../substrate/brand.mjs";
+import { suiPluginError } from "../errors.mjs";
+import { waitForHttpEndpoint } from "../../../substrate/runtime/http-probe.mjs";
+import { makeSuiChainProbe } from "../chain-probe.mjs";
+import { toDockerHostGatewayUrl } from "./shared.mjs";
+import { Duration, Effect, Ref } from "effect";
+//#region src/plugins/sui/mode/shared-boot.ts
+/** Default chain-id fetch timeout. The wire latency is the dominant
+*  cost on real RPCs; 30 s is the documented ceiling. */
+const DEFAULT_CHAIN_ID_TIMEOUT = Duration.seconds(30);
+/** Fetch the chain identifier off a constructed grpc client. The
+*  result is the bare string that downstream cache layers fold into
+*  their state-store keys. */
+const fetchChainId = (sdkClient, opts) => {
+	const timeout = opts?.timeout ?? DEFAULT_CHAIN_ID_TIMEOUT;
+	const timeoutMs = Duration.toMillis(timeout);
+	return Effect.tryPromise({
+		try: (signal) => sdkClient.ledgerService.getServiceInfo({}, {
+			abort: signal,
+			timeout: timeoutMs
+		}).response.then((response) => {
+			if (!response.chainId) throw new Error("Chain identifier not found in service info");
+			return response.chainId;
+		}),
+		catch: (cause) => suiPluginError("chain-id-fetch", `sui chain-id fetch failed: ${stringifyCause(cause)}`, cause)
+	}).pipe(Effect.timeoutOrElse({
+		duration: timeout,
+		orElse: () => Effect.fail(suiPluginError("chain-id-fetch", `sui chain-id fetch did not respond within ${timeoutMs}ms`))
+	}), Effect.tap((id) => Effect.annotateCurrentSpan({ "sui.chain": id })), Effect.withSpan(opts?.span ?? "devstack.plugin.sui.fetchChainId"));
+};
+/** Per-attempt and total budget for the `waitForTransactionsReady`
+*  retry loop. The 2 s spacing matches the upstream sui-faucet's
+*  internal cadence; the 90 s ceiling matches the v3 service's
+*  documented wall-clock. */
+const FUNDS_READY_RETRY_SPACING = Duration.seconds(2);
+const FUNDS_READY_TIMEOUT = Duration.seconds(90);
+/** Per-fetch deadline for the faucet probe POST. Bounded short so
+*  the outer retry loop hammers quickly. */
+const PROBE_FETCH_TIMEOUT_MS = 3e3;
+/** Probe recipient for the faucet funds-ready check. A literal
+*  zero-balance address so the real call doesn't pollute caller wallets;
+*  any well-formed address works. */
+const FAUCET_PROBE_RECIPIENT = "0x0000000000000000000000000000000000000000000000000000000000000001";
+/**
+* Build the funds-transferable gate against a real HTTP faucet.
+* Memoised — first successful resolution sticks for the scope; the
+* manual `invalidate` surface clears the memo so long-running
+* supervisors can re-probe without a full restart.
+*/
+const buildWaitForTransactionsReady = (faucetUrl, opts) => Effect.gen(function* () {
+	const retrySpacing = opts?.retrySpacing ?? FUNDS_READY_RETRY_SPACING;
+	const timeout = opts?.timeout ?? FUNDS_READY_TIMEOUT;
+	const ref = yield* Ref.make(null);
+	const makeProbe = () => waitForHttpEndpoint({
+		endpoint: `${faucetUrl}/v2/gas`,
+		timeoutMs: Duration.toMillis(timeout),
+		intervalMs: Duration.toMillis(retrySpacing),
+		requestTimeoutMs: PROBE_FETCH_TIMEOUT_MS,
+		requestInit: {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({ FixedAmountRequest: { recipient: FAUCET_PROBE_RECIPIENT } })
+		},
+		validate: async (response) => {
+			if (!response.ok) throw new Error(`faucet HTTP ${response.status}`);
+			const status = (await response.json()).status;
+			if (typeof status === "object" && status !== null && "Failure" in status) {
+				const failure = status.Failure;
+				throw new Error(`faucet body: Failure ${JSON.stringify(failure)}`);
+			}
+			return true;
+		}
+	}).pipe(Effect.mapError((cause) => suiPluginError("wait-funds-ready", `sui faucet at ${faucetUrl} did not become funds-transferable within ${Duration.toMillis(timeout)}ms (still returning body-level Failure or 5xx): ` + stringifyCause(cause), cause)));
+	return {
+		wait: Effect.gen(function* () {
+			const existing = yield* Ref.get(ref);
+			if (existing !== null) return existing;
+			const cached = yield* Effect.cached(makeProbe());
+			yield* Ref.set(ref, cached);
+			return cached;
+		}).pipe(Effect.flatMap((eff) => eff)),
+		invalidate: Ref.set(ref, null)
+	};
+});
+/** Trivially-succeeding gate. Used by faucet-less networks (live
+*  mainnet, fork — fork funds via impersonation, not HTTP). */
+const noopWaitForTransactionsReady = {
+	wait: Effect.void,
+	invalidate: Effect.void
+};
+const SUI_RPC_READ_TIMEOUT_MS = 1e4;
+const postJsonRpc = async (rpcUrl, method, params) => {
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), SUI_RPC_READ_TIMEOUT_MS);
+	timeout.unref?.();
+	try {
+		const response = await fetch(rpcUrl, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({
+				jsonrpc: "2.0",
+				id: 1,
+				method,
+				params
+			}),
+			signal: controller.signal
+		});
+		if (!response.ok) throw new Error(`Sui RPC HTTP ${response.status}`);
+		const payload = await response.json();
+		if (payload.error !== void 0) throw new Error(payload.error.message ?? JSON.stringify(payload.error));
+		if (payload.result === void 0) throw new Error(`Sui RPC ${method} returned no result`);
+		return payload.result;
+	} finally {
+		clearTimeout(timeout);
+	}
+};
+const normalizeJsonOwner = (owner) => {
+	if (owner === "Immutable") return {
+		$kind: "Immutable",
+		Immutable: true
+	};
+	if (typeof owner !== "object" || owner === null) return {
+		$kind: "Unknown",
+		Unknown: owner
+	};
+	const record = owner;
+	if (typeof record.AddressOwner === "string") return {
+		$kind: "AddressOwner",
+		AddressOwner: record.AddressOwner
+	};
+	if (record.ObjectOwner !== void 0) return {
+		$kind: "Parent",
+		Parent: record.ObjectOwner
+	};
+	if (record.Shared !== void 0) {
+		const initialSharedVersion = record.Shared.initialSharedVersion ?? record.Shared.initial_shared_version;
+		return {
+			$kind: "Shared",
+			Shared: { initialSharedVersion: String(initialSharedVersion) }
+		};
+	}
+	if (record.ConsensusAddressOwner !== void 0) return {
+		$kind: "ConsensusAddressOwner",
+		ConsensusAddressOwner: record.ConsensusAddressOwner
+	};
+	return {
+		$kind: "Unknown",
+		Unknown: owner
+	};
+};
+const getObjectViaJsonRpc = async (rpcUrl, args) => {
+	const showContent = args.include?.content === true || args.include?.json === true;
+	const data = (await postJsonRpc("" + rpcUrl, "sui_getObject", [args.objectId, {
+		showType: true,
+		showOwner: true,
+		showContent
+	}])).data;
+	if (data?.objectId === void 0) throw new Error(`object ${args.objectId} not found`);
+	const object = {
+		objectId: data.objectId,
+		version: String(data.version ?? ""),
+		type: data.type ?? "unknown",
+		owner: normalizeJsonOwner(data.owner),
+		...args.include?.json === true ? { json: data.content?.fields } : {},
+		...args.include?.content === true ? { content: data.content } : {}
+	};
+	return {
+		...object,
+		object
+	};
+};
+/** Build the `SuiSdkShim` over a constructed grpc client.
+*  Account/Coin/Wallet read through this seam, so we expose
+*  `executeTransaction` + `waitForTransaction` in addition to the
+*  read methods needed by the chain probe. */
+const makeSdkShim = (sdkClient, rpcUrl) => ({
+	core: {
+		getObject: (args) => getObjectViaJsonRpc(rpcUrl, args),
+		getTransaction: (args) => sdkClient.core.getTransaction(args),
+		getBalance: (args) => sdkClient.core.getBalance(args),
+		listCoins: (args) => sdkClient.core.listCoins(args),
+		executeTransaction: (args) => sdkClient.executeTransaction({
+			transaction: args.transaction,
+			signatures: [...args.signatures],
+			...args.include !== void 0 ? { include: args.include } : {}
+		}),
+		waitForTransaction: (args) => sdkClient.waitForTransaction({
+			digest: args.digest,
+			...args.timeout !== void 0 ? { timeout: args.timeout } : {}
+		})
+	},
+	client: sdkClient
+});
+/** Assemble a `SuiClient` from the per-mode building blocks. The
+*  `fork: null` discriminator is invariant for non-fork modes; the
+*  fork builder constructs its own client with the admin surface.
+*
+*  `chain` is accepted as a bare string and branded to `ChainId` at
+*  this single boundary — every consumer downstream reads the
+*  branded shape so capability-key constructors (`chainProbe…`,
+*  `faucet…`) accept it without a cast. */
+const assembleSuiClient = (parts) => {
+	const sdkShim = makeSdkShim(parts.sdkClient, parts.sdkRpcUrl ?? parts.rpcUrl);
+	const chainProbe = makeSuiChainProbe(sdkShim, parts.chain);
+	return {
+		client: {
+			sdk: sdkShim,
+			rpcUrl: parts.rpcUrl,
+			faucetUrl: parts.faucetUrl ?? null,
+			fundingFaucetUrl: parts.fundingFaucetUrl ?? parts.faucetUrl ?? null,
+			graphqlUrl: parts.graphqlUrl ?? null,
+			hostGateway: parts.hostGateway ?? {
+				rpcUrl: toDockerHostGatewayUrl(parts.rpcUrl),
+				faucetUrl: parts.faucetUrl === void 0 ? null : toDockerHostGatewayUrl(parts.faucetUrl),
+				graphqlUrl: parts.graphqlUrl === void 0 ? null : toDockerHostGatewayUrl(parts.graphqlUrl)
+			},
+			chain: chainId(parts.chain),
+			waitForTransactionsReady: parts.waitForTransactionsReady,
+			chainProbe,
+			fork: null,
+			buildImage: parts.buildImage ?? null
+		},
+		sdkShim,
+		chainProbe
+	};
+};
+/** Shape the resolved network record the boot builders all hand
+*  back. The substrate-network mapping is uniform per mode. Brands
+*  the raw chain string at this boundary so consumers downstream
+*  (codegen, capabilities, walrus/seal deps) read a `ChainId` and
+*  don't re-wrap. */
+const makeResolvedNetwork = (parts) => ({
+	mode: parts.mode,
+	chain: chainId(parts.chain),
+	rpc: parts.rpc,
+	source: parts.source,
+	...parts.faucet !== void 0 ? { faucet: parts.faucet } : {},
+	...parts.graphql !== void 0 ? { graphql: parts.graphql } : {},
+	...parts.checkpoint !== void 0 ? { checkpoint: parts.checkpoint } : {},
+	...parts.forkUpstream !== void 0 ? { forkUpstream: parts.forkUpstream } : {}
+});
+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 { assembleSuiClient, buildWaitForTransactionsReady, fetchChainId, makeResolvedNetwork, noopWaitForTransactionsReady };
+
+//# sourceMappingURL=shared-boot.mjs.map