crypto-aio 0.0.2 → 0.1.0

package/dist/core/container/internals.d.ts

@@ -0,0 +1,54 @@
+import type { AssetService } from '../assets/service';
+import type { EffectiveOptions, ScopeOptions } from '../config/types';
+import { StateError } from '../errors/error';
+import type { EventBus } from '../events/bus';
+import type { Logger } from '../events/logger';
+import type { OperationEngine } from '../lifecycle/engine';
+import type { Monitor } from '../lifecycle/monitor';
+import type { Catalogs } from '../registry/plugin';
+import type { SignerDeadline } from '../signing/guard';
+import type { Stores } from '../store/types';
+import type { TransportOptions } from '../transport/types';
+import type { Clock } from '../util/clock';
+import type { DriverPool } from './pool';
+/** State shared by a root container and all of its scopes. */
+export interface RootRuntime {
+    readonly namespace: string;
+    catalogs: Catalogs;
+    envLayer: ScopeOptions;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly profile?: string;
+    readonly clock: Clock;
+    readonly log: Logger;
+    readonly events: EventBus;
+    readonly stores: Stores;
+    readonly pool: DriverPool;
+    readonly assets: AssetService;
+    readonly transport: TransportOptions;
+    /** Owner id used for leases and claims taken by this process. */
+    readonly owner: string;
+    /**
+     * Set by the root's `close()`; a closed container refuses handle and `native()` work.
+     */
+    closed: boolean;
+    /** Aborted by the root's `close()`, which stops every worker loop and recovery. */
+    readonly closing: AbortController;
+    /** The `close` of every native SDK client handed out, run by the root's `close()`. */
+    readonly natives: Set<() => void | Promise<void>>;
+}
+/** What a closed container's handles and `native()` fail with. */
+export declare function closedError(): StateError;
+export interface ContainerInternals {
+    readonly runtime: RootRuntime;
+    readonly layers: readonly ScopeOptions[];
+    readonly isRoot: boolean;
+    effective(): EffectiveOptions;
+    /** Lazily created per container (scopes have their own hooks and lifecycle settings). */
+    engine(): OperationEngine;
+    /** Lazily created per container, on top of its engine. */
+    monitor(): Monitor;
+    /** The bound on a signer's public-key read (this container's `signTimeoutMs`). */
+    signerDeadline(): SignerDeadline;
+}
+export declare function bindContainer(container: object, internals: ContainerInternals): void;
+export declare function containerOf(container: object): ContainerInternals;

package/dist/core/container/internals.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.closedError = closedError;
+exports.bindContainer = bindContainer;
+exports.containerOf = containerOf;
+const error_1 = require("../errors/error");
+/** What a closed container's handles and `native()` fail with. */
+function closedError() {
+    return new error_1.StateError('INVALID_TRANSITION', 'this crypto-aio container is closed');
+}
+const registry = new WeakMap();
+function bindContainer(container, internals) {
+    registry.set(container, internals);
+}
+function containerOf(container) {
+    const internals = registry.get(container);
+    if (!internals)
+        throw new error_1.ConfigError('CONFIG_INVALID', 'not a CryptoAio container');
+    return internals;
+}
+//# sourceMappingURL=internals.js.map

package/dist/core/container/internals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internals.js","sourceRoot":"","sources":["../../../src/core/container/internals.ts"],"names":[],"mappings":";;AAyCA,kCAEC;AAiBD,sCAEC;AAED,kCAIC;AAlED,2CAA0D;AAsC1D,kEAAkE;AAClE,SAAgB,WAAW;IACzB,OAAO,IAAI,kBAAU,CAAC,oBAAoB,EAAE,qCAAqC,CAAC,CAAC;AACrF,CAAC;AAeD,MAAM,QAAQ,GAAG,IAAI,OAAO,EAA8B,CAAC;AAE3D,SAAgB,aAAa,CAAC,SAAiB,EAAE,SAA6B;IAC5E,QAAQ,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;AACrC,CAAC;AAED,SAAgB,WAAW,CAAC,SAAiB;IAC3C,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAC1C,IAAI,CAAC,SAAS;QAAE,MAAM,IAAI,mBAAW,CAAC,gBAAgB,EAAE,2BAA2B,CAAC,CAAC;IACrF,OAAO,SAAS,CAAC;AACnB,CAAC","sourcesContent":["import type { AssetService } from '../assets/service';\nimport type { EffectiveOptions, ScopeOptions } from '../config/types';\nimport { ConfigError, StateError } from '../errors/error';\nimport type { EventBus } from '../events/bus';\nimport type { Logger } from '../events/logger';\nimport type { OperationEngine } from '../lifecycle/engine';\nimport type { Monitor } from '../lifecycle/monitor';\nimport type { Catalogs } from '../registry/plugin';\nimport type { SignerDeadline } from '../signing/guard';\nimport type { Stores } from '../store/types';\nimport type { TransportOptions } from '../transport/types';\nimport type { Clock } from '../util/clock';\nimport type { DriverPool } from './pool';\n\n/** State shared by a root container and all of its scopes. */\nexport interface RootRuntime {\n  readonly namespace: string;\n  catalogs: Catalogs;\n  envLayer: ScopeOptions;\n  readonly env: Readonly<Record<string, string | undefined>>;\n  readonly profile?: string;\n  readonly clock: Clock;\n  readonly log: Logger;\n  readonly events: EventBus;\n  readonly stores: Stores;\n  readonly pool: DriverPool;\n  readonly assets: AssetService;\n  readonly transport: TransportOptions;\n  /** Owner id used for leases and claims taken by this process. */\n  readonly owner: string;\n  /**\n   * Set by the root's `close()`; a closed container refuses handle and `native()` work.\n   */\n  closed: boolean;\n  /** Aborted by the root's `close()`, which stops every worker loop and recovery. */\n  readonly closing: AbortController;\n  /** The `close` of every native SDK client handed out, run by the root's `close()`. */\n  readonly natives: Set<() => void | Promise<void>>;\n}\n\n/** What a closed container's handles and `native()` fail with. */\nexport function closedError(): StateError {\n  return new StateError('INVALID_TRANSITION', 'this crypto-aio container is closed');\n}\n\nexport interface ContainerInternals {\n  readonly runtime: RootRuntime;\n  readonly layers: readonly ScopeOptions[];\n  readonly isRoot: boolean;\n  effective(): EffectiveOptions;\n  /** Lazily created per container (scopes have their own hooks and lifecycle settings). */\n  engine(): OperationEngine;\n  /** Lazily created per container, on top of its engine. */\n  monitor(): Monitor;\n  /** The bound on a signer's public-key read (this container's `signTimeoutMs`). */\n  signerDeadline(): SignerDeadline;\n}\n\nconst registry = new WeakMap<object, ContainerInternals>();\n\nexport function bindContainer(container: object, internals: ContainerInternals): void {\n  registry.set(container, internals);\n}\n\nexport function containerOf(container: object): ContainerInternals {\n  const internals = registry.get(container);\n  if (!internals) throw new ConfigError('CONFIG_INVALID', 'not a CryptoAio container');\n  return internals;\n}\n"]}

package/dist/core/container/pool.d.ts

@@ -0,0 +1,27 @@
+import type { ResolvedSelection } from '../config/types';
+import type { ChainDriver } from '../driver/types';
+import type { EventBus } from '../events/bus';
+import type { Logger } from '../events/logger';
+import type { Catalogs } from '../registry/plugin';
+import type { Transport, TransportOptions } from '../transport/types';
+import type { Clock } from '../util/clock';
+export interface PooledDriver {
+    readonly driver: ChainDriver;
+    readonly transport: Transport;
+    readonly indexer?: Transport;
+}
+export interface DriverPoolDeps {
+    readonly catalogs: () => Catalogs;
+    readonly clock: Clock;
+    readonly events: EventBus;
+    readonly log: Logger;
+    readonly transport: () => TransportOptions;
+}
+/** Shares one driver + transport per (chain, network, library, provider credentials, options). */
+export declare class DriverPool {
+    #private;
+    private readonly deps;
+    constructor(deps: DriverPoolDeps);
+    get(selection: ResolvedSelection): Promise<PooledDriver>;
+    close(): Promise<void>;
+}

package/dist/core/container/pool.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DriverPool = void 0;
+const error_1 = require("../errors/error");
+const http_transport_1 = require("../transport/http-transport");
+const bytes_1 = require("../util/bytes");
+/** Shares one driver + transport per (chain, network, library, provider credentials, options). */
+class DriverPool {
+    deps;
+    #entries = new Map();
+    #closed = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    get(selection) {
+        if (this.#closed) {
+            return Promise.reject(new error_1.StateError('INVALID_TRANSITION', 'driver pool is closed'));
+        }
+        let entry = this.#entries.get(selection.poolKey);
+        if (!entry) {
+            entry = this.#create(selection);
+            this.#entries.set(selection.poolKey, entry);
+            entry.catch(() => {
+                // Only evict THIS entry: a concurrent get() may already have replaced it (e.g. a
+                // retry after this one failed), and that newer entry must survive.
+                if (this.#entries.get(selection.poolKey) === entry) {
+                    this.#entries.delete(selection.poolKey);
+                }
+            });
+        }
+        return entry;
+    }
+    async close() {
+        this.#closed = true;
+        const entries = [...this.#entries.values()];
+        this.#entries.clear();
+        await Promise.allSettled(entries.map(async (entry) => (await entry).driver.close?.()));
+    }
+    async #create(selection) {
+        const factory = await this.deps.catalogs().adapters.load(selection.manifest);
+        const root = this.deps.transport();
+        // First match wins: the user's per-chain config, the user's root transport option,
+        // the plugin network's own, then (left unset) the transport's built-in default.
+        const maxLagBlocks = selection.maxLagBlocks ?? root.maxLagBlocks ?? selection.network.maxLagBlocks;
+        const options = {
+            ...root,
+            ...(maxLagBlocks !== undefined ? { maxLagBlocks } : {}),
+        };
+        // `poolKey` fingerprints revealed provider URLs and must stay an in-memory map key
+        // only (never persisted, emitted or logged); the transport's public id — which flows
+        // into every rpc.*/provider.* event — is generated independently of it.
+        const id = (0, bytes_1.randomId)('tr');
+        const shared = {
+            clock: this.deps.clock,
+            events: this.deps.events,
+            log: this.deps.log.child('transport'),
+            options,
+        };
+        const transport = new http_transport_1.HttpTransport(selection.providers.flatMap((p) => p.endpoints), { ...shared, id });
+        const indexer = selection.indexers.length > 0
+            ? new http_transport_1.HttpTransport(selection.indexers.flatMap((p) => p.endpoints), { ...shared, id: `${id}_idx` })
+            : undefined;
+        const driver = await factory.create({
+            chain: selection.chain,
+            network: selection.network,
+            library: selection.library,
+            transport,
+            ...(indexer ? { indexer } : {}),
+            clock: this.deps.clock,
+            log: this.deps.log.child(selection.chain.id),
+            options: selection.options,
+        });
+        return { driver, transport, ...(indexer ? { indexer } : {}) };
+    }
+}
+exports.DriverPool = DriverPool;
+//# sourceMappingURL=pool.js.map

package/dist/core/container/pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.js","sourceRoot":"","sources":["../../../src/core/container/pool.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ResolvedSelection } from '../config/types';\nimport type { ChainDriver } from '../driver/types';\nimport { StateError } from '../errors/error';\nimport type { EventBus } from '../events/bus';\nimport type { Logger } from '../events/logger';\nimport type { Catalogs } from '../registry/plugin';\nimport { HttpTransport } from '../transport/http-transport';\nimport type { Transport, TransportOptions } from '../transport/types';\nimport { randomId } from '../util/bytes';\nimport type { Clock } from '../util/clock';\n\nexport interface PooledDriver {\n  readonly driver: ChainDriver;\n  readonly transport: Transport;\n  readonly indexer?: Transport;\n}\n\nexport interface DriverPoolDeps {\n  readonly catalogs: () => Catalogs;\n  readonly clock: Clock;\n  readonly events: EventBus;\n  readonly log: Logger;\n  readonly transport: () => TransportOptions;\n}\n\n/** Shares one driver + transport per (chain, network, library, provider credentials, options). */\nexport class DriverPool {\n  readonly #entries = new Map<string, Promise<PooledDriver>>();\n  #closed = false;\n\n  constructor(private readonly deps: DriverPoolDeps) {}\n\n  get(selection: ResolvedSelection): Promise<PooledDriver> {\n    if (this.#closed) {\n      return Promise.reject(\n        new StateError('INVALID_TRANSITION', 'driver pool is closed'),\n      );\n    }\n    let entry = this.#entries.get(selection.poolKey);\n    if (!entry) {\n      entry = this.#create(selection);\n      this.#entries.set(selection.poolKey, entry);\n      entry.catch(() => {\n        // Only evict THIS entry: a concurrent get() may already have replaced it (e.g. a\n        // retry after this one failed), and that newer entry must survive.\n        if (this.#entries.get(selection.poolKey) === entry) {\n          this.#entries.delete(selection.poolKey);\n        }\n      });\n    }\n    return entry;\n  }\n\n  async close(): Promise<void> {\n    this.#closed = true;\n    const entries = [...this.#entries.values()];\n    this.#entries.clear();\n    await Promise.allSettled(\n      entries.map(async (entry) => (await entry).driver.close?.()),\n    );\n  }\n\n  async #create(selection: ResolvedSelection): Promise<PooledDriver> {\n    const factory = await this.deps.catalogs().adapters.load(selection.manifest);\n    const root = this.deps.transport();\n    // First match wins: the user's per-chain config, the user's root transport option,\n    // the plugin network's own, then (left unset) the transport's built-in default.\n    const maxLagBlocks =\n      selection.maxLagBlocks ?? root.maxLagBlocks ?? selection.network.maxLagBlocks;\n    const options: TransportOptions = {\n      ...root,\n      ...(maxLagBlocks !== undefined ? { maxLagBlocks } : {}),\n    };\n    // `poolKey` fingerprints revealed provider URLs and must stay an in-memory map key\n    // only (never persisted, emitted or logged); the transport's public id — which flows\n    // into every rpc.*/provider.* event — is generated independently of it.\n    const id = randomId('tr');\n    const shared = {\n      clock: this.deps.clock,\n      events: this.deps.events,\n      log: this.deps.log.child('transport'),\n      options,\n    };\n    const transport = new HttpTransport(\n      selection.providers.flatMap((p) => p.endpoints),\n      { ...shared, id },\n    );\n    const indexer =\n      selection.indexers.length > 0\n        ? new HttpTransport(\n            selection.indexers.flatMap((p) => p.endpoints),\n            { ...shared, id: `${id}_idx` },\n          )\n        : undefined;\n    const driver = await factory.create({\n      chain: selection.chain,\n      network: selection.network,\n      library: selection.library,\n      transport,\n      ...(indexer ? { indexer } : {}),\n      clock: this.deps.clock,\n      log: this.deps.log.child(selection.chain.id),\n      options: selection.options,\n    });\n    return { driver, transport, ...(indexer ? { indexer } : {}) };\n  }\n}\n"]}

package/dist/core/driver/types.d.ts

@@ -0,0 +1,346 @@
+import type { CodesOf } from '../errors/codes';
+import type { Logger } from '../events/logger';
+import type { AddressFormatter, NormalizedAddress } from '../model/address';
+import type { AssetMetadata, AssetRef, TokenRef } from '../model/asset';
+import type { Capability } from '../model/capability';
+import type { ChainInfo, NetworkInfo } from '../model/chain';
+import type { FeeEstimateDraft, FeeOverride, FeeSpeed } from '../model/fee';
+import type { DriverIntent } from '../model/intent';
+import type { OrderingData, OrderingKind } from '../model/ordering';
+import type { AttemptRef, Decoding, RawTx, SignedTx, TransferSource, UnsignedTx } from '../model/transaction';
+import type { KeyRef, SignatureBundle } from '../signing/types';
+import type { Transport } from '../transport/types';
+import type { Clock } from '../util/clock';
+/**
+ * Family-specific wallet settings (e.g. `utxo.addressType`, TON wallet identity). The `hd`
+ * key is reserved and core-built: the core sets it to the wallet's `WalletHdOptions` when
+ * the wallet has an `xpub`, and a user's or caller's `hd` never reaches a driver, since a
+ * driver trusts `hd` to validate change addresses.
+ */
+export type WalletOptions = Readonly<Record<string, unknown>>;
+export interface WalletKey {
+    readonly scheme: string;
+    readonly publicKey: Uint8Array;
+    readonly keyRef?: KeyRef;
+}
+export interface BuildContext {
+    readonly from: string;
+    readonly keys: readonly WalletKey[];
+    readonly wallet: WalletOptions;
+    /** Allocated by the core for `nonce` and `seqno` ordering. */
+    readonly ordering?: OrderingData;
+    /** Inputs held by other live Operations of this wallet (`inputs` ordering). */
+    readonly excludeInputs?: readonly string[];
+    readonly signal?: AbortSignal;
+}
+export type FundsCheck = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly asset: AssetRef;
+    readonly required: bigint;
+    readonly available: bigint;
+};
+/**
+ * `refused`: state-dependent (may become valid, or may already be included) — observed only.
+ * `rejected`: permanently invalid by construction (malformed, bad signature, wrong chain).
+ */
+export type BroadcastResult = {
+    readonly kind: 'accepted';
+} | {
+    readonly kind: 'already-known';
+} | {
+    readonly kind: 'refused';
+    readonly code: CodesOf<'chain'>;
+    readonly reason: string;
+} | {
+    readonly kind: 'rejected';
+    readonly reason: string;
+};
+export interface DriverTxObservation {
+    readonly seen: 'none' | 'mempool' | 'block';
+    readonly txHash?: string;
+    readonly blockHeight?: bigint;
+    readonly blockHash?: string;
+    /** For included transactions: false when execution failed or reverted. */
+    readonly success?: boolean;
+    /**
+     * With `success: false`, why, as a short fixed text: no addresses, amounts or node
+     * text, which can carry either. The monitor records it on the observation
+     * (`TxStatus.reason`).
+     */
+    readonly reason?: string;
+}
+export interface DriverTransfer {
+    /** Deterministic within the transaction, e.g. `native`, `log:3`, `vout:1`, `ix:0.2`. */
+    readonly locator: string;
+    readonly from: readonly string[];
+    readonly to: string;
+    readonly asset: AssetRef;
+    readonly amount: bigint;
+    readonly source: TransferSource;
+    readonly memo?: string;
+}
+export interface DriverTransaction {
+    readonly id: string;
+    readonly observation: DriverTxObservation;
+    readonly fee?: readonly {
+        readonly asset: AssetRef;
+        readonly amount: bigint;
+    }[];
+    readonly transfers: readonly DriverTransfer[];
+    readonly decoding: Decoding;
+    readonly raw?: RawTx;
+    readonly timestamp?: number;
+    readonly details: Readonly<Record<string, unknown>>;
+}
+export interface DriverBlock {
+    readonly height: bigint;
+    readonly hash: string;
+    readonly parentHash: string;
+    readonly timestamp?: number;
+    readonly transactionIds?: readonly string[];
+}
+export interface AddressCodec {
+    validate(address: string): boolean;
+    /**
+     * Throws `ValidationError('INVALID_ADDRESS')`. The returned `variant` is part of the
+     * intent hash: it must hold only JSON scalars (strings, finite numbers, booleans, `null`)
+     * and should contain only semantic fields that change what the transfer does (for example
+     * TON's `bounceable`), never encoding-only choices, so two spellings of one recipient
+     * with the same meaning hash the same.
+     */
+    normalize(address: string): NormalizedAddress;
+    fromPublicKey(publicKey: Uint8Array, wallet?: WalletOptions): NormalizedAddress;
+    readonly format?: AddressFormatter;
+}
+export interface ChainReader {
+    getBalance(address: string, asset: AssetRef): Promise<bigint>;
+    getBlockHeight(): Promise<bigint>;
+    /** Highest block satisfying the network's finality policy. */
+    getFinalizedHeight(): Promise<bigint>;
+    getBlock(ref: bigint | string): Promise<DriverBlock | null>;
+    getTransaction(id: string): Promise<DriverTransaction | null>;
+    /**
+     * Current view of an Attempt (uses `purpose: 'monitor'` reads). `ordering` and `from` are
+     * `undefined` for a transaction the library does not manage (a status lookup by id).
+     */
+    observe(ref: AttemptRef, ordering: OrderingData | undefined, from: string | undefined): Promise<DriverTxObservation>;
+    getTokenMetadata?(ref: TokenRef): Promise<AssetMetadata>;
+    /** Canonicalizes a token contract (e.g. EIP-55); identity for asset ids. */
+    normalizeTokenRef?(ref: TokenRef): TokenRef;
+}
+export interface TxBuilder {
+    estimateFee(intent: DriverIntent, ctx: BuildContext): Promise<FeeEstimateDraft>;
+    checkFunds(intent: DriverIntent, fee: FeeEstimateDraft, ctx: BuildContext): Promise<FundsCheck>;
+    build(intent: DriverIntent, fee: FeeEstimateDraft, ctx: BuildContext): Promise<UnsignedTx>;
+    assemble(unsigned: UnsignedTx, signatures: readonly SignatureBundle[]): Promise<SignedTx>;
+    /**
+     * The signatures a payload signed elsewhere carries for `unsigned`'s requests,
+     * e.g. a PSBT a cold signer returned. No I/O. Throws `ValidationError('INVALID_INTENT')`
+     * when `signed` is not the prepared transaction; one it does not tell apart still fails
+     * the core's check with `SIGNATURE_MISMATCH`. Only signature bytes are taken from it: the
+     * core verifies each one against its stored request, as for any bundle. A request
+     * without a signature in `signed` is left out (a partial set).
+     */
+    signaturesFrom?(unsigned: UnsignedTx, signed: RawTx): readonly SignatureBundle[];
+}
+export interface Broadcaster {
+    /**
+     * Throws (ambiguous) on transport failure; returns a classified result otherwise.
+     * `signed.ref.id` is empty for bare broadcasts (`Blockchain.broadcast`); never rely on it.
+     */
+    broadcast(signed: SignedTx, options?: {
+        readonly fanout?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<BroadcastResult>;
+}
+export type FinalityLevel = 'latest' | 'finalized';
+/**
+ * Finalized-state checks behind `proven` verdicts; implementations use quorum reads.
+ * Only a definitive negative proof answers "no". Every other RPC error (state or
+ * history not available, pruned data, indexing in progress, a non-definitive error) throws
+ * a retryable `ProviderError('PROVIDER_UNAVAILABLE')`, which decides nothing.
+ */
+export interface ProofSource {
+    finalizedHead(): Promise<{
+        readonly height: bigint;
+        readonly hash: string;
+        readonly timestamp?: number;
+    }>;
+    includedFinal(ref: AttemptRef, ordering: OrderingData, from: string): Promise<{
+        readonly included: false;
+    } | {
+        readonly included: true;
+        readonly success: boolean;
+        readonly blockHeight: bigint;
+        readonly blockHash: string;
+        readonly txHash: string;
+        /**
+         * With `success: false`, a short fixed text, never node text. It is recorded as
+         * proven.
+         */
+        readonly reason?: string;
+    }>;
+    /** Whether the ordering slot (nonce/seqno/an input) is consumed by ANY transaction at `level`. */
+    slotConsumed(ordering: OrderingData, from: string, level: FinalityLevel): Promise<boolean>;
+    /** Whether expiry has passed per finalized state (expiry/seqno models; false otherwise). */
+    expired(ordering: OrderingData): Promise<boolean>;
+    /**
+     * The hash of the block at `height` on the chain at `level`, or `null` when there is
+     * none yet (above the head, or above the finalized height for `'finalized'`). Confirms
+     * the monitor's orphan decisions and the scanner's rollback and TOO_DEEP verdicts.
+     */
+    blockHash(height: bigint, level: FinalityLevel): Promise<string | null>;
+}
+export interface SequenceSource {
+    /** Next nonce/seqno including pending transactions. */
+    pending(address: string): Promise<bigint>;
+    /** Next nonce/seqno per the latest block. */
+    latest(address: string): Promise<bigint>;
+}
+export interface ReplacementPolicy {
+    readonly replace: boolean;
+    readonly cancel: boolean;
+    buildReplacement?(previous: UnsignedTx, fee: FeeSpeed | FeeOverride, ctx: BuildContext): Promise<UnsignedTx>;
+    /**
+     * A transaction for `previous`'s slot that does not execute the transfer (e.g. a
+     * self-transfer). Without `fee` it pays the network's minimum bump over `previous`; with
+     * one, that fee, refused (FEE_TOO_LOW) below the bump. `previous` may itself be a cancel
+     * (a repeat cancel bumps a stuck one).
+     */
+    buildCancel?(previous: UnsignedTx, ctx: BuildContext, fee?: FeeSpeed | FeeOverride): Promise<UnsignedTx>;
+}
+export interface ScanFilter {
+    readonly addresses?: readonly string[];
+    readonly assets?: readonly AssetRef[];
+}
+export interface BlockSource {
+    header(height: bigint): Promise<DriverBlock | null>;
+    transactions(block: DriverBlock, filter?: ScanFilter): Promise<readonly DriverTransaction[]>;
+}
+export interface AddressHistorySource {
+    list(address: string, options: {
+        readonly cursor?: string;
+        readonly limit: number;
+    }): Promise<{
+        readonly items: readonly DriverTransaction[];
+        readonly next?: string;
+    }>;
+}
+export interface DriverLimits {
+    readonly maxOutputs: number;
+}
+/**
+ * A native SDK client for `crypto-aio/native` and how to release it. `close` frees
+ * what the client holds (sockets, timers, workers); the root container's `close()` runs it
+ * once, before closing its pooled drivers.
+ */
+export interface DisposableNativeClient {
+    readonly client: unknown;
+    close?(): void | Promise<void>;
+}
+/**
+ * The driver port: every method's contract, as the core relies on it. Purpose, retry
+ * class and quorum are the `CallOptions` a driver passes to its `Transport` (defaults:
+ * purpose `read`, retry `safe`, no quorum). A `monitor` or `proof` read only goes to
+ * endpoints that are not lagging.
+ *
+ * | Method | Purpose | Retry | Quorum | Returns / throws |
+ * | --- | --- | --- | --- | --- |
+ * | `reader.getBalance`, `getBlock`, `getTransaction` | `read` | `safe` | none | `null` when not found; provider errors propagate |
+ * | `reader.getTokenMetadata` | `read` | `safe` | none (a driver may use a quorum) | A token's own unusable metadata (no contract, a reverting or malformed `decimals`/`symbol`) throws `ValidationError('ASSET_RESOLUTION')`, which the core caches per container (only a non-retryable `ASSET_RESOLUTION` is cached); every other failure, e.g. a transient provider failure (propagated retryable) or any other provider error, is not cached and the next lookup queries again. Stricter than this minimum, the EVM driver reads `decimals()` and `symbol()` under `quorum: 'proof'`: the metadata is cached for the container's life, and one endpoint's wrong `decimals` would mis-scale every amount; endpoints that disagree throw retryable `PROVIDER_INCONSISTENT`, which is not cached |
+ * | `reader.getBlockHeight`, `getFinalizedHeight` | `monitor` | `safe` | none | propagate; they feed the stale-view guards and confirmation depths |
+ * | `reader.observe(ref, ordering, from)` | `monitor` | `safe` | none | `{ seen: 'none' }` when not visible; `ordering` and `from` are `undefined` for a transaction the library does not manage |
+ * | `sequence.pending`, `sequence.latest` | `monitor` | `safe` | none | propagate |
+ * | `proofs.*` (`finalizedHead`, `includedFinal`, `slotConsumed`, `expired`, `blockHash`) | `proof` | `safe` | `'proof'` | endpoints that disagree throw retryable `PROVIDER_INCONSISTENT`, and the core then decides nothing. Only a definitive negative proof answers "no"; every other RPC error throws retryable `PROVIDER_UNAVAILABLE`, which decides nothing (see below). Only `slotConsumed(…, 'latest')` may be a single `monitor` read: the core records it as observed evidence |
+ * | `broadcaster.broadcast` | `broadcast` | `ambiguous-on-failure` | none (passes `fanout` and `signal` through) | classifies a definitive `RPC_ERROR` into a `BroadcastResult`; rethrows an ambiguous one (`error.ambiguous`) and every other failure unclassified |
+ * | `builder.estimateFee`, `checkFunds`, `build` | `read` | `safe` | none | `ValidationError` / `UnsupportedCapabilityError` for an intent it cannot build |
+ * | `builder.assemble` | no I/O | – | – | `SigningError('SIGNING_FAILED')` when a signature is missing |
+ * | `builder.signaturesFrom` (optional) | no I/O | – | – | `ValidationError('INVALID_INTENT')` when the signed payload is not the prepared transaction |
+ * | `replacement.buildReplacement`, `buildCancel` | `read` | `safe` | none | `ChainError('FEE_TOO_LOW')` below the network's bump; `buildCancel` honours a given `fee` and never substitutes its own |
+ * | `blocks.header` | `monitor` | `safe` | none | `null` while the height is not visible |
+ * | `blocks.transactions` | `monitor` | `safe` | none | retryable `PROVIDER_INCONSISTENT` when the block at `block.height` no longer has `block.hash` |
+ * | `history.list` | `read` (indexer transport when configured) | `safe` | none | propagate |
+ * | `createNativeClient` | no I/O | – | – | a fresh SDK instance on every call, never the pooled one |
+ *
+ * Further rules:
+ * - On a proof path (`proofs.*`), only a definitive negative proof may
+ *   answer "no" (`included: false`, a slot not consumed, a `null` block hash). Every other
+ *   RPC error, including state or history not available, pruned data, an index still being
+ *   built ("transaction indexing is in progress"), or an endpoint's non-definitive error,
+ *   must surface as a retryable `ProviderError('PROVIDER_UNAVAILABLE')`, which decides
+ *   nothing: the core looks again later and never takes it for an answer.
+ * - `BlockSource` heights are dense: every height up to the head has one block, and
+ *   `header(h)` is `null` only while `h` is not visible, never for a skipped slot.
+ * - A provider must serve headers at least about 2 × `reorgWindow` below the head. A new
+ *   cursor loads `reorgWindow` blocks below its start, and a rollback refills its window
+ *   below the common ancestor.
+ * - `ScanFilter.addresses`: when non-empty, return at least every transaction with a transfer
+ *   from or to one of them; empty (`[]`) or absent means no filter. `ScanFilter.assets` is a
+ *   hint only: a driver may narrow by it or ignore it, and the core does not filter again.
+ * - `fee.details.requestedFee` is reserved. On replacements the core records the requested
+ *   fee spec there, so a driver never sets or reads it.
+ * - `DriverContext` has no asset resolver and `DriverIntent` carries no decimals. Amounts
+ *   reach drivers in base units only; a driver that needs a token's decimals (Solana's
+ *   `transferChecked`) reads them from the chain itself.
+ */
+export interface ChainDriver {
+    readonly ordering: OrderingKind;
+    readonly capabilities: ReadonlySet<Capability>;
+    readonly address: AddressCodec;
+    readonly reader: ChainReader;
+    readonly builder: TxBuilder;
+    readonly broadcaster: Broadcaster;
+    readonly proofs: ProofSource;
+    readonly sequence?: SequenceSource;
+    readonly replacement?: ReplacementPolicy;
+    readonly blocks?: BlockSource;
+    readonly history?: AddressHistorySource;
+    /** Two-level, capability-gated family API: `ext.<family>.<method>(...) → Promise`. */
+    readonly ext?: Readonly<Record<string, Readonly<Record<string, (...args: never[]) => Promise<unknown>>>>>;
+    limits?(wallet: WalletOptions): DriverLimits;
+    /**
+     * A fresh, caller-owned SDK client for `crypto-aio/native`: a new SDK instance on every
+     * call, never the pooled one.
+     */
+    createNativeClient?(): DisposableNativeClient;
+    close?(): Promise<void>;
+}
+/**
+ * A factory's `create()` must call `transport.setProbes(...)` exactly once, before any
+ * other traffic, on every `Transport` it receives here — including `indexer`, when present.
+ * `setProbes` resets health/identity state, so calling it again later, or skipping it on one
+ * of the two transports, leaves that transport's health checks silently unconfigured.
+ *
+ * There is no asset resolver here, and `DriverIntent` carries no decimals: drivers work
+ * in base units only.
+ */
+export interface DriverContext {
+    readonly chain: ChainInfo;
+    readonly network: NetworkInfo;
+    readonly library: string;
+    readonly transport: Transport;
+    readonly indexer?: Transport;
+    readonly clock: Clock;
+    readonly log: Logger;
+    readonly options: Readonly<Record<string, unknown>>;
+}
+export interface DriverFactory {
+    create(ctx: DriverContext): Promise<ChainDriver>;
+}
+export interface PeerDependency {
+    readonly name: string;
+    readonly range: string;
+}
+/** Static metadata (no SDK import) plus a lazy `load()` that `require()`s the driver module. */
+export interface AdapterManifest {
+    readonly family: string;
+    readonly library: string;
+    readonly chains: readonly string[];
+    readonly capabilities: readonly Capability[];
+    readonly indexerCapabilities?: readonly Capability[];
+    readonly requiresIndexer?: boolean;
+    readonly peerDependencies: readonly PeerDependency[];
+    load(): Promise<DriverFactory>;
+}

package/dist/core/driver/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/driver/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { CodesOf } from '../errors/codes';\nimport type { Logger } from '../events/logger';\nimport type { AddressFormatter, NormalizedAddress } from '../model/address';\nimport type { AssetMetadata, AssetRef, TokenRef } from '../model/asset';\nimport type { Capability } from '../model/capability';\nimport type { ChainInfo, NetworkInfo } from '../model/chain';\nimport type { FeeEstimateDraft, FeeOverride, FeeSpeed } from '../model/fee';\nimport type { DriverIntent } from '../model/intent';\nimport type { OrderingData, OrderingKind } from '../model/ordering';\nimport type {\n  AttemptRef,\n  Decoding,\n  RawTx,\n  SignedTx,\n  TransferSource,\n  UnsignedTx,\n} from '../model/transaction';\nimport type { KeyRef, SignatureBundle } from '../signing/types';\nimport type { Transport } from '../transport/types';\nimport type { Clock } from '../util/clock';\n\n/**\n * Family-specific wallet settings (e.g. `utxo.addressType`, TON wallet identity). The `hd`\n * key is reserved and core-built: the core sets it to the wallet's `WalletHdOptions` when\n * the wallet has an `xpub`, and a user's or caller's `hd` never reaches a driver, since a\n * driver trusts `hd` to validate change addresses.\n */\nexport type WalletOptions = Readonly<Record<string, unknown>>;\n\nexport interface WalletKey {\n  readonly scheme: string;\n  readonly publicKey: Uint8Array;\n  readonly keyRef?: KeyRef;\n}\n\nexport interface BuildContext {\n  readonly from: string;\n  readonly keys: readonly WalletKey[];\n  readonly wallet: WalletOptions;\n  /** Allocated by the core for `nonce` and `seqno` ordering. */\n  readonly ordering?: OrderingData;\n  /** Inputs held by other live Operations of this wallet (`inputs` ordering). */\n  readonly excludeInputs?: readonly string[];\n  readonly signal?: AbortSignal;\n}\n\nexport type FundsCheck =\n  | { readonly ok: true }\n  | {\n      readonly ok: false;\n      readonly asset: AssetRef;\n      readonly required: bigint;\n      readonly available: bigint;\n    };\n\n/**\n * `refused`: state-dependent (may become valid, or may already be included) — observed only.\n * `rejected`: permanently invalid by construction (malformed, bad signature, wrong chain).\n */\nexport type BroadcastResult =\n  | { readonly kind: 'accepted' }\n  | { readonly kind: 'already-known' }\n  | { readonly kind: 'refused'; readonly code: CodesOf<'chain'>; readonly reason: string }\n  | { readonly kind: 'rejected'; readonly reason: string };\n\nexport interface DriverTxObservation {\n  readonly seen: 'none' | 'mempool' | 'block';\n  readonly txHash?: string;\n  readonly blockHeight?: bigint;\n  readonly blockHash?: string;\n  /** For included transactions: false when execution failed or reverted. */\n  readonly success?: boolean;\n  /**\n   * With `success: false`, why, as a short fixed text: no addresses, amounts or node\n   * text, which can carry either. The monitor records it on the observation\n   * (`TxStatus.reason`).\n   */\n  readonly reason?: string;\n}\n\nexport interface DriverTransfer {\n  /** Deterministic within the transaction, e.g. `native`, `log:3`, `vout:1`, `ix:0.2`. */\n  readonly locator: string;\n  readonly from: readonly string[];\n  readonly to: string;\n  readonly asset: AssetRef;\n  readonly amount: bigint;\n  readonly source: TransferSource;\n  readonly memo?: string;\n}\n\nexport interface DriverTransaction {\n  readonly id: string;\n  readonly observation: DriverTxObservation;\n  readonly fee?: readonly { readonly asset: AssetRef; readonly amount: bigint }[];\n  readonly transfers: readonly DriverTransfer[];\n  readonly decoding: Decoding;\n  readonly raw?: RawTx;\n  readonly timestamp?: number;\n  readonly details: Readonly<Record<string, unknown>>;\n}\n\nexport interface DriverBlock {\n  readonly height: bigint;\n  readonly hash: string;\n  readonly parentHash: string;\n  readonly timestamp?: number;\n  readonly transactionIds?: readonly string[];\n}\n\nexport interface AddressCodec {\n  validate(address: string): boolean;\n  /**\n   * Throws `ValidationError('INVALID_ADDRESS')`. The returned `variant` is part of the\n   * intent hash: it must hold only JSON scalars (strings, finite numbers, booleans, `null`)\n   * and should contain only semantic fields that change what the transfer does (for example\n   * TON's `bounceable`), never encoding-only choices, so two spellings of one recipient\n   * with the same meaning hash the same.\n   */\n  normalize(address: string): NormalizedAddress;\n  fromPublicKey(publicKey: Uint8Array, wallet?: WalletOptions): NormalizedAddress;\n  readonly format?: AddressFormatter;\n}\n\nexport interface ChainReader {\n  getBalance(address: string, asset: AssetRef): Promise<bigint>;\n  getBlockHeight(): Promise<bigint>;\n  /** Highest block satisfying the network's finality policy. */\n  getFinalizedHeight(): Promise<bigint>;\n  getBlock(ref: bigint | string): Promise<DriverBlock | null>;\n  getTransaction(id: string): Promise<DriverTransaction | null>;\n  /**\n   * Current view of an Attempt (uses `purpose: 'monitor'` reads). `ordering` and `from` are\n   * `undefined` for a transaction the library does not manage (a status lookup by id).\n   */\n  observe(\n    ref: AttemptRef,\n    ordering: OrderingData | undefined,\n    from: string | undefined,\n  ): Promise<DriverTxObservation>;\n  getTokenMetadata?(ref: TokenRef): Promise<AssetMetadata>;\n  /** Canonicalizes a token contract (e.g. EIP-55); identity for asset ids. */\n  normalizeTokenRef?(ref: TokenRef): TokenRef;\n}\n\nexport interface TxBuilder {\n  estimateFee(intent: DriverIntent, ctx: BuildContext): Promise<FeeEstimateDraft>;\n  checkFunds(\n    intent: DriverIntent,\n    fee: FeeEstimateDraft,\n    ctx: BuildContext,\n  ): Promise<FundsCheck>;\n  build(\n    intent: DriverIntent,\n    fee: FeeEstimateDraft,\n    ctx: BuildContext,\n  ): Promise<UnsignedTx>;\n  assemble(\n    unsigned: UnsignedTx,\n    signatures: readonly SignatureBundle[],\n  ): Promise<SignedTx>;\n  /**\n   * The signatures a payload signed elsewhere carries for `unsigned`'s requests,\n   * e.g. a PSBT a cold signer returned. No I/O. Throws `ValidationError('INVALID_INTENT')`\n   * when `signed` is not the prepared transaction; one it does not tell apart still fails\n   * the core's check with `SIGNATURE_MISMATCH`. Only signature bytes are taken from it: the\n   * core verifies each one against its stored request, as for any bundle. A request\n   * without a signature in `signed` is left out (a partial set).\n   */\n  signaturesFrom?(unsigned: UnsignedTx, signed: RawTx): readonly SignatureBundle[];\n}\n\nexport interface Broadcaster {\n  /**\n   * Throws (ambiguous) on transport failure; returns a classified result otherwise.\n   * `signed.ref.id` is empty for bare broadcasts (`Blockchain.broadcast`); never rely on it.\n   */\n  broadcast(\n    signed: SignedTx,\n    options?: { readonly fanout?: number; readonly signal?: AbortSignal },\n  ): Promise<BroadcastResult>;\n}\n\nexport type FinalityLevel = 'latest' | 'finalized';\n\n/**\n * Finalized-state checks behind `proven` verdicts; implementations use quorum reads.\n * Only a definitive negative proof answers \"no\". Every other RPC error (state or\n * history not available, pruned data, indexing in progress, a non-definitive error) throws\n * a retryable `ProviderError('PROVIDER_UNAVAILABLE')`, which decides nothing.\n */\nexport interface ProofSource {\n  finalizedHead(): Promise<{\n    readonly height: bigint;\n    readonly hash: string;\n    readonly timestamp?: number;\n  }>;\n  includedFinal(\n    ref: AttemptRef,\n    ordering: OrderingData,\n    from: string,\n  ): Promise<\n    | { readonly included: false }\n    | {\n        readonly included: true;\n        readonly success: boolean;\n        readonly blockHeight: bigint;\n        readonly blockHash: string;\n        readonly txHash: string;\n        /**\n         * With `success: false`, a short fixed text, never node text. It is recorded as\n         * proven.\n         */\n        readonly reason?: string;\n      }\n  >;\n  /** Whether the ordering slot (nonce/seqno/an input) is consumed by ANY transaction at `level`. */\n  slotConsumed(\n    ordering: OrderingData,\n    from: string,\n    level: FinalityLevel,\n  ): Promise<boolean>;\n  /** Whether expiry has passed per finalized state (expiry/seqno models; false otherwise). */\n  expired(ordering: OrderingData): Promise<boolean>;\n  /**\n   * The hash of the block at `height` on the chain at `level`, or `null` when there is\n   * none yet (above the head, or above the finalized height for `'finalized'`). Confirms\n   * the monitor's orphan decisions and the scanner's rollback and TOO_DEEP verdicts.\n   */\n  blockHash(height: bigint, level: FinalityLevel): Promise<string | null>;\n}\n\nexport interface SequenceSource {\n  /** Next nonce/seqno including pending transactions. */\n  pending(address: string): Promise<bigint>;\n  /** Next nonce/seqno per the latest block. */\n  latest(address: string): Promise<bigint>;\n}\n\nexport interface ReplacementPolicy {\n  readonly replace: boolean;\n  readonly cancel: boolean;\n  buildReplacement?(\n    previous: UnsignedTx,\n    fee: FeeSpeed | FeeOverride,\n    ctx: BuildContext,\n  ): Promise<UnsignedTx>;\n  /**\n   * A transaction for `previous`'s slot that does not execute the transfer (e.g. a\n   * self-transfer). Without `fee` it pays the network's minimum bump over `previous`; with\n   * one, that fee, refused (FEE_TOO_LOW) below the bump. `previous` may itself be a cancel\n   * (a repeat cancel bumps a stuck one).\n   */\n  buildCancel?(\n    previous: UnsignedTx,\n    ctx: BuildContext,\n    fee?: FeeSpeed | FeeOverride,\n  ): Promise<UnsignedTx>;\n}\n\nexport interface ScanFilter {\n  readonly addresses?: readonly string[];\n  readonly assets?: readonly AssetRef[];\n}\n\nexport interface BlockSource {\n  header(height: bigint): Promise<DriverBlock | null>;\n  transactions(\n    block: DriverBlock,\n    filter?: ScanFilter,\n  ): Promise<readonly DriverTransaction[]>;\n}\n\nexport interface AddressHistorySource {\n  list(\n    address: string,\n    options: { readonly cursor?: string; readonly limit: number },\n  ): Promise<{ readonly items: readonly DriverTransaction[]; readonly next?: string }>;\n}\n\nexport interface DriverLimits {\n  readonly maxOutputs: number;\n}\n\n/**\n * A native SDK client for `crypto-aio/native` and how to release it. `close` frees\n * what the client holds (sockets, timers, workers); the root container's `close()` runs it\n * once, before closing its pooled drivers.\n */\nexport interface DisposableNativeClient {\n  readonly client: unknown;\n  close?(): void | Promise<void>;\n}\n\n/**\n * The driver port: every method's contract, as the core relies on it. Purpose, retry\n * class and quorum are the `CallOptions` a driver passes to its `Transport` (defaults:\n * purpose `read`, retry `safe`, no quorum). A `monitor` or `proof` read only goes to\n * endpoints that are not lagging.\n *\n * | Method | Purpose | Retry | Quorum | Returns / throws |\n * | --- | --- | --- | --- | --- |\n * | `reader.getBalance`, `getBlock`, `getTransaction` | `read` | `safe` | none | `null` when not found; provider errors propagate |\n * | `reader.getTokenMetadata` | `read` | `safe` | none (a driver may use a quorum) | A token's own unusable metadata (no contract, a reverting or malformed `decimals`/`symbol`) throws `ValidationError('ASSET_RESOLUTION')`, which the core caches per container (only a non-retryable `ASSET_RESOLUTION` is cached); every other failure, e.g. a transient provider failure (propagated retryable) or any other provider error, is not cached and the next lookup queries again. Stricter than this minimum, the EVM driver reads `decimals()` and `symbol()` under `quorum: 'proof'`: the metadata is cached for the container's life, and one endpoint's wrong `decimals` would mis-scale every amount; endpoints that disagree throw retryable `PROVIDER_INCONSISTENT`, which is not cached |\n * | `reader.getBlockHeight`, `getFinalizedHeight` | `monitor` | `safe` | none | propagate; they feed the stale-view guards and confirmation depths |\n * | `reader.observe(ref, ordering, from)` | `monitor` | `safe` | none | `{ seen: 'none' }` when not visible; `ordering` and `from` are `undefined` for a transaction the library does not manage |\n * | `sequence.pending`, `sequence.latest` | `monitor` | `safe` | none | propagate |\n * | `proofs.*` (`finalizedHead`, `includedFinal`, `slotConsumed`, `expired`, `blockHash`) | `proof` | `safe` | `'proof'` | endpoints that disagree throw retryable `PROVIDER_INCONSISTENT`, and the core then decides nothing. Only a definitive negative proof answers \"no\"; every other RPC error throws retryable `PROVIDER_UNAVAILABLE`, which decides nothing (see below). Only `slotConsumed(…, 'latest')` may be a single `monitor` read: the core records it as observed evidence |\n * | `broadcaster.broadcast` | `broadcast` | `ambiguous-on-failure` | none (passes `fanout` and `signal` through) | classifies a definitive `RPC_ERROR` into a `BroadcastResult`; rethrows an ambiguous one (`error.ambiguous`) and every other failure unclassified |\n * | `builder.estimateFee`, `checkFunds`, `build` | `read` | `safe` | none | `ValidationError` / `UnsupportedCapabilityError` for an intent it cannot build |\n * | `builder.assemble` | no I/O | – | – | `SigningError('SIGNING_FAILED')` when a signature is missing |\n * | `builder.signaturesFrom` (optional) | no I/O | – | – | `ValidationError('INVALID_INTENT')` when the signed payload is not the prepared transaction |\n * | `replacement.buildReplacement`, `buildCancel` | `read` | `safe` | none | `ChainError('FEE_TOO_LOW')` below the network's bump; `buildCancel` honours a given `fee` and never substitutes its own |\n * | `blocks.header` | `monitor` | `safe` | none | `null` while the height is not visible |\n * | `blocks.transactions` | `monitor` | `safe` | none | retryable `PROVIDER_INCONSISTENT` when the block at `block.height` no longer has `block.hash` |\n * | `history.list` | `read` (indexer transport when configured) | `safe` | none | propagate |\n * | `createNativeClient` | no I/O | – | – | a fresh SDK instance on every call, never the pooled one |\n *\n * Further rules:\n * - On a proof path (`proofs.*`), only a definitive negative proof may\n *   answer \"no\" (`included: false`, a slot not consumed, a `null` block hash). Every other\n *   RPC error, including state or history not available, pruned data, an index still being\n *   built (\"transaction indexing is in progress\"), or an endpoint's non-definitive error,\n *   must surface as a retryable `ProviderError('PROVIDER_UNAVAILABLE')`, which decides\n *   nothing: the core looks again later and never takes it for an answer.\n * - `BlockSource` heights are dense: every height up to the head has one block, and\n *   `header(h)` is `null` only while `h` is not visible, never for a skipped slot.\n * - A provider must serve headers at least about 2 × `reorgWindow` below the head. A new\n *   cursor loads `reorgWindow` blocks below its start, and a rollback refills its window\n *   below the common ancestor.\n * - `ScanFilter.addresses`: when non-empty, return at least every transaction with a transfer\n *   from or to one of them; empty (`[]`) or absent means no filter. `ScanFilter.assets` is a\n *   hint only: a driver may narrow by it or ignore it, and the core does not filter again.\n * - `fee.details.requestedFee` is reserved. On replacements the core records the requested\n *   fee spec there, so a driver never sets or reads it.\n * - `DriverContext` has no asset resolver and `DriverIntent` carries no decimals. Amounts\n *   reach drivers in base units only; a driver that needs a token's decimals (Solana's\n *   `transferChecked`) reads them from the chain itself.\n */\nexport interface ChainDriver {\n  readonly ordering: OrderingKind;\n  readonly capabilities: ReadonlySet<Capability>;\n  readonly address: AddressCodec;\n  readonly reader: ChainReader;\n  readonly builder: TxBuilder;\n  readonly broadcaster: Broadcaster;\n  readonly proofs: ProofSource;\n  readonly sequence?: SequenceSource;\n  readonly replacement?: ReplacementPolicy;\n  readonly blocks?: BlockSource;\n  readonly history?: AddressHistorySource;\n  /** Two-level, capability-gated family API: `ext.<family>.<method>(...) → Promise`. */\n  readonly ext?: Readonly<\n    Record<string, Readonly<Record<string, (...args: never[]) => Promise<unknown>>>>\n  >;\n  limits?(wallet: WalletOptions): DriverLimits;\n  /**\n   * A fresh, caller-owned SDK client for `crypto-aio/native`: a new SDK instance on every\n   * call, never the pooled one.\n   */\n  createNativeClient?(): DisposableNativeClient;\n  close?(): Promise<void>;\n}\n\n/**\n * A factory's `create()` must call `transport.setProbes(...)` exactly once, before any\n * other traffic, on every `Transport` it receives here — including `indexer`, when present.\n * `setProbes` resets health/identity state, so calling it again later, or skipping it on one\n * of the two transports, leaves that transport's health checks silently unconfigured.\n *\n * There is no asset resolver here, and `DriverIntent` carries no decimals: drivers work\n * in base units only.\n */\nexport interface DriverContext {\n  readonly chain: ChainInfo;\n  readonly network: NetworkInfo;\n  readonly library: string;\n  readonly transport: Transport;\n  readonly indexer?: Transport;\n  readonly clock: Clock;\n  readonly log: Logger;\n  readonly options: Readonly<Record<string, unknown>>;\n}\n\nexport interface DriverFactory {\n  create(ctx: DriverContext): Promise<ChainDriver>;\n}\n\nexport interface PeerDependency {\n  readonly name: string;\n  readonly range: string;\n}\n\n/** Static metadata (no SDK import) plus a lazy `load()` that `require()`s the driver module. */\nexport interface AdapterManifest {\n  readonly family: string;\n  readonly library: string;\n  readonly chains: readonly string[];\n  readonly capabilities: readonly Capability[];\n  readonly indexerCapabilities?: readonly Capability[];\n  readonly requiresIndexer?: boolean;\n  readonly peerDependencies: readonly PeerDependency[];\n  load(): Promise<DriverFactory>;\n}\n"]}