crypto-aio 0.0.3 → 0.1.0

package/dist/core/blockchain/handle.d.ts

@@ -0,0 +1,200 @@
+import type { HandleConfig } from '../config/types';
+import type { BroadcastResult, DriverLimits, WalletOptions } from '../driver/types';
+import { Address } from '../model/address';
+import { Amount } from '../model/amount';
+import type { AssetInfo, AssetRef } from '../model/asset';
+import type { Capability } from '../model/capability';
+import type { FeeEstimate, FeeOverride, FeeSpeed } from '../model/fee';
+import type { ChainId, ExtOf, LibraryOf, NetworkOf } from '../model/ids';
+import { type TransferIntent } from '../model/intent';
+import type { Block, RawTx, Transaction, TxStatus } from '../model/transaction';
+import { type OperationEngine, type OperationTarget, type ReadTarget, type TransferOptions } from '../lifecycle/engine';
+import { type ConfirmationResult, type Monitor, type TxStatusEvent, type WaitOptions } from '../lifecycle/monitor';
+import { type OperationView, type PreparedOperation, type Submission } from '../lifecycle/views';
+import { Scanner, type ScannerOptions } from '../observe/scanner';
+import type { SignatureBundle } from '../signing/types';
+import type { OperationRecord } from '../store/types';
+import type { EndpointStatus } from '../transport/types';
+import { type HandleInternals } from './internal';
+import { type MappingContext } from './mapping';
+export interface Balance {
+    readonly address: Address;
+    readonly asset: AssetInfo;
+    readonly amount: Amount;
+}
+export interface NetworkStatus {
+    readonly chain: string;
+    readonly network: string;
+    readonly height: bigint;
+    readonly finalizedHeight: bigint;
+    readonly endpoints: readonly EndpointStatus[];
+    readonly indexers: readonly EndpointStatus[];
+}
+/** Immutable handle bound to one chain, network, library, provider set and wallet. */
+export declare class Blockchain<C extends ChainId = ChainId> {
+    /** @internal Use `CryptoAio#blockchain` or `Blockchain.create`. */
+    constructor(internals: HandleInternals);
+    /** Creates a handle on the default container (see `configure`). */
+    static create<C extends ChainId>(config: HandleConfig<C>): Blockchain<C>;
+    get chain(): C;
+    get network(): NetworkOf<C>;
+    get library(): LibraryOf<C>;
+    /** Frozen, redacted snapshot of the resolved configuration. */
+    get config(): Readonly<Record<string, unknown>>;
+    /** A fresh copy on every read; mutating the result never affects `supports()`. */
+    get capabilities(): ReadonlySet<Capability>;
+    supports(capability: Capability): boolean;
+    /** Returns a NEW handle; this handle and operations started from it are unaffected. */
+    with(overrides: Partial<Omit<HandleConfig<C>, 'chain'>>): Blockchain<C>;
+    /**
+     * Loads the adapter, connects its transport and validates it's actually usable; fails fast
+     * on a missing dependency (`DEPENDENCY_MISSING`), an invalid wallet (surfaced by resolving
+     * it), or a provider that can't serve reads: `PROVIDER_UNAVAILABLE` when no configured
+     * endpoint is usable, `PROVIDER_MISCONFIGURED` (non-retryable) when every endpoint's
+     * identity mismatches the configured network. An endpoint is usable when it's 'healthy',
+     * 'lagging' or 'half-open' (the breaker is willing to try it), or 'unknown' while the
+     * transport has no health probes configured at all — nothing could ever have marked it
+     * healthy/lagging in that case, so 'unknown' is simply its steady state.
+     */
+    ready(): Promise<this>;
+    limits(): Promise<DriverLimits>;
+    validateAddress(address: string): Promise<boolean>;
+    normalizeAddress(address: string): Promise<Address>;
+    /** The chain's address for `publicKey`. `options.hd` is reserved: the core builds it
+     * from a wallet's `xpub`, so a caller's `hd` is dropped and never reaches the driver.
+     * `null` options (from an untyped caller) are none. */
+    addressFromPublicKey(publicKey: Uint8Array | string, options?: WalletOptions): Promise<Address>;
+    /** Address of the handle's own selected wallet, or of another configured `wallet` by name
+     * — resolved fresh against this handle's driver, without switching the handle.
+     * Re-resolved through `resolveSelection` (not `resolveWallet` directly) so a
+     * named wallet gets the same `wallet.chains` enablement check, unknown-signer validation and
+     * signer-scheme compatibility check that the handle's own wallet got at construction. */
+    walletAddress(wallet?: string): Promise<Address>;
+    /** Derives a deposit address from the wallet's xpub (capability `hd-public-derivation`). */
+    deriveAddress(wallet: string, index: number): Promise<Address>;
+    resolveAsset(asset?: AssetRef | string): Promise<AssetInfo>;
+    getBalance(address: string, asset?: AssetRef | string): Promise<Balance>;
+    getBalances(address: string, assets: readonly (AssetRef | string)[]): Promise<Balance[]>;
+    estimateFee(intent: TransferIntent): Promise<FeeEstimate>;
+    getTransaction(id: string): Promise<Transaction | null>;
+    /** Status of a managed Operation (by id, Attempt ref or tx hash) or of any transaction id. */
+    getTransactionStatus(id: string): Promise<TxStatus>;
+    /**
+     * Resolves once `confirmations` (default: the handle's) are reached. With
+     * `finality: 'final'`, a managed Operation (by id, Attempt ref or tx hash) resolves on
+     * **proven** finality (finalized data confirmed by quorum proof reads); a transaction the
+     * library does not manage resolves on **observed** finality (one endpoint's view of a
+     * block at or below the finalized height). Rejects with the chain error when the
+     * Operation fails, expires or is replaced (`TX_REVERTED` for an unmanaged transaction
+     * that reverted), with `TIMEOUT` (retryable, state unchanged) when time runs out, and
+     * with the reason of an aborted `signal`.
+     */
+    waitForConfirmation(ref: string, options?: WaitOptions): Promise<ConfirmationResult>;
+    /** Yields each status change until the Operation is terminal (or the transaction is final). */
+    watch(ref: string, options?: {
+        readonly pollIntervalMs?: number;
+        readonly signal?: AbortSignal;
+    }): AsyncIterable<TxStatusEvent>;
+    getBlockHeight(): Promise<bigint>;
+    getBlock(ref: bigint | string): Promise<Block | null>;
+    /**
+     * Reorg-aware, at-least-once block scanner (capability `block-scan`): `ack()` each event
+     * to commit the cursor before asking for the next. Invalid options throw `CONFIG_INVALID`.
+     */
+    scanner(options: ScannerOptions): Scanner;
+    /** Indexer-backed transaction history of an address (capability `address-history`). */
+    history(address: string, options?: {
+        readonly cursor?: string;
+        readonly limit?: number;
+    }): Promise<{
+        readonly items: readonly Transaction[];
+        readonly next?: string;
+    }>;
+    getNetworkStatus(): Promise<NetworkStatus>;
+    /** Builds and persists the unsigned transaction (reserving nonce/inputs) for offline or async signing. */
+    prepareTransfer(intent: TransferIntent, options?: TransferOptions): Promise<PreparedOperation>;
+    /**
+     * Idempotent transfer. Throws the mapped chain error when the Operation stalls or fails;
+     * throws an `ambiguous` error (with `context.operationId`) when the broadcast outcome is
+     * unknown. Retry with the same `idempotencyKey` in both cases.
+     */
+    transfer(intent: TransferIntent, options?: TransferOptions): Promise<Submission>;
+    /**
+     * Completes an Operation that awaits signatures, with signature bundles or with the whole
+     * payload signed elsewhere, e.g. a signed PSBT: the driver extracts its signatures
+     * (`TxBuilder.signaturesFrom`), and each is verified against the stored request exactly
+     * like a bundle. `UNSUPPORTED_CAPABILITY` when the chain's driver cannot read one.
+     */
+    submitSignatures(operationId: string, signatures: readonly SignatureBundle[] | RawTx): Promise<Submission>;
+    /** Resends the active Attempt's stored raw transaction (e.g. after topping up a stalled wallet). */
+    rebroadcast(operationId: string): Promise<Submission>;
+    /**
+     * Replaces a pending transfer with a higher-fee, mutually exclusive Attempt (capability
+     * `replace-fee`; a synchronous signer). If the node refuses it, the original stays live
+     * and active, and the node's error is thrown.
+     *
+     * Idempotent per fee spec: repeating the call with the same `fee` (the same speed name,
+     * or an equal override) returns the replacement it already made, resending it if its
+     * broadcast was never recorded or it was refused; nothing is signed again, and a refusal
+     * is thrown, never reported as a success. To bump again, pass another spec, such as a
+     * higher explicit override.
+     *
+     * While that replacement is stored but not yet sent, another fee spec (or a cancel) is
+     * refused with `INVALID_TRANSITION`: repeat the same spec, or call `rebroadcast`, first.
+     */
+    replace(operationId: string, options: {
+        readonly fee: FeeSpeed | FeeOverride;
+    }): Promise<Submission>;
+    /**
+     * Tries to cancel with a conflicting Attempt (capability `cancel`); the outcome is
+     * `cancelled` only if the cancel wins at finality, and the original may still win. The
+     * cancel pays the network's minimum bump over the highest earlier cancel, or `options.fee`
+     * (refused below that bump).
+     *
+     * Repeating the call while a cancel is pending resends it if its broadcast was never
+     * recorded, and returns it while a node holds it or once it is on chain, so concurrent and
+     * retried calls create one cancel. Only a cancel the node refused or dropped is bumped by
+     * a repeat, one step at a time; when the node's minimum fee is more than one bump away,
+     * pass `options.fee`, which always builds a new cancel while none is on chain.
+     *
+     * While a replacement is stored but not yet sent, a cancel is refused with
+     * `INVALID_TRANSITION`: repeat that replacement's fee, or call `rebroadcast`, first.
+     */
+    cancel(operationId: string, options?: {
+        readonly fee?: FeeSpeed | FeeOverride;
+    }): Promise<Submission>;
+    /** Expiry-based chains: re-issues an Operation whose earlier Attempts are provably expired. */
+    rebuild(operationId: string): Promise<Submission>;
+    /**
+     * Broadcasts an externally signed transaction WITHOUT creating an Operation: no idempotency,
+     * persistence or monitoring. Prefer prepareTransfer + submitSignatures for managed flows.
+     */
+    broadcast(raw: RawTx): Promise<BroadcastResult>;
+    /** Abandons an Operation that has no signed transaction yet and releases its reservation. */
+    abandon(operationId: string): Promise<OperationView>;
+    /** An Operation of this handle's chain and network (another one is INVALID_INTENT). */
+    getOperation(operationId: string): Promise<OperationView | null>;
+    /** Typed family extensions: `bc.ext.<family>.<method>(...)` (async, loads the adapter on demand). */
+    get ext(): ExtOf<C>;
+    /** @internal The driver's address for `publicKey` under options the core built. */
+    protected driverAddress(publicKey: Uint8Array, options: WalletOptions): Promise<Address>;
+    /** @internal */
+    protected mapping(): Promise<MappingContext>;
+    /** @internal */
+    protected engine(): OperationEngine;
+    /** @internal */
+    protected monitor(): Monitor;
+    /** @internal */
+    protected readTarget(): Promise<ReadTarget>;
+    /** @internal */
+    protected target(): Promise<OperationTarget>;
+    /** @internal */
+    protected view(record: OperationRecord): Promise<OperationView>;
+    /** @internal */
+    protected submission(record: OperationRecord): Promise<Submission>;
+    /**
+     * @internal Signing material only while the Operation awaits signatures: an idempotent
+     * repeat of an abandoned Operation returns its view alone.
+     */
+    protected prepared(target: OperationTarget, record: OperationRecord): Promise<PreparedOperation>;
+}