@mysten-incubation/devstack 0.0.0

package/dist/plugins/account/service.mjs

@@ -0,0 +1,405 @@
+import { LeaseBrokerService } from "../../substrate/runtime/lease-broker/service.mjs";
+import { accountAcquireError, accountSignError } from "./errors.mjs";
+import { withAddressLease } from "./lease.mjs";
+import { DEFAULT_EPHEMERAL_FUND_MIST, SUI_FULL_COIN_TYPE, applyCrossCuttingFunding, fundEphemeralDefault } from "./funding.mjs";
+import { resolveEphemeralVariant } from "./variants/ephemeral.mjs";
+import { resolveKeystoreVariant } from "./variants/keystore.mjs";
+import { resolveEnvVariant } from "./variants/env.mjs";
+import { resolveInlineVariant } from "./variants/inline.mjs";
+import { resolveSignerVariant } from "./variants/signer.mjs";
+import { resolveImpersonateVariant } from "./variants/impersonate.mjs";
+import { Effect } from "effect";
+//#region src/plugins/account/service.ts
+/** Architecture-distilled invariant: name flows into the resource id, an
+*  on-disk path, a manifest key, container labels, and generated
+*  TypeScript exports. Keep the public name identifier-safe instead
+*  of accepting path-safe spellings that codegen later rejects. */
+const ACCOUNT_NAME_RE = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+const ACCOUNT_NAME_HINT = "letters, digits, and underscores; must start with a letter; max 64 chars; cannot be a TypeScript reserved word";
+const TS_RESERVED_BINDING_NAMES = new Set([
+	"as",
+	"async",
+	"await",
+	"break",
+	"case",
+	"catch",
+	"class",
+	"const",
+	"continue",
+	"debugger",
+	"default",
+	"delete",
+	"do",
+	"else",
+	"enum",
+	"export",
+	"extends",
+	"false",
+	"finally",
+	"for",
+	"from",
+	"function",
+	"if",
+	"import",
+	"in",
+	"instanceof",
+	"let",
+	"new",
+	"null",
+	"of",
+	"return",
+	"super",
+	"switch",
+	"this",
+	"throw",
+	"true",
+	"try",
+	"typeof",
+	"var",
+	"void",
+	"while",
+	"with",
+	"yield"
+]);
+const accountNameInvalidReason = (name) => {
+	if (!ACCOUNT_NAME_RE.test(name)) return `must match ${ACCOUNT_NAME_RE.source}`;
+	if (TS_RESERVED_BINDING_NAMES.has(name)) return "cannot be a TypeScript reserved word";
+	return null;
+};
+const assertAccountName = (name) => {
+	const reason = accountNameInvalidReason(name);
+	if (reason !== null) throw new TypeError(`Account name '${name}' is invalid — ${reason}. ${ACCOUNT_NAME_HINT}`);
+};
+const validateAccountName = (name) => {
+	const reason = accountNameInvalidReason(name);
+	if (reason !== null) return Effect.fail(accountAcquireError({
+		phase: "validate-name",
+		accountName: name,
+		variant: "ephemeral",
+		message: `Account name '${name}' is invalid — ${reason}.`,
+		hint: ACCOUNT_NAME_HINT
+	}));
+	return Effect.void;
+};
+const FUNDING_BALANCE_TIMEOUT_MS = 5e3;
+const makeFundingBalanceReader = (sdk) => ({ readBalance: ({ owner, coinType }) => Effect.promise(async () => {
+	try {
+		return balanceAmountFromSdkResponse(await sdk.core.getBalance({
+			owner,
+			coinType
+		}));
+	} catch {
+		return null;
+	}
+}).pipe(Effect.timeoutOrElse({
+	duration: `${FUNDING_BALANCE_TIMEOUT_MS} millis`,
+	orElse: () => Effect.succeed(null)
+})) });
+const balanceAmountFromSdkResponse = (response) => {
+	const outer = typeof response === "object" && response !== null && "balance" in response ? response.balance : response;
+	const value = typeof outer === "object" && outer !== null && "balance" in outer ? outer.balance : outer;
+	if (typeof value === "bigint") return value;
+	if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) return BigInt(value);
+	if (typeof value === "string" && /^\d+$/.test(value)) return BigInt(value);
+	return null;
+};
+/** Dispatch on the variant discriminator. */
+const resolveVariant = (opts, ctx) => {
+	switch (opts.kind) {
+		case "ephemeral": return resolveEphemeralVariant({
+			name: opts.name,
+			secretFilePath: `${ctx.runtimeRoot}/account/${opts.name}.key`
+		});
+		case "keystore": return resolveKeystoreVariant({
+			name: opts.name,
+			path: opts.path,
+			aliasOrAddress: opts.aliasOrAddress
+		});
+		case "env": return resolveEnvVariant({
+			name: opts.name,
+			varName: opts.key
+		});
+		case "inline": return resolveInlineVariant({
+			name: opts.name,
+			privateKey: opts.privateKey
+		});
+		case "signer": return resolveSignerVariant({
+			name: opts.name,
+			signer: opts.signer,
+			...opts.addressOverride !== void 0 ? { addressOverride: opts.addressOverride } : {}
+		});
+		case "impersonate": return resolveImpersonateVariant({
+			name: opts.name,
+			address: opts.address,
+			suiMode: ctx.sui.mode
+		});
+	}
+};
+/** Promote a Promise-returning sign call into the typed-error
+*  channel. The `signer.signTransaction` / `signPersonalMessage`
+*  helpers on `@mysten/sui` `Signer` instances are async; the
+*  bring-your-own-signer variant uses the same shape. */
+const signWith = (signer, tx, accountName, address) => Effect.tryPromise({
+	try: () => signer.signTransaction(tx),
+	catch: (cause) => accountSignError({
+		phase: "sign",
+		accountName,
+		address,
+		message: `Account '${accountName}': signer.signTransaction() rejected.`,
+		cause
+	})
+});
+const signPersonalWith = (signer, msg, accountName, address) => Effect.tryPromise({
+	try: () => signer.signPersonalMessage(msg),
+	catch: (cause) => accountSignError({
+		phase: "sign",
+		accountName,
+		address,
+		message: `Account '${accountName}': signer.signPersonalMessage() rejected.`,
+		cause
+	})
+});
+/** Project the raw `@mysten/sui` executeTransaction response into
+*  the narrowed `TxResult` shape consumers depend on. The SDK
+*  response carries a discriminated union; the result we surface
+*  always carries a digest plus the include-projected sub-fields. */
+const projectTxResult = (raw, accountName, address) => {
+	const r = raw;
+	if (r.$kind === "FailedTransaction") return Effect.fail(accountSignError({
+		phase: "submit",
+		accountName,
+		address,
+		message: `Account '${accountName}': transaction execution failed on-chain (digest=${r.FailedTransaction?.digest ?? "<unknown>"}).`
+	}));
+	const tx = r.Transaction;
+	if (tx?.digest === void 0) return Effect.fail(accountSignError({
+		phase: "submit",
+		accountName,
+		address,
+		message: `Account '${accountName}': executeTransaction returned no digest. Raw shape=${JSON.stringify(r).slice(0, 200)}.`
+	}));
+	return Effect.succeed({
+		digest: tx.digest,
+		effects: tx.effects ?? null,
+		objectChanges: projectObjectChanges(tx.effects, tx.objectTypes ?? {}),
+		balanceChanges: tx.balanceChanges ?? []
+	});
+};
+const extractExecuteDigest = (raw) => {
+	const r = raw;
+	return r.$kind === "FailedTransaction" ? r.FailedTransaction?.digest : r.Transaction?.digest;
+};
+const projectObjectChanges = (effects, objectTypes) => {
+	const changedObjects = typeof effects === "object" && effects !== null && "changedObjects" in effects ? effects.changedObjects : void 0;
+	if (changedObjects === void 0) return [];
+	return changedObjects.filter((change) => typeof change.objectId === "string").map((change) => {
+		const objectType = objectTypes[change.objectId];
+		const entry = {
+			type: change.outputState === "PackageWrite" ? "published" : change.idOperation === "Created" ? "created" : "mutated",
+			objectId: change.objectId
+		};
+		if (objectType !== void 0) entry.objectType = objectType;
+		if (change.outputState !== void 0) entry.outputState = change.outputState;
+		if (change.idOperation !== void 0) entry.idOperation = change.idOperation;
+		return entry;
+	});
+};
+const buildClosures = (args) => {
+	const { accountName, resolved, sui, broker, source } = args;
+	if (source === "impersonate") {
+		const refuse = () => Effect.fail(accountSignError({
+			phase: "impersonation-bypass-attempt",
+			accountName,
+			address: resolved.address,
+			message: `Account '${accountName}' is an impersonation account — sign/execute must route through Sui's fork admin surface.`
+		}));
+		const unlockedSignAndExecute = (tx) => Effect.gen(function* () {
+			const fork = sui.fork ?? null;
+			if (fork === null) return yield* Effect.fail(accountSignError({
+				phase: "submit",
+				accountName,
+				address: resolved.address,
+				message: `Account '${accountName}': impersonation requires a fork-mode Sui client.`
+			}));
+			const submitted = yield* fork.impersonate(resolved.address, tx).pipe(Effect.mapError((cause) => accountSignError({
+				phase: "submit",
+				accountName,
+				address: resolved.address,
+				message: `Account '${accountName}': fork impersonation submit failed.`,
+				cause
+			})));
+			yield* Effect.tryPromise({
+				try: () => sui.sdk.core.waitForTransaction({ digest: submitted.digest }),
+				catch: (cause) => accountSignError({
+					phase: "await-finality",
+					accountName,
+					address: resolved.address,
+					message: `Account '${accountName}': waitForTransaction(${submitted.digest}) failed.`,
+					cause
+				})
+			});
+			return yield* projectTxResult(submitted.raw, accountName, resolved.address);
+		});
+		const transactionSigner = {
+			signTransaction: refuse,
+			signAndExecute: unlockedSignAndExecute
+		};
+		const withTransactionSigner = (body) => withAddressLease(broker, accountName, resolved.address, Effect.gen(function* () {
+			return yield* body(transactionSigner);
+		})).pipe(Effect.withSpan("devstack.plugin.account.transactionSigner", { attributes: {
+			"account.name": accountName,
+			"account.address": resolved.address
+		} }));
+		return {
+			signAndExecute: (tx) => withTransactionSigner((locked) => locked.signAndExecute(tx)).pipe(Effect.withSpan("devstack.plugin.account.signAndExecute", { attributes: {
+				"account.name": accountName,
+				"account.address": resolved.address
+			} })),
+			withTransactionSigner,
+			signTransaction: refuse,
+			signPersonalMessage: refuse
+		};
+	}
+	const signer = resolved.signer;
+	const unlockedSignTransaction = (tx) => signWith(signer, tx, accountName, resolved.address);
+	const unlockedSignAndExecute = (tx) => Effect.gen(function* () {
+		const signed = yield* unlockedSignTransaction(tx);
+		const raw = yield* Effect.tryPromise({
+			try: () => sui.sdk.core.executeTransaction({
+				transaction: tx,
+				signatures: [signed.signature],
+				include: {
+					effects: true,
+					objectTypes: true
+				}
+			}),
+			catch: (cause) => accountSignError({
+				phase: "submit",
+				accountName,
+				address: resolved.address,
+				message: `Account '${accountName}': executeTransaction transport failed.`,
+				cause
+			})
+		});
+		const digest = extractExecuteDigest(raw);
+		if (digest !== void 0) yield* Effect.tryPromise({
+			try: () => sui.sdk.core.waitForTransaction({ digest }),
+			catch: (cause) => accountSignError({
+				phase: "await-finality",
+				accountName,
+				address: resolved.address,
+				message: `Account '${accountName}': waitForTransaction(${digest}) failed.`,
+				cause
+			})
+		});
+		return yield* projectTxResult(raw, accountName, resolved.address);
+	});
+	const transactionSigner = {
+		signTransaction: unlockedSignTransaction,
+		signAndExecute: unlockedSignAndExecute
+	};
+	const withTransactionSigner = (body) => withAddressLease(broker, accountName, resolved.address, Effect.gen(function* () {
+		return yield* body(transactionSigner);
+	})).pipe(Effect.withSpan("devstack.plugin.account.transactionSigner", { attributes: {
+		"account.name": accountName,
+		"account.address": resolved.address
+	} }));
+	const signTransaction = (tx) => withTransactionSigner((locked) => locked.signTransaction(tx)).pipe(Effect.withSpan("devstack.plugin.account.signTransaction", { attributes: {
+		"account.name": accountName,
+		"account.address": resolved.address
+	} }));
+	const signPersonalMessage = (msg) => withAddressLease(broker, accountName, resolved.address, signPersonalWith(signer, msg, accountName, resolved.address)).pipe(Effect.withSpan("devstack.plugin.account.signPersonalMessage", { attributes: {
+		"account.name": accountName,
+		"account.address": resolved.address
+	} }));
+	const signAndExecute = (tx) => withTransactionSigner((locked) => locked.signAndExecute(tx)).pipe(Effect.withSpan("devstack.plugin.account.signAndExecute", { attributes: {
+		"account.name": accountName,
+		"account.address": resolved.address
+	} }));
+	return {
+		signAndExecute,
+		withTransactionSigner,
+		signTransaction,
+		signPersonalMessage
+	};
+};
+/** Acquire an account. Coordinates variant dispatch + funding +
+*  the resolved-value projection. */
+const acquireAccount = (opts, ctx) => Effect.gen(function* () {
+	yield* validateAccountName(opts.name);
+	yield* Effect.annotateCurrentSpan({
+		"account.name": opts.name,
+		"account.variant": opts.kind,
+		"sui.mode": ctx.sui.mode
+	});
+	const resolved = yield* resolveVariant(opts, ctx);
+	yield* Effect.annotateCurrentSpan({
+		"account.address": resolved.address,
+		"account.scheme": resolved.scheme
+	});
+	const broker = yield* LeaseBrokerService;
+	const balanceReader = makeFundingBalanceReader(ctx.sui.sdk);
+	const defaultFunding = opts.kind === "ephemeral" && opts.funding === void 0 ? {
+		coin: "SUI",
+		fullCoinType: SUI_FULL_COIN_TYPE,
+		amount: DEFAULT_EPHEMERAL_FUND_MIST
+	} : null;
+	const requestedFunding = defaultFunding === null ? ctx.projectedFunding ?? [] : [defaultFunding, ...ctx.projectedFunding ?? []];
+	const appliedDefaultFunding = [];
+	if (defaultFunding !== null) {
+		yield* fundEphemeralDefault({
+			accountName: opts.name,
+			address: resolved.address,
+			amountMist: defaultFunding.amount,
+			suiMode: ctx.sui.mode,
+			chainId: ctx.sui.chain,
+			emitAutoPromotionEvent: ctx.emitAutoPromotionEvent,
+			broker,
+			balanceReader
+		});
+		if (defaultFunding.amount > 0n) appliedDefaultFunding.push(defaultFunding);
+	}
+	const source = opts.kind === "impersonate" ? "impersonate" : "real";
+	const closures = buildClosures({
+		accountName: opts.name,
+		resolved,
+		sui: ctx.sui,
+		broker,
+		source
+	});
+	const value = {
+		name: opts.name,
+		address: resolved.address,
+		scheme: resolved.scheme,
+		publicKey: resolved.publicKey,
+		source,
+		funding: {
+			requested: requestedFunding,
+			applied: appliedDefaultFunding
+		},
+		...closures
+	};
+	const projected = ctx.projectedFunding ?? [];
+	let appliedCrossCuttingFunding = [];
+	if (projected.length > 0) appliedCrossCuttingFunding = yield* applyCrossCuttingFunding({
+		accountName: opts.name,
+		address: resolved.address,
+		variant: opts.kind,
+		account: value,
+		funding: projected,
+		chainId: ctx.sui.chain,
+		broker,
+		balanceReader
+	});
+	return {
+		...value,
+		funding: {
+			requested: requestedFunding,
+			applied: [...appliedDefaultFunding, ...appliedCrossCuttingFunding]
+		}
+	};
+});
+//#endregion
+export { acquireAccount, assertAccountName };
+
+//# sourceMappingURL=service.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"service.mjs","names":[],"sources":["../../../src/plugins/account/service.ts"],"sourcesContent":["// Account plugin — service body (main acquire Effect).\n//\n// What this file does:\n//\n//   1. Validate the account name (12-account.md \"Name shape\"\n//      invariant) — strict charset, length-bounded. Loud-fail at\n//      the factory boundary.\n//   2. Dispatch on the variant discriminator to the right resolver\n//      under `variants/`.\n//   3. Coordinate the funding pass (default + cross-cutting).\n//   4. Project the resolved keypair into the user-facing\n//      `AccountValue` shape (sign + execute closures).\n//\n// What it does NOT do:\n//\n//   - Talk to the chain or the faucet directly — the variant\n//     resolvers + the funding helpers own those wires.\n//   - Wire the capabilities — that's the barrel's job (`index.ts`).\n//\n// Distilled-doc invariant (\"Acquisition vs signing error split\"):\n// the acquire body emits ONLY `AccountAcquireError`; the resolved\n// value's sign/execute closures emit `AccountSignError`. The two\n// channels never mix.\n//\n// Per-address serialization (architecture invariant): concurrent\n// account-bound transactions for the same address MUST serialize\n// across build + sign + execute. `Transaction.build({ client })`\n// resolves gas/object versions, so taking the lease only while\n// signing still lets two callers build stale object references. The\n// substrate's `LeaseBrokerService` is the L0 primitive: each\n// transaction scope opens a fresh lease keyed by `account:<address>`.\n// The public sign helpers are implemented in terms of that scope so\n// they keep the historical per-address behavior.\n\nimport { Effect } from 'effect';\n\nimport type { Signer, SignatureWithBytes } from '@mysten/sui/cryptography';\n\nimport {\n\taccountAcquireError,\n\taccountSignError,\n\ttype AccountAcquireError,\n\ttype AccountSignError,\n} from './errors.ts';\nimport { type ResolvedKeypair } from './keypair.ts';\nimport {\n\tapplyCrossCuttingFunding,\n\tfundEphemeralDefault,\n\tDEFAULT_EPHEMERAL_FUND_MIST,\n\tSUI_FULL_COIN_TYPE,\n\ttype AccountFunding,\n\ttype AccountFundingResult,\n\ttype FundingBalanceReader,\n\ttype ProjectedFunding,\n\ttype ProjectedFundingEntry,\n} from './funding.ts';\nimport { resolveEphemeralVariant } from './variants/ephemeral.ts';\nimport { resolveKeystoreVariant } from './variants/keystore.ts';\nimport { resolveEnvVariant } from './variants/env.ts';\nimport { resolveInlineVariant } from './variants/inline.ts';\nimport { resolveSignerVariant } from './variants/signer.ts';\nimport { resolveImpersonateVariant } from './variants/impersonate.ts';\nimport type { SuiSdkShim } from '../sui/chain-probe.ts';\nimport type { StrategyRegistryService } from '../../substrate/runtime/strategy-registry/service.ts';\nimport type { ChainId } from '../../substrate/brand.ts';\nimport type { TransactionSignerScope } from '../../substrate/runtime/sui-execute/index.ts';\nimport {\n\tLeaseBrokerService,\n\ttype LeaseBroker,\n} from '../../substrate/runtime/lease-broker/index.ts';\nimport type { ForkAdminSurface } from '../sui/index.ts';\nimport { withAddressLease } from './lease.ts';\n\n// -----------------------------------------------------------------------------\n// User-facing options shape\n// -----------------------------------------------------------------------------\n\n/** Account variant discriminated union. The user-facing factory\n *  takes one of these shapes (or omits `opts` entirely for the\n *  default ephemeral form). */\nexport type AccountOptions<Funding extends AccountFunding = AccountFunding> =\n\t| {\n\t\t\treadonly kind: 'ephemeral';\n\t\t\treadonly funding?: Funding;\n\t  }\n\t| {\n\t\t\treadonly kind: 'keystore';\n\t\t\treadonly path: string;\n\t\t\treadonly aliasOrAddress: string;\n\t\t\treadonly funding?: Funding;\n\t  }\n\t| {\n\t\t\treadonly kind: 'env';\n\t\t\treadonly key: string;\n\t\t\treadonly funding?: Funding;\n\t  }\n\t| {\n\t\t\treadonly kind: 'inline';\n\t\t\treadonly privateKey: string | Uint8Array;\n\t\t\treadonly funding?: Funding;\n\t  }\n\t| {\n\t\t\treadonly kind: 'signer';\n\t\t\treadonly signer: {\n\t\t\t\treadonly toSuiAddress: () => string;\n\t\t\t\treadonly getKeyScheme: () => string;\n\t\t\t\treadonly getPublicKey: () => { readonly toRawBytes: () => Uint8Array };\n\t\t\t\treadonly signTransaction: (\n\t\t\t\t\ttx: Uint8Array,\n\t\t\t\t) => Promise<{ readonly bytes: string; readonly signature: string }>;\n\t\t\t\treadonly signPersonalMessage: (\n\t\t\t\t\tmsg: Uint8Array,\n\t\t\t\t) => Promise<{ readonly bytes: string; readonly signature: string }>;\n\t\t\t};\n\t\t\treadonly addressOverride?: string;\n\t\t\treadonly funding?: Funding;\n\t  }\n\t| {\n\t\t\treadonly kind: 'impersonate';\n\t\t\treadonly address: string;\n\t\t\treadonly funding?: Funding;\n\t  };\n\nexport type ResolvedAccountOptions<Funding extends AccountFunding = AccountFunding> =\n\tAccountOptions<Funding> & { readonly name: string };\n\n// -----------------------------------------------------------------------------\n// Resolved value (the Tag's resolved-shape)\n// -----------------------------------------------------------------------------\n\n/** Per-account resolved value — the typed handle the Account tag\n *  publishes.\n *\n *  Architecture-distilled finding (12-account.md \"Tighten the\n *  resolved-account type\"): the `source` discriminator is mandatory\n *  so consumers can branch on impersonation. Impersonation accounts\n *  carry a zero-buffer publicKey — the discriminator is the\n *  trustworthy signal. */\nexport interface AccountValue {\n\treadonly name: string;\n\treadonly address: string;\n\treadonly scheme: 'ed25519' | 'secp256k1' | 'secp256r1';\n\treadonly publicKey: Uint8Array;\n\t/** Source discriminator — `'real'` for ephemeral / keystore / env\n\t *  / inline / signer; `'impersonate'` for the fork-only variant. */\n\treadonly source: 'real' | 'impersonate';\n\t/** Sign + execute (the canonical execution surface — per-address\n\t *  serialized, post-submit transaction-wait included, bounded\n\t *  retry on the \"dependent package not found on-chain\" race).\n\t *\n\t *  For impersonation accounts, routes through Sui's fork\n\t *  admin `impersonate` surface; for real signers, routes\n\t *  through the SDK's executeTransaction surface. */\n\treadonly signAndExecute: (tx: Uint8Array) => Effect.Effect<TxResult, AccountSignError>;\n\t/** Run a full account-bound transaction critical section.\n\t *  Callers that must serialize `Transaction.build({ client })`\n\t *  together with signing/execution use the signer passed to this\n\t *  callback; the callback runs while the per-address lease is held. */\n\treadonly withTransactionSigner: <A, E, R>(\n\t\tbody: (signer: AccountTransactionSigner) => Effect.Effect<A, E, R>,\n\t) => Effect.Effect<A, E, R>;\n\t/** Sign-only — real signers honor this; impersonation accounts\n\t *  throw synchronously (see `variants/impersonate.ts`). */\n\treadonly signTransaction: (\n\t\ttx: Uint8Array,\n\t) => Effect.Effect<{ readonly bytes: string; readonly signature: string }, AccountSignError>;\n\treadonly signPersonalMessage: (\n\t\tmsg: Uint8Array,\n\t) => Effect.Effect<{ readonly bytes: string; readonly signature: string }, AccountSignError>;\n\treadonly funding: AccountFundingResult;\n}\n\n/** Submit result projection — kept narrow so downstream consumers\n *  don't depend on the full @mysten/sui execute envelope. */\nexport interface TxResult {\n\treadonly digest: string;\n\treadonly effects: unknown;\n\treadonly objectChanges: ReadonlyArray<unknown>;\n\treadonly balanceChanges: ReadonlyArray<unknown>;\n}\n\nexport interface AccountTransactionSigner extends TransactionSignerScope<AccountSignError> {\n\treadonly signAndExecute: AccountValue['signAndExecute'];\n}\n\n// -----------------------------------------------------------------------------\n// Name validation\n// -----------------------------------------------------------------------------\n\n/** Architecture-distilled invariant: name flows into the resource id, an\n *  on-disk path, a manifest key, container labels, and generated\n *  TypeScript exports. Keep the public name identifier-safe instead\n *  of accepting path-safe spellings that codegen later rejects. */\nconst ACCOUNT_NAME_RE = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;\nconst ACCOUNT_NAME_HINT =\n\t'letters, digits, and underscores; must start with a letter; max 64 chars; cannot be a TypeScript reserved word';\nconst TS_RESERVED_BINDING_NAMES = new Set([\n\t'as',\n\t'async',\n\t'await',\n\t'break',\n\t'case',\n\t'catch',\n\t'class',\n\t'const',\n\t'continue',\n\t'debugger',\n\t'default',\n\t'delete',\n\t'do',\n\t'else',\n\t'enum',\n\t'export',\n\t'extends',\n\t'false',\n\t'finally',\n\t'for',\n\t'from',\n\t'function',\n\t'if',\n\t'import',\n\t'in',\n\t'instanceof',\n\t'let',\n\t'new',\n\t'null',\n\t'of',\n\t'return',\n\t'super',\n\t'switch',\n\t'this',\n\t'throw',\n\t'true',\n\t'try',\n\t'typeof',\n\t'var',\n\t'void',\n\t'while',\n\t'with',\n\t'yield',\n]);\n\nconst accountNameInvalidReason = (name: string): string | null => {\n\tif (!ACCOUNT_NAME_RE.test(name)) {\n\t\treturn `must match ${ACCOUNT_NAME_RE.source}`;\n\t}\n\tif (TS_RESERVED_BINDING_NAMES.has(name)) {\n\t\treturn 'cannot be a TypeScript reserved word';\n\t}\n\treturn null;\n};\n\nexport const assertAccountName = (name: string): void => {\n\tconst reason = accountNameInvalidReason(name);\n\tif (reason !== null) {\n\t\tthrow new TypeError(`Account name '${name}' is invalid — ${reason}. ${ACCOUNT_NAME_HINT}`);\n\t}\n};\n\nexport const validateAccountName = (name: string): Effect.Effect<void, AccountAcquireError> => {\n\tconst reason = accountNameInvalidReason(name);\n\tif (reason !== null) {\n\t\treturn Effect.fail(\n\t\t\taccountAcquireError({\n\t\t\t\tphase: 'validate-name',\n\t\t\t\taccountName: name,\n\t\t\t\tvariant: 'ephemeral',\n\t\t\t\tmessage: `Account name '${name}' is invalid — ${reason}.`,\n\t\t\t\thint: ACCOUNT_NAME_HINT,\n\t\t\t}),\n\t\t);\n\t}\n\treturn Effect.void;\n};\n\n// -----------------------------------------------------------------------------\n// Variant dispatch\n// -----------------------------------------------------------------------------\n\n/** Sui mode + sdk shim — the slice of the resolved `SuiClient` the\n *  account service actually consumes. Kept narrow so the variants +\n *  funding helpers stay typed at the resolved-fields level (mode,\n *  chain, sdk) rather than at the wide `SuiClient` shape. */\nexport interface AccountSuiShim {\n\treadonly mode: 'local' | 'local-rpc' | 'live' | 'fork';\n\treadonly chain: ChainId;\n\t/** SDK shim — exposes `executeTransaction` + `waitForTransaction`\n\t *  for the signAndExecute pipeline. */\n\treadonly sdk: SuiSdkShim;\n\treadonly fork?: ForkAdminSurface | null;\n}\n\n/** Per-acquire context — supplied by the barrel from resolved plugin\n *  dependencies and per-stack identity.\n *\n *  `projectedFunding` carries the funding entries already resolved\n *  from each `opts.funding[i].coin` dependency and projected to\n *  `{fullCoinType, amount}` BEFORE handing off to `acquireAccount`.\n *  The acquire body never sees the raw member refs — keeps the\n *  cross-cutting funding dispatch substrate-name-blind. */\nexport interface AccountAcquireContext {\n\treadonly sui: AccountSuiShim;\n\treadonly runtimeRoot: string;\n\treadonly app: string;\n\treadonly stack: string;\n\treadonly emitAutoPromotionEvent: () => Effect.Effect<void>;\n\t/** Projected cross-cutting funding entries. Empty when `opts.funding`\n\t *  is absent. The barrel stamps each resolved coin dependency's\n\t *  `fullCoinType` here. */\n\treadonly projectedFunding?: ProjectedFunding;\n}\n\nconst FUNDING_BALANCE_TIMEOUT_MS = 5_000;\n\nconst makeFundingBalanceReader = (sdk: SuiSdkShim): FundingBalanceReader => ({\n\treadBalance: ({ owner, coinType }) =>\n\t\tEffect.promise(async () => {\n\t\t\ttry {\n\t\t\t\treturn balanceAmountFromSdkResponse(await sdk.core.getBalance({ owner, coinType }));\n\t\t\t} catch {\n\t\t\t\treturn null;\n\t\t\t}\n\t\t}).pipe(\n\t\t\tEffect.timeoutOrElse({\n\t\t\t\tduration: `${FUNDING_BALANCE_TIMEOUT_MS} millis`,\n\t\t\t\torElse: () => Effect.succeed(null),\n\t\t\t}),\n\t\t),\n});\n\nconst balanceAmountFromSdkResponse = (response: unknown): bigint | null => {\n\tconst outer =\n\t\ttypeof response === 'object' && response !== null && 'balance' in response\n\t\t\t? (response as { readonly balance?: unknown }).balance\n\t\t\t: response;\n\tconst value =\n\t\ttypeof outer === 'object' && outer !== null && 'balance' in outer\n\t\t\t? (outer as { readonly balance?: unknown }).balance\n\t\t\t: outer;\n\tif (typeof value === 'bigint') return value;\n\tif (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0) return BigInt(value);\n\tif (typeof value === 'string' && /^\\d+$/.test(value)) return BigInt(value);\n\treturn null;\n};\n\n/** Dispatch on the variant discriminator. */\nconst resolveVariant = (\n\topts: ResolvedAccountOptions,\n\tctx: AccountAcquireContext,\n): Effect.Effect<ResolvedKeypair, AccountAcquireError> => {\n\tswitch (opts.kind) {\n\t\tcase 'ephemeral':\n\t\t\treturn resolveEphemeralVariant({\n\t\t\t\tname: opts.name,\n\t\t\t\t// Architecture-distilled (12-account.md \"Cross-component\n\t\t\t\t// references\"): persisted key lives under the stack's\n\t\t\t\t// runtime tree. Path shape mirrors the on-disk convention.\n\t\t\t\tsecretFilePath: `${ctx.runtimeRoot}/account/${opts.name}.key`,\n\t\t\t});\n\t\tcase 'keystore':\n\t\t\treturn resolveKeystoreVariant({\n\t\t\t\tname: opts.name,\n\t\t\t\tpath: opts.path,\n\t\t\t\taliasOrAddress: opts.aliasOrAddress,\n\t\t\t});\n\t\tcase 'env':\n\t\t\treturn resolveEnvVariant({\n\t\t\t\tname: opts.name,\n\t\t\t\tvarName: opts.key,\n\t\t\t});\n\t\tcase 'inline':\n\t\t\treturn resolveInlineVariant({\n\t\t\t\tname: opts.name,\n\t\t\t\tprivateKey: opts.privateKey,\n\t\t\t});\n\t\tcase 'signer':\n\t\t\treturn resolveSignerVariant({\n\t\t\t\tname: opts.name,\n\t\t\t\tsigner: opts.signer,\n\t\t\t\t...(opts.addressOverride !== undefined ? { addressOverride: opts.addressOverride } : {}),\n\t\t\t});\n\t\tcase 'impersonate':\n\t\t\treturn resolveImpersonateVariant({\n\t\t\t\tname: opts.name,\n\t\t\t\taddress: opts.address,\n\t\t\t\tsuiMode: ctx.sui.mode,\n\t\t\t});\n\t}\n};\n\n// -----------------------------------------------------------------------------\n// Sign + execute closures\n// -----------------------------------------------------------------------------\n\n/** Promote a Promise-returning sign call into the typed-error\n *  channel. The `signer.signTransaction` / `signPersonalMessage`\n *  helpers on `@mysten/sui` `Signer` instances are async; the\n *  bring-your-own-signer variant uses the same shape. */\nconst signWith = (\n\tsigner: {\n\t\treadonly signTransaction: (\n\t\t\ttx: Uint8Array,\n\t\t) => Promise<{ readonly bytes: string; readonly signature: string }>;\n\t},\n\ttx: Uint8Array,\n\taccountName: string,\n\taddress: string,\n): Effect.Effect<{ readonly bytes: string; readonly signature: string }, AccountSignError> =>\n\tEffect.tryPromise({\n\t\ttry: () => signer.signTransaction(tx),\n\t\tcatch: (cause): AccountSignError =>\n\t\t\taccountSignError({\n\t\t\t\tphase: 'sign',\n\t\t\t\taccountName,\n\t\t\t\taddress,\n\t\t\t\tmessage: `Account '${accountName}': signer.signTransaction() rejected.`,\n\t\t\t\tcause,\n\t\t\t}),\n\t});\n\nconst signPersonalWith = (\n\tsigner: {\n\t\treadonly signPersonalMessage: (\n\t\t\tmsg: Uint8Array,\n\t\t) => Promise<{ readonly bytes: string; readonly signature: string }>;\n\t},\n\tmsg: Uint8Array,\n\taccountName: string,\n\taddress: string,\n): Effect.Effect<{ readonly bytes: string; readonly signature: string }, AccountSignError> =>\n\tEffect.tryPromise({\n\t\ttry: () => signer.signPersonalMessage(msg),\n\t\tcatch: (cause): AccountSignError =>\n\t\t\taccountSignError({\n\t\t\t\tphase: 'sign',\n\t\t\t\taccountName,\n\t\t\t\taddress,\n\t\t\t\tmessage: `Account '${accountName}': signer.signPersonalMessage() rejected.`,\n\t\t\t\tcause,\n\t\t\t}),\n\t});\n\n/** Project the raw `@mysten/sui` executeTransaction response into\n *  the narrowed `TxResult` shape consumers depend on. The SDK\n *  response carries a discriminated union; the result we surface\n *  always carries a digest plus the include-projected sub-fields. */\nconst projectTxResult = (\n\traw: unknown,\n\taccountName: string,\n\taddress: string,\n): Effect.Effect<TxResult, AccountSignError> => {\n\t// Defensive shape: the SDK's TransactionResult is\n\t// `{$kind, Transaction?, FailedTransaction?}` — `Transaction.digest`\n\t// is the canonical id we need. We do best-effort projection here\n\t// rather than schema-decode (the shape is wide + the SDK pins it).\n\tconst r = raw as {\n\t\t$kind?: 'Transaction' | 'FailedTransaction';\n\t\tTransaction?: {\n\t\t\tdigest?: string;\n\t\t\teffects?: unknown;\n\t\t\tobjectTypes?: Readonly<Record<string, string>>;\n\t\t\tbalanceChanges?: ReadonlyArray<unknown>;\n\t\t};\n\t\tFailedTransaction?: {\n\t\t\tdigest?: string;\n\t\t};\n\t};\n\tif (r.$kind === 'FailedTransaction') {\n\t\treturn Effect.fail(\n\t\t\taccountSignError({\n\t\t\t\tphase: 'submit',\n\t\t\t\taccountName,\n\t\t\t\taddress,\n\t\t\t\tmessage: `Account '${accountName}': transaction execution failed on-chain (digest=${r.FailedTransaction?.digest ?? '<unknown>'}).`,\n\t\t\t}),\n\t\t);\n\t}\n\tconst tx = r.Transaction;\n\tif (tx?.digest === undefined) {\n\t\treturn Effect.fail(\n\t\t\taccountSignError({\n\t\t\t\tphase: 'submit',\n\t\t\t\taccountName,\n\t\t\t\taddress,\n\t\t\t\tmessage: `Account '${accountName}': executeTransaction returned no digest. Raw shape=${JSON.stringify(r).slice(0, 200)}.`,\n\t\t\t}),\n\t\t);\n\t}\n\treturn Effect.succeed({\n\t\tdigest: tx.digest,\n\t\teffects: tx.effects ?? null,\n\t\tobjectChanges: projectObjectChanges(tx.effects, tx.objectTypes ?? {}),\n\t\tbalanceChanges: tx.balanceChanges ?? [],\n\t});\n};\n\nconst extractExecuteDigest = (raw: unknown): string | undefined => {\n\tconst r = raw as {\n\t\t$kind?: 'Transaction' | 'FailedTransaction';\n\t\tTransaction?: { readonly digest?: string };\n\t\tFailedTransaction?: { readonly digest?: string };\n\t};\n\treturn r.$kind === 'FailedTransaction' ? r.FailedTransaction?.digest : r.Transaction?.digest;\n};\n\nconst projectObjectChanges = (\n\teffects: unknown,\n\tobjectTypes: Readonly<Record<string, string>>,\n): ReadonlyArray<unknown> => {\n\tconst changedObjects =\n\t\ttypeof effects === 'object' && effects !== null && 'changedObjects' in effects\n\t\t\t? (\n\t\t\t\t\teffects as {\n\t\t\t\t\t\treadonly changedObjects?: ReadonlyArray<{\n\t\t\t\t\t\t\treadonly objectId?: string;\n\t\t\t\t\t\t\treadonly outputState?: string;\n\t\t\t\t\t\t\treadonly idOperation?: string;\n\t\t\t\t\t\t}>;\n\t\t\t\t\t}\n\t\t\t\t).changedObjects\n\t\t\t: undefined;\n\tif (changedObjects === undefined) return [];\n\treturn changedObjects\n\t\t.filter(\n\t\t\t(\n\t\t\t\tchange,\n\t\t\t): change is {\n\t\t\t\treadonly objectId: string;\n\t\t\t\treadonly outputState?: string;\n\t\t\t\treadonly idOperation?: string;\n\t\t\t} => typeof change.objectId === 'string',\n\t\t)\n\t\t.map((change) => {\n\t\t\tconst objectType = objectTypes[change.objectId];\n\t\t\tconst entry: {\n\t\t\t\ttype: 'published' | 'created' | 'mutated';\n\t\t\t\tobjectId: string;\n\t\t\t\tobjectType?: string;\n\t\t\t\toutputState?: string;\n\t\t\t\tidOperation?: string;\n\t\t\t} = {\n\t\t\t\ttype:\n\t\t\t\t\tchange.outputState === 'PackageWrite'\n\t\t\t\t\t\t? 'published'\n\t\t\t\t\t\t: change.idOperation === 'Created'\n\t\t\t\t\t\t\t? 'created'\n\t\t\t\t\t\t\t: 'mutated',\n\t\t\t\tobjectId: change.objectId,\n\t\t\t};\n\t\t\tif (objectType !== undefined) entry.objectType = objectType;\n\t\t\tif (change.outputState !== undefined) entry.outputState = change.outputState;\n\t\t\tif (change.idOperation !== undefined) entry.idOperation = change.idOperation;\n\t\t\treturn entry;\n\t\t});\n};\n\ninterface BuildClosuresArgs {\n\treadonly accountName: string;\n\treadonly resolved: ResolvedKeypair;\n\treadonly sui: AccountSuiShim;\n\treadonly broker: LeaseBroker;\n\treadonly source: 'real' | 'impersonate';\n}\n\nconst buildClosures = (\n\targs: BuildClosuresArgs,\n): Pick<\n\tAccountValue,\n\t'signAndExecute' | 'withTransactionSigner' | 'signTransaction' | 'signPersonalMessage'\n> => {\n\tconst { accountName, resolved, sui, broker, source } = args;\n\n\t// Impersonation accounts MUST NOT sign — the synthetic signer's\n\t// signTransaction throws synchronously (architecture invariant).\n\t// signAndExecute routes through sui-fork's empty-signature\n\t// execution path while still holding the per-address lease.\n\tif (source === 'impersonate') {\n\t\tconst refuse = <A>(): Effect.Effect<A, AccountSignError> =>\n\t\t\tEffect.fail(\n\t\t\t\taccountSignError({\n\t\t\t\t\tphase: 'impersonation-bypass-attempt',\n\t\t\t\t\taccountName,\n\t\t\t\t\taddress: resolved.address,\n\t\t\t\t\tmessage: `Account '${accountName}' is an impersonation account — sign/execute must route through Sui's fork admin surface.`,\n\t\t\t\t}),\n\t\t\t);\n\t\tconst unlockedSignAndExecute: AccountTransactionSigner['signAndExecute'] = (tx) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst fork = sui.fork ?? null;\n\t\t\t\tif (fork === null) {\n\t\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\t\taccountSignError({\n\t\t\t\t\t\t\tphase: 'submit',\n\t\t\t\t\t\t\taccountName,\n\t\t\t\t\t\t\taddress: resolved.address,\n\t\t\t\t\t\t\tmessage: `Account '${accountName}': impersonation requires a fork-mode Sui client.`,\n\t\t\t\t\t\t}),\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tconst submitted = yield* fork.impersonate(resolved.address, tx).pipe(\n\t\t\t\t\tEffect.mapError(\n\t\t\t\t\t\t(cause): AccountSignError =>\n\t\t\t\t\t\t\taccountSignError({\n\t\t\t\t\t\t\t\tphase: 'submit',\n\t\t\t\t\t\t\t\taccountName,\n\t\t\t\t\t\t\t\taddress: resolved.address,\n\t\t\t\t\t\t\t\tmessage: `Account '${accountName}': fork impersonation submit failed.`,\n\t\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t\tyield* Effect.tryPromise({\n\t\t\t\t\ttry: () =>\n\t\t\t\t\t\tsui.sdk.core.waitForTransaction({\n\t\t\t\t\t\t\tdigest: submitted.digest,\n\t\t\t\t\t\t}),\n\t\t\t\t\tcatch: (cause): AccountSignError =>\n\t\t\t\t\t\taccountSignError({\n\t\t\t\t\t\t\tphase: 'await-finality',\n\t\t\t\t\t\t\taccountName,\n\t\t\t\t\t\t\taddress: resolved.address,\n\t\t\t\t\t\t\tmessage: `Account '${accountName}': waitForTransaction(${submitted.digest}) failed.`,\n\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t}),\n\t\t\t\t});\n\t\t\t\treturn yield* projectTxResult(submitted.raw, accountName, resolved.address);\n\t\t\t});\n\t\tconst transactionSigner: AccountTransactionSigner = {\n\t\t\tsignTransaction: refuse<{ readonly bytes: string; readonly signature: string }>,\n\t\t\tsignAndExecute: unlockedSignAndExecute,\n\t\t};\n\t\tconst withTransactionSigner: AccountValue['withTransactionSigner'] = (body) =>\n\t\t\twithAddressLease(\n\t\t\t\tbroker,\n\t\t\t\taccountName,\n\t\t\t\tresolved.address,\n\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\treturn yield* body(transactionSigner);\n\t\t\t\t}),\n\t\t\t).pipe(\n\t\t\t\tEffect.withSpan('devstack.plugin.account.transactionSigner', {\n\t\t\t\t\tattributes: { 'account.name': accountName, 'account.address': resolved.address },\n\t\t\t\t}),\n\t\t\t);\n\t\treturn {\n\t\t\tsignAndExecute: (tx) =>\n\t\t\t\twithTransactionSigner((locked) => locked.signAndExecute(tx)).pipe(\n\t\t\t\t\tEffect.withSpan('devstack.plugin.account.signAndExecute', {\n\t\t\t\t\t\tattributes: { 'account.name': accountName, 'account.address': resolved.address },\n\t\t\t\t\t}),\n\t\t\t\t),\n\t\t\twithTransactionSigner,\n\t\t\tsignTransaction: refuse<{ readonly bytes: string; readonly signature: string }>,\n\t\t\tsignPersonalMessage: refuse<{ readonly bytes: string; readonly signature: string }>,\n\t\t};\n\t}\n\n\t// Both real-keypair and bring-your-own-signer paths satisfy the\n\t// minimal `signTransaction` / `signPersonalMessage` shape (the\n\t// SDK's `Signer` and the BYO `signer` declaration agree on it).\n\tconst signer = resolved.signer as Pick<Signer, 'signTransaction' | 'signPersonalMessage'>;\n\n\tconst unlockedSignTransaction: AccountTransactionSigner['signTransaction'] = (tx) =>\n\t\tsignWith(signer, tx, accountName, resolved.address);\n\n\tconst unlockedSignAndExecute: AccountTransactionSigner['signAndExecute'] = (tx) =>\n\t\tEffect.gen(function* () {\n\t\t\tconst signed: SignatureWithBytes = yield* unlockedSignTransaction(tx);\n\t\t\tconst raw = yield* Effect.tryPromise({\n\t\t\t\ttry: () =>\n\t\t\t\t\tsui.sdk.core.executeTransaction({\n\t\t\t\t\t\ttransaction: tx,\n\t\t\t\t\t\tsignatures: [signed.signature],\n\t\t\t\t\t\tinclude: { effects: true, objectTypes: true },\n\t\t\t\t\t}),\n\t\t\t\tcatch: (cause): AccountSignError =>\n\t\t\t\t\taccountSignError({\n\t\t\t\t\t\tphase: 'submit',\n\t\t\t\t\t\taccountName,\n\t\t\t\t\t\taddress: resolved.address,\n\t\t\t\t\t\tmessage: `Account '${accountName}': executeTransaction transport failed.`,\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\tyield* Effect.tryPromise({\n\t\t\t\t\ttry: () =>\n\t\t\t\t\t\tsui.sdk.core.waitForTransaction({\n\t\t\t\t\t\t\tdigest,\n\t\t\t\t\t\t}),\n\t\t\t\t\tcatch: (cause): AccountSignError =>\n\t\t\t\t\t\taccountSignError({\n\t\t\t\t\t\t\tphase: 'await-finality',\n\t\t\t\t\t\t\taccountName,\n\t\t\t\t\t\t\taddress: resolved.address,\n\t\t\t\t\t\t\tmessage: `Account '${accountName}': waitForTransaction(${digest}) failed.`,\n\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t}),\n\t\t\t\t});\n\t\t\t}\n\t\t\tconst result = yield* projectTxResult(raw, accountName, resolved.address);\n\t\t\treturn result;\n\t\t});\n\n\tconst transactionSigner: AccountTransactionSigner = {\n\t\tsignTransaction: unlockedSignTransaction,\n\t\tsignAndExecute: unlockedSignAndExecute,\n\t};\n\n\tconst withTransactionSigner: AccountValue['withTransactionSigner'] = (body) =>\n\t\twithAddressLease(\n\t\t\tbroker,\n\t\t\taccountName,\n\t\t\tresolved.address,\n\t\t\tEffect.gen(function* () {\n\t\t\t\treturn yield* body(transactionSigner);\n\t\t\t}),\n\t\t).pipe(\n\t\t\tEffect.withSpan('devstack.plugin.account.transactionSigner', {\n\t\t\t\tattributes: { 'account.name': accountName, 'account.address': resolved.address },\n\t\t\t}),\n\t\t);\n\n\tconst signTransaction: AccountValue['signTransaction'] = (tx) =>\n\t\twithTransactionSigner((locked) => locked.signTransaction(tx)).pipe(\n\t\t\tEffect.withSpan('devstack.plugin.account.signTransaction', {\n\t\t\t\tattributes: { 'account.name': accountName, 'account.address': resolved.address },\n\t\t\t}),\n\t\t);\n\n\tconst signPersonalMessage: AccountValue['signPersonalMessage'] = (msg) =>\n\t\twithAddressLease(\n\t\t\tbroker,\n\t\t\taccountName,\n\t\t\tresolved.address,\n\t\t\tsignPersonalWith(signer, msg, accountName, resolved.address),\n\t\t).pipe(\n\t\t\tEffect.withSpan('devstack.plugin.account.signPersonalMessage', {\n\t\t\t\tattributes: { 'account.name': accountName, 'account.address': resolved.address },\n\t\t\t}),\n\t\t);\n\n\tconst signAndExecute: AccountValue['signAndExecute'] = (tx) =>\n\t\twithTransactionSigner((locked) => locked.signAndExecute(tx)).pipe(\n\t\t\tEffect.withSpan('devstack.plugin.account.signAndExecute', {\n\t\t\t\tattributes: { 'account.name': accountName, 'account.address': resolved.address },\n\t\t\t}),\n\t\t);\n\n\treturn { signAndExecute, withTransactionSigner, signTransaction, signPersonalMessage };\n};\n\n// -----------------------------------------------------------------------------\n// Acquire orchestration\n// -----------------------------------------------------------------------------\n\n/** Acquire an account. Coordinates variant dispatch + funding +\n *  the resolved-value projection. */\nexport const acquireAccount = (\n\topts: ResolvedAccountOptions,\n\tctx: AccountAcquireContext,\n): Effect.Effect<AccountValue, AccountAcquireError, StrategyRegistryService | LeaseBrokerService> =>\n\tEffect.gen(function* () {\n\t\tyield* validateAccountName(opts.name);\n\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t'account.name': opts.name,\n\t\t\t'account.variant': opts.kind,\n\t\t\t'sui.mode': ctx.sui.mode,\n\t\t});\n\n\t\t// --- variant dispatch ----------------------------------------\n\t\tconst resolved = yield* resolveVariant(opts, ctx);\n\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t'account.address': resolved.address,\n\t\t\t'account.scheme': resolved.scheme,\n\t\t});\n\n\t\t// --- lease broker handle (captured once; both funding and the\n\t\t//     resolved-value closures share this handle so concurrent\n\t\t//     callers serialize through the substrate broker's per-key\n\t\t//     FIFO queue) -------------------------------------------\n\t\tconst broker = yield* LeaseBrokerService;\n\t\tconst balanceReader = makeFundingBalanceReader(ctx.sui.sdk);\n\n\t\tconst defaultFunding: ProjectedFundingEntry | null =\n\t\t\topts.kind === 'ephemeral' && opts.funding === undefined\n\t\t\t\t? {\n\t\t\t\t\t\tcoin: 'SUI',\n\t\t\t\t\t\tfullCoinType: SUI_FULL_COIN_TYPE,\n\t\t\t\t\t\tamount: DEFAULT_EPHEMERAL_FUND_MIST,\n\t\t\t\t\t}\n\t\t\t\t: null;\n\t\tconst requestedFunding =\n\t\t\tdefaultFunding === null\n\t\t\t\t? (ctx.projectedFunding ?? [])\n\t\t\t\t: [defaultFunding, ...(ctx.projectedFunding ?? [])];\n\t\tconst appliedDefaultFunding: ProjectedFundingEntry[] = [];\n\n\t\t// --- default funding (bare ephemeral only) -------------------\n\t\tif (defaultFunding !== null) {\n\t\t\tyield* fundEphemeralDefault({\n\t\t\t\taccountName: opts.name,\n\t\t\t\taddress: resolved.address,\n\t\t\t\tamountMist: defaultFunding.amount,\n\t\t\t\tsuiMode: ctx.sui.mode,\n\t\t\t\tchainId: ctx.sui.chain,\n\t\t\t\temitAutoPromotionEvent: ctx.emitAutoPromotionEvent,\n\t\t\t\tbroker,\n\t\t\t\tbalanceReader,\n\t\t\t});\n\t\t\tif (defaultFunding.amount > 0n) {\n\t\t\t\tappliedDefaultFunding.push(defaultFunding);\n\t\t\t}\n\t\t}\n\n\t\tconst source: AccountValue['source'] = opts.kind === 'impersonate' ? 'impersonate' : 'real';\n\t\tconst closures = buildClosures({\n\t\t\taccountName: opts.name,\n\t\t\tresolved,\n\t\t\tsui: ctx.sui,\n\t\t\tbroker,\n\t\t\tsource,\n\t\t});\n\n\t\t// --- project the resolved value ------------------------------\n\t\tconst value: AccountValue = {\n\t\t\tname: opts.name,\n\t\t\taddress: resolved.address,\n\t\t\tscheme: resolved.scheme,\n\t\t\tpublicKey: resolved.publicKey,\n\t\t\tsource,\n\t\t\tfunding: {\n\t\t\t\trequested: requestedFunding,\n\t\t\t\tapplied: appliedDefaultFunding,\n\t\t\t},\n\t\t\t...closures,\n\t\t};\n\n\t\t// --- cross-cutting funding (all variants) --------------------\n\t\t//\n\t\t// The barrel pre-projects each user-supplied `CoinMember` to\n\t\t// `{fullCoinType, amount}` from resolved dependencies so this\n\t\t// dispatch stays substrate-name-blind. The resolved account\n\t\t// handle is passed so strategy providers without admin\n\t\t// capabilities can sign account-owned funding swaps. Missing /\n\t\t// empty `projectedFunding` is a no-op (matches the \"Optional\n\t\t// Faucet is a noop\" invariant).\n\t\tconst projected = ctx.projectedFunding ?? [];\n\t\tlet appliedCrossCuttingFunding: ProjectedFunding = [];\n\t\tif (projected.length > 0) {\n\t\t\tappliedCrossCuttingFunding = yield* applyCrossCuttingFunding({\n\t\t\t\taccountName: opts.name,\n\t\t\t\taddress: resolved.address,\n\t\t\t\tvariant: opts.kind,\n\t\t\t\taccount: value,\n\t\t\t\tfunding: projected,\n\t\t\t\tchainId: ctx.sui.chain,\n\t\t\t\tbroker,\n\t\t\t\tbalanceReader,\n\t\t\t});\n\t\t}\n\n\t\treturn {\n\t\t\t...value,\n\t\t\tfunding: {\n\t\t\t\trequested: requestedFunding,\n\t\t\t\tapplied: [...appliedDefaultFunding, ...appliedCrossCuttingFunding],\n\t\t\t},\n\t\t};\n\t});\n"],"mappings":"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"}

package/dist/plugins/account/snapshot.mjs

@@ -0,0 +1,33 @@
+import { Effect } from "effect";
+//#region src/plugins/account/snapshot.ts
+/** Build the Snapshotable contribution for a resolved variant.
+*
+*  Only the `ephemeral` variant declares a persisted subtree. The
+*  subtree is per-account so wipe-single-account (12-account.md
+*  open question) would target a single path; today's "wipe whole
+*  stack" recipe doesn't need this granularity but the seam is here. */
+const makeAccountSnapshotable = (parts) => {
+	parts.app, parts.stack, parts.accountName;
+	if (parts.variant !== "ephemeral") return {
+		kind: "snapshotable",
+		subtrees: [],
+		missingTolerance: "fine"
+	};
+	return {
+		kind: "snapshotable",
+		subtrees: [`account/${parts.accountName}.key`],
+		missingTolerance: "fine",
+		secretMaterial: true,
+		preRestore: Effect.succeed({
+			kind: "account-secret",
+			account: parts.accountName,
+			app: parts.app,
+			stack: parts.stack
+		}),
+		postRestore: Effect.void
+	};
+};
+//#endregion
+export { makeAccountSnapshotable };
+
+//# sourceMappingURL=snapshot.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.mjs","names":[],"sources":["../../../src/plugins/account/snapshot.ts"],"sourcesContent":["// Account plugin — Snapshotable contribution.\n//\n// Architecture §3 + 12-account.md \"Cross-component references\":\n// Account's persisted secret material lives under the runtime tree\n// at `runtime/account/<name>.key` (bech32 secret, 0o600 inside a\n// 0o700 parent). The runtime-rooted tar already captures this via\n// the substrate's auto-included subtree convention — Account just\n// declares the SECRET-MATERIAL flag so the substrate preserves the\n// permissions bits on round-trip.\n//\n// Distilled-doc invariant (\"Restrictive file permissions\"): the\n// 0o600 / 0o700 mode bits are load-bearing. The `secretMaterial:\n// true` flag drives the substrate's mode-bit preservation;\n// re-tightening on warm-start is the runtime's job (snapshot only\n// captures + restores).\n//\n// Variants that do NOT persist secret material (`keystore`, `env`,\n// `inline`, `signer`, `impersonate`) emit an EMPTY snapshot decl\n// with `missingTolerance: 'fine'` so cross-variant restores are\n// clean no-ops.\n\nimport { Effect } from 'effect';\n\nimport type { ContainerLabelTuple, SnapshotableDecl } from '../../contracts/snapshotable.ts';\nimport type { AccountVariantKind } from './errors.ts';\n\n/** Build the Snapshotable contribution for a resolved variant.\n *\n *  Only the `ephemeral` variant declares a persisted subtree. The\n *  subtree is per-account so wipe-single-account (12-account.md\n *  open question) would target a single path; today's \"wipe whole\n *  stack\" recipe doesn't need this granularity but the seam is here. */\nexport const makeAccountSnapshotable = (parts: {\n\treadonly accountName: string;\n\treadonly variant: AccountVariantKind;\n\treadonly app: string;\n\treadonly stack: string;\n}): SnapshotableDecl => {\n\tconst _labels: ContainerLabelTuple = {\n\t\tapp: parts.app,\n\t\tstack: parts.stack,\n\t\tplugin: 'account',\n\t\trole: parts.accountName,\n\t};\n\t// Account is value-producing — no managed container. We retain\n\t// the label tuple in the file for symmetry with Sui's snapshot\n\t// decl (and for the future `wipe-single-account` recipe).\n\tvoid _labels;\n\n\tif (parts.variant !== 'ephemeral') {\n\t\treturn {\n\t\t\tkind: 'snapshotable',\n\t\t\tsubtrees: [],\n\t\t\tmissingTolerance: 'fine',\n\t\t};\n\t}\n\n\treturn {\n\t\tkind: 'snapshotable',\n\t\t// Per-account secret file under the runtime tree. The\n\t\t// substrate's runtime-tar already covers `runtime/account/`\n\t\t// inclusively; this opt-in extra is symmetric with Sui's\n\t\t// `sui-fork/` subtree declaration and serves as the\n\t\t// authoritative path for the future per-account wipe.\n\t\tsubtrees: [`account/${parts.accountName}.key`],\n\t\tmissingTolerance: 'fine',\n\t\tsecretMaterial: true,\n\t\t// Pre-restore identity guard: assert the snapshot was taken\n\t\t// under the same `(app, stack, name)` triplet. The substrate's\n\t\t// identity walker reads this opaquely.\n\t\tpreRestore: Effect.succeed({\n\t\t\tkind: 'account-secret',\n\t\t\taccount: parts.accountName,\n\t\t\tapp: parts.app,\n\t\t\tstack: parts.stack,\n\t\t}),\n\t\tpostRestore: Effect.void,\n\t};\n};\n"],"mappings":";;;;;;;;AAgCA,MAAa,2BAA2B,UAKhB;AAEjB,OAAM,KACJ,MAAM,OAEP,MAAM;AAOb,KAAI,MAAM,YAAY,YACrB,QAAO;EACN,MAAM;EACN,UAAU,EAAE;EACZ,kBAAkB;EAClB;AAGF,QAAO;EACN,MAAM;EAMN,UAAU,CAAC,WAAW,MAAM,YAAY,MAAM;EAC9C,kBAAkB;EAClB,gBAAgB;EAIhB,YAAY,OAAO,QAAQ;GAC1B,MAAM;GACN,SAAS,MAAM;GACf,KAAK,MAAM;GACX,OAAO,MAAM;GACb,CAAC;EACF,aAAa,OAAO;EACpB"}

package/dist/plugins/account/variants/env.mjs

@@ -0,0 +1,24 @@
+import { accountAcquireError } from "../errors.mjs";
+import { decodeBech32Secret } from "../keypair.mjs";
+import { Effect } from "effect";
+//#region src/plugins/account/variants/env.ts
+/** Resolve the env variant.
+*
+*  Stub: the actual env-read happens inside `Effect.sync` against
+*  the resolved-once process env. The decode path then funnels into
+*  `decodeBech32Secret`. */
+const resolveEnvVariant = (args) => Effect.gen(function* () {
+	return yield* decodeBech32Secret(yield* Effect.sync(() => {
+		return globalThis.process?.env?.[args.varName];
+	}).pipe(Effect.flatMap((v) => v === void 0 || v === "" ? Effect.fail(accountAcquireError({
+		phase: "read-env",
+		accountName: args.name,
+		variant: "env",
+		message: `Account '${args.name}': env var '${args.varName}' is missing or empty.`,
+		hint: `Set ${args.varName}=suiprivkey1... in the process environment.`
+	})) : Effect.succeed(v))), args.name, "env");
+});
+//#endregion
+export { resolveEnvVariant };
+
+//# sourceMappingURL=env.mjs.map

package/dist/plugins/account/variants/env.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.mjs","names":[],"sources":["../../../../src/plugins/account/variants/env.ts"],"sourcesContent":["// Account variant — env (read bech32 secret from a process env var).\n//\n// Distilled-doc surface: scoped to CI / vault-injected configurations.\n// The env-var NAME is taken verbatim from the user's options — the\n// VALUE is never logged, spanned, or surfaced in error messages\n// (security invariant: only the variable name is referenced).\n\nimport { Effect } from 'effect';\n\nimport { accountAcquireError, type AccountAcquireError } from '../errors.ts';\nimport { decodeBech32Secret, type ResolvedKeypair } from '../keypair.ts';\n\nexport interface EnvVariantArgs {\n\treadonly name: string;\n\t/** The `process.env` variable name holding the bech32 secret. */\n\treadonly varName: string;\n}\n\n/** Resolve the env variant.\n *\n *  Stub: the actual env-read happens inside `Effect.sync` against\n *  the resolved-once process env. The decode path then funnels into\n *  `decodeBech32Secret`. */\nexport const resolveEnvVariant = (\n\targs: EnvVariantArgs,\n): Effect.Effect<ResolvedKeypair, AccountAcquireError> =>\n\tEffect.gen(function* () {\n\t\t// Stub: read env, refuse empty / missing.\n\t\tconst bech32 = yield* Effect.sync((): string | undefined => {\n\t\t\tconst proc = (globalThis as { process?: { env?: Record<string, string | undefined> } })\n\t\t\t\t.process;\n\t\t\treturn proc?.env?.[args.varName];\n\t\t}).pipe(\n\t\t\tEffect.flatMap((v) =>\n\t\t\t\tv === undefined || v === ''\n\t\t\t\t\t? Effect.fail(\n\t\t\t\t\t\t\taccountAcquireError({\n\t\t\t\t\t\t\t\tphase: 'read-env',\n\t\t\t\t\t\t\t\taccountName: args.name,\n\t\t\t\t\t\t\t\tvariant: 'env',\n\t\t\t\t\t\t\t\t// Reference the variable's NAME only — never the value.\n\t\t\t\t\t\t\t\tmessage: `Account '${args.name}': env var '${args.varName}' is missing or empty.`,\n\t\t\t\t\t\t\t\thint: `Set ${args.varName}=suiprivkey1... in the process environment.`,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t)\n\t\t\t\t\t: Effect.succeed(v),\n\t\t\t),\n\t\t);\n\t\treturn yield* decodeBech32Secret(bech32, args.name, 'env');\n\t});\n"],"mappings":";;;;;;;;;AAuBA,MAAa,qBACZ,SAEA,OAAO,IAAI,aAAa;AAsBvB,QAAO,OAAO,mBAAmB,OApBX,OAAO,WAA+B;AAG3D,SAFc,WACZ,SACW,MAAM,KAAK;GACvB,CAAC,KACF,OAAO,SAAS,MACf,MAAM,KAAA,KAAa,MAAM,KACtB,OAAO,KACP,oBAAoB;EACnB,OAAO;EACP,aAAa,KAAK;EAClB,SAAS;EAET,SAAS,YAAY,KAAK,KAAK,cAAc,KAAK,QAAQ;EAC1D,MAAM,OAAO,KAAK,QAAQ;EAC1B,CAAC,CACF,GACA,OAAO,QAAQ,EAAE,CACpB,CACD,EACwC,KAAK,MAAM,MAAM;EACzD"}

package/dist/plugins/account/variants/ephemeral.mjs

@@ -0,0 +1,72 @@
+import { accountAcquireError } from "../errors.mjs";
+import { decodeBech32Secret, generateEd25519Keypair } from "../keypair.mjs";
+import { Effect } from "effect";
+import { dirname } from "node:path";
+import * as nodeFs from "node:fs/promises";
+//#region src/plugins/account/variants/ephemeral.ts
+const isErrnoCode = (cause, code) => typeof cause === "object" && cause !== null && "code" in cause && cause.code === code;
+const bestEffortChmod = (path, mode) => Effect.promise(() => nodeFs.chmod(path, mode)).pipe(Effect.ignore);
+const readPersistedKeypair = (args, message) => Effect.gen(function* () {
+	const raw = yield* Effect.tryPromise({
+		try: () => nodeFs.readFile(args.secretFilePath, "utf8"),
+		catch: (cause) => accountAcquireError({
+			phase: "read-persisted-keypair",
+			accountName: args.name,
+			variant: "ephemeral",
+			message,
+			cause
+		})
+	});
+	yield* bestEffortChmod(args.secretFilePath, 384);
+	return yield* decodeBech32Secret(raw.trim(), args.name, "ephemeral");
+});
+const readPersistedKeypairIfPresent = (args) => readPersistedKeypair(args, `Account '${args.name}': failed to read persisted ephemeral keypair at ${args.secretFilePath}.`).pipe(Effect.catch((cause) => isErrnoCode(cause.cause, "ENOENT") ? Effect.succeed(null) : Effect.fail(cause)));
+const persistGeneratedSecret = (args, secret) => Effect.tryPromise({
+	try: async () => {
+		await nodeFs.mkdir(dirname(args.secretFilePath), {
+			recursive: true,
+			mode: 448
+		});
+		await nodeFs.chmod(dirname(args.secretFilePath), 448).catch(() => {});
+		try {
+			await nodeFs.writeFile(args.secretFilePath, secret, {
+				flag: "wx",
+				mode: 384
+			});
+			return "wrote";
+		} catch (cause) {
+			if (isErrnoCode(cause, "EEXIST")) return "exists";
+			throw cause;
+		}
+	},
+	catch: (cause) => accountAcquireError({
+		phase: "persist-keypair",
+		accountName: args.name,
+		variant: "ephemeral",
+		message: `Account '${args.name}': failed to persist ephemeral keypair at ${args.secretFilePath}.`,
+		cause
+	})
+});
+/** Resolve the ephemeral variant — read or generate an Ed25519 keypair.
+*
+*  First-time writes use O_EXCL so parallel acquires for the same
+*  account cannot both publish different addresses; the loser re-reads
+*  the winner's file and returns the persisted identity. */
+const resolveEphemeralVariant = (args) => Effect.gen(function* () {
+	const persisted = yield* readPersistedKeypairIfPresent(args);
+	if (persisted !== null) return persisted;
+	const generated = yield* generateEd25519Keypair(args.name);
+	if (generated.bech32Secret === null) return yield* Effect.fail(accountAcquireError({
+		phase: "generate-keypair",
+		accountName: args.name,
+		variant: "ephemeral",
+		message: `Account '${args.name}': generated keypair did not expose a bech32 secret.`
+	}));
+	if ((yield* persistGeneratedSecret(args, generated.bech32Secret)) === "exists") return yield* readPersistedKeypair(args, `Account '${args.name}': lost ephemeral keypair write race at ${args.secretFilePath} and failed to read the winner.`);
+	yield* bestEffortChmod(args.secretFilePath, 384);
+	return generated;
+});
+//#endregion
+export { resolveEphemeralVariant };
+
+//# sourceMappingURL=ephemeral.mjs.map