@mysten-incubation/devstack 0.0.0

package/dist/plugins/deepbook/types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.mjs","names":[],"sources":["../../../src/plugins/deepbook/types.ts"],"sourcesContent":["// Deepbook plugin — public user-facing types.\n//\n// This file declares the DeepBook resolved-value and helper shapes.\n// The local factory in `index.ts` only accepts options that acquire\n// real behavior in the current implementation.\n//\n// Substrate-blindness rule: nothing here references a specific\n// account / coin / package member's resolved value — the references\n// flow in as Direct Member Refs (the locked Decision per\n// `feedback_no_inline_validation_in_parallel_agents` /\n// `project_devstack_api_design_locked_decisions`).\n\nimport type { AccountValue } from '../account/index.ts';\nimport type { CoinValue } from '../coin/index.ts';\nimport type { LocalPackageResolved } from '../package/index.ts';\nimport type { ResourceRef } from '../../api/define-plugin.ts';\n\n// ---------------------------------------------------------------------------\n// Pyth — internal sub-module shapes (NOT a top-level plugin per memory\n// `project_pyth_inside_deepbook`).\n// ---------------------------------------------------------------------------\n\n/** A Pyth price feed id — opaque 64-character hex string. */\nexport type PythPriceFeedId = string & { readonly __pythPriceFeedId: unique symbol };\n\nexport const pythPriceFeedId = (s: string): PythPriceFeedId => s as PythPriceFeedId;\n\n/** Pyth feed binding — symbol + feed id + initial price. */\nexport interface PythFeed {\n\treadonly symbol: string;\n\treadonly feedId: PythPriceFeedId;\n\t/** Initial price expressed in feed-native scale (Pyth conf is the\n\t *  signed-int representation; bigint avoids float precision drift). */\n\treadonly initialPrice: bigint;\n\t/** Feed exponent. Defaults to -8, matching the DeepBook sandbox. */\n\treadonly expo?: number;\n\t/** Optional confidence interval. Defaults to 0 for deterministic local feeds. */\n\treadonly confidence?: bigint;\n\t/** Optional EMA price. Defaults to `initialPrice`. */\n\treadonly emaPrice?: bigint;\n}\n\n/** Pyth options. `package` and `pusher` are member refs, not magic strings. */\nexport interface PythOptions<\n\tPackage extends PythPackageMember = PythPackageMember,\n\tPusher extends AccountMemberAlias = AccountMemberAlias,\n> {\n\treadonly package: Package;\n\treadonly pusher: Pusher;\n\treadonly feeds: ReadonlyArray<PythFeed>;\n}\n\n/** Resolved Pyth handle exposed inside the deepbook resolved value. */\nexport interface PythHandle {\n\t/** Local sandbox Pyth has no Wormhole state; known deployments do. */\n\treadonly packageId: string | null;\n\treadonly stateId: string | null;\n\treadonly wormholeStateId: string | null;\n\treadonly feeds: ReadonlyArray<{\n\t\treadonly symbol: string;\n\t\treadonly feedId: PythPriceFeedId;\n\t\treadonly priceInfoObjectId: string;\n\t\treadonly price: bigint;\n\t\treadonly expo: number;\n\t}>;\n}\n\n/** Common Pyth price feed ids (subset; users pass their own as\n *  needed). These are the well-known Pyth hex feed ids, NOT\n *  per-stack derived. */\nexport const SUI_PRICE_FEED_ID: PythPriceFeedId = pythPriceFeedId(\n\t'23d7315113f5b1d3ba7a83604c44b94d79f4fd69af77f804fc7f920a6dc65744',\n);\nexport const USDC_PRICE_FEED_ID: PythPriceFeedId = pythPriceFeedId(\n\t'eaa020c61cc479712813461ce153894a96a6c00b21ed0cfc2798d1f9a9e9c94a',\n);\nexport const DEEP_PRICE_FEED_ID: PythPriceFeedId = pythPriceFeedId(\n\t'29bdd5248234e33bd93d3b81100b5fa32eaa5997843847e2c2cb16d7c6d9f7ff',\n);\n\n// ---------------------------------------------------------------------------\n// Pool spec\n// ---------------------------------------------------------------------------\n\n/** Coin handle used by local DeepBook pool specs. `key` is the SDK-facing\n *  coin key (for example `DEEP` or `SUI`); `coin` is the devstack member ref\n *  whose resolved value supplies the full Move coin type. */\nexport interface DeepbookPoolCoin<Coin extends CoinMemberAlias = CoinMemberAlias> {\n\treadonly key: string;\n\treadonly coin: Coin;\n\t/** SDK scalar for this coin. Defaults to the resolved coin decimals. */\n\treadonly scalar?: number;\n\t/** SDK address column. Defaults to the package id for package coins, or\n\t *  the address portion of the resolved full coin type. */\n\treadonly address?: string;\n}\n\n/** Seed order placed after a local pool is created. Price and quantity use\n *  DeepBook's on-chain units: `price` is quote-unit price and `quantity` is\n *  base-asset quantity. */\nexport interface DeepbookPoolSeedOrder {\n\treadonly side: 'ask' | 'bid';\n\treadonly price: bigint;\n\treadonly quantity: bigint;\n\treadonly clientOrderId?: bigint;\n\treadonly payWithDeep?: boolean;\n}\n\n/** Optional local liquidity seed. Package coins with a generic funding\n *  strategy are minted to the publisher before the seed transaction; otherwise\n *  the publisher must already own the deposited coins. */\nexport interface DeepbookPoolSeedLiquidity {\n\treadonly baseAmount?: bigint;\n\treadonly quoteAmount?: bigint;\n\treadonly orders: ReadonlyArray<DeepbookPoolSeedOrder>;\n}\n\n/** Whitelisted pool to create at deploy time. `base` / `quote` are real coin\n *  member refs so pool creation cannot race package/coin resolution. */\nexport interface DeepbookPoolSpec<\n\tBase extends CoinMemberAlias = CoinMemberAlias,\n\tQuote extends CoinMemberAlias = CoinMemberAlias,\n> {\n\treadonly name: string;\n\treadonly base: DeepbookPoolCoin<Base>;\n\treadonly quote: DeepbookPoolCoin<Quote>;\n\treadonly tickSize: bigint;\n\treadonly lotSize: bigint;\n\treadonly minSize: bigint;\n\t/** Whitelisted? Defaults true for local deploy (no DEEP-burn). */\n\treadonly whitelisted?: boolean;\n\t/** Stable pool? Defaults false. */\n\treadonly stablePool?: boolean;\n\t/** Optional publisher-owned BalanceManager + seed orders for local demos. */\n\treadonly seed?: DeepbookPoolSeedLiquidity;\n}\n\n/** A resolved pool record on chain. */\nexport interface DeepbookPool {\n\treadonly name: string;\n\treadonly poolId: string;\n\treadonly base: string;\n\treadonly baseCoinType: string;\n\treadonly quote: string;\n\treadonly quoteCoinType: string;\n\treadonly tickSize: bigint;\n\treadonly lotSize: bigint;\n\treadonly minSize: bigint;\n}\n\n// ---------------------------------------------------------------------------\n// Margin\n// ---------------------------------------------------------------------------\n\n/** Per-asset margin parameters (matches deepbook-v3 margin module). */\nexport interface DeepbookMarginAssetConfig {\n\treadonly label: string;\n\treadonly coinType: string;\n\treadonly scalar: number;\n\treadonly feed: PythPriceFeedId;\n\treadonly maxConfBps: number;\n\treadonly maxEwmaDifferenceBps: number;\n\treadonly supplyCap: number;\n\treadonly maxUtilizationRate: number;\n\treadonly referralSpread: number;\n\treadonly minBorrow: number;\n\treadonly rateLimitCapacity: number;\n\treadonly rateLimitRefillRatePerMs: number;\n\treadonly rateLimitEnabled: boolean;\n\treadonly baseRate: number;\n\treadonly baseSlope: number;\n\treadonly optimalUtilization: number;\n\treadonly excessSlope: number;\n}\n\n/** Per-pool risk parameters. */\nexport interface DeepbookMarginPoolRiskConfig {\n\treadonly minWithdrawRiskRatio: number;\n\treadonly minBorrowRiskRatio: number;\n\treadonly liquidationRiskRatio: number;\n\treadonly targetLiquidationRiskRatio: number;\n\treadonly userLiquidationReward: number;\n\treadonly poolLiquidationReward: number;\n}\n\nexport interface DeepbookMarginPoolRegistration {\n\treadonly pool: string;\n\treadonly risk?: DeepbookMarginPoolRiskConfig;\n}\n\nexport interface DeepbookMarginOptions {\n\treadonly assets: ReadonlyArray<\n\t\tOmit<DeepbookMarginAssetConfig, 'coinType'> & {\n\t\t\treadonly coinType?: string;\n\t\t}\n\t>;\n\treadonly pools: ReadonlyArray<DeepbookMarginPoolRegistration>;\n\treadonly maxAgeSeconds?: bigint;\n}\n\nexport interface DeepbookMargin {\n\treadonly packageId: string;\n\treadonly registryId: string;\n\treadonly adminCapId: string;\n\treadonly marginPools: ReadonlyArray<{\n\t\treadonly label: string;\n\t\treadonly coinType: string;\n\t\treadonly marginPoolId: string;\n\t}>;\n\treadonly registeredPools: ReadonlyArray<string>;\n}\n\n/** Sensible defaults for the common assets. The user passes\n *  `{ ...USDC_MARGIN_DEFAULTS, coinType: '0x...::usdc::USDC' }`. */\nexport const USDC_MARGIN_DEFAULTS: Omit<DeepbookMarginAssetConfig, 'coinType'> = {\n\tlabel: 'USDC',\n\tscalar: 1_000_000,\n\tfeed: USDC_PRICE_FEED_ID,\n\tmaxConfBps: 100,\n\tmaxEwmaDifferenceBps: 500,\n\tsupplyCap: 1_000_000,\n\tmaxUtilizationRate: 0.8,\n\treferralSpread: 0.2,\n\tminBorrow: 0.1,\n\trateLimitCapacity: 200_000,\n\trateLimitRefillRatePerMs: 0.009259,\n\trateLimitEnabled: true,\n\tbaseRate: 0.1,\n\tbaseSlope: 0.15,\n\toptimalUtilization: 0.8,\n\texcessSlope: 5,\n};\n\nexport const SUI_MARGIN_DEFAULTS: Omit<DeepbookMarginAssetConfig, 'coinType'> = {\n\tlabel: 'SUI',\n\tscalar: 1_000_000_000,\n\tfeed: SUI_PRICE_FEED_ID,\n\tmaxConfBps: 300,\n\tmaxEwmaDifferenceBps: 1500,\n\tsupplyCap: 500_000,\n\tmaxUtilizationRate: 0.8,\n\treferralSpread: 0.2,\n\tminBorrow: 0.1,\n\trateLimitCapacity: 100_000,\n\trateLimitRefillRatePerMs: 0.00462963,\n\trateLimitEnabled: true,\n\tbaseRate: 0.1,\n\tbaseSlope: 0.2,\n\toptimalUtilization: 0.8,\n\texcessSlope: 5,\n};\n\nexport const DEFAULT_POOL_RISK_CONFIG: DeepbookMarginPoolRiskConfig = {\n\tminWithdrawRiskRatio: 2,\n\tminBorrowRiskRatio: 1.2499,\n\tliquidationRiskRatio: 1.1,\n\ttargetLiquidationRiskRatio: 1.25,\n\tuserLiquidationReward: 0.02,\n\tpoolLiquidationReward: 0.03,\n};\n\n// ---------------------------------------------------------------------------\n// Market maker\n// ---------------------------------------------------------------------------\n\n/** Strategy descriptor — narrow union; deepbook bps-grid is the\n *  reference. */\nexport type DeepbookMarketMakerStrategy = {\n\treadonly kind: 'bps';\n\treadonly spreadBps: number;\n\treadonly levelSpacingBps: number;\n\treadonly levels: number;\n};\n\nexport interface DeepbookMarketMakerOptions {\n\treadonly signer: AccountMemberAlias;\n\treadonly strategy: DeepbookMarketMakerStrategy;\n\t/** Optional cadence; defaults to 5s. */\n\treadonly tickIntervalMillis?: number;\n\t/** Optional pool filter; defaults to all pools. */\n\treadonly pools?: ReadonlyArray<string>;\n}\n\nexport interface DeepbookMarketMaker {\n\treadonly signer: string;\n\treadonly running: boolean;\n\treadonly pools: ReadonlyArray<string>;\n}\n\n// ---------------------------------------------------------------------------\n// Member ref aliases — Direct Member Refs surface (locked API decision)\n// ---------------------------------------------------------------------------\n\n/** Account ref alias — the user passes the value returned by\n *  `account('name')`. Resource-typed at the factory boundary so a\n *  package-shaped ref is a TS error while preserving the literal\n *  `account/<name>` id. */\nexport type AccountMemberAlias<Name extends string = string> = ResourceRef<\n\t`account/${Name}`,\n\tAccountValue\n>;\n\n/** Coin ref alias — the user passes `coin.fromPackage(...)`, `coin.known(...)`,\n *  or `coin.builtin(...)`. */\nexport type CoinMemberAlias<Name extends string = string> = ResourceRef<`coin:${Name}`, CoinValue>;\n\n/** Local package ref alias for the published DeepBook package. The package\n *  should capture `registryId` and `adminCapId` from its publish output. */\nexport type DeepbookPackageMember<Name extends string = string> = ResourceRef<\n\t`package:${Name}`,\n\tLocalPackageResolved\n>;\n\n/** Local package ref alias for the mock Pyth package used by local DeepBook. */\nexport type PythPackageMember<Name extends string = string> = ResourceRef<\n\t`package:${Name}`,\n\tLocalPackageResolved\n>;\n"],"mappings":";AAyBA,MAAa,mBAAmB,MAA+B;;;;AA6C/D,MAAa,oBAAqC,gBACjD,mEACA;AACD,MAAa,qBAAsC,gBAClD,mEACA;AACD,MAAa,qBAAsC,gBAClD,mEACA"}

package/dist/plugins/faucet/dispatcher.d.mts

@@ -0,0 +1,9 @@
+import { Effect } from "effect";
+
+//#region src/plugins/faucet/dispatcher.d.ts
+/** Capability key prefix for a faucet request strategy. The full
+ *  key is `faucet:request:<chainId>`. */
+declare const FAUCET_CAPABILITY_KEY_PREFIX: "faucet:request";
+//#endregion
+export { FAUCET_CAPABILITY_KEY_PREFIX };
+//# sourceMappingURL=dispatcher.d.mts.map

package/dist/plugins/faucet/dispatcher.mjs

@@ -0,0 +1,13 @@
+import "effect";
+//#region src/plugins/faucet/dispatcher.ts
+/** Capability key prefix for a faucet request strategy. The full
+*  key is `faucet:request:<chainId>`. */
+const FAUCET_CAPABILITY_KEY_PREFIX = "faucet:request";
+/** Build the full capability key for a chain. Literal-typed so the
+*  downstream `StrategyFor<Caps, Key>` lookup picks the strategy
+*  shape out of a tuple by name. */
+const faucetCapabilityKey = (chainId) => `${FAUCET_CAPABILITY_KEY_PREFIX}:${chainId}`;
+//#endregion
+export { faucetCapabilityKey };
+
+//# sourceMappingURL=dispatcher.mjs.map

package/dist/plugins/faucet/dispatcher.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.mjs","names":[],"sources":["../../../src/plugins/faucet/dispatcher.ts"],"sourcesContent":["// Faucet dispatcher.\n//\n// Architecture (distilled doc §Selection rule): dispatch by\n// capability key ONLY. The user's network mode (local vs testnet vs\n// mainnet vs fork) does NOT branch at dispatch time — mode shapes\n// the POPULATION of the registry; the dispatcher itself is mode-\n// agnostic.\n//\n// Capability key shape: `faucet:request:<chainId>`. The chain id is\n// the substrate-level `NetworkConfig.chain` value (e.g. `'sui:localnet'`,\n// `'sui:testnet'`, `'sui:mainnet-fork@123'`). Future per-coin\n// dispatch (WAL exchange, treasury-cap-mint) extends this with a\n// `:<coinType>` suffix; today the dispatcher only handles the\n// SUI-side coin flow. (Open question in the distilled doc §Open\n// questions #3.)\n\nimport { Effect } from 'effect';\n\nimport type { StrategyRegistry } from '../../contracts/strategy-contributor.ts';\nimport { faucetStrategyMissing } from './errors.ts';\nimport type {\n\tFaucetBodyError,\n\tFaucetExhausted,\n\tFaucetStrategyMissing,\n\tFaucetUnreachable,\n} from './errors.ts';\nimport type { FaucetStrategy } from './strategies/sui-local.ts';\n\n/** Capability key prefix for a faucet request strategy. The full\n *  key is `faucet:request:<chainId>`. */\nexport const FAUCET_CAPABILITY_KEY_PREFIX = 'faucet:request' as const;\n\n/** Build the full capability key for a chain. Literal-typed so the\n *  downstream `StrategyFor<Caps, Key>` lookup picks the strategy\n *  shape out of a tuple by name. */\nexport const faucetCapabilityKey = <ChainId extends string>(\n\tchainId: ChainId,\n): `${typeof FAUCET_CAPABILITY_KEY_PREFIX}:${ChainId}` =>\n\t`${FAUCET_CAPABILITY_KEY_PREFIX}:${chainId}` as const;\n\n/** A single funding request. */\nexport interface FaucetRequest {\n\t/** Chain id (`'sui:localnet'`, `'sui:testnet'`, etc.). Selects\n\t *  the strategy via capability-key lookup. */\n\treadonly chainId: string;\n\t/** Destination address. */\n\treadonly address: string;\n\t/** Amount in the chain-native smallest unit (MIST for sui). The\n\t *  SUI HTTP faucet binary itself ignores `amount` and grants a\n\t *  fixed value per request; the field is the dispatcher-level\n\t *  unit and carries through to error payloads. */\n\treadonly amount: bigint;\n}\n\n/** Dispatcher view exposed by the plugin's resolved value. */\nexport interface FaucetDispatcher {\n\t/** Dispatch a funding request to the matching strategy. */\n\treadonly request: (\n\t\treq: FaucetRequest,\n\t) => Effect.Effect<\n\t\tvoid,\n\t\tFaucetStrategyMissing | FaucetUnreachable | FaucetBodyError | FaucetExhausted\n\t>;\n\t/** List the capability keys currently registered for faucet\n\t *  requests. Used by surfaces that want to render \"what chains\n\t *  can this stack hand out coins to right now.\" */\n\treadonly listFundableChains: Effect.Effect<ReadonlyArray<string>>;\n}\n\n/** Build a dispatcher closure over the substrate's\n *  `StrategyRegistry`. The dispatcher is created at the plugin's\n *  acquire and stored on the resolved value. */\nexport const makeDispatcher = (registry: StrategyRegistry): FaucetDispatcher => ({\n\trequest: (req) =>\n\t\tEffect.gen(function* () {\n\t\t\tconst key = faucetCapabilityKey(req.chainId);\n\t\t\t// Convert the substrate-level `StrategyNotFoundError` into\n\t\t\t// the faucet-flavored `FaucetStrategyMissing` (carries\n\t\t\t// amount + address) at the plugin boundary.\n\t\t\tconst strategy = yield* registry.get<typeof key, FaucetStrategy>(key).pipe(\n\t\t\t\tEffect.catchTag('StrategyNotFoundError', (err) =>\n\t\t\t\t\tEffect.fail(\n\t\t\t\t\t\tfaucetStrategyMissing({\n\t\t\t\t\t\t\tcapabilityKey: key,\n\t\t\t\t\t\t\taddress: req.address,\n\t\t\t\t\t\t\tamount: req.amount,\n\t\t\t\t\t\t\tregisteredKeys: err.registeredKeys,\n\t\t\t\t\t\t\thint:\n\t\t\t\t\t\t\t\t`no faucet strategy registered for '${req.chainId}'. ` +\n\t\t\t\t\t\t\t\t`Registered keys: [${err.registeredKeys.join(', ')}]. ` +\n\t\t\t\t\t\t\t\t`Check that the corresponding sui() plugin is in the stack ` +\n\t\t\t\t\t\t\t\t`AND its mode has a faucet (mainnet has none).`,\n\t\t\t\t\t\t}),\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t);\n\t\t\tyield* strategy.request({ address: req.address, amount: req.amount });\n\t\t}).pipe(\n\t\t\tEffect.withSpan('faucet.dispatch', {\n\t\t\t\tattributes: {\n\t\t\t\t\t'faucet.chainId': req.chainId,\n\t\t\t\t\t'faucet.address': req.address,\n\t\t\t\t\t'faucet.amount': req.amount.toString(),\n\t\t\t\t},\n\t\t\t}),\n\t\t),\n\n\tlistFundableChains: Effect.gen(function* () {\n\t\tconst keys = yield* registry.list();\n\t\t// Surface only the chain ids — strip the capability prefix.\n\t\treturn keys\n\t\t\t.filter((k) => k.startsWith(`${FAUCET_CAPABILITY_KEY_PREFIX}:`))\n\t\t\t.map((k) => k.slice(FAUCET_CAPABILITY_KEY_PREFIX.length + 1));\n\t}),\n});\n"],"mappings":";;;;AA8BA,MAAa,+BAA+B;;;;AAK5C,MAAa,uBACZ,YAEA,GAAG,6BAA6B,GAAG"}

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

@@ -0,0 +1,86 @@
+import { ConfigIssue } from "../../substrate/runtime/config-validation.mjs";
+
+//#region src/plugins/faucet/errors.d.ts
+/**
+ * Transport-level reachability failure. Raised when `fetch` itself
+ * rejects (ECONNREFUSED, DNS failure, TLS failure, AbortSignal
+ * timeout). Typical during cold boot before the faucet HTTP server
+ * binds.
+ *
+ * The retry loop catches this; it surfaces to the caller only after
+ * the wall-clock budget elapses.
+ */
+interface FaucetUnreachable {
+  readonly _tag: 'FaucetUnreachable';
+  readonly url: string;
+  readonly address: string;
+  readonly amount: bigint;
+  readonly message: string;
+  readonly cause?: unknown;
+}
+/**
+ * Retry-budget exhaustion. The wall-clock budget elapsed before any
+ * attempt succeeded, OR the attempt count cap was hit first. Both
+ * paths land here; `kind` discriminates so renderers can distinguish
+ * "we ran out of time" from "we ran out of attempts".
+ *
+ * Carries the last underlying cause so pretty-error rendering can
+ * show what was actually failing instead of just the budget message.
+ */
+interface FaucetExhausted {
+  readonly _tag: 'FaucetExhausted';
+  readonly kind: 'wall-clock' | 'attempts';
+  readonly url: string;
+  readonly address: string;
+  readonly amount: bigint;
+  readonly attempts: number;
+  readonly message: string;
+  readonly lastCause?: unknown;
+}
+/**
+ * Body-level Failure on a 200 OK. The load-bearing invariant: the
+ * Sui faucet returns `{ status: { Failure: ... } }` when it accepted
+ * the request but couldn't execute the underlying tx (gas object
+ * stale, mid-genesis, consensus hiccup).
+ *
+ * Also covers JSON-parse failures on a 200 body and other malformed-
+ * response cases — anything that means "the HTTP layer says OK but
+ * the body does not confirm a successful transfer". Caller code MUST
+ * treat this as a failed funding, not a silent success.
+ */
+interface FaucetBodyError {
+  readonly _tag: 'FaucetBodyError';
+  readonly url: string;
+  readonly address: string;
+  readonly amount: bigint;
+  readonly status: number;
+  readonly reason: 'failure-status' | 'malformed-body' | 'invalid-json';
+  readonly message: string;
+  /** The raw body payload (truncated where necessary) for diagnostics. */
+  readonly bodySnippet?: string;
+}
+/**
+ * Unknown coin / chain id at dispatch. The strategy registry held
+ * no contributor matching `capabilityKey`. The error names the
+ * registered set so users can see "I asked for X, only Y is wired".
+ *
+ * Distinct from substrate-level `StrategyNotFoundError` — this one
+ * is faucet-flavored (carries amount + address) and lives at the
+ * plugin's public boundary.
+ */
+interface FaucetStrategyMissing {
+  readonly _tag: 'FaucetStrategyMissing';
+  readonly capabilityKey: string;
+  readonly address: string;
+  readonly amount: bigint;
+  readonly registeredKeys: ReadonlyArray<string>;
+  readonly hint: string;
+}
+interface FaucetConfigError extends ConfigIssue {
+  readonly _tag: 'FaucetConfigError';
+}
+/** Union of every error a faucet caller may encounter. */
+type FaucetError = FaucetUnreachable | FaucetExhausted | FaucetBodyError | FaucetStrategyMissing | FaucetConfigError;
+//#endregion
+export { FaucetBodyError, FaucetConfigError, FaucetError, FaucetExhausted, FaucetUnreachable };
+//# sourceMappingURL=errors.d.mts.map

package/dist/plugins/faucet/errors.mjs

@@ -0,0 +1,19 @@
+import { defineConfigError } from "../../substrate/runtime/config-validation.mjs";
+//#region src/plugins/faucet/errors.ts
+const faucetUnreachable = (parts) => ({
+	_tag: "FaucetUnreachable",
+	...parts
+});
+const faucetExhausted = (parts) => ({
+	_tag: "FaucetExhausted",
+	...parts
+});
+const faucetBodyError = (parts) => ({
+	_tag: "FaucetBodyError",
+	...parts
+});
+defineConfigError("FaucetConfigError");
+//#endregion
+export { faucetBodyError, faucetExhausted, faucetUnreachable };
+
+//# sourceMappingURL=errors.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../../src/plugins/faucet/errors.ts"],"sourcesContent":["// Faucet plugin — typed errors.\n//\n// Architecture (distilled doc §Invariants / §Edge cases):\n//   - A non-2xx HTTP status MUST raise (NOT be silently treated as\n//     success). The Sui faucet binary binds its socket before its\n//     validator can transfer coins → the warm-up window returns 5xx.\n//   - A 200 OK body carrying `{ status: { Failure: ... } }` MUST\n//     raise. The most load-bearing wire-level invariant: during\n//     warm-up the faucet accepts requests it cannot execute, and\n//     treating those bodies as success marks accounts funded when\n//     no coins moved.\n//   - A wall-clock budget exhaustion is distinct from a retry-count\n//     exhaustion; both surface through the same `FaucetExhausted`\n//     class but carry the discriminating field.\n//\n// Effect v4: tagged errors are plain interfaces; `Effect.catchTag` /\n// `catchTags` match on the `_tag` literal. The error tags this\n// plugin contributes are surfaced via `FAUCET_ERROR_TAGS` for the\n// substrate cause walker.\n\nimport { defineConfigError, type ConfigIssue } from '../../substrate/runtime/config-validation.ts';\n\n/**\n * Transport-level reachability failure. Raised when `fetch` itself\n * rejects (ECONNREFUSED, DNS failure, TLS failure, AbortSignal\n * timeout). Typical during cold boot before the faucet HTTP server\n * binds.\n *\n * The retry loop catches this; it surfaces to the caller only after\n * the wall-clock budget elapses.\n */\nexport interface FaucetUnreachable {\n\treadonly _tag: 'FaucetUnreachable';\n\treadonly url: string;\n\treadonly address: string;\n\treadonly amount: bigint;\n\treadonly message: string;\n\treadonly cause?: unknown;\n}\n\nexport const faucetUnreachable = (parts: Omit<FaucetUnreachable, '_tag'>): FaucetUnreachable => ({\n\t_tag: 'FaucetUnreachable',\n\t...parts,\n});\n\n/**\n * Retry-budget exhaustion. The wall-clock budget elapsed before any\n * attempt succeeded, OR the attempt count cap was hit first. Both\n * paths land here; `kind` discriminates so renderers can distinguish\n * \"we ran out of time\" from \"we ran out of attempts\".\n *\n * Carries the last underlying cause so pretty-error rendering can\n * show what was actually failing instead of just the budget message.\n */\nexport interface FaucetExhausted {\n\treadonly _tag: 'FaucetExhausted';\n\treadonly kind: 'wall-clock' | 'attempts';\n\treadonly url: string;\n\treadonly address: string;\n\treadonly amount: bigint;\n\treadonly attempts: number;\n\treadonly message: string;\n\treadonly lastCause?: unknown;\n}\n\nexport const faucetExhausted = (parts: Omit<FaucetExhausted, '_tag'>): FaucetExhausted => ({\n\t_tag: 'FaucetExhausted',\n\t...parts,\n});\n\n/**\n * Body-level Failure on a 200 OK. The load-bearing invariant: the\n * Sui faucet returns `{ status: { Failure: ... } }` when it accepted\n * the request but couldn't execute the underlying tx (gas object\n * stale, mid-genesis, consensus hiccup).\n *\n * Also covers JSON-parse failures on a 200 body and other malformed-\n * response cases — anything that means \"the HTTP layer says OK but\n * the body does not confirm a successful transfer\". Caller code MUST\n * treat this as a failed funding, not a silent success.\n */\nexport interface FaucetBodyError {\n\treadonly _tag: 'FaucetBodyError';\n\treadonly url: string;\n\treadonly address: string;\n\treadonly amount: bigint;\n\treadonly status: number;\n\treadonly reason: 'failure-status' | 'malformed-body' | 'invalid-json';\n\treadonly message: string;\n\t/** The raw body payload (truncated where necessary) for diagnostics. */\n\treadonly bodySnippet?: string;\n}\n\nexport const faucetBodyError = (parts: Omit<FaucetBodyError, '_tag'>): FaucetBodyError => ({\n\t_tag: 'FaucetBodyError',\n\t...parts,\n});\n\n/**\n * Unknown coin / chain id at dispatch. The strategy registry held\n * no contributor matching `capabilityKey`. The error names the\n * registered set so users can see \"I asked for X, only Y is wired\".\n *\n * Distinct from substrate-level `StrategyNotFoundError` — this one\n * is faucet-flavored (carries amount + address) and lives at the\n * plugin's public boundary.\n */\nexport interface FaucetStrategyMissing {\n\treadonly _tag: 'FaucetStrategyMissing';\n\treadonly capabilityKey: string;\n\treadonly address: string;\n\treadonly amount: bigint;\n\treadonly registeredKeys: ReadonlyArray<string>;\n\treadonly hint: string;\n}\n\nexport const faucetStrategyMissing = (\n\tparts: Omit<FaucetStrategyMissing, '_tag'>,\n): FaucetStrategyMissing => ({\n\t_tag: 'FaucetStrategyMissing',\n\t...parts,\n});\n\nexport interface FaucetConfigError extends ConfigIssue {\n\treadonly _tag: 'FaucetConfigError';\n}\n\nexport const faucetConfigError = defineConfigError('FaucetConfigError');\n\n/** Union of every error a faucet caller may encounter. */\nexport type FaucetError =\n\t| FaucetUnreachable\n\t| FaucetExhausted\n\t| FaucetBodyError\n\t| FaucetStrategyMissing\n\t| FaucetConfigError;\n\n/** Error tags this plugin contributes — surfaced to the substrate's\n *  cause walker via `PluginErrorContribution`. */\nexport const FAUCET_ERROR_TAGS: ReadonlyArray<FaucetError['_tag']> = [\n\t'FaucetUnreachable',\n\t'FaucetExhausted',\n\t'FaucetBodyError',\n\t'FaucetStrategyMissing',\n\t'FaucetConfigError',\n] as const;\n"],"mappings":";;AAwCA,MAAa,qBAAqB,WAA+D;CAChG,MAAM;CACN,GAAG;CACH;AAsBD,MAAa,mBAAmB,WAA2D;CAC1F,MAAM;CACN,GAAG;CACH;AAyBD,MAAa,mBAAmB,WAA2D;CAC1F,MAAM;CACN,GAAG;CACH;AA+BgC,kBAAkB,oBAAoB"}

package/dist/plugins/faucet/http.mjs

@@ -0,0 +1,127 @@
+import { faucetBodyError, faucetExhausted, faucetUnreachable } from "./errors.mjs";
+import { makeExponentialRetrySchedule } from "../../substrate/runtime/retry-policy.mjs";
+import { Effect, Ref } from "effect";
+/** Exponential growth factor between retries. */
+const BACKOFF_FACTOR = 1.5;
+/**
+* One-shot POST: send + check status + parse body + check body
+* status. Exported so tests can pin the body-Failure detection
+* without paying the retry / wall-clock cost of the wrapper. Production
+* callers go through `requestFundsWithRetry`.
+*
+* Failure modes raised:
+*   - `FaucetUnreachable` on transport failure (fetch reject, abort
+*      timeout, network error).
+*   - `FaucetBodyError` on non-2xx, body Failure status, or
+*     unparseable JSON. The doc-load-bearing distinction.
+*/
+const requestFundsOnce = (opts) => Effect.gen(function* () {
+	const path = opts.path ?? "/v2/gas";
+	const endpoint = `${opts.faucetUrl}${path}`;
+	const deadlineMs = opts.fetchDeadlineMs ?? 5e3;
+	const response = yield* Effect.tryPromise({
+		try: () => fetch(endpoint, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({ FixedAmountRequest: { recipient: opts.address } }),
+			signal: AbortSignal.timeout(deadlineMs)
+		}),
+		catch: (cause) => faucetUnreachable({
+			url: opts.faucetUrl,
+			address: opts.address,
+			amount: opts.amount,
+			message: `faucet POST to ${endpoint} failed (transport)`,
+			cause
+		})
+	});
+	if (!response.ok) {
+		const body = yield* Effect.tryPromise({
+			try: () => response.text(),
+			catch: () => void 0
+		}).pipe(Effect.orElseSucceed(() => void 0));
+		return yield* Effect.fail(faucetBodyError({
+			url: opts.faucetUrl,
+			address: opts.address,
+			amount: opts.amount,
+			status: response.status,
+			reason: "failure-status",
+			message: `faucet returned ${response.status} ${response.statusText}`,
+			...body !== void 0 && body.length > 0 ? { bodySnippet: body } : {}
+		}));
+	}
+	const status = (yield* Effect.tryPromise({
+		try: () => response.json(),
+		catch: (cause) => faucetBodyError({
+			url: opts.faucetUrl,
+			address: opts.address,
+			amount: opts.amount,
+			status: response.status,
+			reason: "invalid-json",
+			message: "faucet response was not valid JSON",
+			...cause !== void 0 ? { bodySnippet: String(cause) } : {}
+		})
+	})).status;
+	if (typeof status === "object" && status !== null && "Failure" in status) {
+		const payload = JSON.stringify(status.Failure);
+		return yield* Effect.fail(faucetBodyError({
+			url: opts.faucetUrl,
+			address: opts.address,
+			amount: opts.amount,
+			status: response.status,
+			reason: "failure-status",
+			message: `faucet body reported Failure: ${payload}`,
+			bodySnippet: payload
+		}));
+	}
+}).pipe(Effect.withSpan("faucet.requestFundsOnce"));
+/**
+* Retry-wrapped POST. Combines `requestFundsOnce` with a jittered
+* exponential schedule and a wall-clock budget; on exhaustion raises
+* `FaucetExhausted` carrying the last underlying cause.
+*
+* Invariant #4 (jitter): handled by the schedule above. Invariant #3
+* (per-fetch deadline): handled by `requestFundsOnce`'s
+* `AbortSignal.timeout`.
+*/
+const requestFundsWithRetry = (opts) => Effect.gen(function* () {
+	const timeoutMs = opts.timeoutMs ?? 9e4;
+	const maxAttempts = opts.maxAttempts ?? 15;
+	const initialDelayMs = opts.initialDelayMs ?? 500;
+	yield* Effect.annotateCurrentSpan({
+		"faucet.url": opts.faucetUrl,
+		"faucet.address": opts.address,
+		"faucet.amount": opts.amount.toString(),
+		"faucet.budget_ms": timeoutMs,
+		"faucet.max_attempts": maxAttempts
+	});
+	const attempts = yield* Ref.make(0);
+	const lastError = yield* Ref.make(void 0);
+	yield* requestFundsOnce(opts).pipe(Effect.tapError((err) => Effect.gen(function* () {
+		const n = yield* Ref.updateAndGet(attempts, (x) => x + 1);
+		yield* Ref.set(lastError, err);
+		if (opts.onAttempt !== void 0) yield* opts.onAttempt(n, err);
+	}))).pipe(Effect.retry(makeExponentialRetrySchedule({
+		initialDelayMs,
+		maxRetries: maxAttempts,
+		factor: BACKOFF_FACTOR
+	})), Effect.timeoutOrElse({
+		duration: `${timeoutMs} millis`,
+		orElse: () => Effect.gen(function* () {
+			const n = yield* Ref.get(attempts);
+			const last = yield* Ref.get(lastError);
+			return yield* Effect.fail(faucetExhausted({
+				kind: "wall-clock",
+				url: opts.faucetUrl,
+				address: opts.address,
+				amount: opts.amount,
+				attempts: n,
+				message: `faucet did not accept request within ${timeoutMs}ms (${n} attempts; last: ${last?.message ?? "unknown"})`,
+				lastCause: last
+			}));
+		})
+	}));
+}).pipe(Effect.withSpan("faucet.requestFundsWithRetry"));
+//#endregion
+export { requestFundsWithRetry };
+
+//# sourceMappingURL=http.mjs.map

package/dist/plugins/faucet/http.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.mjs","names":[],"sources":["../../../src/plugins/faucet/http.ts"],"sourcesContent":["// Faucet HTTP wrapper.\n//\n// One module per the distilled-doc \"collapse engine/service split\"\n// guidance — the HTTP helper is the only wire-level path for any\n// HTTP-based faucet strategy, and it lives WITH the plugin instead\n// of in a sibling engine module.\n//\n// Wire-level invariants (distilled doc §Invariants):\n//\n//   1. A non-2xx HTTP status MUST raise (NOT be treated as success).\n//      The Sui faucet binds its TCP socket before its validator can\n//      transfer coins — the warm-up window returns 5xx and must be\n//      retried, not silently absorbed.\n//\n//   2. A 200 OK body with `{ status: { Failure: ... } }` MUST raise.\n//      The single most load-bearing invariant in this module: during\n//      warm-up the faucet ACCEPTS requests it cannot execute (gas\n//      object stale, consensus hiccup, mid-genesis). Treating those\n//      bodies as success marks accounts funded when no coins moved.\n//\n//   3. Per-fetch deadline is short relative to wall-clock budget\n//      (5s vs 90s). The faucet's internal retries can block one POST\n//      for ~60s; capping each POST lets the outer retry loop hammer\n//      quickly and land on the first attempt after the chain catches\n//      up.\n//\n//   4. Retry MUST jitter. Pre-jitter, parallel-account retries\n//      synchronized on the wall-clock tick and thundering-herded the\n//      faucet.\n//\n// The shared funds-transferable barrier (invariant #5 in the doc)\n// is owned by Sui and surfaced via the `gate:funds-ready` strategy\n// in `contracts/network-resolver.ts`; consumers call it before the\n// FIRST POST. This module is barrier-agnostic: it assumes callers\n// gate themselves.\n//\n// HTTP transport: `globalThis.fetch` + `AbortSignal.timeout`. Kept\n// direct rather than going through `@effect/platform-node`'s\n// `HttpClient`: this body owns the wire-level contract (status,\n// body-Failure detection, per-fetch deadline) and adding the Effect\n// HttpClient layer here would not change behaviour at any of the\n// invariants above.\n\nimport { Effect, Ref } from 'effect';\n\nimport { makeExponentialRetrySchedule } from '../../substrate/runtime/retry-policy.ts';\nimport {\n\tfaucetBodyError,\n\tfaucetExhausted,\n\tfaucetUnreachable,\n\ttype FaucetBodyError,\n\ttype FaucetExhausted,\n\ttype FaucetUnreachable,\n} from './errors.ts';\n\n// ---------------------------------------------------------------------------\n// Default retry profile\n// ---------------------------------------------------------------------------\n\n/** Retry attempts cap. Paired with the wall-clock budget below: at\n *  500ms initial × 1.5 backoff × jitter, 15 attempts saturates well\n *  before 90s, so the wall-clock check is the dominant exit. */\nexport const DEFAULT_MAX_ATTEMPTS = 15;\n\n/** Initial delay between retries (ms). Subsequent delays grow by\n *  the `BACKOFF_FACTOR`. */\nexport const DEFAULT_INITIAL_DELAY_MS = 500;\n\n/** Wall-clock budget for the WHOLE request including all retries.\n *  Sized for a cold sui-localnet boot — the validator binary needs\n *  ~30–60s after its HTTP socket opens before it can submit txs. */\nexport const DEFAULT_TIMEOUT_MS = 90_000;\n\n/** Exponential growth factor between retries. */\nexport const BACKOFF_FACTOR = 1.5;\n\n/** Per-POST hard deadline. The sui-faucet binary internally retries\n *  the underlying SUI transfer tx twice with ~30s timeouts; a single\n *  cold-chain request blocks ~60s before returning 500. Capping each\n *  POST at 5s lets the outer retry loop hammer quickly — when the\n *  chain catches up the next attempt lands in <1s. Successful\n *  warm-faucet calls return well under 1s, so 5s is a safe ceiling. */\nexport const DEFAULT_FETCH_DEADLINE_MS = 5_000;\n\n// ---------------------------------------------------------------------------\n// Single-shot POST + body parser\n// ---------------------------------------------------------------------------\n\n/** Configuration for a single faucet POST. */\nexport interface FaucetPostOptions {\n\t/** Base URL — e.g. `http://localhost:9123` or\n\t *  `https://faucet.testnet.sui.io`. Path is appended internally. */\n\treadonly faucetUrl: string;\n\t/** Recipient address. */\n\treadonly address: string;\n\t/** Amount in the strategy-native unit (carried through to error\n\t *  payloads). The Sui HTTP faucet itself ignores `amount` and\n\t *  funds a fixed grant per request; the field is here so\n\t *  exhaustion errors carry the unit-correct value. */\n\treadonly amount: bigint;\n\t/** Endpoint path (default `/v2/gas`). Live faucets sometimes\n\t *  diverge — `/gas` on older endpoints. */\n\treadonly path?: string;\n\t/** Per-fetch deadline in ms (default `DEFAULT_FETCH_DEADLINE_MS`). */\n\treadonly fetchDeadlineMs?: number;\n}\n\n/**\n * One-shot POST: send + check status + parse body + check body\n * status. Exported so tests can pin the body-Failure detection\n * without paying the retry / wall-clock cost of the wrapper. Production\n * callers go through `requestFundsWithRetry`.\n *\n * Failure modes raised:\n *   - `FaucetUnreachable` on transport failure (fetch reject, abort\n *      timeout, network error).\n *   - `FaucetBodyError` on non-2xx, body Failure status, or\n *     unparseable JSON. The doc-load-bearing distinction.\n */\nexport const requestFundsOnce = (\n\topts: FaucetPostOptions,\n): Effect.Effect<void, FaucetUnreachable | FaucetBodyError> =>\n\tEffect.gen(function* () {\n\t\tconst path = opts.path ?? '/v2/gas';\n\t\tconst endpoint = `${opts.faucetUrl}${path}`;\n\t\tconst deadlineMs = opts.fetchDeadlineMs ?? DEFAULT_FETCH_DEADLINE_MS;\n\n\t\tconst response = yield* Effect.tryPromise({\n\t\t\ttry: () =>\n\t\t\t\tfetch(endpoint, {\n\t\t\t\t\tmethod: 'POST',\n\t\t\t\t\theaders: { 'content-type': 'application/json' },\n\t\t\t\t\tbody: JSON.stringify({\n\t\t\t\t\t\tFixedAmountRequest: { recipient: opts.address },\n\t\t\t\t\t}),\n\t\t\t\t\tsignal: AbortSignal.timeout(deadlineMs),\n\t\t\t\t}),\n\t\t\tcatch: (cause) =>\n\t\t\t\tfaucetUnreachable({\n\t\t\t\t\turl: opts.faucetUrl,\n\t\t\t\t\taddress: opts.address,\n\t\t\t\t\tamount: opts.amount,\n\t\t\t\t\tmessage: `faucet POST to ${endpoint} failed (transport)`,\n\t\t\t\t\tcause,\n\t\t\t\t}),\n\t\t});\n\n\t\t// Invariant #1: non-2xx MUST raise. We read the body\n\t\t// best-effort so the diagnostic carries the upstream reason\n\t\t// instead of just a numeric status.\n\t\tif (!response.ok) {\n\t\t\tconst body = yield* Effect.tryPromise({\n\t\t\t\ttry: () => response.text(),\n\t\t\t\tcatch: () => undefined,\n\t\t\t}).pipe(Effect.orElseSucceed(() => undefined as string | undefined));\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tfaucetBodyError({\n\t\t\t\t\turl: opts.faucetUrl,\n\t\t\t\t\taddress: opts.address,\n\t\t\t\t\tamount: opts.amount,\n\t\t\t\t\tstatus: response.status,\n\t\t\t\t\treason: 'failure-status',\n\t\t\t\t\tmessage: `faucet returned ${response.status} ${response.statusText}`,\n\t\t\t\t\t...(body !== undefined && body.length > 0 ? { bodySnippet: body } : {}),\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\n\t\t// Invariant #2: 200 OK with body-level Failure MUST raise.\n\t\t// We treat JSON-parse failure as a `malformed-body` raise too —\n\t\t// during cold boot the faucet very occasionally writes an empty\n\t\t// or truncated body before it's ready, and silently accepting\n\t\t// that mirrors the bug we're explicitly guarding against.\n\t\tconst body = (yield* Effect.tryPromise({\n\t\t\ttry: () => response.json() as Promise<unknown>,\n\t\t\tcatch: (cause) =>\n\t\t\t\tfaucetBodyError({\n\t\t\t\t\turl: opts.faucetUrl,\n\t\t\t\t\taddress: opts.address,\n\t\t\t\t\tamount: opts.amount,\n\t\t\t\t\tstatus: response.status,\n\t\t\t\t\treason: 'invalid-json',\n\t\t\t\t\tmessage: 'faucet response was not valid JSON',\n\t\t\t\t\t...(cause !== undefined ? { bodySnippet: String(cause) } : {}),\n\t\t\t\t}),\n\t\t})) as { status?: unknown };\n\n\t\tconst status = body.status;\n\t\tif (typeof status === 'object' && status !== null && 'Failure' in status) {\n\t\t\tconst payload = JSON.stringify((status as { Failure: unknown }).Failure);\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tfaucetBodyError({\n\t\t\t\t\turl: opts.faucetUrl,\n\t\t\t\t\taddress: opts.address,\n\t\t\t\t\tamount: opts.amount,\n\t\t\t\t\tstatus: response.status,\n\t\t\t\t\treason: 'failure-status',\n\t\t\t\t\tmessage: `faucet body reported Failure: ${payload}`,\n\t\t\t\t\tbodySnippet: payload,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t}).pipe(Effect.withSpan('faucet.requestFundsOnce'));\n\n// ---------------------------------------------------------------------------\n// Retry wrapper\n// ---------------------------------------------------------------------------\n\n/** Configuration for a retry-wrapped faucet POST. */\nexport interface RetryOptions extends FaucetPostOptions {\n\t/** Wall-clock budget for the WHOLE request including retries.\n\t *  Default `DEFAULT_TIMEOUT_MS`. CI configs pointing at a clearly\n\t *  broken faucet can lower this to fail-fast. */\n\treadonly timeoutMs?: number;\n\t/** Max attempts cap. Default `DEFAULT_MAX_ATTEMPTS`. */\n\treadonly maxAttempts?: number;\n\t/** Initial inter-attempt delay (ms). Default\n\t *  `DEFAULT_INITIAL_DELAY_MS`. */\n\treadonly initialDelayMs?: number;\n\t/** Optional per-attempt callback. Lets callers surface \"waiting\n\t *  on faucet (attempt N)\" in a TUI row so cold-start doesn't look\n\t *  like a hang. */\n\treadonly onAttempt?: (\n\t\tattempt: number,\n\t\terror: FaucetUnreachable | FaucetBodyError,\n\t) => Effect.Effect<void>;\n}\n\n/**\n * Retry-wrapped POST. Combines `requestFundsOnce` with a jittered\n * exponential schedule and a wall-clock budget; on exhaustion raises\n * `FaucetExhausted` carrying the last underlying cause.\n *\n * Invariant #4 (jitter): handled by the schedule above. Invariant #3\n * (per-fetch deadline): handled by `requestFundsOnce`'s\n * `AbortSignal.timeout`.\n */\nexport const requestFundsWithRetry = (\n\topts: RetryOptions,\n): Effect.Effect<void, FaucetExhausted | FaucetUnreachable | FaucetBodyError> =>\n\tEffect.gen(function* () {\n\t\tconst timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n\t\tconst maxAttempts = opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;\n\t\tconst initialDelayMs = opts.initialDelayMs ?? DEFAULT_INITIAL_DELAY_MS;\n\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t'faucet.url': opts.faucetUrl,\n\t\t\t'faucet.address': opts.address,\n\t\t\t'faucet.amount': opts.amount.toString(),\n\t\t\t'faucet.budget_ms': timeoutMs,\n\t\t\t'faucet.max_attempts': maxAttempts,\n\t\t});\n\n\t\tconst attempts = yield* Ref.make(0);\n\t\tconst lastError = yield* Ref.make<FaucetUnreachable | FaucetBodyError | undefined>(undefined);\n\n\t\tconst wrapped = requestFundsOnce(opts).pipe(\n\t\t\tEffect.tapError((err) =>\n\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\tconst n = yield* Ref.updateAndGet(attempts, (x) => x + 1);\n\t\t\t\t\tyield* Ref.set(lastError, err);\n\t\t\t\t\tif (opts.onAttempt !== undefined) {\n\t\t\t\t\t\tyield* opts.onAttempt(n, err);\n\t\t\t\t\t}\n\t\t\t\t}),\n\t\t\t),\n\t\t);\n\n\t\tyield* wrapped.pipe(\n\t\t\tEffect.retry(\n\t\t\t\tmakeExponentialRetrySchedule({\n\t\t\t\t\tinitialDelayMs,\n\t\t\t\t\tmaxRetries: maxAttempts,\n\t\t\t\t\tfactor: BACKOFF_FACTOR,\n\t\t\t\t}),\n\t\t\t),\n\t\t\tEffect.timeoutOrElse({\n\t\t\t\tduration: `${timeoutMs} millis`,\n\t\t\t\torElse: () =>\n\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\tconst n = yield* Ref.get(attempts);\n\t\t\t\t\t\tconst last = yield* Ref.get(lastError);\n\t\t\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\t\t\tfaucetExhausted({\n\t\t\t\t\t\t\t\tkind: 'wall-clock',\n\t\t\t\t\t\t\t\turl: opts.faucetUrl,\n\t\t\t\t\t\t\t\taddress: opts.address,\n\t\t\t\t\t\t\t\tamount: opts.amount,\n\t\t\t\t\t\t\t\tattempts: n,\n\t\t\t\t\t\t\t\tmessage:\n\t\t\t\t\t\t\t\t\t`faucet did not accept request within ${timeoutMs}ms ` +\n\t\t\t\t\t\t\t\t\t`(${n} attempts; last: ${last?.message ?? 'unknown'})`,\n\t\t\t\t\t\t\t\tlastCause: last,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t);\n\t\t\t\t\t}),\n\t\t\t}),\n\t\t);\n\t}).pipe(Effect.withSpan('faucet.requestFundsWithRetry'));\n"],"mappings":";;;;AA0EA,MAAa,iBAAiB;;;;;;;;;;;;;AA6C9B,MAAa,oBACZ,SAEA,OAAO,IAAI,aAAa;CACvB,MAAM,OAAO,KAAK,QAAQ;CAC1B,MAAM,WAAW,GAAG,KAAK,YAAY;CACrC,MAAM,aAAa,KAAK,mBAAA;CAExB,MAAM,WAAW,OAAO,OAAO,WAAW;EACzC,WACC,MAAM,UAAU;GACf,QAAQ;GACR,SAAS,EAAE,gBAAgB,oBAAoB;GAC/C,MAAM,KAAK,UAAU,EACpB,oBAAoB,EAAE,WAAW,KAAK,SAAS,EAC/C,CAAC;GACF,QAAQ,YAAY,QAAQ,WAAW;GACvC,CAAC;EACH,QAAQ,UACP,kBAAkB;GACjB,KAAK,KAAK;GACV,SAAS,KAAK;GACd,QAAQ,KAAK;GACb,SAAS,kBAAkB,SAAS;GACpC;GACA,CAAC;EACH,CAAC;AAKF,KAAI,CAAC,SAAS,IAAI;EACjB,MAAM,OAAO,OAAO,OAAO,WAAW;GACrC,WAAW,SAAS,MAAM;GAC1B,aAAa,KAAA;GACb,CAAC,CAAC,KAAK,OAAO,oBAAoB,KAAA,EAAgC,CAAC;AACpE,SAAO,OAAO,OAAO,KACpB,gBAAgB;GACf,KAAK,KAAK;GACV,SAAS,KAAK;GACd,QAAQ,KAAK;GACb,QAAQ,SAAS;GACjB,QAAQ;GACR,SAAS,mBAAmB,SAAS,OAAO,GAAG,SAAS;GACxD,GAAI,SAAS,KAAA,KAAa,KAAK,SAAS,IAAI,EAAE,aAAa,MAAM,GAAG,EAAE;GACtE,CAAC,CACF;;CAsBF,MAAM,UAAS,OAdM,OAAO,WAAW;EACtC,WAAW,SAAS,MAAM;EAC1B,QAAQ,UACP,gBAAgB;GACf,KAAK,KAAK;GACV,SAAS,KAAK;GACd,QAAQ,KAAK;GACb,QAAQ,SAAS;GACjB,QAAQ;GACR,SAAS;GACT,GAAI,UAAU,KAAA,IAAY,EAAE,aAAa,OAAO,MAAM,EAAE,GAAG,EAAE;GAC7D,CAAC;EACH,CAAC,EAEkB;AACpB,KAAI,OAAO,WAAW,YAAY,WAAW,QAAQ,aAAa,QAAQ;EACzE,MAAM,UAAU,KAAK,UAAW,OAAgC,QAAQ;AACxE,SAAO,OAAO,OAAO,KACpB,gBAAgB;GACf,KAAK,KAAK;GACV,SAAS,KAAK;GACd,QAAQ,KAAK;GACb,QAAQ,SAAS;GACjB,QAAQ;GACR,SAAS,iCAAiC;GAC1C,aAAa;GACb,CAAC,CACF;;EAED,CAAC,KAAK,OAAO,SAAS,0BAA0B,CAAC;;;;;;;;;;AAmCpD,MAAa,yBACZ,SAEA,OAAO,IAAI,aAAa;CACvB,MAAM,YAAY,KAAK,aAAA;CACvB,MAAM,cAAc,KAAK,eAAA;CACzB,MAAM,iBAAiB,KAAK,kBAAA;AAE5B,QAAO,OAAO,oBAAoB;EACjC,cAAc,KAAK;EACnB,kBAAkB,KAAK;EACvB,iBAAiB,KAAK,OAAO,UAAU;EACvC,oBAAoB;EACpB,uBAAuB;EACvB,CAAC;CAEF,MAAM,WAAW,OAAO,IAAI,KAAK,EAAE;CACnC,MAAM,YAAY,OAAO,IAAI,KAAsD,KAAA,EAAU;AAc7F,QAZgB,iBAAiB,KAAK,CAAC,KACtC,OAAO,UAAU,QAChB,OAAO,IAAI,aAAa;EACvB,MAAM,IAAI,OAAO,IAAI,aAAa,WAAW,MAAM,IAAI,EAAE;AACzD,SAAO,IAAI,IAAI,WAAW,IAAI;AAC9B,MAAI,KAAK,cAAc,KAAA,EACtB,QAAO,KAAK,UAAU,GAAG,IAAI;GAE7B,CACF,CAGY,CAAC,KACd,OAAO,MACN,6BAA6B;EAC5B;EACA,YAAY;EACZ,QAAQ;EACR,CAAC,CACF,EACD,OAAO,cAAc;EACpB,UAAU,GAAG,UAAU;EACvB,cACC,OAAO,IAAI,aAAa;GACvB,MAAM,IAAI,OAAO,IAAI,IAAI,SAAS;GAClC,MAAM,OAAO,OAAO,IAAI,IAAI,UAAU;AACtC,UAAO,OAAO,OAAO,KACpB,gBAAgB;IACf,MAAM;IACN,KAAK,KAAK;IACV,SAAS,KAAK;IACd,QAAQ,KAAK;IACb,UAAU;IACV,SACC,wCAAwC,UAAU,MAC9C,EAAE,mBAAmB,MAAM,WAAW,UAAU;IACrD,WAAW;IACX,CAAC,CACF;IACA;EACH,CAAC,CACF;EACA,CAAC,KAAK,OAAO,SAAS,+BAA+B,CAAC"}

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

@@ -0,0 +1,43 @@
+import { StrategyContributorDecl } from "../../contracts/strategy-contributor.mjs";
+import { FaucetBodyError, FaucetConfigError, FaucetError, FaucetExhausted, FaucetUnreachable } from "./errors.mjs";
+import { FAUCET_CAPABILITY_KEY_PREFIX } from "./dispatcher.mjs";
+import { FaucetStrategy } from "./strategies/sui-local.mjs";
+import { FaucetStrategyContribution } from "./service.mjs";
+
+//#region src/plugins/faucet/index.d.ts
+/**
+ * Build a `StrategyContributorDecl` for a faucet request strategy.
+ * Use from a sibling plugin's `capabilities` array so the
+ * substrate auto-registers the strategy as the plugin acquires:
+ *
+ * ```ts
+ * definePlugin({
+ *   id: 'my-faucet-strategy',
+ *   role: 'service',
+ *   start: () => Effect.succeed({}),
+ *   capabilities: [
+ *     defineFaucetStrategy({
+ *       chainId: 'sui:my-net',
+ *       strategy: makeMyFaucetStrategy(opts),
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * The capability key is computed from the chain id so the dispatcher
+ * picks the contribution up automatically — no extra wiring on the
+ * faucet-plugin side.
+ *
+ * `autoMounted` defaults to `false` (third-party contributions show
+ * up in the dashboard). Pass `autoMounted: true` for built-ins that
+ * the orchestrator includes automatically.
+ */
+declare function defineFaucetStrategy<ChainId extends string>(decl: {
+  readonly chainId: ChainId;
+  readonly strategy: FaucetStrategy;
+  readonly autoMounted?: boolean;
+  readonly priority?: number;
+}): StrategyContributorDecl<`${typeof FAUCET_CAPABILITY_KEY_PREFIX}:${ChainId}`, FaucetStrategy>;
+//#endregion
+export { defineFaucetStrategy };
+//# sourceMappingURL=index.d.mts.map

package/dist/plugins/faucet/index.mjs

@@ -0,0 +1,42 @@
+import { faucetCapabilityKey } from "./dispatcher.mjs";
+//#region src/plugins/faucet/index.ts
+/**
+* Build a `StrategyContributorDecl` for a faucet request strategy.
+* Use from a sibling plugin's `capabilities` array so the
+* substrate auto-registers the strategy as the plugin acquires:
+*
+* ```ts
+* definePlugin({
+*   id: 'my-faucet-strategy',
+*   role: 'service',
+*   start: () => Effect.succeed({}),
+*   capabilities: [
+*     defineFaucetStrategy({
+*       chainId: 'sui:my-net',
+*       strategy: makeMyFaucetStrategy(opts),
+*     }),
+*   ],
+* });
+* ```
+*
+* The capability key is computed from the chain id so the dispatcher
+* picks the contribution up automatically — no extra wiring on the
+* faucet-plugin side.
+*
+* `autoMounted` defaults to `false` (third-party contributions show
+* up in the dashboard). Pass `autoMounted: true` for built-ins that
+* the orchestrator includes automatically.
+*/
+function defineFaucetStrategy(decl) {
+	return {
+		kind: "strategy-contributor",
+		capabilityKey: faucetCapabilityKey(decl.chainId),
+		strategy: decl.strategy,
+		autoMounted: decl.autoMounted ?? false,
+		...decl.priority !== void 0 ? { priority: decl.priority } : {}
+	};
+}
+//#endregion
+export { defineFaucetStrategy };
+
+//# sourceMappingURL=index.mjs.map

package/dist/plugins/faucet/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../src/plugins/faucet/index.ts"],"sourcesContent":["// Faucet plugin-author helpers.\n//\n// Author-side helper: `defineFaucetStrategy(...)` packages a\n// `{ chainId, strategy }` pair into a `StrategyContributorDecl` so\n// third-party plugins can contribute strategies declaratively. The\n// helper threads the literal `chainId` through the type so the\n// downstream consumer's `StrategyFor<...>` lookup recovers the\n// strategy's shape. Built-in account funding reads the strategy\n// registry directly; there is no public `faucet()` stack member.\n\nimport type { StrategyContributorDecl } from '../../contracts/strategy-contributor.ts';\nimport { FAUCET_CAPABILITY_KEY_PREFIX, faucetCapabilityKey } from './dispatcher.ts';\nimport type { FaucetStrategy } from './strategies/sui-local.ts';\n\n// ---------------------------------------------------------------------------\n// Author-side: helper for third-party strategy contributions.\n// ---------------------------------------------------------------------------\n\n/**\n * Build a `StrategyContributorDecl` for a faucet request strategy.\n * Use from a sibling plugin's `capabilities` array so the\n * substrate auto-registers the strategy as the plugin acquires:\n *\n * ```ts\n * definePlugin({\n *   id: 'my-faucet-strategy',\n *   role: 'service',\n *   start: () => Effect.succeed({}),\n *   capabilities: [\n *     defineFaucetStrategy({\n *       chainId: 'sui:my-net',\n *       strategy: makeMyFaucetStrategy(opts),\n *     }),\n *   ],\n * });\n * ```\n *\n * The capability key is computed from the chain id so the dispatcher\n * picks the contribution up automatically — no extra wiring on the\n * faucet-plugin side.\n *\n * `autoMounted` defaults to `false` (third-party contributions show\n * up in the dashboard). Pass `autoMounted: true` for built-ins that\n * the orchestrator includes automatically.\n */\nexport function defineFaucetStrategy<ChainId extends string>(decl: {\n\treadonly chainId: ChainId;\n\treadonly strategy: FaucetStrategy;\n\treadonly autoMounted?: boolean;\n\treadonly priority?: number;\n}): StrategyContributorDecl<`${typeof FAUCET_CAPABILITY_KEY_PREFIX}:${ChainId}`, FaucetStrategy> {\n\treturn {\n\t\tkind: 'strategy-contributor',\n\t\tcapabilityKey: faucetCapabilityKey(decl.chainId),\n\t\tstrategy: decl.strategy,\n\t\tautoMounted: decl.autoMounted ?? false,\n\t\t...(decl.priority !== undefined ? { priority: decl.priority } : {}),\n\t};\n}\n\n// ---------------------------------------------------------------------------\n// Re-exports\n// ---------------------------------------------------------------------------\n\nexport type { FaucetStrategyContribution } from './service.ts';\nexport type {\n\tFaucetError,\n\tFaucetUnreachable,\n\tFaucetExhausted,\n\tFaucetBodyError,\n\tFaucetConfigError,\n} from './errors.ts';\nexport type { FaucetStrategy } from './strategies/sui-local.ts';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,SAAgB,qBAA6C,MAKoC;AAChG,QAAO;EACN,MAAM;EACN,eAAe,oBAAoB,KAAK,QAAQ;EAChD,UAAU,KAAK;EACf,aAAa,KAAK,eAAe;EACjC,GAAI,KAAK,aAAa,KAAA,IAAY,EAAE,UAAU,KAAK,UAAU,GAAG,EAAE;EAClE"}

package/dist/plugins/faucet/service.d.mts

@@ -0,0 +1,20 @@
+import { FaucetStrategy } from "./strategies/sui-local.mjs";
+import { Effect } from "effect";
+
+//#region src/plugins/faucet/service.d.ts
+/** A registered strategy contribution. The faucet plugin accepts
+ *  these from the factory's options so callers can add per-chain
+ *  faucets (custom fork admins, alt-network strategies) without
+ *  authoring a sibling plugin. */
+interface FaucetStrategyContribution {
+  /** Capability-key chain id (`'sui:localnet'`, `'sui:testnet'`, etc.). */
+  readonly chainId: string;
+  /** The strategy value — closes over its own dependencies. */
+  readonly strategy: FaucetStrategy;
+  /** Optional priority. Defaults to `1` so user strategies win
+   *  over the built-in's `0`. */
+  readonly priority?: number;
+}
+//#endregion
+export { FaucetStrategyContribution };
+//# sourceMappingURL=service.d.mts.map

package/dist/plugins/faucet/strategies/sui-local.d.mts

@@ -0,0 +1,23 @@
+import { FaucetBodyError, FaucetExhausted, FaucetUnreachable } from "../errors.mjs";
+import { Effect } from "effect";
+
+//#region src/plugins/faucet/strategies/sui-local.d.ts
+/**
+ * Faucet strategy value. The dispatch surface is uniform across
+ * strategies — the dispatcher doesn't know how a strategy delivers
+ * coins, only how to invoke it.
+ *
+ * `amount` is in MIST (1 SUI = 10^9 MIST), the chain's smallest unit.
+ * The local faucet binary itself ignores this and grants a fixed
+ * amount per request; the parameter is here for type uniformity and
+ * to land correctly-denominated values in `FaucetExhausted`.
+ */
+interface FaucetStrategy {
+  readonly request: (req: {
+    readonly address: string;
+    readonly amount: bigint;
+  }) => Effect.Effect<void, FaucetExhausted | FaucetUnreachable | FaucetBodyError>;
+}
+//#endregion
+export { FaucetStrategy };
+//# sourceMappingURL=sui-local.d.mts.map

package/dist/plugins/faucet/strategies/sui-local.mjs

@@ -0,0 +1,29 @@
+import { leaseKey } from "../../../substrate/runtime/lease-broker/service.mjs";
+import { requestFundsWithRetry } from "../http.mjs";
+import { Effect } from "effect";
+//#region src/plugins/faucet/strategies/sui-local.ts
+const withSerialization = (serialization, effect) => {
+	if (serialization === void 0) return effect;
+	return Effect.scoped(Effect.gen(function* () {
+		yield* serialization.broker.acquire(leaseKey(serialization.key), serialization.owner);
+		yield* effect;
+	})).pipe(Effect.withSpan("faucet.suiLocal.serializedRequest", { attributes: {
+		"faucet.lease.key": serialization.key,
+		"faucet.lease.owner": serialization.owner
+	} }));
+};
+/** Build a SUI local-faucet HTTP strategy. */
+const suiLocalStrategy = (opts) => ({ request: ({ address, amount }) => {
+	const retryOpts = {
+		faucetUrl: opts.faucetUrl,
+		address,
+		amount,
+		...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {},
+		...opts.maxAttempts !== void 0 ? { maxAttempts: opts.maxAttempts } : {}
+	};
+	return withSerialization(opts.serialization, requestFundsWithRetry(retryOpts));
+} });
+//#endregion
+export { suiLocalStrategy };
+
+//# sourceMappingURL=sui-local.mjs.map

package/dist/plugins/faucet/strategies/sui-local.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sui-local.mjs","names":[],"sources":["../../../../src/plugins/faucet/strategies/sui-local.ts"],"sourcesContent":["// SUI local-faucet HTTP strategy.\n//\n// Wraps the in-stack `sui-faucet` HTTP server hosted by the local\n// (or external) Sui container. The faucet URL comes from Sui's\n// resolver (`ResolvedSuiNetwork.faucet`) at acquire time; the\n// strategy CLOSES OVER the URL at construction, so the dispatch\n// site never sees Sui context.\n//\n// Amount semantics: the local faucet returns a fixed-amount grant\n// per request (the binary doesn't honor a variable amount today).\n// We carry `amount` through to error payloads so exhaustion errors\n// match the strategy-native unit (MIST), but the wire request\n// itself does not include it.\n//\n// Distilled-doc opportunity #1 (`Generalize the strategy-registry\n// pattern`): this file is the canonical small example. The whole\n// strategy is 30-ish lines because everything wire-level lives in\n// the shared `http.ts` helper.\n\nimport { Effect } from 'effect';\n\nimport { leaseKey, type LeaseBroker } from '../../../substrate/runtime/lease-broker/index.ts';\nimport { requestFundsWithRetry, type RetryOptions } from '../http.ts';\nimport type { FaucetBodyError, FaucetExhausted, FaucetUnreachable } from '../errors.ts';\n\n/** Optional serialization for faucet backends that spend a shared funding coin. */\nexport interface SuiLocalFaucetSerialization {\n\t/** Stack-local broker; callers choose the resource key shape. */\n\treadonly broker: LeaseBroker;\n\t/** Opaque lease key, typically scoped by chain id. */\n\treadonly key: string;\n\t/** Diagnostic owner reported by the lease broker. */\n\treadonly owner: string;\n}\n\n/** Per-strategy options. */\nexport interface SuiLocalStrategyOptions {\n\t/** Faucet base URL — e.g. `http://localhost:9123`. The strategy\n\t *  appends `/v2/gas` internally. */\n\treadonly faucetUrl: string;\n\t/** Wall-clock budget; forwarded to `requestFundsWithRetry`. */\n\treadonly timeoutMs?: number;\n\t/** Max retry attempts; forwarded to `requestFundsWithRetry`. */\n\treadonly maxAttempts?: number;\n\t/** Serialize requests when the faucet backend shares one funding coin. */\n\treadonly serialization?: SuiLocalFaucetSerialization;\n}\n\n/**\n * Faucet strategy value. The dispatch surface is uniform across\n * strategies — the dispatcher doesn't know how a strategy delivers\n * coins, only how to invoke it.\n *\n * `amount` is in MIST (1 SUI = 10^9 MIST), the chain's smallest unit.\n * The local faucet binary itself ignores this and grants a fixed\n * amount per request; the parameter is here for type uniformity and\n * to land correctly-denominated values in `FaucetExhausted`.\n */\nexport interface FaucetStrategy {\n\treadonly request: (req: {\n\t\treadonly address: string;\n\t\treadonly amount: bigint;\n\t}) => Effect.Effect<void, FaucetExhausted | FaucetUnreachable | FaucetBodyError>;\n}\n\nconst withSerialization = <E>(\n\tserialization: SuiLocalFaucetSerialization | undefined,\n\teffect: Effect.Effect<void, E>,\n): Effect.Effect<void, E> => {\n\tif (serialization === undefined) {\n\t\treturn effect;\n\t}\n\treturn Effect.scoped(\n\t\tEffect.gen(function* () {\n\t\t\tyield* serialization.broker.acquire(leaseKey(serialization.key), serialization.owner);\n\t\t\tyield* effect;\n\t\t}),\n\t).pipe(\n\t\tEffect.withSpan('faucet.suiLocal.serializedRequest', {\n\t\t\tattributes: {\n\t\t\t\t'faucet.lease.key': serialization.key,\n\t\t\t\t'faucet.lease.owner': serialization.owner,\n\t\t\t},\n\t\t}),\n\t);\n};\n\n/** Build a SUI local-faucet HTTP strategy. */\nexport const suiLocalStrategy = (opts: SuiLocalStrategyOptions): FaucetStrategy => ({\n\trequest: ({ address, amount }) => {\n\t\tconst retryOpts: RetryOptions = {\n\t\t\tfaucetUrl: opts.faucetUrl,\n\t\t\taddress,\n\t\t\tamount,\n\t\t\t...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),\n\t\t\t...(opts.maxAttempts !== undefined ? { maxAttempts: opts.maxAttempts } : {}),\n\t\t};\n\t\treturn withSerialization(opts.serialization, requestFundsWithRetry(retryOpts));\n\t},\n});\n"],"mappings":";;;;AAiEA,MAAM,qBACL,eACA,WAC4B;AAC5B,KAAI,kBAAkB,KAAA,EACrB,QAAO;AAER,QAAO,OAAO,OACb,OAAO,IAAI,aAAa;AACvB,SAAO,cAAc,OAAO,QAAQ,SAAS,cAAc,IAAI,EAAE,cAAc,MAAM;AACrF,SAAO;GACN,CACF,CAAC,KACD,OAAO,SAAS,qCAAqC,EACpD,YAAY;EACX,oBAAoB,cAAc;EAClC,sBAAsB,cAAc;EACpC,EACD,CAAC,CACF;;;AAIF,MAAa,oBAAoB,UAAmD,EACnF,UAAU,EAAE,SAAS,aAAa;CACjC,MAAM,YAA0B;EAC/B,WAAW,KAAK;EAChB;EACA;EACA,GAAI,KAAK,cAAc,KAAA,IAAY,EAAE,WAAW,KAAK,WAAW,GAAG,EAAE;EACrE,GAAI,KAAK,gBAAgB,KAAA,IAAY,EAAE,aAAa,KAAK,aAAa,GAAG,EAAE;EAC3E;AACD,QAAO,kBAAkB,KAAK,eAAe,sBAAsB,UAAU,CAAC;GAE/E"}

package/dist/plugins/host-service/errors.d.mts

@@ -0,0 +1,27 @@
+import { ConfigIssue } from "../../substrate/runtime/config-validation.mjs";
+import * as _$effect_Types0 from "effect/Types";
+import * as _$effect_Cause0 from "effect/Cause";
+
+//#region src/plugins/host-service/errors.d.ts
+interface HostServiceConfigError extends ConfigIssue {
+  readonly _tag: 'HostServiceConfigError';
+  readonly serviceName: string;
+}
+declare const HostServiceAcquireError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "HostServiceAcquireError";
+} & Readonly<A>;
+declare class HostServiceAcquireError extends HostServiceAcquireError_base<{
+  readonly serviceName: string;
+  readonly cwd: string;
+  readonly command: string;
+  readonly args: ReadonlyArray<string>;
+  readonly phase: 'allocate-port' | 'spawn' | 'ready' | 'exit';
+  readonly message: string;
+  readonly exitCode?: number | null;
+  readonly signal?: NodeJS.Signals | null;
+  readonly cause?: unknown;
+}> {}
+type HostServiceError = HostServiceConfigError | HostServiceAcquireError;
+//#endregion
+export { HostServiceAcquireError, HostServiceConfigError, HostServiceError };
+//# sourceMappingURL=errors.d.mts.map

package/dist/plugins/host-service/errors.mjs

@@ -0,0 +1,14 @@
+import { defineConfigError } from "../../substrate/runtime/config-validation.mjs";
+import { Data } from "effect";
+//#region src/plugins/host-service/errors.ts
+const makeHostServiceConfigError = defineConfigError("HostServiceConfigError");
+const hostServiceConfigError = (serviceName, issue) => ({
+	...makeHostServiceConfigError(issue),
+	serviceName
+});
+var HostServiceAcquireError = class extends Data.TaggedError("HostServiceAcquireError") {};
+const HOST_SERVICE_ERROR_TAGS = ["HostServiceConfigError", "HostServiceAcquireError"];
+//#endregion
+export { HOST_SERVICE_ERROR_TAGS, HostServiceAcquireError, hostServiceConfigError };
+
+//# sourceMappingURL=errors.mjs.map

package/dist/plugins/host-service/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../../src/plugins/host-service/errors.ts"],"sourcesContent":["import { Data } from 'effect';\n\nimport { defineConfigError, type ConfigIssue } from '../../substrate/runtime/config-validation.ts';\n\nexport interface HostServiceConfigError extends ConfigIssue {\n\treadonly _tag: 'HostServiceConfigError';\n\treadonly serviceName: string;\n}\n\nconst makeHostServiceConfigError = defineConfigError('HostServiceConfigError');\n\nexport const hostServiceConfigError = (\n\tserviceName: string,\n\tissue: ConfigIssue,\n): HostServiceConfigError => ({\n\t...makeHostServiceConfigError(issue),\n\tserviceName,\n});\n\nexport class HostServiceAcquireError extends Data.TaggedError('HostServiceAcquireError')<{\n\treadonly serviceName: string;\n\treadonly cwd: string;\n\treadonly command: string;\n\treadonly args: ReadonlyArray<string>;\n\treadonly phase: 'allocate-port' | 'spawn' | 'ready' | 'exit';\n\treadonly message: string;\n\treadonly exitCode?: number | null;\n\treadonly signal?: NodeJS.Signals | null;\n\treadonly cause?: unknown;\n}> {}\n\nexport type HostServiceError = HostServiceConfigError | HostServiceAcquireError;\n\nexport const HOST_SERVICE_ERROR_TAGS = [\n\t'HostServiceConfigError',\n\t'HostServiceAcquireError',\n] as const;\n"],"mappings":";;;AASA,MAAM,6BAA6B,kBAAkB,yBAAyB;AAE9E,MAAa,0BACZ,aACA,WAC6B;CAC7B,GAAG,2BAA2B,MAAM;CACpC;CACA;AAED,IAAa,0BAAb,cAA6C,KAAK,YAAY,0BAA0B,CAUrF;AAIH,MAAa,0BAA0B,CACtC,0BACA,0BACA"}

package/dist/plugins/host-service/index.d.mts

@@ -0,0 +1,10 @@
+import { RoutableDecl } from "../../contracts/routable.mjs";
+import { AnyResourceRef, Plugin } from "../../substrate/plugin.mjs";
+import { HostServiceAcquireError, HostServiceConfigError, HostServiceError } from "./errors.mjs";
+import { HOST_SERVICE_PORT_TOKEN, HostServiceOptions, HostServiceReadyProbe, HostServiceValue } from "./service.mjs";
+//#region src/plugins/host-service/index.d.ts
+type HostServiceAfter = ReadonlyArray<AnyResourceRef>;
+declare const hostService: <const After extends HostServiceAfter = readonly []>(options: HostServiceOptions<After>) => Plugin<`host-service/${string}`, HostServiceValue, After, readonly [RoutableDecl]>;
+//#endregion
+export { hostService };
+//# sourceMappingURL=index.d.mts.map