@vtx-labs/solana-explain 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,116 @@
+import { E as ExplainInput, a as ExplainResult, b as ExplainInstruction, c as ExplainOptions, d as ExplainInstructionsOptions, e as ExplainSignatureOptions, f as ExplainTransactionOptions, B as BalanceSnapshot, g as BalanceDelta, R as RpcClient } from './types-MSKEy1VA.js';
+export { A as AccountCreation, h as Action, i as Approval, C as Commitment, j as CompiledInstructionView, D as DecodeOutput, k as DecodedInstruction, l as DecoderEffect, m as ExplainInstructionAccount, G as GetAccountsOpts, n as GetTransactionOpts, K as KnownProgramInfo, P as ProgramDecoder, o as ProgramInvocation, p as ProgramKind, q as ProgramRegistry, r as RawAccount, s as RawSimulateResponse, t as RawTransactionResponse, u as RenderOptions, S as SimulateOpts, T as TokenBalanceEntry, W as Warning, v as WarningCode } from './types-MSKEy1VA.js';
+export { KNOWN_PROGRAMS, createRegistry, decodeInstruction, defaultRegistry } from './programs.js';
+export { renderJson, renderMarkdown, renderText } from './render.js';
+
+/**
+ * Error hierarchy for solana-explain.
+ *
+ * Every public async function rejects ONLY with a {@link SolanaExplainError}
+ * subclass. Raw/underlying errors are always wrapped and preserved on `.cause`.
+ */
+type ErrorCode = 'INVALID_INPUT' | 'INVALID_SIGNATURE' | 'INVALID_ENCODING' | 'EMPTY_INPUT' | 'TX_NOT_FOUND' | 'RPC_HTTP' | 'RPC_JSON' | 'RPC_TIMEOUT' | 'ABORTED' | 'DECODE_FAILED' | 'SIMULATION_REJECTED' | 'UNSUPPORTED_TX_VERSION';
+interface SolanaExplainErrorOptions {
+    cause?: unknown;
+    /** Optional human hint surfaced by the CLI alongside the message. */
+    hint?: string;
+}
+/** Base class. Never thrown directly by public functions — only its subclasses. */
+declare class SolanaExplainError extends Error {
+    readonly code: ErrorCode;
+    readonly cause?: unknown;
+    /** Optional, CLI-friendly remediation hint. */
+    readonly hint?: string;
+    constructor(code: ErrorCode, message: string, options?: SolanaExplainErrorOptions);
+}
+/** Transport / JSON-RPC error (HTTP failure, malformed JSON, JSON-RPC error object, timeout). */
+declare class RpcError extends SolanaExplainError {
+}
+/** Malformed transaction bytes / wire message. */
+declare class DecodeError extends SolanaExplainError {
+}
+/**
+ * Simulation produced a runtime error (the tx would fail). Still carries a
+ * partial {@link import('./types').ExplainResult} on `.result` when available,
+ * because the user usually wants to know *why* it failed.
+ *
+ * Note: a node *rejecting* the simulation outright (bad blockhash, etc.) is a
+ * different condition and is also surfaced as a `SimulationError`, with code
+ * `SIMULATION_REJECTED`.
+ */
+declare class SimulationError extends SolanaExplainError {
+    /** Partial result when the simulation ran but reverted. */
+    readonly result?: unknown;
+    /** Tail of the node's program logs, for diagnostics. */
+    readonly logs?: readonly string[];
+    constructor(code: ErrorCode, message: string, options?: SolanaExplainErrorOptions & {
+        result?: unknown;
+        logs?: readonly string[];
+    });
+}
+/** Bad signature / encoding / empty input. */
+declare class InputError extends SolanaExplainError {
+}
+
+/**
+ * Top-level orchestrators: `explain`, `explainSignature`, `explainTransaction`,
+ * `explainInstructions`, and the pure `buildExplanation`.
+ *
+ * Behavioral contracts:
+ *  - All public async functions reject ONLY with a SolanaExplainError subclass.
+ *  - A failed/reverted tx still returns a fully-populated ExplainResult
+ *    (success:false); it does NOT throw.
+ *  - explainSignature on a missing sig throws RpcError TX_NOT_FOUND.
+ *  - Simulation the node outright rejects throws SimulationError.
+ */
+
+/** Pure: given pre/post balances + decoded instructions, produce the narrative. */
+declare function buildExplanation(input: ExplainInput): ExplainResult;
+declare function explainSignature(signature: string, options: ExplainSignatureOptions): Promise<ExplainResult>;
+declare function explainTransaction(tx: string | Uint8Array, options: ExplainTransactionOptions): Promise<ExplainResult>;
+declare function explainInstructions(instructions: ExplainInstruction[], options: ExplainInstructionsOptions): Promise<ExplainResult>;
+declare function explain(input: string | Uint8Array | ExplainInstruction[], options: ExplainOptions): Promise<ExplainResult>;
+
+/**
+ * `diffBalances`: pure diff of pre/post lamport + token balances into typed
+ * {@link BalanceDelta}[]. No I/O.
+ *
+ * - SOL deltas: by account key index (post − pre).
+ * - Token deltas: keyed by token-account address + mint, matching pre/post.
+ *   Accounts present on only one side are created (post-only) or closed
+ *   (pre-only).
+ */
+
+declare function diffBalances(pre: BalanceSnapshot, post: BalanceSnapshot): BalanceDelta[];
+
+/**
+ * `createHttpRpc`: zero-dep JSON-RPC over the global `fetch` (Node 18+).
+ *
+ * - Per-call timeout via AbortController, composed with the caller's signal.
+ * - Single jittered-backoff retry on 429/5xx.
+ * - Strict JSON-RPC error mapping → RpcError.
+ */
+
+interface HttpRpcOptions {
+    /** Default per-call timeout in ms. Default 30_000. */
+    timeoutMs?: number;
+    /** Extra HTTP headers (e.g. API key). */
+    headers?: Record<string, string>;
+    /** Override fetch (for testing). Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+declare function createHttpRpc(url: string, opts?: HttpRpcOptions): RpcClient;
+
+/**
+ * `fromWeb3Rpc`: adapt an existing `@solana/web3.js` v1 `Connection` or a
+ * `@solana/kit` / web3.js v2 RPC object to our {@link RpcClient}, by
+ * duck-typing its methods. We never import web3.js — it stays an optional peer.
+ */
+
+/**
+ * Wrap a web3.js v1 `Connection` or a kit RPC into an {@link RpcClient}.
+ * Throws {@link RpcError} if the object exposes neither shape.
+ */
+declare function fromWeb3Rpc(rpc: unknown): RpcClient;
+
+export { BalanceDelta, BalanceSnapshot, DecodeError, type ErrorCode, ExplainInput, ExplainInstruction, ExplainInstructionsOptions, ExplainOptions, ExplainResult, ExplainSignatureOptions, ExplainTransactionOptions, type HttpRpcOptions, InputError, RpcClient, RpcError, SimulationError, SolanaExplainError, buildExplanation, createHttpRpc, diffBalances, explain, explainInstructions, explainSignature, explainTransaction, fromWeb3Rpc };