crypto-aio 0.0.3 → 0.1.0

package/dist/core/store/types.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DATA_CLASSIFICATION = exports.OPERATION_PATCH_KEYS = exports.CLEARABLE_FIELDS = exports.NON_TERMINAL_STATES = exports.TERMINAL_STATES = void 0;
+exports.isTerminal = isTerminal;
+// The exported tables in this module are frozen: they are shared by every caller.
+exports.TERMINAL_STATES = Object.freeze([
+    'final',
+    'failed',
+    'expired',
+    'abandoned',
+]);
+exports.NON_TERMINAL_STATES = Object.freeze([
+    'created',
+    'prepared',
+    'awaiting-signature',
+    'signed',
+    'submitted',
+    'stalled',
+    'included',
+]);
+/** A private copy taken at load, so `isTerminal` never reads an exported value. */
+const TERMINAL = new Set(exports.TERMINAL_STATES);
+function isTerminal(state) {
+    return TERMINAL.has(state);
+}
+exports.CLEARABLE_FIELDS = Object.freeze([
+    'outcome',
+    'unsigned',
+    'reservation',
+    'signerTickets',
+    'partialSignatures',
+    'activeAttemptId',
+    'ambiguous',
+    'error',
+    'nextCheckAt',
+]);
+/** Runtime whitelist of writable `OperationPatch` fields (everything but `clear`). */
+exports.OPERATION_PATCH_KEYS = Object.freeze([
+    'state',
+    'outcome',
+    'unsigned',
+    'reservation',
+    'signerTickets',
+    'partialSignatures',
+    'activeAttemptId',
+    'ambiguous',
+    'error',
+    'nextCheckAt',
+]);
+const _assertNoMissingPatchKeys = true;
+const _assertNoExtraPatchKeys = true;
+const _assertClearableIsWritable = true;
+/**
+ * Field classification so backing stores can apply encryption and retention per field.
+ *
+ * `operation.reservation` and `attempt.ordering` are `sensitive` because an `inputs`
+ * ordering lists UTXO outpoints, which tie a wallet to its coins. A nonce or seqno value
+ * on its own is an operational identifier, like an Operation id: the `nonce.allocated`
+ * and `nonce.gap` events carry it, and logs may too.
+ */
+exports.DATA_CLASSIFICATION = Object.freeze({
+    operation: Object.freeze({
+        id: 'operational',
+        namespace: 'operational',
+        idempotencyKey: 'sensitive',
+        intentHash: 'operational',
+        context: 'sensitive',
+        kind: 'operational',
+        state: 'operational',
+        outcome: 'operational',
+        intent: 'sensitive',
+        unsigned: 'sensitive',
+        // `inputs` orderings carry UTXO outpoints; nonce and seqno values are operational.
+        reservation: 'sensitive',
+        signerTickets: 'sensitive',
+        partialSignatures: 'sensitive',
+        attempts: 'sensitive-until-broadcast',
+        activeAttemptId: 'operational',
+        ambiguous: 'operational',
+        version: 'operational',
+        claim: 'operational',
+        error: 'sensitive',
+        createdAt: 'operational',
+        updatedAt: 'operational',
+        nextCheckAt: 'operational',
+    }),
+    attempt: Object.freeze({
+        id: 'operational',
+        ref: 'sensitive-until-broadcast',
+        raw: 'sensitive-until-broadcast',
+        // As `operation.reservation`.
+        ordering: 'sensitive',
+        fee: 'sensitive',
+        unsigned: 'sensitive',
+        purpose: 'operational',
+        supersedes: 'operational',
+        createdAt: 'operational',
+    }),
+    observation: Object.freeze({
+        attemptId: 'operational',
+        operationId: 'operational',
+        state: 'operational',
+        evidence: 'operational',
+        txHash: 'operational',
+        blockHash: 'operational',
+        blockHeight: 'operational',
+        confirmations: 'operational',
+        firstSeenAt: 'operational',
+        lastSeenAt: 'operational',
+        lastBroadcastAt: 'operational',
+        // A node's refusal or rejection text can carry addresses or amounts.
+        reason: 'sensitive',
+        replacedBy: 'operational',
+        version: 'operational',
+    }),
+});
+//# sourceMappingURL=types.js.map

package/dist/core/store/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/store/types.ts"],"names":[],"mappings":"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","sourcesContent":["import type { SerializedError } from '../errors/error';\nimport type { FeeEstimateDraft } from '../model/fee';\nimport type { StoredIntent } from '../model/intent';\nimport type { OrderingData } from '../model/ordering';\nimport type {\n  AttemptRef,\n  Evidence,\n  RawTx,\n  TxState,\n  UnsignedTx,\n} from '../model/transaction';\nimport type { SignatureBundle, SignerTicket } from '../signing/types';\n\nexport type OperationState =\n  | 'created'\n  | 'prepared'\n  | 'awaiting-signature'\n  | 'signed'\n  | 'submitted'\n  | 'stalled'\n  | 'included'\n  | 'final'\n  | 'failed'\n  | 'expired'\n  | 'abandoned';\n\n// The exported tables in this module are frozen: they are shared by every caller.\n\nexport const TERMINAL_STATES: readonly OperationState[] = Object.freeze([\n  'final',\n  'failed',\n  'expired',\n  'abandoned',\n]);\n\nexport const NON_TERMINAL_STATES: readonly OperationState[] = Object.freeze([\n  'created',\n  'prepared',\n  'awaiting-signature',\n  'signed',\n  'submitted',\n  'stalled',\n  'included',\n]);\n\n/** A private copy taken at load, so `isTerminal` never reads an exported value. */\nconst TERMINAL: ReadonlySet<OperationState> = new Set(TERMINAL_STATES);\n\nexport function isTerminal(state: OperationState): boolean {\n  return TERMINAL.has(state);\n}\n\n/** Frozen at Operation creation; later handle or config changes never affect it. */\nexport interface ExecutionContext {\n  readonly chain: string;\n  readonly network: string;\n  readonly library: string;\n  /** Provider names, or `inline:<hash>` for inline configs (never secrets). */\n  readonly providers: readonly string[];\n  readonly indexers: readonly string[];\n  readonly wallet: string;\n  readonly signer?: string;\n  readonly configHash: string;\n}\n\nexport type AttemptPurpose = 'original' | 'replacement' | 'cancel' | 'rebuild';\n\n/** One concrete signed transaction. Immutable after insertion. */\nexport interface AttemptRecord {\n  readonly id: string;\n  readonly ref: AttemptRef;\n  readonly raw: RawTx;\n  readonly ordering: OrderingData;\n  readonly fee: FeeEstimateDraft;\n  readonly unsigned: UnsignedTx;\n  readonly purpose: AttemptPurpose;\n  readonly supersedes?: string;\n  readonly createdAt: number;\n}\n\n/** Mutable, versioned view of what the chain says about an Attempt. */\nexport interface AttemptObservation {\n  readonly attemptId: string;\n  readonly operationId: string;\n  readonly state: TxState;\n  readonly evidence: Evidence;\n  readonly txHash?: string;\n  readonly blockHash?: string;\n  readonly blockHeight?: bigint;\n  readonly confirmations: number;\n  readonly firstSeenAt?: number;\n  readonly lastSeenAt?: number;\n  readonly lastBroadcastAt?: number;\n  readonly reason?: string;\n  readonly replacedBy?: string;\n  readonly version: number;\n}\n\nexport interface OperationClaim {\n  readonly workerId: string;\n  /** Strictly increasing per store (decimal string of a bigint). */\n  readonly token: string;\n  readonly until: number;\n}\n\nexport interface OperationRecord {\n  readonly id: string;\n  readonly namespace: string;\n  readonly idempotencyKey: string;\n  readonly intentHash: string;\n  readonly context: ExecutionContext;\n  readonly kind: 'transfer';\n  readonly state: OperationState;\n  readonly outcome?: 'executed' | 'cancelled';\n  readonly intent: StoredIntent;\n  readonly unsigned?: UnsignedTx;\n  readonly reservation?: OrderingData;\n  readonly signerTickets?: readonly SignerTicket[];\n  readonly partialSignatures?: readonly SignatureBundle[];\n  readonly attempts: readonly AttemptRecord[];\n  readonly activeAttemptId?: string;\n  readonly ambiguous?: boolean;\n  readonly version: number;\n  readonly claim?: OperationClaim;\n  readonly error?: SerializedError;\n  readonly createdAt: number;\n  readonly updatedAt: number;\n  readonly nextCheckAt?: number;\n}\n\nexport type NewOperation = Omit<\n  OperationRecord,\n  'version' | 'createdAt' | 'updatedAt' | 'claim'\n>;\n\nexport const CLEARABLE_FIELDS = Object.freeze([\n  'outcome',\n  'unsigned',\n  'reservation',\n  'signerTickets',\n  'partialSignatures',\n  'activeAttemptId',\n  'ambiguous',\n  'error',\n  'nextCheckAt',\n] as const);\n\n/** The only fields an `OperationPatch` may `clear`; never store-owned state or `state`. */\nexport type ClearableField = (typeof CLEARABLE_FIELDS)[number];\n\nexport interface OperationPatch {\n  readonly state?: OperationState;\n  readonly outcome?: 'executed' | 'cancelled';\n  readonly unsigned?: UnsignedTx;\n  readonly reservation?: OrderingData;\n  readonly signerTickets?: readonly SignerTicket[];\n  readonly partialSignatures?: readonly SignatureBundle[];\n  readonly activeAttemptId?: string;\n  readonly ambiguous?: boolean;\n  readonly error?: SerializedError;\n  readonly nextCheckAt?: number;\n  /** Fields to delete; applied after the values above. */\n  readonly clear?: readonly ClearableField[];\n}\n\n/** Runtime whitelist of writable `OperationPatch` fields (everything but `clear`). */\nexport const OPERATION_PATCH_KEYS = Object.freeze([\n  'state',\n  'outcome',\n  'unsigned',\n  'reservation',\n  'signerTickets',\n  'partialSignatures',\n  'activeAttemptId',\n  'ambiguous',\n  'error',\n  'nextCheckAt',\n] as const);\n\n// Compile-time check, in both directions: OPERATION_PATCH_KEYS must list exactly the\n// writable (non-'clear') fields of OperationPatch, so a future field added to one but\n// not the other fails the build instead of silently opening a hole in `update`.\ntype PatchFieldKeys = Exclude<keyof OperationPatch, 'clear'>;\ntype ListedPatchKeys = (typeof OPERATION_PATCH_KEYS)[number];\ntype AssertNoMissingPatchKeys = PatchFieldKeys extends ListedPatchKeys ? true : never;\ntype AssertNoExtraPatchKeys = ListedPatchKeys extends PatchFieldKeys ? true : never;\nconst _assertNoMissingPatchKeys: AssertNoMissingPatchKeys = true;\nconst _assertNoExtraPatchKeys: AssertNoExtraPatchKeys = true;\n\n// Compile-time check: every CLEARABLE_FIELDS entry must be a writable patch field\n// other than 'state' (which is written but never cleared). Fails the build if\n// 'attempts', 'claim', or any other non-writable field is ever added to\n// CLEARABLE_FIELDS, since that would let `clear` reach into store-owned state.\ntype AssertClearableIsWritable =\n  ClearableField extends Exclude<ListedPatchKeys, 'state'> ? true : never;\nconst _assertClearableIsWritable: AssertClearableIsWritable = true;\n\nexport interface Fence {\n  readonly claimToken: string;\n}\n\nexport interface OperationFilter {\n  readonly namespace: string;\n  readonly chain?: string;\n  readonly network?: string;\n  readonly from?: string;\n  readonly states?: readonly OperationState[];\n  readonly limit?: number;\n}\n\nexport interface CreateResult {\n  readonly created: boolean;\n  readonly record: OperationRecord;\n}\n\n/**\n * Durable Operation storage. Required guarantees (verified by the contract suite),\n * binding on every implementation (memory, Redis, Postgres, ...):\n * - `create` is create-if-absent on `(namespace, idempotencyKey)`: a second `create`\n *   for an existing key returns the stored record unchanged, regardless of\n *   `intentHash` — this store never performs the idempotency-conflict check itself;\n *   the calling engine does.\n * - `update`/`appendAttempt` are version-checked (compare-and-set on\n *   `expectedVersion`) and optionally fenced by a claim token. Both are restricted to\n *   the same runtime patch whitelist (`OPERATION_PATCH_KEYS`), and `clear` may only\n *   name `CLEARABLE_FIELDS`; any other key anywhere in the patch rejects the whole\n *   call with `INVALID_TRANSITION` before any mutation. An explicit `undefined` value\n *   for a writable field is a no-op (the stored value survives); only `clear` removes\n *   a field.\n * - `appendAttempt` is atomic with its accompanying patch, never rewrites a\n *   previously stored `AttemptRecord`, and rejects a duplicate attempt id. Attempt ids\n *   are globally unique across every Operation and namespace (observations are keyed\n *   by attempt id alone).\n * - `claimDue` and `list` are scoped by namespace: they never return a record of another\n *   namespace, even one with the same id.\n * - `claimDue` returns only non-terminal operations with `nextCheckAt` set and `<=\n *   now`, ordered by `(nextCheckAt, createdAt)` with a stable tie-break for equal\n *   values, and returns `[]` for `limit <= 0`. A claimed Operation is excluded until\n *   its `claim.until <= now`; then another worker may take it over. Claim tokens are\n *   strictly increasing per store; fenced writes are rejected after a takeover.\n * - `list` returns matches in creation order.\n * - `ClearableField` is restricted on purpose: `clear` can never remove store-owned or\n *   identity fields (`attempts`, `claim`, `version`, `id`, ...) or `state`. An\n *   implementation reads the caller's `clear` list once, so the list it validates is\n *   the list it applies.\n * - A key set to `undefined`, in an observation or a patch, is never persisted as a value\n *   such as `null`. In a patch, the stored field keeps its value. In an\n *   observation, which replaces the whole record, the field reads back `undefined` (never\n *   `null`).\n */\nexport interface OperationStore {\n  create(operation: NewOperation): Promise<CreateResult>;\n  get(namespace: string, id: string): Promise<OperationRecord | null>;\n  getByKey(namespace: string, idempotencyKey: string): Promise<OperationRecord | null>;\n  /**\n   * Finds by an Attempt ref id or by an observed canonical tx hash. The engine's\n   * AttemptRef guard, which refuses an Attempt whose ref another Operation of the\n   * namespace holds, relies on this read being read-your-writes consistent across every\n   * process that shares the store: it must see any `appendAttempt` that another store\n   * instance committed before it was called (no read replica, no eventually consistent\n   * index).\n   */\n  findByRef(namespace: string, refOrTxHash: string): Promise<OperationRecord | null>;\n  /**\n   * Compare-and-set on `expectedVersion`, optionally fenced. Every successful update bumps\n   * version, even when the patch changes no field (the engine fences stale writers\n   * with such a no-effect update).\n   */\n  update(\n    namespace: string,\n    id: string,\n    patch: OperationPatch,\n    expectedVersion: number,\n    fence?: Fence,\n  ): Promise<OperationRecord>;\n  appendAttempt(\n    namespace: string,\n    id: string,\n    attempt: AttemptRecord,\n    patch: OperationPatch,\n    expectedVersion: number,\n    fence?: Fence,\n  ): Promise<OperationRecord>;\n  getObservation(attemptId: string): Promise<AttemptObservation | null>;\n  /**\n   * Stores `observation` as the whole new record, version-checked. An optional field left\n   * out of it or set to `undefined` (a cleared `reason`, `blockHash` or `blockHeight`)\n   * reads back `undefined` (never `null`) afterwards. A store must replace the record, never\n   * merge fields into the old one. The monitor relies on this to clear stale values.\n   */\n  putObservation(\n    observation: Omit<AttemptObservation, 'version'>,\n    expectedVersion: number | null,\n  ): Promise<AttemptObservation>;\n  /** Claims non-terminal operations whose `nextCheckAt` is set and <= now (unscheduled ones are never due). */\n  claimDue(\n    namespace: string,\n    workerId: string,\n    now: number,\n    leaseMs: number,\n    limit: number,\n  ): Promise<OperationRecord[]>;\n  releaseClaim(namespace: string, id: string, fence: Fence): Promise<void>;\n  list(filter: OperationFilter): Promise<OperationRecord[]>;\n  purge?(filter: OperationFilter): Promise<number>;\n}\n\nexport interface Lease {\n  readonly key: string;\n  readonly owner: string;\n  /** Strictly increasing per key across all acquisitions. */\n  readonly token: bigint;\n  readonly expiresAt: number;\n}\n\nexport interface LockManager {\n  acquire(key: string, owner: string, ttlMs: number): Promise<Lease | null>;\n  renew(lease: Lease, ttlMs: number): Promise<Lease | null>;\n  release(lease: Lease): Promise<void>;\n}\n\nexport interface SequenceState {\n  readonly next: bigint;\n  readonly released: readonly bigint[];\n  readonly fence: bigint;\n  readonly version: number;\n}\n\nexport interface SequenceStore {\n  get(key: string): Promise<SequenceState | null>;\n  /** Rejects on version mismatch (`VERSION_CONFLICT`) or when `fence` < stored fence (`FENCING`). */\n  put(\n    key: string,\n    state: Omit<SequenceState, 'version'>,\n    expectedVersion: number | null,\n  ): Promise<void>;\n}\n\nexport interface ScanCursor {\n  readonly height: bigint;\n  readonly hash: string;\n  readonly recent: readonly { readonly height: bigint; readonly hash: string }[];\n}\n\nexport interface StoredCursor {\n  readonly cursor: ScanCursor;\n  readonly version: number;\n}\n\nexport interface CursorStore {\n  get(key: string): Promise<StoredCursor | null>;\n  /** Returns the new version. */\n  put(key: string, cursor: ScanCursor, expectedVersion: number | null): Promise<number>;\n}\n\nexport interface Stores {\n  readonly operations: OperationStore;\n  readonly locks: LockManager;\n  readonly sequences: SequenceStore;\n  readonly cursors: CursorStore;\n}\n\nexport type DataClass =\n  'secret' | 'sensitive' | 'sensitive-until-broadcast' | 'operational';\n\n/**\n * Field classification so backing stores can apply encryption and retention per field.\n *\n * `operation.reservation` and `attempt.ordering` are `sensitive` because an `inputs`\n * ordering lists UTXO outpoints, which tie a wallet to its coins. A nonce or seqno value\n * on its own is an operational identifier, like an Operation id: the `nonce.allocated`\n * and `nonce.gap` events carry it, and logs may too.\n */\nexport const DATA_CLASSIFICATION: {\n  readonly operation: Readonly<Record<keyof OperationRecord, DataClass>>;\n  readonly attempt: Readonly<Record<keyof AttemptRecord, DataClass>>;\n  readonly observation: Readonly<Record<keyof AttemptObservation, DataClass>>;\n} = Object.freeze({\n  operation: Object.freeze({\n    id: 'operational',\n    namespace: 'operational',\n    idempotencyKey: 'sensitive',\n    intentHash: 'operational',\n    context: 'sensitive',\n    kind: 'operational',\n    state: 'operational',\n    outcome: 'operational',\n    intent: 'sensitive',\n    unsigned: 'sensitive',\n    // `inputs` orderings carry UTXO outpoints; nonce and seqno values are operational.\n    reservation: 'sensitive',\n    signerTickets: 'sensitive',\n    partialSignatures: 'sensitive',\n    attempts: 'sensitive-until-broadcast',\n    activeAttemptId: 'operational',\n    ambiguous: 'operational',\n    version: 'operational',\n    claim: 'operational',\n    error: 'sensitive',\n    createdAt: 'operational',\n    updatedAt: 'operational',\n    nextCheckAt: 'operational',\n  }),\n  attempt: Object.freeze({\n    id: 'operational',\n    ref: 'sensitive-until-broadcast',\n    raw: 'sensitive-until-broadcast',\n    // As `operation.reservation`.\n    ordering: 'sensitive',\n    fee: 'sensitive',\n    unsigned: 'sensitive',\n    purpose: 'operational',\n    supersedes: 'operational',\n    createdAt: 'operational',\n  }),\n  observation: Object.freeze({\n    attemptId: 'operational',\n    operationId: 'operational',\n    state: 'operational',\n    evidence: 'operational',\n    txHash: 'operational',\n    blockHash: 'operational',\n    blockHeight: 'operational',\n    confirmations: 'operational',\n    firstSeenAt: 'operational',\n    lastSeenAt: 'operational',\n    lastBroadcastAt: 'operational',\n    // A node's refusal or rejection text can carry addresses or amounts.\n    reason: 'sensitive',\n    replacedBy: 'operational',\n    version: 'operational',\n  }),\n});\n"]}

package/dist/core/transport/backoff.d.ts

@@ -0,0 +1,8 @@
+export interface BackoffOptions {
+    readonly baseDelayMs: number;
+    readonly maxDelayMs: number;
+}
+/** Full-jitter exponential backoff: uniform in [0, min(max, base · 2^attempt)). */
+export declare function backoffDelay(attempt: number, options: BackoffOptions, random?: () => number): number;
+/** Parses `Retry-After` (delta-seconds or HTTP-date) into milliseconds. */
+export declare function parseRetryAfter(value: string | null | undefined, now: number): number | undefined;

package/dist/core/transport/backoff.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.backoffDelay = backoffDelay;
+exports.parseRetryAfter = parseRetryAfter;
+/** Full-jitter exponential backoff: uniform in [0, min(max, base · 2^attempt)). */
+function backoffDelay(attempt, options, random = Math.random) {
+    const clamped = Math.min(attempt, 30);
+    const cap = Math.min(options.maxDelayMs, options.baseDelayMs * 2 ** clamped);
+    return Math.floor(random() * cap);
+}
+/** Parses `Retry-After` (delta-seconds or HTTP-date) into milliseconds. */
+function parseRetryAfter(value, now) {
+    if (!value)
+        return undefined;
+    // Delta-seconds: 1-10 digits only
+    if (/^\d{1,10}$/.test(value))
+        return Number(value) * 1_000;
+    // IMF-fixdate (RFC 7231): e.g. "Wed, 21 Oct 2015 07:28:00 GMT"
+    if (/^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(value)) {
+        const at = Date.parse(value);
+        if (Number.isNaN(at))
+            return undefined;
+        return Math.max(0, at - now);
+    }
+    return undefined;
+}
+//# sourceMappingURL=backoff.js.map

package/dist/core/transport/backoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.js","sourceRoot":"","sources":["../../../src/core/transport/backoff.ts"],"names":[],"mappings":";;AAMA,oCAQC;AAGD,0CAkBC;AA9BD,mFAAmF;AACnF,SAAgB,YAAY,CAC1B,OAAe,EACf,OAAuB,EACvB,SAAuB,IAAI,CAAC,MAAM;IAElC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IACtC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,WAAW,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC;IAC7E,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC;AACpC,CAAC;AAED,2EAA2E;AAC3E,SAAgB,eAAe,CAC7B,KAAgC,EAChC,GAAW;IAEX,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,kCAAkC;IAClC,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC;IAC3D,+DAA+D;IAC/D,IACE,sHAAsH,CAAC,IAAI,CACzH,KAAK,CACN,EACD,CAAC;QACD,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC7B,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YAAE,OAAO,SAAS,CAAC;QACvC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,GAAG,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC","sourcesContent":["export interface BackoffOptions {\n  readonly baseDelayMs: number;\n  readonly maxDelayMs: number;\n}\n\n/** Full-jitter exponential backoff: uniform in [0, min(max, base · 2^attempt)). */\nexport function backoffDelay(\n  attempt: number,\n  options: BackoffOptions,\n  random: () => number = Math.random,\n): number {\n  const clamped = Math.min(attempt, 30);\n  const cap = Math.min(options.maxDelayMs, options.baseDelayMs * 2 ** clamped);\n  return Math.floor(random() * cap);\n}\n\n/** Parses `Retry-After` (delta-seconds or HTTP-date) into milliseconds. */\nexport function parseRetryAfter(\n  value: string | null | undefined,\n  now: number,\n): number | undefined {\n  if (!value) return undefined;\n  // Delta-seconds: 1-10 digits only\n  if (/^\\d{1,10}$/.test(value)) return Number(value) * 1_000;\n  // IMF-fixdate (RFC 7231): e.g. \"Wed, 21 Oct 2015 07:28:00 GMT\"\n  if (\n    /^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \\d{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \\d{4} \\d{2}:\\d{2}:\\d{2} GMT$/.test(\n      value,\n    )\n  ) {\n    const at = Date.parse(value);\n    if (Number.isNaN(at)) return undefined;\n    return Math.max(0, at - now);\n  }\n  return undefined;\n}\n"]}

package/dist/core/transport/circuit.d.ts

@@ -0,0 +1,25 @@
+import type { Clock } from '../util/clock';
+export type CircuitState = 'closed' | 'open' | 'half-open';
+export interface CircuitOptions {
+    readonly failureThreshold: number;
+    readonly openMs: number;
+}
+export declare class CircuitBreaker {
+    #private;
+    private readonly options;
+    private readonly clock;
+    constructor(options: CircuitOptions, clock: Clock);
+    get state(): CircuitState;
+    canRequest(): boolean;
+    /** Returns true when this call actually took the half-open probe slot, so the caller
+     * can track ownership of it (e.g. to decide whether it may later abandon it). A slot
+     * another attempt already holds is not taken again — false. Known gap: the slot is
+     * claimed here, as the request is sent, not when the endpoint is picked, so a second
+     * request picked while the slot was free still goes out; claiming it earlier would
+     * change how proof reads try a recovering endpoint. */
+    onAttempt(): boolean;
+    /** Clears a half-open probe slot without changing state (e.g. the probe was abandoned). */
+    onAbandon(): void;
+    onSuccess(): void;
+    onFailure(): void;
+}

package/dist/core/transport/circuit.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircuitBreaker = void 0;
+class CircuitBreaker {
+    options;
+    clock;
+    #failures = 0;
+    #openedAt;
+    #probing = false;
+    constructor(options, clock) {
+        this.options = options;
+        this.clock = clock;
+    }
+    get state() {
+        if (this.#openedAt === undefined)
+            return 'closed';
+        return this.clock.now() - this.#openedAt >= this.options.openMs
+            ? 'half-open'
+            : 'open';
+    }
+    canRequest() {
+        const state = this.state;
+        if (state === 'closed')
+            return true;
+        return state === 'half-open' && !this.#probing;
+    }
+    /** Returns true when this call actually took the half-open probe slot, so the caller
+     * can track ownership of it (e.g. to decide whether it may later abandon it). A slot
+     * another attempt already holds is not taken again — false. Known gap: the slot is
+     * claimed here, as the request is sent, not when the endpoint is picked, so a second
+     * request picked while the slot was free still goes out; claiming it earlier would
+     * change how proof reads try a recovering endpoint. */
+    onAttempt() {
+        if (this.state !== 'half-open' || this.#probing)
+            return false;
+        this.#probing = true;
+        return true;
+    }
+    /** Clears a half-open probe slot without changing state (e.g. the probe was abandoned). */
+    onAbandon() {
+        this.#probing = false;
+    }
+    onSuccess() {
+        this.#failures = 0;
+        this.#openedAt = undefined;
+        this.#probing = false;
+    }
+    onFailure() {
+        this.#probing = false;
+        if (this.state === 'half-open') {
+            this.#openedAt = this.clock.now();
+            return;
+        }
+        this.#failures += 1;
+        if (this.#failures >= this.options.failureThreshold) {
+            this.#openedAt = this.clock.now();
+        }
+    }
+}
+exports.CircuitBreaker = CircuitBreaker;
+//# sourceMappingURL=circuit.js.map

package/dist/core/transport/circuit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit.js","sourceRoot":"","sources":["../../../src/core/transport/circuit.ts"],"names":[],"mappings":";;;AASA,MAAa,cAAc;IAMN;IACA;IANnB,SAAS,GAAG,CAAC,CAAC;IACd,SAAS,CAAqB;IAC9B,QAAQ,GAAG,KAAK,CAAC;IAEjB,YACmB,OAAuB,EACvB,KAAY;QADZ,YAAO,GAAP,OAAO,CAAgB;QACvB,UAAK,GAAL,KAAK,CAAO;IAC5B,CAAC;IAEJ,IAAI,KAAK;QACP,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;YAAE,OAAO,QAAQ,CAAC;QAClD,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM;YAC7D,CAAC,CAAC,WAAW;YACb,CAAC,CAAC,MAAM,CAAC;IACb,CAAC;IAED,UAAU;QACR,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACzB,IAAI,KAAK,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACpC,OAAO,KAAK,KAAK,WAAW,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC;IACjD,CAAC;IAED;;;;;2DAKuD;IACvD,SAAS;QACP,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO,KAAK,CAAC;QAC9D,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,2FAA2F;IAC3F,SAAS;QACP,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;IACxB,CAAC;IAED,SAAS;QACP,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;QACnB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;IACxB,CAAC;IAED,SAAS;QACP,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QACtB,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;YAC/B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;YAClC,OAAO;QACT,CAAC;QACD,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC;QACpB,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,OAAO,CAAC,gBAAgB,EAAE,CAAC;YACpD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;QACpC,CAAC;IACH,CAAC;CACF;AAzDD,wCAyDC","sourcesContent":["import type { Clock } from '../util/clock';\n\nexport type CircuitState = 'closed' | 'open' | 'half-open';\n\nexport interface CircuitOptions {\n  readonly failureThreshold: number;\n  readonly openMs: number;\n}\n\nexport class CircuitBreaker {\n  #failures = 0;\n  #openedAt: number | undefined;\n  #probing = false;\n\n  constructor(\n    private readonly options: CircuitOptions,\n    private readonly clock: Clock,\n  ) {}\n\n  get state(): CircuitState {\n    if (this.#openedAt === undefined) return 'closed';\n    return this.clock.now() - this.#openedAt >= this.options.openMs\n      ? 'half-open'\n      : 'open';\n  }\n\n  canRequest(): boolean {\n    const state = this.state;\n    if (state === 'closed') return true;\n    return state === 'half-open' && !this.#probing;\n  }\n\n  /** Returns true when this call actually took the half-open probe slot, so the caller\n   * can track ownership of it (e.g. to decide whether it may later abandon it). A slot\n   * another attempt already holds is not taken again — false. Known gap: the slot is\n   * claimed here, as the request is sent, not when the endpoint is picked, so a second\n   * request picked while the slot was free still goes out; claiming it earlier would\n   * change how proof reads try a recovering endpoint. */\n  onAttempt(): boolean {\n    if (this.state !== 'half-open' || this.#probing) return false;\n    this.#probing = true;\n    return true;\n  }\n\n  /** Clears a half-open probe slot without changing state (e.g. the probe was abandoned). */\n  onAbandon(): void {\n    this.#probing = false;\n  }\n\n  onSuccess(): void {\n    this.#failures = 0;\n    this.#openedAt = undefined;\n    this.#probing = false;\n  }\n\n  onFailure(): void {\n    this.#probing = false;\n    if (this.state === 'half-open') {\n      this.#openedAt = this.clock.now();\n      return;\n    }\n    this.#failures += 1;\n    if (this.#failures >= this.options.failureThreshold) {\n      this.#openedAt = this.clock.now();\n    }\n  }\n}\n"]}

package/dist/core/transport/http-transport.d.ts

@@ -0,0 +1,30 @@
+import type { EventBus } from '../events/bus';
+import type { Logger } from '../events/logger';
+import type { Clock } from '../util/clock';
+import { type CallOptions, type EndpointConfig, type EndpointStatus, type HealthProbes, type HttpRequest, type Transport, type TransportOptions } from './types';
+export interface HttpTransportDeps {
+    readonly clock: Clock;
+    readonly events: EventBus;
+    readonly log: Logger;
+    readonly options?: TransportOptions;
+    readonly id?: string;
+    readonly random?: () => number;
+}
+export declare class HttpTransport implements Transport {
+    #private;
+    readonly id: string;
+    constructor(endpoints: readonly EndpointConfig[], deps: HttpTransportDeps);
+    rpc<T = unknown>(method: string, params?: unknown, options?: CallOptions): Promise<T>;
+    rpcRaw(payload: unknown, options?: CallOptions): Promise<unknown>;
+    http<T = unknown>(request: HttpRequest, options?: CallOptions): Promise<T>;
+    createFetch(classify?: (url: URL, init: RequestInit | undefined) => CallOptions): typeof fetch;
+    /** Least-invasive detector for "no health probe was ever configured" — mirrors the same
+     * condition `ensureFreshHealth` already uses to skip probing entirely. */
+    hasProbes(): boolean;
+    setProbes(probes: HealthProbes): void;
+    ensureFreshHealth(signal?: AbortSignal): Promise<void>;
+    refreshHealth(signal?: AbortSignal): Promise<void>;
+    status(): EndpointStatus[];
+    highestHeight(): bigint | undefined;
+    get maxLagBlocks(): number;
+}