@vtx-labs/solana-explain 0.1.0

package/dist/types-MSKEy1VA.d.ts

@@ -0,0 +1,482 @@
+/**
+ * The RpcClient interface + raw RPC response shapes.
+ *
+ * The library only ever talks to {@link RpcClient}, which makes it
+ * network-source-agnostic and keeps `@solana/web3.js` an optional peer dep.
+ */
+
+interface GetTransactionOpts {
+    commitment?: Commitment;
+    maxSupportedTransactionVersion?: number;
+    signal?: AbortSignal;
+}
+interface SimulateOpts {
+    commitment?: Commitment;
+    sigVerify?: boolean;
+    replaceRecentBlockhash?: boolean;
+    /** Accounts to return post-state for (jsonParsed). */
+    accounts?: {
+        addresses: string[];
+        encoding?: 'jsonParsed' | 'base64';
+    };
+    innerInstructions?: boolean;
+    signal?: AbortSignal;
+}
+interface GetAccountsOpts {
+    commitment?: Commitment;
+    encoding?: 'jsonParsed' | 'base64';
+    signal?: AbortSignal;
+}
+interface RpcClient {
+    getTransaction(sig: string, opts: GetTransactionOpts): Promise<RawTransactionResponse | null>;
+    simulateTransaction(txBase64: string, opts: SimulateOpts): Promise<RawSimulateResponse>;
+    getMultipleAccounts(addresses: string[], opts: GetAccountsOpts): Promise<(RawAccount | null)[]>;
+    getLatestBlockhash(opts?: {
+        commitment?: Commitment;
+        signal?: AbortSignal;
+    }): Promise<{
+        blockhash: string;
+        lastValidBlockHeight: number;
+    }>;
+}
+interface RawTokenAmount {
+    amount: string;
+    decimals: number;
+    uiAmount: number | null;
+    uiAmountString?: string;
+}
+interface RawTokenBalance {
+    accountIndex: number;
+    mint: string;
+    owner?: string;
+    programId?: string;
+    uiTokenAmount: RawTokenAmount;
+}
+interface RawInstructionCompiled {
+    programIdIndex: number;
+    accounts: number[];
+    data: string;
+}
+interface RawInnerInstructions {
+    index: number;
+    instructions: RawInstructionCompiled[];
+}
+interface RawLoadedAddresses {
+    writable: string[];
+    readonly: string[];
+}
+interface RawTransactionMeta {
+    err: unknown;
+    fee: number;
+    preBalances: number[];
+    postBalances: number[];
+    preTokenBalances?: RawTokenBalance[];
+    postTokenBalances?: RawTokenBalance[];
+    innerInstructions?: RawInnerInstructions[];
+    loadedAddresses?: RawLoadedAddresses;
+    computeUnitsConsumed?: number;
+    logMessages?: string[];
+}
+interface RawTransactionResponse {
+    slot: number;
+    blockTime: number | null;
+    version?: number | 'legacy';
+    meta: RawTransactionMeta | null;
+    transaction: {
+        signatures: string[];
+        /** We request base64 message encoding so we can decode roles ourselves. */
+        message: string | unknown;
+    };
+}
+interface RawSimulateValue {
+    err: unknown;
+    logs: string[] | null;
+    unitsConsumed?: number;
+    accounts?: (RawAccount | null)[];
+    innerInstructions?: RawInnerInstructions[];
+    returnData?: unknown;
+}
+interface RawSimulateResponse {
+    context: {
+        slot: number;
+    };
+    value: RawSimulateValue;
+}
+interface RawAccount {
+    lamports: number;
+    owner: string;
+    data: unknown;
+    executable: boolean;
+    rentEpoch?: number | string;
+    space?: number;
+}
+
+/**
+ * All shared public types & interfaces for solana-explain.
+ *
+ * All numeric on-chain quantities are `bigint`; `ui*` string fields carry
+ * human/decimal formatting so callers never lose precision.
+ */
+
+type Commitment = 'processed' | 'confirmed' | 'finalized';
+interface ExplainOptions {
+    /** RPC URL string OR a pre-built {@link RpcClient}. Required (no default endpoint, to avoid abuse). */
+    rpc: string | RpcClient;
+    /** Commitment level for reads/sim. Default `'confirmed'`. */
+    commitment?: Commitment;
+    /** Extra/override program decoders. Merged over {@link defaultRegistry}. */
+    registry?: ProgramRegistry;
+    /** AbortSignal for cancellation; all RPC calls honor it. */
+    signal?: AbortSignal;
+    /** Per-call timeout in ms. Default `30_000`. */
+    timeoutMs?: number;
+    /** "Whose view" to phrase deltas from. Highlights this account in output. */
+    focusAccount?: string;
+    /** Attach the raw RPC payload under {@link ExplainResult.raw}. */
+    includeRaw?: boolean;
+}
+interface ExplainSignatureOptions extends ExplainOptions {
+    /** Max supported tx version for `getTransaction`. Default `0` (versioned txs). */
+    maxSupportedTransactionVersion?: number;
+}
+interface ExplainTransactionOptions extends ExplainOptions {
+    /** Input encoding. Default `'auto'`. */
+    encoding?: 'base64' | 'base58' | 'auto';
+    /** Let simulation run unsigned. Default `true`. */
+    replaceRecentBlockhash?: boolean;
+    /** Verify signatures during simulation. Default `false`. */
+    sigVerify?: boolean;
+}
+interface ExplainInstructionsOptions extends ExplainOptions {
+    /** Required to assemble a simulatable message. */
+    feePayer: string;
+}
+interface ExplainInstructionAccount {
+    pubkey: string;
+    isSigner: boolean;
+    isWritable: boolean;
+}
+interface ExplainInstruction {
+    programId: string;
+    accounts: ExplainInstructionAccount[];
+    /** Base64 or base58 encoded instruction data, OR a raw byte array. */
+    data: string | Uint8Array | number[];
+}
+interface ExplainResult {
+    source: 'signature' | 'simulation';
+    signature?: string;
+    /** Commitment level the result was read at (signature source only). */
+    commitment?: Commitment;
+    /** `false` if on-chain err or sim err. */
+    success: boolean;
+    error?: {
+        raw: unknown;
+        human: string;
+    };
+    slot?: number;
+    blockTime?: number | null;
+    feeLamports: bigint;
+    computeUnits?: number;
+    feePayer: string;
+    /** One-line plain-English headline. */
+    summary: string;
+    actions: Action[];
+    balanceChanges: BalanceDelta[];
+    instructions: DecodedInstruction[];
+    accountsCreated: AccountCreation[];
+    approvals: Approval[];
+    programsInvoked: ProgramInvocation[];
+    warnings: Warning[];
+    /** Attached only when {@link ExplainOptions.includeRaw}. */
+    raw?: unknown;
+}
+type Action = {
+    kind: 'sol-transfer';
+    from: string;
+    to: string;
+    lamports: bigint;
+    sol: string;
+} | {
+    kind: 'token-transfer';
+    from: string;
+    to: string;
+    mint: string;
+    amount: bigint;
+    uiAmount: string;
+    decimals: number;
+    symbol?: string;
+    tokenProgram: 'spl-token' | 'token-2022';
+} | {
+    kind: 'mint';
+    mint: string;
+    to: string;
+    amount: bigint;
+    uiAmount: string;
+} | {
+    kind: 'burn';
+    mint: string;
+    from: string;
+    amount: bigint;
+    uiAmount: string;
+} | {
+    kind: 'account-created';
+    address: string;
+    owner: string;
+    lamports: bigint;
+    space?: number;
+    as?: 'token-account' | 'mint' | 'ata' | 'system';
+} | {
+    kind: 'approval';
+    owner: string;
+    delegate: string;
+    mint: string;
+    amount: bigint | 'unlimited';
+    revoke?: boolean;
+} | {
+    kind: 'close-account';
+    account: string;
+    destination: string;
+    reclaimedLamports: bigint;
+} | {
+    kind: 'memo';
+    text: string;
+} | {
+    kind: 'compute-budget';
+    unitLimit?: number;
+    unitPriceMicroLamports?: bigint;
+} | {
+    kind: 'program-call';
+    programId: string;
+    program?: string;
+    instruction?: string;
+    note?: string;
+};
+interface BalanceDelta {
+    account: string;
+    asset: {
+        kind: 'SOL';
+    } | {
+        kind: 'token';
+        mint: string;
+        decimals: number;
+        symbol?: string;
+        tokenProgram: string;
+    };
+    pre: bigint;
+    post: bigint;
+    /** Signed: `post - pre`. */
+    delta: bigint;
+    /** Human, e.g. `"-1.5 SOL"`, `"+250 USDC"`. */
+    uiDelta: string;
+    /** For token accounts. */
+    owner?: string;
+}
+interface DecodedInstruction {
+    index: number;
+    programId: string;
+    /** Recognized program name (e.g. `"SPL Token"`). */
+    program?: string;
+    /** Recognized instruction name (e.g. `"transferChecked"`). */
+    type?: string;
+    /** `false` => only programId recognized, or fully unknown. */
+    decoded: boolean;
+    accounts: {
+        pubkey: string;
+        name?: string;
+        isSigner: boolean;
+        isWritable: boolean;
+    }[];
+    /** Stringified bigints to keep the structure JSON-safe. */
+    args?: Record<string, string | number | boolean>;
+    /** CPI tree when meta.innerInstructions present. */
+    inner?: DecodedInstruction[];
+    warning?: string;
+}
+interface AccountCreation {
+    address: string;
+    owner: string;
+    lamports: bigint;
+    space?: number;
+    as?: 'token-account' | 'mint' | 'ata' | 'system';
+}
+interface Approval {
+    owner: string;
+    delegate: string;
+    mint: string;
+    amount: bigint | 'unlimited';
+    revoke?: boolean;
+}
+interface ProgramInvocation {
+    programId: string;
+    /** Recognized name (e.g. `"Jupiter v6"`). */
+    name?: string;
+    count: number;
+}
+interface Warning {
+    code: WarningCode;
+    message: string;
+    instructionIndex?: number;
+}
+type WarningCode = 'unknown-program' | 'partial-decode' | 'ambiguous-amount' | 'token-2022-extension-unparsed' | 'lut-unresolved' | 'simulation-failed' | 'version-skew' | 'inner-instructions-missing';
+/** One instruction as resolved from a wire message, with per-account roles. */
+interface CompiledInstructionView {
+    index: number;
+    programId: string;
+    accounts: {
+        pubkey: string;
+        isSigner: boolean;
+        isWritable: boolean;
+    }[];
+    data: Uint8Array;
+}
+type ProgramKind = 'system' | 'token' | 'token-2022' | 'ata' | 'memo' | 'compute-budget' | 'stake' | 'vote' | 'loader' | 'amm' | 'aggregator' | 'nft' | 'other';
+interface KnownProgramInfo {
+    name: string;
+    kind: ProgramKind;
+}
+/** Result of decoding a single instruction. */
+interface DecodeOutput {
+    program?: string;
+    type?: string;
+    decoded: boolean;
+    /** Stringified bigints / scalars. */
+    args?: Record<string, string | number | boolean>;
+    /** Optional friendly names for the instruction's accounts, by index. */
+    accountNames?: (string | undefined)[];
+    warning?: string;
+    warningCode?: WarningCode;
+    /**
+     * Structured side-effects this decoder is *certain* about (e.g. a decoded
+     * `transferChecked` knows the exact mint and amount). The correlation layer
+     * fuses these with the balance diff.
+     */
+    effects?: DecoderEffect[];
+}
+/** Certain, structured effects emitted by a decoder, consumed by `correlate()`. */
+type DecoderEffect = {
+    kind: 'sol-transfer';
+    from: string;
+    to: string;
+    lamports: bigint;
+} | {
+    kind: 'token-transfer';
+    from: string;
+    to: string;
+    mint?: string;
+    amount: bigint;
+    decimals?: number;
+    tokenProgram: 'spl-token' | 'token-2022';
+} | {
+    kind: 'mint';
+    mint: string;
+    to: string;
+    amount: bigint;
+    decimals?: number;
+} | {
+    kind: 'burn';
+    mint: string;
+    from: string;
+    amount: bigint;
+    decimals?: number;
+} | {
+    kind: 'approval';
+    owner: string;
+    delegate: string;
+    mint: string;
+    amount: bigint | 'unlimited';
+    revoke?: boolean;
+} | {
+    kind: 'close-account';
+    account: string;
+    destination: string;
+} | {
+    kind: 'account-created';
+    address: string;
+    owner: string;
+    lamports?: bigint;
+    space?: number;
+    as?: 'token-account' | 'mint' | 'ata' | 'system';
+} | {
+    kind: 'memo';
+    text: string;
+} | {
+    kind: 'compute-budget';
+    unitLimit?: number;
+    unitPriceMicroLamports?: bigint;
+} | {
+    kind: 'sync-native';
+    account: string;
+};
+interface ProgramDecoder {
+    /** Program ID(s) this decoder handles. */
+    programId: string;
+    /** Friendly program name. */
+    name: string;
+    kind: ProgramKind;
+    /** Decode an instruction. MUST NOT throw; return `{ decoded: false }` on failure. */
+    decode(ix: CompiledInstructionView): DecodeOutput;
+}
+interface ProgramRegistry {
+    get(programId: string): ProgramDecoder | undefined;
+    has(programId: string): boolean;
+    /** All registered decoders. */
+    list(): ProgramDecoder[];
+    /** Return a new registry with `decoders` merged over this one. */
+    merge(decoders: ProgramDecoder[]): ProgramRegistry;
+}
+interface BalanceSnapshot {
+    /** Account keys in message order. */
+    accountKeys: string[];
+    /** Lamport balance per account key index. */
+    lamports: bigint[];
+    /** Token balances keyed loosely; matched by account address + mint. */
+    tokenBalances: TokenBalanceEntry[];
+}
+interface TokenBalanceEntry {
+    /** Token account address. */
+    account: string;
+    mint: string;
+    owner?: string;
+    amount: bigint;
+    decimals: number;
+    /** Owning token program ('spl-token' | 'token-2022' | raw id). */
+    tokenProgram: string;
+    symbol?: string;
+}
+interface ExplainInput {
+    source: 'signature' | 'simulation';
+    signature?: string;
+    feePayer: string;
+    success: boolean;
+    error?: {
+        raw: unknown;
+        human: string;
+    };
+    slot?: number;
+    blockTime?: number | null;
+    feeLamports: bigint;
+    computeUnits?: number;
+    pre: BalanceSnapshot;
+    post: BalanceSnapshot;
+    instructions: CompiledInstructionView[];
+    /** Inner instructions per top-level index, when available. */
+    innerInstructions?: {
+        index: number;
+        instructions: CompiledInstructionView[];
+    }[];
+    registry: ProgramRegistry;
+    focusAccount?: string;
+    warnings?: Warning[];
+    raw?: unknown;
+    includeRaw?: boolean;
+}
+interface RenderOptions {
+    /** Force-enable ANSI color. When omitted, the renderer leaves output plain. */
+    color?: boolean;
+    /** Show every instruction including the inner/CPI tree + raw args. */
+    verbose?: boolean;
+    /** Only print the summary line. */
+    quiet?: boolean;
+}
+
+export type { AccountCreation as A, BalanceSnapshot as B, Commitment as C, DecodeOutput as D, ExplainInput as E, GetAccountsOpts as G, KnownProgramInfo as K, ProgramDecoder as P, RpcClient as R, SimulateOpts as S, TokenBalanceEntry as T, Warning as W, ExplainResult as a, ExplainInstruction as b, ExplainOptions as c, ExplainInstructionsOptions as d, ExplainSignatureOptions as e, ExplainTransactionOptions as f, BalanceDelta as g, Action as h, Approval as i, CompiledInstructionView as j, DecodedInstruction as k, DecoderEffect as l, ExplainInstructionAccount as m, GetTransactionOpts as n, ProgramInvocation as o, ProgramKind as p, ProgramRegistry as q, RawAccount as r, RawSimulateResponse as s, RawTransactionResponse as t, RenderOptions as u, WarningCode as v };

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@vtx-labs/solana-explain",
+  "version": "0.1.0",
+  "description": "Turn any Solana transaction signature, raw/base64 transaction, or unsigned instruction set into a plain-English \"what this actually does\" report — net balance deltas, transfers, account creations, approvals, and program invocations. No IDLs required.",
+  "type": "module",
+  "license": "MIT",
+  "author": "VTX Labs (https://vtxlabs.dev)",
+  "homepage": "https://github.com/VTX-Labs/solana-explain#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/VTX-Labs/solana-explain.git"
+  },
+  "bugs": {
+    "url": "https://github.com/VTX-Labs/solana-explain/issues"
+  },
+  "keywords": [
+    "solana",
+    "transaction",
+    "explain",
+    "decode",
+    "spl-token",
+    "token-2022",
+    "simulate",
+    "balance-diff",
+    "web3",
+    "cli",
+    "typescript"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "solana-explain": "dist/cli/index.js",
+    "sx": "dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./programs": {
+      "types": "./dist/programs.d.ts",
+      "import": "./dist/programs.js"
+    },
+    "./render": {
+      "types": "./dist/render.d.ts",
+      "import": "./dist/render.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/cli/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "pnpm typecheck && pnpm test && pnpm build"
+  },
+  "dependencies": {
+    "bs58": "^6.0.0"
+  },
+  "peerDependencies": {
+    "@solana/web3.js": "^1.95.0 || ^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@solana/web3.js": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsup": "^8.2.0",
+    "tsx": "^4.16.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "packageManager": "pnpm@10.6.5"
+}