@mysten-incubation/devstack 0.0.1 → 0.1.1

package/dist/plugins/deepbook/type-strings.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-strings.mjs","names":[],"sources":["../../../src/plugins/deepbook/type-strings.ts"],"sourcesContent":["// DeepBook type-string helpers.\n//\n// Mirrors `plugins/coin/type-strings.ts`: a position-aware matcher over\n// a fully-qualified Sui type string instead of substring sniffing.\n//\n// The coin helper is anchored to the framework `0x2::coin::<Wrapper><T>`\n// (single inner generic). A DeepBook pool object is\n// `<pkg>::pool::Pool<Base, Quote>` — a NON-framework package with TWO\n// positional generic arguments — so it needs its own parser. Both\n// arguments and the spec coin types are normalized with the shared SDK\n// `normalizeStructTag` (which recursively pads addresses) and compared\n// POSITIONALLY, so a reversed pair (`DEEP/SUI` vs `SUI/DEEP`) or a coin\n// type that is a substring of another can no longer cross-match.\n\nimport { normalizeStructTag } from '@mysten/sui/utils';\n\n/** Parse the two positional generic arguments out of a\n *  `<pkg>::pool::Pool<Base, Quote>` object type. Returns `null` when the\n *  type is not a `::pool::Pool<…>` with exactly two top-level arguments\n *  (the SDK may pad the package address, so the module/wrapper suffix is\n *  matched on the `::pool::Pool<` marker rather than the full prefix). */\nexport const parsePoolGenericArgs = (\n\tobjectType: string,\n): { readonly base: string; readonly quote: string } | null => {\n\tif (!objectType.endsWith('>')) return null;\n\tconst marker = '::pool::Pool<';\n\tconst markerIndex = objectType.indexOf(marker);\n\tif (markerIndex === -1) return null;\n\tconst inner = objectType.slice(markerIndex + marker.length, -1);\n\tconst args = splitTopLevelGenericArgs(inner);\n\tif (args.length !== 2) return null;\n\tconst [base, quote] = args;\n\tif (base === undefined || quote === undefined) return null;\n\treturn { base, quote };\n};\n\n/** Does `objectType` name a `Pool<Base, Quote>` whose generic arguments\n *  match `(baseCoinType, quoteCoinType)` POSITIONALLY? Each side is\n *  compared via `normalizeStructTag` so framework-address padding does\n *  not defeat the match and a reversed pair does not collide. */\nexport const isPoolForPair = (\n\tobjectType: string,\n\tbaseCoinType: string,\n\tquoteCoinType: string,\n): boolean => {\n\tconst parsed = parsePoolGenericArgs(objectType);\n\tif (parsed === null) return false;\n\tconst base = normalizeStructTagSafe(parsed.base);\n\tconst quote = normalizeStructTagSafe(parsed.quote);\n\tconst wantBase = normalizeStructTagSafe(baseCoinType);\n\tconst wantQuote = normalizeStructTagSafe(quoteCoinType);\n\t// A malformed tag normalizes to `null`; never let two nulls compare\n\t// equal — a doubly-malformed side must NOT spuriously pair.\n\tif (base === null || quote === null || wantBase === null || wantQuote === null) return false;\n\treturn base === wantBase && quote === wantQuote;\n};\n\n/** Split a generic-argument list on top-level commas, respecting nested\n *  `<…>` so a generic coin type argument is not split mid-bracket. */\nconst splitTopLevelGenericArgs = (inner: string): ReadonlyArray<string> => {\n\tconst args: string[] = [];\n\tlet depth = 0;\n\tlet start = 0;\n\tfor (let i = 0; i < inner.length; i += 1) {\n\t\tconst ch = inner[i];\n\t\tif (ch === '<') depth += 1;\n\t\telse if (ch === '>') depth -= 1;\n\t\telse if (ch === ',' && depth === 0) {\n\t\t\targs.push(inner.slice(start, i).trim());\n\t\t\tstart = i + 1;\n\t\t}\n\t}\n\targs.push(inner.slice(start).trim());\n\treturn args;\n};\n\n/** `normalizeStructTag` throws on a malformed tag; coerce to a sentinel\n *  so a bad parse fails the positional compare rather than the caller. */\nconst normalizeStructTagSafe = (tag: string): string | null => {\n\ttry {\n\t\treturn normalizeStructTag(tag);\n\t} catch {\n\t\treturn null;\n\t}\n};\n"],"mappings":";;;;;;;AAqBA,MAAa,wBACZ,eAC8D;AAC9D,KAAI,CAAC,WAAW,SAAS,IAAI,CAAE,QAAO;CAEtC,MAAM,cAAc,WAAW,QAAQ,gBAAO;AAC9C,KAAI,gBAAgB,GAAI,QAAO;CAE/B,MAAM,OAAO,yBADC,WAAW,MAAM,cAAc,IAAe,GACjB,CAAC;AAC5C,KAAI,KAAK,WAAW,EAAG,QAAO;CAC9B,MAAM,CAAC,MAAM,SAAS;AACtB,KAAI,SAAS,KAAA,KAAa,UAAU,KAAA,EAAW,QAAO;AACtD,QAAO;EAAE;EAAM;EAAO;;;;;;AAOvB,MAAa,iBACZ,YACA,cACA,kBACa;CACb,MAAM,SAAS,qBAAqB,WAAW;AAC/C,KAAI,WAAW,KAAM,QAAO;CAC5B,MAAM,OAAO,uBAAuB,OAAO,KAAK;CAChD,MAAM,QAAQ,uBAAuB,OAAO,MAAM;CAClD,MAAM,WAAW,uBAAuB,aAAa;CACrD,MAAM,YAAY,uBAAuB,cAAc;AAGvD,KAAI,SAAS,QAAQ,UAAU,QAAQ,aAAa,QAAQ,cAAc,KAAM,QAAO;AACvF,QAAO,SAAS,YAAY,UAAU;;;;AAKvC,MAAM,4BAA4B,UAAyC;CAC1E,MAAM,OAAiB,EAAE;CACzB,IAAI,QAAQ;CACZ,IAAI,QAAQ;AACZ,MAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK,GAAG;EACzC,MAAM,KAAK,MAAM;AACjB,MAAI,OAAO,IAAK,UAAS;WAChB,OAAO,IAAK,UAAS;WACrB,OAAO,OAAO,UAAU,GAAG;AACnC,QAAK,KAAK,MAAM,MAAM,OAAO,EAAE,CAAC,MAAM,CAAC;AACvC,WAAQ,IAAI;;;AAGd,MAAK,KAAK,MAAM,MAAM,MAAM,CAAC,MAAM,CAAC;AACpC,QAAO;;;;AAKR,MAAM,0BAA0B,QAA+B;AAC9D,KAAI;AACH,SAAO,mBAAmB,IAAI;SACvB;AACP,SAAO"}

package/dist/plugins/deepbook/types.d.mts

@@ -1,8 +1,7 @@
 import { ResourceRef } from "../../substrate/plugin.mjs";
-import { CoinValue } from "../coin/service.mjs";
 import { AccountValue } from "../account/service.mjs";
 import { LocalPackageResolved } from "../package/index.mjs";
-
+import { CoinValue } from "../coin/service.mjs";
 //#region src/plugins/deepbook/types.d.ts
 /** A Pyth price feed id — opaque 64-character hex string. */
 type PythPriceFeedId = string & {
@@ -121,5 +120,5 @@ type DeepbookPackageMember<Name extends string = string> = ResourceRef<`package:
 /** Local package ref alias for the mock Pyth package used by local DeepBook. */
 type PythPackageMember<Name extends string = string> = ResourceRef<`package:${Name}`, LocalPackageResolved>;
 //#endregion
-export { AccountMemberAlias, CoinMemberAlias, DEEP_PRICE_FEED_ID, DeepbookPackageMember, DeepbookPool, DeepbookPoolCoin, DeepbookPoolSeedLiquidity, DeepbookPoolSeedOrder, DeepbookPoolSpec, PythFeed, PythHandle, PythOptions, PythPackageMember, PythPriceFeedId, SUI_PRICE_FEED_ID, USDC_PRICE_FEED_ID, pythPriceFeedId };
+export { AccountMemberAlias, CoinMemberAlias, DEEP_PRICE_FEED_ID, DeepbookPackageMember, DeepbookPool, DeepbookPoolCoin, DeepbookPoolSeedLiquidity, DeepbookPoolSeedOrder, DeepbookPoolSpec, PythHandle, PythOptions, SUI_PRICE_FEED_ID, USDC_PRICE_FEED_ID, pythPriceFeedId };
 //# sourceMappingURL=types.d.mts.map

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

@@ -1 +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"}
+{"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// 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

@@ -1,9 +1,28 @@
-import { Effect } from "effect";
+import { FaucetStrategy as FaucetStrategy$1 } from "../../contracts/faucet-strategy.mjs";
+import { FaucetBodyError, FaucetExhausted, FaucetUnreachable } from "./errors.mjs";
 
 //#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";
+/**
+ * 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.
+ *
+ * The generic contract lives in `contracts/faucet-strategy.ts` and
+ * is parameterised over the strategy's error channel. The faucet
+ * plugin narrows the alias to its tagged-error union so existing
+ * dispatcher consumers (the strategy registry, request retry shim)
+ * see the historical type unchanged.
+ *
+ * `amount` is the chain-native smallest unit (MIST for SUI). Some
+ * backends (the local sui-faucet binary) grant a fixed amount per
+ * request and IGNORE this value; the parameter is here for type
+ * uniformity and to land correctly-denominated values in
+ * `FaucetExhausted`.
+ */
+type FaucetStrategy = FaucetStrategy$1<FaucetExhausted | FaucetUnreachable | FaucetBodyError>;
 //#endregion
-export { FAUCET_CAPABILITY_KEY_PREFIX };
+export { FAUCET_CAPABILITY_KEY_PREFIX, FaucetStrategy };
 //# sourceMappingURL=dispatcher.d.mts.map

package/dist/plugins/faucet/dispatcher.mjs

@@ -1,4 +1,3 @@
-import "effect";
 //#region src/plugins/faucet/dispatcher.ts
 /** Capability key prefix for a faucet request strategy. The full
 *  key is `faucet:request:<chainId>`. */
@@ -8,6 +7,6 @@ const FAUCET_CAPABILITY_KEY_PREFIX = "faucet:request";
 *  shape out of a tuple by name. */
 const faucetCapabilityKey = (chainId) => `${FAUCET_CAPABILITY_KEY_PREFIX}:${chainId}`;
 //#endregion
-export { faucetCapabilityKey };
+export { FAUCET_CAPABILITY_KEY_PREFIX, faucetCapabilityKey };
 
 //# sourceMappingURL=dispatcher.mjs.map

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

@@ -1 +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"}
+{"version":3,"file":"dispatcher.mjs","names":[],"sources":["../../../src/plugins/faucet/dispatcher.ts"],"sourcesContent":["// Faucet capability-key encoding + dispatch contract.\n//\n// Architecture (distilled doc §Selection rule): the faucet plugin's\n// substrate-side dispatch is by capability key only — `faucet:request:<chainId>`.\n// The chain id is the substrate-level `NetworkConfig.chain` value\n// (e.g. `'sui:localnet'`, `'sui:testnet'`, `'sui:mainnet-fork@123'`).\n//\n// Sibling plugins (currently `sui`) reach in for `faucetCapabilityKey`\n// to register a faucet strategy keyed by chain id. The previous\n// `FaucetDispatcher` / `makeDispatcher` shape was a dead acquire-time\n// closure with no callers; the substrate-level\n// `substrate/runtime/strategy-registry/faucet-capability-for.ts` is the\n// canonical lookup helper now.\n//\n// The generic `FaucetStrategy<E>` contract lives in\n// `contracts/faucet-strategy.ts` (substrate-neutral, name-blind). This\n// file narrows the alias to the faucet plugin's tagged-error union so\n// strategy implementations (sui-local, future user strategies) close\n// over their own wire surface and satisfy this shape; the dispatcher\n// is implementation-blind.\n\nimport type { FaucetStrategy as FaucetStrategyContract } from '../../contracts/faucet-strategy.ts';\n\nimport type { FaucetBodyError, FaucetExhausted, FaucetUnreachable } from './errors.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/**\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 * The generic contract lives in `contracts/faucet-strategy.ts` and\n * is parameterised over the strategy's error channel. The faucet\n * plugin narrows the alias to its tagged-error union so existing\n * dispatcher consumers (the strategy registry, request retry shim)\n * see the historical type unchanged.\n *\n * `amount` is the chain-native smallest unit (MIST for SUI). Some\n * backends (the local sui-faucet binary) grant a fixed amount per\n * request and IGNORE this value; the parameter is here for type\n * uniformity and to land correctly-denominated values in\n * `FaucetExhausted`.\n */\nexport type FaucetStrategy = FaucetStrategyContract<\n\tFaucetExhausted | FaucetUnreachable | FaucetBodyError\n>;\n"],"mappings":";;;AA2BA,MAAa,+BAA+B;;;;AAK5C,MAAa,uBACZ,YAEA,GAAG,6BAA6B,GAAG"}

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

@@ -19,17 +19,21 @@ interface FaucetUnreachable {
   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".
+ * Wall-clock budget exhaustion. The retry loop did not land a
+ * successful attempt within the configured `timeoutMs`.
+ *
+ * The attempt-count cap (`maxRetries` on the schedule) does NOT
+ * surface as `FaucetExhausted` — when the retry schedule exhausts,
+ * Effect re-raises the LAST `FaucetUnreachable | FaucetBodyError`
+ * verbatim, which is more informative than a wrapped budget message.
+ * Callers handling `FaucetUnreachable | FaucetBodyError` already see
+ * the right wire-level cause.
  *
  * 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;
@@ -54,33 +58,16 @@ interface FaucetBodyError {
   readonly address: string;
   readonly amount: bigint;
   readonly status: number;
-  readonly reason: 'failure-status' | 'malformed-body' | 'invalid-json';
+  readonly reason: 'failure-status' | '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;
+type FaucetError = FaucetUnreachable | FaucetExhausted | FaucetBodyError | FaucetConfigError;
 //#endregion
 export { FaucetBodyError, FaucetConfigError, FaucetError, FaucetExhausted, FaucetUnreachable };
 //# sourceMappingURL=errors.d.mts.map

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

@@ -1 +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"}
+{"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//   - Wall-clock budget exhaustion surfaces as `FaucetExhausted`. The\n//     attempt-cap (`maxRetries` on the underlying retry schedule)\n//     re-raises the LAST `FaucetUnreachable | FaucetBodyError` directly\n//     — wrapping it in `FaucetExhausted` would just hide the wire-level\n//     error the cap was triggered by. The wall-clock budget is the\n//     dominant exit; the attempt cap exists as a safety net.\n//\n// Effect v4: tagged errors are plain interfaces; `Effect.catchTag` /\n// `catchTags` match on the `_tag` literal.\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 * Wall-clock budget exhaustion. The retry loop did not land a\n * successful attempt within the configured `timeoutMs`.\n *\n * The attempt-count cap (`maxRetries` on the schedule) does NOT\n * surface as `FaucetExhausted` — when the retry schedule exhausts,\n * Effect re-raises the LAST `FaucetUnreachable | FaucetBodyError`\n * verbatim, which is more informative than a wrapped budget message.\n * Callers handling `FaucetUnreachable | FaucetBodyError` already see\n * the right wire-level cause.\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 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' | '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\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| FaucetConfigError;\n"],"mappings":";;AAyCA,MAAa,qBAAqB,WAA+D;CAChG,MAAM;CACN,GAAG;CACH;AA0BD,MAAa,mBAAmB,WAA2D;CAC1F,MAAM;CACN,GAAG;CACH;AAyBD,MAAa,mBAAmB,WAA2D;CAC1F,MAAM;CACN,GAAG;CACH;AAMgC,kBAAkB,oBAAoB"}

package/dist/plugins/faucet/http.mjs

@@ -1,8 +1,28 @@
+import { FAUCET_HTTP_RETRY_PROFILE, makeExponentialRetrySchedule } from "../../substrate/runtime/retry-policy.mjs";
 import { faucetBodyError, faucetExhausted, faucetUnreachable } from "./errors.mjs";
-import { makeExponentialRetrySchedule } from "../../substrate/runtime/retry-policy.mjs";
+import { FaucetSpans } from "./spans.mjs";
 import { Effect, Ref } from "effect";
+//#region src/plugins/faucet/http.ts
+/** Retry attempts cap. Paired with the wall-clock budget below: at
+*  500ms initial × 1.5 backoff × jitter, 15 attempts saturates well
+*  before 90s, so the wall-clock check is the dominant exit. */
+const DEFAULT_MAX_ATTEMPTS = FAUCET_HTTP_RETRY_PROFILE.maxAttempts;
+/** Initial delay between retries (ms). Subsequent delays grow by
+*  the `BACKOFF_FACTOR`. */
+const DEFAULT_INITIAL_DELAY_MS = FAUCET_HTTP_RETRY_PROFILE.initialDelayMs;
+/** Wall-clock budget for the WHOLE request including all retries.
+*  Sized for a cold sui-localnet boot — the validator binary needs
+*  ~30–60s after its HTTP socket opens before it can submit txs. */
+const DEFAULT_TIMEOUT_MS = FAUCET_HTTP_RETRY_PROFILE.wallClockBudgetMs;
 /** Exponential growth factor between retries. */
-const BACKOFF_FACTOR = 1.5;
+const BACKOFF_FACTOR = FAUCET_HTTP_RETRY_PROFILE.backoffFactor;
+/** Per-POST hard deadline. The sui-faucet binary internally retries
+*  the underlying SUI transfer tx twice with ~30s timeouts; a single
+*  cold-chain request blocks ~60s before returning 500. Capping each
+*  POST at 5s lets the outer retry loop hammer quickly — when the
+*  chain catches up the next attempt lands in <1s. Successful
+*  warm-faucet calls return well under 1s, so 5s is a safe ceiling. */
+const DEFAULT_FETCH_DEADLINE_MS = FAUCET_HTTP_RETRY_PROFILE.perRequestDeadlineMs;
 /**
 * One-shot POST: send + check status + parse body + check body
 * status. Exported so tests can pin the body-Failure detection
@@ -18,7 +38,7 @@ const BACKOFF_FACTOR = 1.5;
 const requestFundsOnce = (opts) => Effect.gen(function* () {
 	const path = opts.path ?? "/v2/gas";
 	const endpoint = `${opts.faucetUrl}${path}`;
-	const deadlineMs = opts.fetchDeadlineMs ?? 5e3;
+	const deadlineMs = opts.fetchDeadlineMs ?? DEFAULT_FETCH_DEADLINE_MS;
 	const response = yield* Effect.tryPromise({
 		try: () => fetch(endpoint, {
 			method: "POST",
@@ -73,7 +93,7 @@ const requestFundsOnce = (opts) => Effect.gen(function* () {
 			bodySnippet: payload
 		}));
 	}
-}).pipe(Effect.withSpan("faucet.requestFundsOnce"));
+}).pipe(Effect.withSpan("devstack.plugin.faucet.requestFundsOnce"));
 /**
 * Retry-wrapped POST. Combines `requestFundsOnce` with a jittered
 * exponential schedule and a wall-clock budget; on exhaustion raises
@@ -84,15 +104,15 @@ const requestFundsOnce = (opts) => Effect.gen(function* () {
 * `AbortSignal.timeout`.
 */
 const requestFundsWithRetry = (opts) => Effect.gen(function* () {
-	const timeoutMs = opts.timeoutMs ?? 9e4;
-	const maxAttempts = opts.maxAttempts ?? 15;
-	const initialDelayMs = opts.initialDelayMs ?? 500;
+	const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const maxAttempts = opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+	const initialDelayMs = opts.initialDelayMs ?? DEFAULT_INITIAL_DELAY_MS;
 	yield* Effect.annotateCurrentSpan({
-		"faucet.url": opts.faucetUrl,
-		"faucet.address": opts.address,
-		"faucet.amount": opts.amount.toString(),
-		"faucet.budget_ms": timeoutMs,
-		"faucet.max_attempts": maxAttempts
+		[FaucetSpans.url]: opts.faucetUrl,
+		[FaucetSpans.address]: opts.address,
+		[FaucetSpans.amount]: opts.amount.toString(),
+		[FaucetSpans.budgetMs]: timeoutMs,
+		[FaucetSpans.maxAttempts]: maxAttempts
 	});
 	const attempts = yield* Ref.make(0);
 	const lastError = yield* Ref.make(void 0);
@@ -110,7 +130,6 @@ const requestFundsWithRetry = (opts) => 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,
@@ -120,7 +139,7 @@ const requestFundsWithRetry = (opts) => Effect.gen(function* () {
 			}));
 		})
 	}));
-}).pipe(Effect.withSpan("faucet.requestFundsWithRetry"));
+}).pipe(Effect.withSpan("devstack.plugin.faucet.requestFundsWithRetry"));
 //#endregion
 export { requestFundsWithRetry };
 

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

@@ -1 +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"}
+{"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 directly via\n// `resolved.waitForTransactionsReady.wait`; consumers call it before\n// the 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//\n// The substrate's `HttpProbes.waitForHttpEndpoint(...)` is for *readiness probes*\n// (poll a GET until ready), not one-shot POST + body-shape validation.\n// The wire-level contract above (non-2xx raise, body-Failure raise,\n// short per-fetch deadline relative to retry budget) is owned here.\n// The retry SCHEDULE shape, however, IS substrate-supplied — it\n// composes `makeExponentialRetrySchedule` from `retry-policy.ts`\n// and reads its constants from `FAUCET_HTTP_RETRY_PROFILE`.\n\nimport { Effect, Ref } from 'effect';\n\nimport {\n\tFAUCET_HTTP_RETRY_PROFILE,\n\tmakeExponentialRetrySchedule,\n} 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';\nimport { FaucetSpans } from './spans.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 = FAUCET_HTTP_RETRY_PROFILE.maxAttempts;\n\n/** Initial delay between retries (ms). Subsequent delays grow by\n *  the `BACKOFF_FACTOR`. */\nexport const DEFAULT_INITIAL_DELAY_MS = FAUCET_HTTP_RETRY_PROFILE.initialDelayMs;\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 = FAUCET_HTTP_RETRY_PROFILE.wallClockBudgetMs;\n\n/** Exponential growth factor between retries. */\nexport const BACKOFF_FACTOR = FAUCET_HTTP_RETRY_PROFILE.backoffFactor;\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 = FAUCET_HTTP_RETRY_PROFILE.perRequestDeadlineMs;\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 an `invalid-json` 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('devstack.plugin.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[FaucetSpans.url]: opts.faucetUrl,\n\t\t\t[FaucetSpans.address]: opts.address,\n\t\t\t[FaucetSpans.amount]: opts.amount.toString(),\n\t\t\t[FaucetSpans.budgetMs]: timeoutMs,\n\t\t\t[FaucetSpans.maxAttempts]: 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\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('devstack.plugin.faucet.requestFundsWithRetry'));\n"],"mappings":"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"}

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

@@ -1,9 +1,6 @@
 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";
-
+import { FAUCET_CAPABILITY_KEY_PREFIX, FaucetStrategy } from "./dispatcher.mjs";
 //#region src/plugins/faucet/index.d.ts
 /**
  * Build a `StrategyContributorDecl` for a faucet request strategy.
@@ -38,6 +35,19 @@ declare function defineFaucetStrategy<ChainId extends string>(decl: {
   readonly autoMounted?: boolean;
   readonly priority?: number;
 }): StrategyContributorDecl<`${typeof FAUCET_CAPABILITY_KEY_PREFIX}:${ChainId}`, FaucetStrategy>;
+/** A registered strategy contribution. Plugin authors that batch
+ *  multiple per-chain strategies (custom fork admins, alt-network
+ *  faucets) shape their config arrays around this; the underlying
+ *  registration mechanic is `defineFaucetStrategy`. */
+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 { defineFaucetStrategy };
+export { FaucetStrategyContribution, defineFaucetStrategy };
 //# sourceMappingURL=index.d.mts.map

package/dist/plugins/faucet/index.mjs

@@ -1,4 +1,7 @@
 import { faucetCapabilityKey } from "./dispatcher.mjs";
+import "./errors.mjs";
+import "./spans.mjs";
+import "./http.mjs";
 //#region src/plugins/faucet/index.ts
 /**
 * Build a `StrategyContributorDecl` for a faucet request strategy.

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

@@ -1 +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"}
+{"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 {\n\tFAUCET_CAPABILITY_KEY_PREFIX,\n\tfaucetCapabilityKey,\n\ttype FaucetStrategy,\n} from './dispatcher.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// Public types\n// ---------------------------------------------------------------------------\n\n/** A registered strategy contribution. Plugin authors that batch\n *  multiple per-chain strategies (custom fork admins, alt-network\n *  faucets) shape their config arrays around this; the underlying\n *  registration mechanic is `defineFaucetStrategy`. */\nexport interface FaucetStrategyContribution {\n\t/** Capability-key chain id (`'sui:localnet'`, `'sui:testnet'`, etc.). */\n\treadonly chainId: string;\n\t/** The strategy value — closes over its own dependencies. */\n\treadonly strategy: FaucetStrategy;\n\t/** Optional priority. Defaults to `1` so user strategies win over\n\t *  the built-in's `0`. */\n\treadonly priority?: number;\n}\n\nexport type {\n\tFaucetError,\n\tFaucetUnreachable,\n\tFaucetExhausted,\n\tFaucetBodyError,\n\tFaucetConfigError,\n} from './errors.ts';\nexport { faucetBodyError, faucetConfigError } from './errors.ts';\nexport { requestFundsWithRetry, type RetryOptions } from './http.ts';\nexport {\n\tFAUCET_CAPABILITY_KEY_PREFIX,\n\tfaucetCapabilityKey,\n\ttype FaucetStrategy,\n} from './dispatcher.ts';\nexport { FaucetSpans } from './spans.ts';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgDA,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/spans.mjs

@@ -0,0 +1,12 @@
+//#region src/plugins/faucet/spans.ts
+const FaucetSpans = {
+	address: "faucet.address",
+	amount: "faucet.amount",
+	budgetMs: "faucet.budget_ms",
+	maxAttempts: "faucet.max_attempts",
+	url: "faucet.url"
+};
+//#endregion
+export { FaucetSpans };
+
+//# sourceMappingURL=spans.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spans.mjs","names":[],"sources":["../../../src/plugins/faucet/spans.ts"],"sourcesContent":["// Faucet plugin span-attribute vocabulary. Plugin-local — substrate's\n// `SpanAttr` carries only engine-dimensional + http/process generic\n// keys; plugin-domain keys live next to the plugin that owns them.\n//\n// Callsite pattern: `Effect.annotateCurrentSpan({ [FaucetSpans.url]:\n// value })`. Free-form string literals are a STYLE_GUIDE §16 violation.\n\nexport const FaucetSpans = {\n\taddress: 'faucet.address',\n\tamount: 'faucet.amount',\n\tbudgetMs: 'faucet.budget_ms',\n\tmaxAttempts: 'faucet.max_attempts',\n\turl: 'faucet.url',\n} as const;\n"],"mappings":";AAOA,MAAa,cAAc;CAC1B,SAAS;CACT,QAAQ;CACR,UAAU;CACV,aAAa;CACb,KAAK;CACL"}

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

@@ -1,6 +1,6 @@
 import { ConfigIssue } from "../../substrate/runtime/config-validation.mjs";
-import * as _$effect_Types0 from "effect/Types";
 import * as _$effect_Cause0 from "effect/Cause";
+import * as _$effect_Types0 from "effect/Types";
 
 //#region src/plugins/host-service/errors.d.ts
 interface HostServiceConfigError extends ConfigIssue {

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

@@ -1,9 +1,15 @@
 import { definePlugin, resource } from "../../substrate/plugin.mjs";
-import { pluginErrorContributions } from "../../api/plugin-errors.mjs";
-import { PortBrokerService } from "../../substrate/runtime/port-broker/service.mjs";
-import { CurrentPluginKey } from "../../substrate/runtime/current-plugin.mjs";
-import { makeHostServiceRoutable } from "./routable.mjs";
+import "../../api/define-plugin.mjs";
+import { IdentityContext, RuntimeRoot } from "../../substrate/runtime/paths.mjs";
 import { Logger as Logger$1 } from "../../substrate/runtime/observability/logger.mjs";
+import "../../substrate/runtime/observability/index.mjs";
+import { CurrentPluginKey } from "../../substrate/runtime/current-plugin.mjs";
+import { PostAcquireTasksService } from "../../substrate/runtime/post-acquire-tasks.mjs";
+import { PortBrokerService } from "../../substrate/runtime/port-broker/service.mjs";
+import "../../substrate/runtime/port-broker/index.mjs";
+import { renderUrl, routedHostname } from "../../substrate/runtime/routed-url.mjs";
+import { HOST_SERVICE_DEFAULT_ENTRYPOINT_PORT, makeHostServiceRoutable } from "./routable.mjs";
+import { pluginErrorContributions } from "../../api/plugin-errors.mjs";
 import { HOST_SERVICE_ERROR_TAGS } from "./errors.mjs";
 import { normalizeHostServiceOptions, prepareHostService } from "./service.mjs";
 import { Effect } from "effect";
@@ -20,18 +26,38 @@ const hostService = (options) => {
 		id: serviceResource.id,
 		dependsOn: after,
 		role: "service",
+		section: "service",
 		start: () => Effect.gen(function* () {
 			const portBroker = yield* PortBrokerService;
+			const logger = yield* Logger$1;
+			const currentPlugin = yield* CurrentPluginKey;
+			const postAcquireTasks = yield* PostAcquireTasksService;
+			const identity = yield* IdentityContext;
+			const { root: runtimeRoot } = yield* RuntimeRoot;
+			const routedUrl = yield* routedHostname(identity, normalized.endpointName).pipe(Effect.map((hostname) => renderUrl({
+				protocol: "http",
+				hostname,
+				port: HOST_SERVICE_DEFAULT_ENTRYPOINT_PORT
+			})), Effect.orElseSucceed(() => null));
 			const prepared = yield* prepareHostService(normalized, {
 				allocatePort: (preferredPort) => portBroker.allocate({
-					kind: "http",
+					owner: `host-service:${normalized.serviceName}`,
 					probeHost: HOST_SERVICE_PORT_PROBE_HOST,
 					...preferredPort === void 0 ? {} : { preferredPort }
 				}).pipe(Effect.map((allocation) => allocation.port)),
-				logger: yield* Logger$1,
-				pluginKey: (yield* CurrentPluginKey).key
+				logger,
+				pluginKey: currentPlugin.key,
+				discoveryIdentity: {
+					stack: identity.stack,
+					runtimeRoot
+				},
+				routedUrl
+			});
+			yield* postAcquireTasks.register({
+				pluginKey: currentPlugin.key,
+				label: `host-service:${normalized.serviceName}.start`,
+				run: prepared.start
 			});
-			yield* prepared.start;
 			return prepared.value;
 		}),
 		errorContributions: hostServiceErrorContributions,