@mysten-incubation/devstack 0.0.0

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

@@ -0,0 +1,38 @@
+import { ConfigIssue } from "../../substrate/runtime/config-validation.mjs";
+import { ForkIncompatibleError } from "../../substrate/runtime/mode-errors.mjs";
+
+//#region src/plugins/walrus/errors.d.ts
+/** Phases for `WalrusError`. Closed sum — keeps the cause-walker's
+ *  display table small. Matches the closed `WalrusPhases` from the
+ *  distilled doc §"Cross-component references" except `'network'`
+ *  is dropped (the substrate's `ContainerRuntime` owns docker network
+ *  creation now, so its errors surface as `ContainerRuntimeError`
+ *  upstream — we narrate the *phase* as `'cluster-network'` but the
+ *  fault tags through the substrate). */
+type WalrusPhase = 'image-build' | 'cluster-network' | 'deploy' | 'exchange' | 'storage-node' | 'proxy' | 'fund-wal' | 'register-known';
+/** Generic Walrus plugin error. Raised by the plugin's acquire
+ *  body, WAL funding strategy, and the per-mode builders. */
+interface WalrusPluginError {
+  readonly _tag: 'WalrusPluginError';
+  readonly phase: WalrusPhase;
+  readonly message: string;
+  readonly cause?: unknown;
+  /** Optional sub-process capture envelope — populated for deploy
+   *  one-shot + per-node container failures. */
+  readonly stderr?: string;
+  readonly stdout?: string;
+  readonly exitCode?: number;
+}
+/** Configuration error — synchronous factory-time guards
+ *  (`nodeCount >= 1`, `shards >= nodeCount`, missing required
+ *  fields on `.known(...)`). Surfaces as a thrown `Error` shaped
+ *  like this in the factory, mirroring the distilled-doc behavior
+ *  of synchronous configuration faults. */
+interface WalrusConfigError extends ConfigIssue {
+  readonly _tag: 'WalrusConfigError';
+}
+/** Union of every error a Walrus-plugin caller may encounter. */
+type WalrusError = WalrusPluginError | ForkIncompatibleError | WalrusConfigError;
+//#endregion
+export { WalrusConfigError, WalrusError, WalrusPhase, WalrusPluginError };
+//# sourceMappingURL=errors.d.mts.map

package/dist/plugins/walrus/errors.mjs

@@ -0,0 +1,26 @@
+import { defineConfigError } from "../../substrate/runtime/config-validation.mjs";
+//#region src/plugins/walrus/errors.ts
+const walrusPluginError = (phase, message, parts = {}) => ({
+	_tag: "WalrusPluginError",
+	phase,
+	message,
+	...parts
+});
+const makeWalrusConfigError = defineConfigError("WalrusConfigError");
+const walrusConfigError = (field, message, hint, cause) => makeWalrusConfigError({
+	field,
+	message,
+	hint,
+	cause
+});
+/** Error tags this plugin contributes — surfaced to the cause
+*  walker via `PluginErrorContribution`. */
+const WALRUS_ERROR_TAGS = [
+	"WalrusPluginError",
+	"ForkIncompatibleError",
+	"WalrusConfigError"
+];
+//#endregion
+export { WALRUS_ERROR_TAGS, walrusConfigError, walrusPluginError };
+
+//# sourceMappingURL=errors.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../../src/plugins/walrus/errors.ts"],"sourcesContent":["// Walrus plugin — typed errors.\n//\n// Errors raised and consumed inside the Walrus plugin live here.\n// Cross-service errors that Walrus *consumes* but the substrate\n// raises (e.g. `ArtifactPublishError`) come from the substrate's\n// primitive — we don't redeclare those.\n//\n// `ForkIncompatibleError` is a cross-cutting mode-refusal shape\n// owned by `substrate/runtime/mode-errors.ts`; walrus contributes\n// the `walrusLocalCluster` variant via the factory below.\n//\n// Effect v4: plain interfaces with `_tag` discriminator (per\n// surrounding subsystem style). `Effect.catchTag` matches on `_tag`.\n\nimport { ForkIncompatibleError } from '../../substrate/runtime/mode-errors.ts';\nimport { defineConfigError, type ConfigIssue } from '../../substrate/runtime/config-validation.ts';\n\nexport { ForkIncompatibleError };\n\n/** Phases for `WalrusError`. Closed sum — keeps the cause-walker's\n *  display table small. Matches the closed `WalrusPhases` from the\n *  distilled doc §\"Cross-component references\" except `'network'`\n *  is dropped (the substrate's `ContainerRuntime` owns docker network\n *  creation now, so its errors surface as `ContainerRuntimeError`\n *  upstream — we narrate the *phase* as `'cluster-network'` but the\n *  fault tags through the substrate). */\nexport type WalrusPhase =\n\t| 'image-build'\n\t| 'cluster-network'\n\t| 'deploy'\n\t| 'exchange'\n\t| 'storage-node'\n\t| 'proxy'\n\t| 'fund-wal'\n\t| 'register-known';\n\n/** Generic Walrus plugin error. Raised by the plugin's acquire\n *  body, WAL funding strategy, and the per-mode builders. */\nexport interface WalrusPluginError {\n\treadonly _tag: 'WalrusPluginError';\n\treadonly phase: WalrusPhase;\n\treadonly message: string;\n\treadonly cause?: unknown;\n\t/** Optional sub-process capture envelope — populated for deploy\n\t *  one-shot + per-node container failures. */\n\treadonly stderr?: string;\n\treadonly stdout?: string;\n\treadonly exitCode?: number;\n}\n\nexport const walrusPluginError = (\n\tphase: WalrusPhase,\n\tmessage: string,\n\tparts: Omit<WalrusPluginError, '_tag' | 'phase' | 'message'> = {},\n): WalrusPluginError => ({ _tag: 'WalrusPluginError', phase, message, ...parts });\n\n/**\n * Synchronous factory-time refusal when the user explicitly composes\n * the local-cluster mode against a fork network.\n *\n * sui-fork doesn't expose JSON-RPC; the local cluster's storage\n * nodes need JSON-RPC against the chain. Letting the supervisor\n * partway through the image build before the nodes fail to dial\n * would be confusing — we refuse synchronously at factory time\n * with an actionable hint pointing at `walrusFor(network).known({...})`.\n *\n * Primary refusal is TYPE-LEVEL via the `walrusFor(network).<mode>`\n * mode-narrowed namespace — fork networks expose only `.known`, so\n * calling `.local` is a compile error. This runtime shape is\n * defense-in-depth for callers that sneak through dynamic dispatch.\n */\nexport const forkIncompatibleError = (network: string): ForkIncompatibleError =>\n\tnew ForkIncompatibleError({\n\t\tvariant: 'walrusLocalCluster',\n\t\tnetwork,\n\t\tmessage: `walrus local-cluster does not support fork networks.`,\n\t\thint:\n\t\t\t`walrus local-cluster requires JSON-RPC, which sui-fork does not expose. ` +\n\t\t\t`Use walrusFor(network).known({...}) instead.`,\n\t});\n\n/** Configuration error — synchronous factory-time guards\n *  (`nodeCount >= 1`, `shards >= nodeCount`, missing required\n *  fields on `.known(...)`). Surfaces as a thrown `Error` shaped\n *  like this in the factory, mirroring the distilled-doc behavior\n *  of synchronous configuration faults. */\nexport interface WalrusConfigError extends ConfigIssue {\n\treadonly _tag: 'WalrusConfigError';\n}\n\nconst makeWalrusConfigError = defineConfigError('WalrusConfigError');\n\nexport const walrusConfigError = (\n\tfield: string,\n\tmessage: string,\n\thint?: string,\n\tcause?: unknown,\n): WalrusConfigError => makeWalrusConfigError({ field, message, hint, cause });\n\n/** Union of every error a Walrus-plugin caller may encounter. */\nexport type WalrusError = WalrusPluginError | ForkIncompatibleError | WalrusConfigError;\n\n/** Error tags this plugin contributes — surfaced to the cause\n *  walker via `PluginErrorContribution`. */\nexport const WALRUS_ERROR_TAGS: ReadonlyArray<WalrusError['_tag']> = [\n\t'WalrusPluginError',\n\t'ForkIncompatibleError',\n\t'WalrusConfigError',\n] as const;\n"],"mappings":";;AAkDA,MAAa,qBACZ,OACA,SACA,QAA+D,EAAE,MACzC;CAAE,MAAM;CAAqB;CAAO;CAAS,GAAG;CAAO;AAoChF,MAAM,wBAAwB,kBAAkB,oBAAoB;AAEpE,MAAa,qBACZ,OACA,SACA,MACA,UACuB,sBAAsB;CAAE;CAAO;CAAS;CAAM;CAAO,CAAC;;;AAO9E,MAAa,oBAAwD;CACpE;CACA;CACA;CACA"}

package/dist/plugins/walrus/faucet-strategy.d.mts

@@ -0,0 +1,12 @@
+import { AccountFundingStrategy } from "../account/funding.mjs";
+import { WalrusPluginError } from "./errors.mjs";
+import { Effect } from "effect";
+
+//#region src/plugins/walrus/faucet-strategy.d.ts
+/** Faucet strategy value — closed over the WAL exchange's object id.
+ *  The requesting account signs the swap through the shared account
+ *  funding pipeline. */
+type WalFaucetStrategy = AccountFundingStrategy<WalrusPluginError>;
+//#endregion
+export { WalFaucetStrategy };
+//# sourceMappingURL=faucet-strategy.d.mts.map

package/dist/plugins/walrus/faucet-strategy.mjs

@@ -0,0 +1,62 @@
+import { walrusPluginError } from "./errors.mjs";
+import { swapAccountSuiForWal } from "./wal-swap.mjs";
+import { Effect, Schema } from "effect";
+//#region src/plugins/walrus/faucet-strategy.ts
+/** Full local WAL coin type derived from the deployed Walrus package. */
+const walCoinType = (packageId) => `${packageId}::wal::WAL`;
+/** Resolve the package id that defines `wal::WAL`.
+*
+*  The Walrus deploy summary's `package_id` can be the latest upgraded
+*  Walrus package, while Sui coin types use the original package id
+*  that defines `wal::WAL`. The protected treasury object is the
+*  reliable on-chain anchor for that original id. */
+const parseWalCoinTypeFromTreasuryType = (treasuryType) => {
+	const protectedTreasury = /^(0x[0-9a-fA-F]+)::wal::ProtectedTreasury$/.exec(treasuryType);
+	if (protectedTreasury?.[1] !== void 0) return walCoinType(protectedTreasury[1]);
+	const treasuryCap = /^0x(?:0+)?2::coin::TreasuryCap<((0x[0-9a-fA-F]+)::wal::WAL)>$/.exec(treasuryType);
+	if (treasuryCap?.[1] !== void 0) return treasuryCap[1];
+	return null;
+};
+const walPackageIdFromCoinType = (fullCoinType) => fullCoinType.split("::")[0];
+const WalTreasuryObjectShape = Schema.Struct({
+	objectId: Schema.String,
+	type: Schema.String
+});
+const resolveWalCoinType = (args) => Effect.gen(function* () {
+	if (args.treasuryObjectId === void 0) {
+		if (!args.requireTreasuryObject) return walCoinType(args.deployPackageId);
+		return yield* Effect.fail(walrusPluginError("exchange", "walrus.exchange: WAL exchange funding requires treasury_object in walrus deploy output so the original WAL coin type can be resolved."));
+	}
+	const found = yield* args.probe.get({
+		kind: "object",
+		objectId: args.treasuryObjectId
+	}, WalTreasuryObjectShape, "lenient").pipe(Effect.mapError((cause) => walrusPluginError("exchange", `walrus.exchange: failed to resolve WAL treasury object ${args.treasuryObjectId}: ${cause.reason}: ${cause.detail}`, { cause })));
+	if (found === null) {
+		if (!args.requireTreasuryObject) return walCoinType(args.deployPackageId);
+		return yield* Effect.fail(walrusPluginError("exchange", `walrus.exchange: WAL treasury object ${args.treasuryObjectId} was not found; cannot derive the WAL coin type for account funding.`));
+	}
+	const parsed = parseWalCoinTypeFromTreasuryType(found.type);
+	if (parsed !== null) return parsed;
+	return yield* Effect.fail(walrusPluginError("exchange", `walrus.exchange: unexpected WAL treasury object type "${found.type}" — expected "<pkg>::wal::ProtectedTreasury" or "0x2::coin::TreasuryCap<<pkg>::wal::WAL>".`));
+});
+/** Capability key for the WAL faucet strategy. */
+const walFaucetStrategyKey = (fullCoinType) => `coinType:${fullCoinType}`;
+/** Build the strategy value.
+*
+*  The request amount is the SUI MIST amount to spend on the local
+*  exchange for WAL. Account funding skips zero amounts before the
+*  strategy is invoked; the guard here keeps direct calls no-op. */
+const makeWalFaucetStrategy = (opts) => ({
+	usesAccountSigner: true,
+	request: (req) => req.amount <= 0n ? Effect.void : swapAccountSuiForWal({
+		account: req.account,
+		sdk: opts.sdk,
+		exchange: opts.exchange,
+		recipientAddress: req.address,
+		paymentMist: req.amount
+	}).pipe(Effect.asVoid)
+});
+//#endregion
+export { makeWalFaucetStrategy, resolveWalCoinType, walCoinType, walFaucetStrategyKey, walPackageIdFromCoinType };
+
+//# sourceMappingURL=faucet-strategy.mjs.map

package/dist/plugins/walrus/faucet-strategy.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"faucet-strategy.mjs","names":[],"sources":["../../../src/plugins/walrus/faucet-strategy.ts"],"sourcesContent":["// Walrus WAL faucet strategy.\n//\n// Distilled-doc reference (06-walrus.md §\"Lifecycle phase 7a\"):\n// when the local cluster has a non-empty `exchange`, walrus registers\n// a WAL exchange strategy on the global strategy registry so any\n// `account('alice', { funding: [{ coin: wal, amount }] })` request\n// gets satisfied via SUI → WAL swap on chain.\n//\n// Architecture (StrategyContributor §7): the faucet registry is\n// `capabilityKey: 'coinType:<fullCoinType>'` (distilled-doc\n// convention shared with the faucet plugin's domain:discriminator\n// pattern). The dispatch site doesn't import this strategy — it\n// looks it up by key.\n//\nimport { Effect, Schema } from 'effect';\n\nimport type { ChainProbe } from '../../contracts/chain-probe.ts';\nimport type { StrategyContributorDecl } from '../../contracts/strategy-contributor.ts';\nimport type { AccountFundingRequest, AccountFundingStrategy } from '../account/index.ts';\nimport { walrusPluginError, type WalrusPluginError } from './errors.ts';\nimport type { WalExchangeProbeKey } from './wal-swap.ts';\nimport { swapAccountSuiForWal, type WalExchangeHandle, type WalSwapSdk } from './wal-swap.ts';\n\n/** Full local WAL coin type derived from the deployed Walrus package. */\nexport const walCoinType = <PackageId extends string>(\n\tpackageId: PackageId,\n): `${PackageId}::wal::WAL` => `${packageId}::wal::WAL` as const;\n\n/** Resolve the package id that defines `wal::WAL`.\n *\n *  The Walrus deploy summary's `package_id` can be the latest upgraded\n *  Walrus package, while Sui coin types use the original package id\n *  that defines `wal::WAL`. The protected treasury object is the\n *  reliable on-chain anchor for that original id. */\nexport const parseWalCoinTypeFromTreasuryType = (\n\ttreasuryType: string,\n): `${string}::wal::WAL` | null => {\n\tconst protectedTreasury = /^(0x[0-9a-fA-F]+)::wal::ProtectedTreasury$/.exec(treasuryType);\n\tif (protectedTreasury?.[1] !== undefined) {\n\t\treturn walCoinType(protectedTreasury[1]);\n\t}\n\n\tconst treasuryCap = /^0x(?:0+)?2::coin::TreasuryCap<((0x[0-9a-fA-F]+)::wal::WAL)>$/.exec(\n\t\ttreasuryType,\n\t);\n\tif (treasuryCap?.[1] !== undefined) {\n\t\treturn treasuryCap[1] as `${string}::wal::WAL`;\n\t}\n\n\treturn null;\n};\n\nexport const walPackageIdFromCoinType = (fullCoinType: `${string}::wal::WAL`): string =>\n\tfullCoinType.split('::')[0]!;\n\nconst WalTreasuryObjectShape = Schema.Struct({\n\tobjectId: Schema.String,\n\ttype: Schema.String,\n});\n\nexport const resolveWalCoinType = (args: {\n\treadonly probe: ChainProbe<WalExchangeProbeKey>;\n\treadonly treasuryObjectId: string | undefined;\n\treadonly deployPackageId: string;\n\treadonly requireTreasuryObject: boolean;\n}): Effect.Effect<`${string}::wal::WAL`, WalrusPluginError> =>\n\tEffect.gen(function* () {\n\t\tif (args.treasuryObjectId === undefined) {\n\t\t\tif (!args.requireTreasuryObject) return walCoinType(args.deployPackageId);\n\t\t\treturn yield* Effect.fail(\n\t\t\t\twalrusPluginError(\n\t\t\t\t\t'exchange',\n\t\t\t\t\t'walrus.exchange: WAL exchange funding requires treasury_object in walrus deploy output so the original WAL coin type can be resolved.',\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\n\t\tconst found = yield* args.probe\n\t\t\t.get({ kind: 'object', objectId: args.treasuryObjectId }, WalTreasuryObjectShape, 'lenient')\n\t\t\t.pipe(\n\t\t\t\tEffect.mapError((cause) =>\n\t\t\t\t\twalrusPluginError(\n\t\t\t\t\t\t'exchange',\n\t\t\t\t\t\t`walrus.exchange: failed to resolve WAL treasury object ${args.treasuryObjectId}: ${cause.reason}: ${cause.detail}`,\n\t\t\t\t\t\t{ cause },\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t);\n\n\t\tif (found === null) {\n\t\t\tif (!args.requireTreasuryObject) return walCoinType(args.deployPackageId);\n\t\t\treturn yield* Effect.fail(\n\t\t\t\twalrusPluginError(\n\t\t\t\t\t'exchange',\n\t\t\t\t\t`walrus.exchange: WAL treasury object ${args.treasuryObjectId} was not found; cannot derive the WAL coin type for account funding.`,\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\n\t\tconst parsed = parseWalCoinTypeFromTreasuryType(found.type);\n\t\tif (parsed !== null) return parsed;\n\n\t\treturn yield* Effect.fail(\n\t\t\twalrusPluginError(\n\t\t\t\t'exchange',\n\t\t\t\t`walrus.exchange: unexpected WAL treasury object type \"${found.type}\" — expected \"<pkg>::wal::ProtectedTreasury\" or \"0x2::coin::TreasuryCap<<pkg>::wal::WAL>\".`,\n\t\t\t),\n\t\t);\n\t});\n\n/** Capability key for the WAL faucet strategy. */\nexport const walFaucetStrategyKey = <FullCoinType extends string>(\n\tfullCoinType: FullCoinType,\n): `coinType:${FullCoinType}` => `coinType:${fullCoinType}` as const;\n\n/** Per-request shape — the shared account funding request. */\nexport type WalFaucetRequest = AccountFundingRequest;\n\n/** Faucet strategy value — closed over the WAL exchange's object id.\n *  The requesting account signs the swap through the shared account\n *  funding pipeline. */\nexport type WalFaucetStrategy = AccountFundingStrategy<WalrusPluginError>;\n\n/** Inputs the local-cluster mode passes when constructing this. */\nexport interface WalFaucetStrategyOptions {\n\treadonly exchange: WalExchangeHandle;\n\treadonly sdk: WalSwapSdk;\n}\n\n/** Build the strategy value.\n *\n *  The request amount is the SUI MIST amount to spend on the local\n *  exchange for WAL. Account funding skips zero amounts before the\n *  strategy is invoked; the guard here keeps direct calls no-op. */\nexport const makeWalFaucetStrategy = (opts: WalFaucetStrategyOptions): WalFaucetStrategy => ({\n\tusesAccountSigner: true,\n\trequest: (req) =>\n\t\treq.amount <= 0n\n\t\t\t? Effect.void\n\t\t\t: swapAccountSuiForWal({\n\t\t\t\t\taccount: req.account,\n\t\t\t\t\tsdk: opts.sdk,\n\t\t\t\t\texchange: opts.exchange,\n\t\t\t\t\trecipientAddress: req.address,\n\t\t\t\t\tpaymentMist: req.amount,\n\t\t\t\t}).pipe(Effect.asVoid),\n});\n\n/** Build the StrategyContributor decl. The faucet plugin's\n *  dispatcher reads this key off the registry and dispatches WAL\n *  funding requests through it. */\nexport const makeWalFaucetContribution = (\n\tfullCoinType: string,\n\topts: WalFaucetStrategyOptions,\n): StrategyContributorDecl<ReturnType<typeof walFaucetStrategyKey>, WalFaucetStrategy> => ({\n\tkind: 'strategy-contributor',\n\tcapabilityKey: walFaucetStrategyKey(fullCoinType),\n\tstrategy: makeWalFaucetStrategy(opts),\n\tautoMounted: true,\n});\n"],"mappings":";;;;;AAwBA,MAAa,eACZ,cAC8B,GAAG,UAAU;;;;;;;AAQ5C,MAAa,oCACZ,iBACkC;CAClC,MAAM,oBAAoB,6CAA6C,KAAK,aAAa;AACzF,KAAI,oBAAoB,OAAO,KAAA,EAC9B,QAAO,YAAY,kBAAkB,GAAG;CAGzC,MAAM,cAAc,gEAAgE,KACnF,aACA;AACD,KAAI,cAAc,OAAO,KAAA,EACxB,QAAO,YAAY;AAGpB,QAAO;;AAGR,MAAa,4BAA4B,iBACxC,aAAa,MAAM,KAAK,CAAC;AAE1B,MAAM,yBAAyB,OAAO,OAAO;CAC5C,UAAU,OAAO;CACjB,MAAM,OAAO;CACb,CAAC;AAEF,MAAa,sBAAsB,SAMlC,OAAO,IAAI,aAAa;AACvB,KAAI,KAAK,qBAAqB,KAAA,GAAW;AACxC,MAAI,CAAC,KAAK,sBAAuB,QAAO,YAAY,KAAK,gBAAgB;AACzE,SAAO,OAAO,OAAO,KACpB,kBACC,YACA,wIACA,CACD;;CAGF,MAAM,QAAQ,OAAO,KAAK,MACxB,IAAI;EAAE,MAAM;EAAU,UAAU,KAAK;EAAkB,EAAE,wBAAwB,UAAU,CAC3F,KACA,OAAO,UAAU,UAChB,kBACC,YACA,0DAA0D,KAAK,iBAAiB,IAAI,MAAM,OAAO,IAAI,MAAM,UAC3G,EAAE,OAAO,CACT,CACD,CACD;AAEF,KAAI,UAAU,MAAM;AACnB,MAAI,CAAC,KAAK,sBAAuB,QAAO,YAAY,KAAK,gBAAgB;AACzE,SAAO,OAAO,OAAO,KACpB,kBACC,YACA,wCAAwC,KAAK,iBAAiB,sEAC9D,CACD;;CAGF,MAAM,SAAS,iCAAiC,MAAM,KAAK;AAC3D,KAAI,WAAW,KAAM,QAAO;AAE5B,QAAO,OAAO,OAAO,KACpB,kBACC,YACA,yDAAyD,MAAM,KAAK,4FACpE,CACD;EACA;;AAGH,MAAa,wBACZ,iBACgC,YAAY;;;;;;AAqB7C,MAAa,yBAAyB,UAAuD;CAC5F,mBAAmB;CACnB,UAAU,QACT,IAAI,UAAU,KACX,OAAO,OACP,qBAAqB;EACrB,SAAS,IAAI;EACb,KAAK,KAAK;EACV,UAAU,KAAK;EACf,kBAAkB,IAAI;EACtB,aAAa,IAAI;EACjB,CAAC,CAAC,KAAK,OAAO,OAAO;CACzB"}

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

@@ -0,0 +1,177 @@
+import { CodegenableDecl } from "../../contracts/codegenable.mjs";
+import { LivenessClassifierDecl } from "../../contracts/liveness-classifier.mjs";
+import { ProjectionDecl } from "../../contracts/projection.mjs";
+import { RoutableDecl } from "../../contracts/routable.mjs";
+import { SnapshotableDecl } from "../../contracts/snapshotable.mjs";
+import { StrategyContributorDecl } from "../../contracts/strategy-contributor.mjs";
+import { Plugin, ResourceRef } from "../../substrate/plugin.mjs";
+import { ModeNamespace } from "../../api/mode-narrowed-factory.mjs";
+import { SeedObjectsAccumulator } from "../sui/seed-objects.mjs";
+import { SuiClient } from "../sui/mode/shared.mjs";
+import { SuiOptions } from "../sui/mode/spec.mjs";
+import { AccountFundingCoinValue } from "../account/funding.mjs";
+import { ForkIncompatibleError } from "../../substrate/runtime/mode-errors.mjs";
+import { WalrusConfigError, WalrusError, WalrusPhase, WalrusPluginError } from "./errors.mjs";
+import { WalFaucetStrategy } from "./faucet-strategy.mjs";
+import { WalrusStorageNode } from "./storage-nodes.mjs";
+import { WalrusLocalClusterOptions } from "./mode/local-cluster.mjs";
+import { WalrusKnownDeploymentOptions, WalrusKnownNetwork } from "./mode/known-deploy.mjs";
+import { WalrusKnownStateEntry, WalrusLocalStateEntry, WalrusStateEntry } from "./registry-publish.mjs";
+import { WalrusBindings, WalrusNodeBinding } from "./codegen.mjs";
+//#region src/plugins/walrus/index.d.ts
+/** The Walrus resolved value carried by the resource. */
+interface WalrusResolved {
+  readonly mode: 'local' | 'known';
+  readonly chain: string;
+  readonly walrusPackageId: string | null;
+  readonly walPackageId: string | null;
+  /** SDK-ready `packageConfig` — structurally compatible with
+   *  `@mysten/walrus`'s `WalrusPackageConfig`. */
+  readonly packageConfig: {
+    readonly systemObjectId: string;
+    readonly stakingPoolId: string;
+    readonly exchangeIds?: ReadonlyArray<string>;
+  };
+  readonly nodes: ReadonlyArray<WalrusStorageNode>;
+  readonly proxyUrl: string | null;
+  readonly aggregatorUrl: string | null;
+  readonly publisherUrl: string | null;
+  readonly walFaucetStrategy: WalFaucetStrategy | null;
+  readonly walCoinType: string | null;
+}
+interface WalCoinValue extends AccountFundingCoinValue {
+  readonly symbol: 'WAL';
+  readonly fullCoinType: `${string}::wal::WAL`;
+  readonly decimals: 9;
+  readonly source: 'walrus';
+}
+/** Resolve the local Walrus deployment's WAL coin as an account-funding
+ *  coin ref. Accounts that need WAL should use:
+ *
+ *      funding: [{ coin: walCoin(localWalrus), amount }]
+ *
+ *  The funding strategy itself is contributed by the Walrus service
+ *  once its local exchange exists. */
+declare const walCoin: (walrusMember: ResourceRef<"walrus", WalrusResolved>) => Plugin<"coin:wal", WalCoinValue, readonly [ResourceRef<"walrus", WalrusResolved>], readonly ((Readonly<{
+  readonly kind: "snapshotable";
+} & Omit<SnapshotableDecl, "kind">> | Readonly<{
+  readonly kind: "routable";
+} & Omit<RoutableDecl, "kind">> | Readonly<{
+  readonly kind: "codegenable";
+} & Omit<CodegenableDecl<string>, "kind">> | Readonly<{
+  readonly kind: "projection";
+} & Omit<ProjectionDecl, "kind">> | Readonly<{
+  readonly kind: "strategy-contributor";
+} & Omit<StrategyContributorDecl<string, unknown>, "kind">> | Readonly<{
+  readonly kind: "liveness-classifier";
+} & Omit<LivenessClassifierDecl, "kind">>) | Readonly<{
+  readonly kind: string;
+} & object>)[]>;
+/** Local-cluster shorthand. Known deployments are selected through
+ *  `walrusFor(network).known(...)` so network choice stays explicit. */
+declare const walrus: (opts?: {
+  readonly local?: WalrusLocalClusterOptions;
+}) => Plugin<"walrus", WalrusResolved, readonly [ResourceRef<"sui", SuiClient & {
+  readonly mode: SuiOptions["mode"];
+  readonly seedObjects: SeedObjectsAccumulator;
+}>], readonly [SnapshotableDecl, CodegenableDecl<"walrus-network">, StrategyContributorDecl<"walrus-state-registry", {
+  readonly noteName: string;
+}>, ...(RoutableDecl | {
+  kind: "strategy-contributor";
+  capabilityKey: `coinType:${string}`;
+  strategy: WalFaucetStrategy;
+  autoMounted: true;
+})[]]>;
+/** Mode-narrowed factory namespace.
+ *
+ *  Usage:
+ *      const network = { mode: 'local', chain: 'sui:localnet' } as const;
+ *      walrusFor(network).local({...})    // OK
+ *      walrusFor(network).known({...})    // type error: 'known' not in 'local' branch
+ *
+ *  Critically, the fork branch exposes ONLY `.known` — calling
+ *  `.local` on a fork-mode network is a **compile error** at the
+ *  call site (distilled-doc invariant 12 — type-level refusal).
+ *  Runtime defense-in-depth: see `mode/fork-refusal.ts`. */
+declare const walrusFor: ModeNamespace<{
+  local: {
+    local: (opts?: WalrusLocalClusterOptions) => Plugin<"walrus", WalrusResolved, readonly [ResourceRef<"sui", SuiClient & {
+      readonly mode: SuiOptions["mode"];
+      readonly seedObjects: SeedObjectsAccumulator;
+    }>], readonly [SnapshotableDecl, CodegenableDecl<"walrus-network">, StrategyContributorDecl<"walrus-state-registry", {
+      readonly noteName: string;
+    }>, ...(RoutableDecl | {
+      kind: "strategy-contributor";
+      capabilityKey: `coinType:${string}`;
+      strategy: WalFaucetStrategy;
+      autoMounted: true;
+    })[]]>;
+    known: (opts: WalrusKnownDeploymentOptions) => Plugin<"walrus", {
+      mode: "known";
+      chain: string;
+      walrusPackageId: null;
+      walPackageId: null;
+      packageConfig: {
+        systemObjectId: string;
+        stakingPoolId: string;
+        exchangeIds: readonly string[] | undefined;
+      };
+      nodes: readonly WalrusStorageNode[];
+      proxyUrl: string | null;
+      aggregatorUrl: string | null;
+      publisherUrl: string | null;
+      walFaucetStrategy: null;
+      walCoinType: null;
+    }, readonly [ResourceRef<"sui", SuiClient & {
+      readonly mode: SuiOptions["mode"];
+      readonly seedObjects: SeedObjectsAccumulator;
+    }>], readonly [SnapshotableDecl, CodegenableDecl<"walrus-network">, StrategyContributorDecl<"walrus-state-registry", WalrusStateEntry>]>;
+  };
+  live: {
+    known: (opts: WalrusKnownDeploymentOptions) => Plugin<"walrus", {
+      mode: "known";
+      chain: string;
+      walrusPackageId: null;
+      walPackageId: null;
+      packageConfig: {
+        systemObjectId: string;
+        stakingPoolId: string;
+        exchangeIds: readonly string[] | undefined;
+      };
+      nodes: readonly WalrusStorageNode[];
+      proxyUrl: string | null;
+      aggregatorUrl: string | null;
+      publisherUrl: string | null;
+      walFaucetStrategy: null;
+      walCoinType: null;
+    }, readonly [ResourceRef<"sui", SuiClient & {
+      readonly mode: SuiOptions["mode"];
+      readonly seedObjects: SeedObjectsAccumulator;
+    }>], readonly [SnapshotableDecl, CodegenableDecl<"walrus-network">, StrategyContributorDecl<"walrus-state-registry", WalrusStateEntry>]>;
+  };
+  fork: {
+    known: (opts: WalrusKnownDeploymentOptions) => Plugin<"walrus", {
+      mode: "known";
+      chain: string;
+      walrusPackageId: null;
+      walPackageId: null;
+      packageConfig: {
+        systemObjectId: string;
+        stakingPoolId: string;
+        exchangeIds: readonly string[] | undefined;
+      };
+      nodes: readonly WalrusStorageNode[];
+      proxyUrl: string | null;
+      aggregatorUrl: string | null;
+      publisherUrl: string | null;
+      walFaucetStrategy: null;
+      walCoinType: null;
+    }, readonly [ResourceRef<"sui", SuiClient & {
+      readonly mode: SuiOptions["mode"];
+      readonly seedObjects: SeedObjectsAccumulator;
+    }>], readonly [SnapshotableDecl, CodegenableDecl<"walrus-network">, StrategyContributorDecl<"walrus-state-registry", WalrusStateEntry>]>;
+  };
+}>;
+//#endregion
+export { WalCoinValue, WalrusResolved, walCoin, walrus, walrusFor };
+//# sourceMappingURL=index.d.mts.map

package/dist/plugins/walrus/index.mjs

@@ -0,0 +1,284 @@
+import { definePlugin, resource } from "../../substrate/plugin.mjs";
+import { pluginErrorContributions } from "../../api/plugin-errors.mjs";
+import { IdentityContext, StackPathsService } from "../../substrate/runtime/paths.mjs";
+import { defineModeNamespace } from "../../api/mode-narrowed-factory.mjs";
+import { ContainerRuntimeService } from "../../runtime/docker/service.mjs";
+import { suiResource } from "../sui/index.mjs";
+import { ArtifactPublisherService } from "../../substrate/runtime/artifact-publisher/index.mjs";
+import { chainProbeFor } from "../../substrate/runtime/strategy-registry/chain-probe-for.mjs";
+import { WALRUS_ERROR_TAGS, walrusPluginError } from "./errors.mjs";
+import { buildWalrusNetworkName } from "./storage-nodes.mjs";
+import { makeLocalRoutables } from "./routable.mjs";
+import { coinResourceId } from "../coin/index.mjs";
+import { makeCodegenable } from "./codegen.mjs";
+import { walrusPluginKey } from "./plugin-key.mjs";
+import { walFaucetStrategyKey } from "./faucet-strategy.mjs";
+import { resolveKnownDeploymentOptions } from "./mode/known-deploy.mjs";
+import { resolveLocalClusterOptions } from "./mode/local-cluster.mjs";
+import { bootWalrusService } from "./service.mjs";
+import { makeSnapshotable } from "./snapshot.mjs";
+import { WALRUS_STATE_REGISTRY_KEY } from "./registry-publish.mjs";
+import { Effect, Path } from "effect";
+//#region src/plugins/walrus/index.ts
+/** Walrus plugin resource. */
+const walrusResource = resource("walrus");
+const walrusErrorContributions = pluginErrorContributions(WALRUS_ERROR_TAGS);
+/** Walrus deploy records storage-node listening IPs under this /24.
+*  Docker network create requests the matching subnet explicitly, with
+*  the prefix derived from the Walrus network identity so parallel
+*  stacks don't all claim the same Docker IPAM range. */
+const deriveWalrusSubnetPrefix = (identity) => {
+	const key = `${identity.app}\0${identity.stack}\0${identity.walrusName}`;
+	let hash = 2166136261;
+	for (let i = 0; i < key.length; i += 1) {
+		hash ^= key.charCodeAt(i);
+		hash = Math.imul(hash, 16777619) >>> 0;
+	}
+	const bucket = hash % (64 * 256);
+	return `10.${64 + Math.floor(bucket / 256)}.${bucket % 256}`;
+};
+const walrusNetworkCreateSpec = (spec, subnetPrefix) => ({
+	...spec,
+	subnet: `${subnetPrefix}.0/24`,
+	gateway: `${subnetPrefix}.1`
+});
+const withWalrusNetworkAddressing = (runtime, walrusNetworkName, subnetPrefix) => ({
+	...runtime,
+	ensureNetwork: (spec) => runtime.ensureNetwork(spec.name === walrusNetworkName ? walrusNetworkCreateSpec(spec, subnetPrefix) : spec)
+});
+const buildLocalPlugin = (opts) => {
+	const resolved = resolveLocalClusterOptions(opts);
+	const walrusKey = walrusPluginKey(resolved.name);
+	return definePlugin({
+		id: walrusResource.id,
+		dependsOn: [suiResource],
+		role: "service",
+		pluginKey: walrusKey,
+		start: (deps) => Effect.gen(function* () {
+			const [sui] = deps;
+			const runtime = yield* ContainerRuntimeService;
+			const identity = yield* IdentityContext;
+			const stackPaths = yield* StackPathsService;
+			const path = yield* Path.Path;
+			const publisher = yield* ArtifactPublisherService;
+			const probe = yield* chainProbeFor(sui.chain);
+			const deployHostMountPath = path.join(stackPaths.stackRoot, "walrus", resolved.name, "deploy");
+			const walrusNetworkName = buildWalrusNetworkName(identity.app, identity.stack, resolved.name);
+			const walrusSubnetPrefix = deriveWalrusSubnetPrefix({
+				app: identity.app,
+				stack: identity.stack,
+				walrusName: resolved.name
+			});
+			const walrusRuntime = withWalrusNetworkAddressing(runtime, walrusNetworkName, walrusSubnetPrefix);
+			const suiRpcUrlInNetwork = sui.hostGateway.rpcUrl;
+			const suiFaucetUrlInNetwork = sui.hostGateway.faucetUrl;
+			if (suiFaucetUrlInNetwork === null) return yield* Effect.fail(walrusPluginError("deploy", "walrus local-cluster requires a Sui faucet URL for deploy funding."));
+			const walrusFaucetUrlInNetwork = `${suiFaucetUrlInNetwork}/v2/gas`;
+			const mode = {
+				mode: "local",
+				opts: resolved
+			};
+			const boot = yield* bootWalrusService({
+				runtime: walrusRuntime,
+				publisher,
+				probe,
+				suiSdk: sui.sdk,
+				suiChainId: sui.chain,
+				suiRpcUrlInNetwork,
+				walrusFaucetUrlInNetwork,
+				waitForFundsReady: sui.waitForTransactionsReady.wait,
+				app: identity.app,
+				stack: identity.stack,
+				subnetPrefix: walrusSubnetPrefix,
+				walrusNetworkName,
+				suiNetworkName: walrusNetworkName,
+				deployHostMountPath
+			}, mode);
+			if (boot.mode !== "local") return yield* Effect.die("walrus: mode mismatch in local plugin");
+			return {
+				mode: "local",
+				chain: sui.chain,
+				walrusPackageId: boot.walrusPackageId,
+				walPackageId: boot.walPackageId,
+				packageConfig: {
+					systemObjectId: boot.deploy.systemObject,
+					stakingPoolId: boot.deploy.stakingObject,
+					exchangeIds: boot.exchangeObjectId ? [boot.exchangeObjectId] : void 0
+				},
+				nodes: boot.nodes,
+				proxyUrl: boot.proxyUrl,
+				aggregatorUrl: boot.aggregatorUrl,
+				publisherUrl: boot.publisherUrl,
+				walFaucetStrategy: boot.walFaucetStrategy,
+				walCoinType: boot.walCoinType
+			};
+		}),
+		capabilities: ({ value: resolvedValue, runtime: acquireCtx }) => makeLocalCapabilities({
+			name: resolved.name,
+			nodeCount: resolved.nodeCount,
+			containerApiPort: resolved.containerApiPort,
+			serviceKey: String(walrusKey),
+			resolved: resolvedValue,
+			acquireCtx
+		}),
+		errorContributions: walrusErrorContributions
+	});
+};
+const buildKnownPlugin = (opts) => {
+	const resolved = resolveKnownDeploymentOptions(opts);
+	return definePlugin({
+		id: walrusResource.id,
+		dependsOn: [suiResource],
+		role: "task",
+		start: () => Effect.succeed({
+			mode: "known",
+			chain: resolved.chain,
+			walrusPackageId: null,
+			walPackageId: null,
+			packageConfig: {
+				systemObjectId: resolved.systemObjectId,
+				stakingPoolId: resolved.stakingPoolId,
+				exchangeIds: resolved.exchangeIds.length > 0 ? resolved.exchangeIds : void 0
+			},
+			nodes: resolved.nodes,
+			proxyUrl: resolved.proxyUrl,
+			aggregatorUrl: resolved.aggregatorUrl,
+			publisherUrl: resolved.publisherUrl,
+			walFaucetStrategy: null,
+			walCoinType: null
+		}),
+		capabilities: ({ value: resolvedValue, runtime: acquireCtx }) => makeKnownCapabilities({
+			resolved: resolvedValue,
+			acquireCtx
+		}),
+		errorContributions: walrusErrorContributions
+	});
+};
+const makeLocalCapabilities = (parts) => {
+	const { name, nodeCount, containerApiPort, serviceKey, resolved, acquireCtx } = parts;
+	const snap = makeSnapshotable("local", acquireCtx.identity.app, acquireCtx.identity.stack, name, resolved.chain, nodeCount);
+	const codegen = makeCodegenable({
+		mode: "local",
+		chain: resolved.chain,
+		walrusPackageId: resolved.walrusPackageId,
+		walPackageId: resolved.walPackageId,
+		walCoinType: resolved.walCoinType,
+		systemObjectId: resolved.packageConfig.systemObjectId,
+		stakingPoolId: resolved.packageConfig.stakingPoolId,
+		exchangeIds: resolved.packageConfig.exchangeIds ? [...resolved.packageConfig.exchangeIds] : [],
+		proxyUrl: resolved.proxyUrl,
+		aggregatorUrl: resolved.aggregatorUrl,
+		publisherUrl: resolved.publisherUrl,
+		nodes: resolved.nodes
+	});
+	const stateRegistry = {
+		kind: "strategy-contributor",
+		capabilityKey: WALRUS_STATE_REGISTRY_KEY,
+		strategy: { noteName: name },
+		autoMounted: true
+	};
+	const walFaucetContribution = resolved.walFaucetStrategy === null || resolved.walCoinType === null ? [] : [{
+		kind: "strategy-contributor",
+		capabilityKey: walFaucetStrategyKey(resolved.walCoinType),
+		strategy: resolved.walFaucetStrategy,
+		autoMounted: true
+	}];
+	const routables = makeLocalRoutables({
+		app: acquireCtx.identity.app,
+		stack: acquireCtx.identity.stack,
+		walrusName: name,
+		serviceKey,
+		nodeCount,
+		containerApiPort
+	});
+	return [
+		snap,
+		codegen,
+		stateRegistry,
+		...walFaucetContribution,
+		...routables
+	];
+};
+const makeKnownCapabilities = (parts) => {
+	const { resolved, acquireCtx } = parts;
+	return [
+		makeSnapshotable("known", acquireCtx.identity.app, acquireCtx.identity.stack, "walrusKnownDeployment", resolved.chain),
+		makeCodegenable({
+			mode: "known",
+			chain: resolved.chain,
+			walrusPackageId: resolved.walrusPackageId,
+			walPackageId: resolved.walPackageId,
+			walCoinType: resolved.walCoinType,
+			systemObjectId: resolved.packageConfig.systemObjectId,
+			stakingPoolId: resolved.packageConfig.stakingPoolId,
+			exchangeIds: resolved.packageConfig.exchangeIds ? [...resolved.packageConfig.exchangeIds] : [],
+			proxyUrl: resolved.proxyUrl,
+			aggregatorUrl: resolved.aggregatorUrl,
+			publisherUrl: resolved.publisherUrl,
+			nodes: resolved.nodes
+		}),
+		{
+			kind: "strategy-contributor",
+			capabilityKey: WALRUS_STATE_REGISTRY_KEY,
+			strategy: {
+				name: "walrusKnownDeployment",
+				systemObjectId: resolved.packageConfig.systemObjectId,
+				stakingObjectId: resolved.packageConfig.stakingPoolId,
+				chain: resolved.chain
+			},
+			autoMounted: true
+		}
+	];
+};
+/** Resolve the local Walrus deployment's WAL coin as an account-funding
+*  coin ref. Accounts that need WAL should use:
+*
+*      funding: [{ coin: walCoin(localWalrus), amount }]
+*
+*  The funding strategy itself is contributed by the Walrus service
+*  once its local exchange exists. */
+const walCoin = (walrusMember) => {
+	return definePlugin({
+		id: resource(coinResourceId("wal")).id,
+		dependsOn: walrusMember,
+		role: "task",
+		start: (resolved) => Effect.gen(function* () {
+			if (resolved.walCoinType === null) return yield* Effect.fail(walrusPluginError("exchange", "walCoin(...) requires a local Walrus deployment with a WAL package."));
+			return {
+				symbol: "WAL",
+				fullCoinType: resolved.walCoinType,
+				decimals: 9,
+				source: "walrus"
+			};
+		}),
+		errorContributions: walrusErrorContributions
+	});
+};
+/** Local-cluster shorthand. Known deployments are selected through
+*  `walrusFor(network).known(...)` so network choice stays explicit. */
+const walrus = (opts) => {
+	return buildLocalPlugin(opts?.local ?? {});
+};
+/** Mode-narrowed factory namespace.
+*
+*  Usage:
+*      const network = { mode: 'local', chain: 'sui:localnet' } as const;
+*      walrusFor(network).local({...})    // OK
+*      walrusFor(network).known({...})    // type error: 'known' not in 'local' branch
+*
+*  Critically, the fork branch exposes ONLY `.known` — calling
+*  `.local` on a fork-mode network is a **compile error** at the
+*  call site (distilled-doc invariant 12 — type-level refusal).
+*  Runtime defense-in-depth: see `mode/fork-refusal.ts`. */
+const walrusFor = defineModeNamespace({
+	local: {
+		local: (opts = {}) => buildLocalPlugin(opts),
+		known: (opts) => buildKnownPlugin(opts)
+	},
+	live: { known: (opts) => buildKnownPlugin(opts) },
+	fork: { known: (opts) => buildKnownPlugin(opts) }
+});
+//#endregion
+export { walCoin, walrus, walrusFor };
+
+//# sourceMappingURL=index.mjs.map