sol-parser-sdk-nodejs 0.3.0

package/dist/core/dex_event.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.metadataForDexEvent = metadataForDexEvent;
+exports.defaultPubkey = defaultPubkey;
+const ZERO = "11111111111111111111111111111111";
+function metadataForDexEvent(ev) {
+    if ("Error" in ev)
+        return null;
+    const inner = Object.values(ev)[0];
+    return inner?.metadata ?? null;
+}
+function defaultPubkey() {
+    return ZERO;
+}

package/dist/core/error.d.ts

@@ -0,0 +1,43 @@
+/** 解析错误（RPC / 日志等路径共用） */
+export type ParseError = {
+    kind: "InsufficientData";
+    expected: number;
+    actual: number;
+    context: string;
+} | {
+    kind: "InvalidDiscriminator";
+    expected?: Uint8Array;
+    found: Uint8Array;
+    context: string;
+} | {
+    kind: "Base64DecodeError";
+    context: string;
+} | {
+    kind: "InsufficientAccounts";
+    expected: number;
+    actual: number;
+    context: string;
+} | {
+    kind: "InvalidLogFormat";
+    reason: string;
+} | {
+    kind: "InvalidInstructionFormat";
+    reason: string;
+} | {
+    kind: "UnknownEventType";
+    discriminator: Uint8Array;
+    program: string;
+} | {
+    kind: "UnsupportedProgram";
+    program_id: string;
+} | {
+    kind: "RpcError";
+    message: string;
+} | {
+    kind: "ConversionError";
+    message: string;
+} | {
+    kind: "MissingField";
+    field: string;
+};
+export declare function formatParseError(e: ParseError): string;

package/dist/core/error.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatParseError = formatParseError;
+function formatParseError(e) {
+    switch (e.kind) {
+        case "RpcError":
+        case "ConversionError":
+            return e.message;
+        case "MissingField":
+            return `缺少字段: ${e.field}`;
+        case "InsufficientData":
+            return `数据长度不足: 需要 ${e.expected} 字节，实际 ${e.actual} (${e.context})`;
+        default:
+            return JSON.stringify(e);
+    }
+}

package/dist/core/json_utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `JSON.stringify` 默认无法处理 `bigint`。
+ * 下列工具将树中所有 `bigint` 转为十进制字符串，便于与 Go `DexEvent` / Python 字典经 JSON 输出对齐。
+ */
+/** 供 `JSON.stringify(value, replacer)` 使用 */
+export declare function bigintToJsonReplacer(_key: string, value: unknown): unknown;
+/** 将含 `bigint` 的值序列化为 JSON 字符串（`DexEvent`、元数据等） */
+export declare function dexEventToJsonString(value: unknown, space?: string | number): string;

package/dist/core/json_utils.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * `JSON.stringify` 默认无法处理 `bigint`。
+ * 下列工具将树中所有 `bigint` 转为十进制字符串，便于与 Go `DexEvent` / Python 字典经 JSON 输出对齐。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bigintToJsonReplacer = bigintToJsonReplacer;
+exports.dexEventToJsonString = dexEventToJsonString;
+/** 供 `JSON.stringify(value, replacer)` 使用 */
+function bigintToJsonReplacer(_key, value) {
+    if (typeof value === "bigint")
+        return value.toString();
+    return value;
+}
+/** 将含 `bigint` 的值序列化为 JSON 字符串（`DexEvent`、元数据等） */
+function dexEventToJsonString(value, space) {
+    return JSON.stringify(value, bigintToJsonReplacer, space);
+}

package/dist/core/metadata.d.ts

@@ -0,0 +1,10 @@
+/** 事件元数据（signature 为 Base58 字符串） */
+export interface EventMetadata {
+    signature: string;
+    slot: number;
+    tx_index: number;
+    block_time_us: number;
+    grpc_recv_us: number;
+    recent_blockhash?: string;
+}
+export declare function makeMetadata(signature: string, slot: number, txIndex: number, blockTimeUs: number | undefined, grpcRecvUs: number, recentBlockhash?: string): EventMetadata;

package/dist/core/metadata.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeMetadata = makeMetadata;
+function makeMetadata(signature, slot, txIndex, blockTimeUs, grpcRecvUs, recentBlockhash) {
+    return {
+        signature,
+        slot,
+        tx_index: txIndex,
+        block_time_us: blockTimeUs ?? 0,
+        grpc_recv_us: grpcRecvUs,
+        recent_blockhash: recentBlockhash,
+    };
+}

package/dist/core/rpc_invoke_map.d.ts

@@ -0,0 +1,23 @@
+import { Message, MessageV0, PublicKey, type ConfirmedTransactionMeta } from "@solana/web3.js";
+export type InvokePair = readonly [outerIndex: number, innerIndex: number];
+/**
+ * 将账户表项转为 Base58（与 `PublicKey.toBase58()` 一致）。
+ * 兼容：已是地址字符串、标准 `PublicKey`、以及多份 `@solana/web3.js` 副本导致 `instanceof` 失效的情况。
+ */
+export declare function accountKeyToBase58(account: unknown): string | undefined;
+export declare function isCompiledVersionedMessage(msg: unknown): msg is Message | MessageV0;
+export declare function getAccountKeyResolver(message: Message | MessageV0, meta: ConfirmedTransactionMeta | null): {
+    get(i: number): PublicKey | undefined;
+    length: number;
+};
+export declare function decodeIxData(data: Uint8Array | string): Uint8Array;
+export declare function buildProgramInvokesMap(message: Message | MessageV0, meta: ConfirmedTransactionMeta | null, resolver: {
+    get(i: number): PublicKey | undefined;
+}): Map<string, InvokePair[]>;
+export declare function instructionAccountIndices(message: Message | MessageV0, meta: ConfirmedTransactionMeta | null, invoke: InvokePair): number[] | null;
+export declare function countInstructionAccounts(message: Message | MessageV0, meta: ConfirmedTransactionMeta | null, invoke: InvokePair): number;
+export declare function findMaxAccountsInvoke(programId: string, invokes: Map<string, InvokePair[]>, message: Message | MessageV0, meta: ConfirmedTransactionMeta | null): InvokePair | null;
+export declare function makeInvokeAccountGetter(resolver: {
+    get(i: number): PublicKey | undefined;
+}, invoke: InvokePair, message: Message | MessageV0, meta: ConfirmedTransactionMeta | null): ((i: number) => string) | null;
+export declare function getInstructionDataBytes(message: Message | MessageV0, meta: ConfirmedTransactionMeta | null, invoke: InvokePair): Uint8Array | null;

package/dist/core/rpc_invoke_map.js

@@ -0,0 +1,157 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.accountKeyToBase58 = accountKeyToBase58;
+exports.isCompiledVersionedMessage = isCompiledVersionedMessage;
+exports.getAccountKeyResolver = getAccountKeyResolver;
+exports.decodeIxData = decodeIxData;
+exports.buildProgramInvokesMap = buildProgramInvokesMap;
+exports.instructionAccountIndices = instructionAccountIndices;
+exports.countInstructionAccounts = countInstructionAccounts;
+exports.findMaxAccountsInvoke = findMaxAccountsInvoke;
+exports.makeInvokeAccountGetter = makeInvokeAccountGetter;
+exports.getInstructionDataBytes = getInstructionDataBytes;
+/**
+ * 从 web3.js 交易构建「程序 → 指令调用 (outer, inner)」映射，供 RPC 路径账户填充。
+ * 构造 `program_invokes`（按程序 ID 聚合 invoke，选账户数最多的那次）。
+ */
+const bs58_1 = __importDefault(require("bs58"));
+const web3_js_1 = require("@solana/web3.js");
+/**
+ * 将账户表项转为 Base58（与 `PublicKey.toBase58()` 一致）。
+ * 兼容：已是地址字符串、标准 `PublicKey`、以及多份 `@solana/web3.js` 副本导致 `instanceof` 失效的情况。
+ */
+function accountKeyToBase58(account) {
+    if (account === undefined || account === null)
+        return undefined;
+    if (typeof account === "string") {
+        try {
+            return new web3_js_1.PublicKey(account).toBase58();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const maybeFn = account.toBase58;
+    if (typeof maybeFn === "function") {
+        try {
+            return maybeFn.call(account);
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    try {
+        return new web3_js_1.PublicKey(account).toBase58();
+    }
+    catch {
+        return undefined;
+    }
+}
+function isCompiledVersionedMessage(msg) {
+    if (msg === null || typeof msg !== "object")
+        return false;
+    return ("compiledInstructions" in msg &&
+        Array.isArray(msg.compiledInstructions) &&
+        typeof msg.getAccountKeys === "function");
+}
+function getAccountKeyResolver(message, meta) {
+    if (message.version === "legacy") {
+        const keys = message.getAccountKeys();
+        return { get: (i) => keys.get(i), length: keys.length };
+    }
+    const loaded = meta?.loadedAddresses;
+    const keys = message.getAccountKeys(loaded ? { accountKeysFromLookups: loaded } : undefined);
+    return { get: (i) => keys.get(i), length: keys.length };
+}
+function decodeIxData(data) {
+    if (typeof data === "string")
+        return Uint8Array.from(bs58_1.default.decode(data));
+    if (data instanceof Uint8Array)
+        return data;
+    return new Uint8Array(data);
+}
+function buildProgramInvokesMap(message, meta, resolver) {
+    const m = new Map();
+    const push = (pid, inv) => {
+        const arr = m.get(pid);
+        if (arr)
+            arr.push(inv);
+        else
+            m.set(pid, [inv]);
+    };
+    message.compiledInstructions.forEach((ix, idx) => {
+        const pidx = Number(ix.programIdIndex);
+        const pk = accountKeyToBase58(resolver.get(pidx));
+        if (pk)
+            push(pk, [idx, -1]);
+    });
+    for (const group of meta?.innerInstructions ?? []) {
+        const outer = group.index;
+        group.instructions.forEach((raw, j) => {
+            const ix = raw;
+            const pidx = Number(ix.programIdIndex);
+            const pk = accountKeyToBase58(resolver.get(pidx));
+            if (pk)
+                push(pk, [outer, j]);
+        });
+    }
+    return m;
+}
+function instructionAccountIndices(message, meta, invoke) {
+    const [outerIdx, innerIdx] = invoke;
+    if (innerIdx < 0) {
+        const ix = message.compiledInstructions[outerIdx];
+        return ix ? [...ix.accountKeyIndexes] : null;
+    }
+    const g = meta?.innerInstructions?.find((x) => x.index === outerIdx);
+    const ix = g?.instructions[innerIdx];
+    return ix ? [...ix.accounts] : null;
+}
+function countInstructionAccounts(message, meta, invoke) {
+    return instructionAccountIndices(message, meta, invoke)?.length ?? 0;
+}
+function findMaxAccountsInvoke(programId, invokes, message, meta) {
+    const list = invokes.get(programId);
+    if (!list?.length)
+        return null;
+    let best = list[0];
+    let bestN = countInstructionAccounts(message, meta, best);
+    for (let i = 1; i < list.length; i++) {
+        const inv = list[i];
+        const n = countInstructionAccounts(message, meta, inv);
+        if (n > bestN) {
+            best = inv;
+            bestN = n;
+        }
+    }
+    return best;
+}
+const DEFAULT_PK = web3_js_1.PublicKey.default.toBase58();
+function makeInvokeAccountGetter(resolver, invoke, message, meta) {
+    const indices = instructionAccountIndices(message, meta, invoke);
+    if (!indices)
+        return null;
+    return (i) => {
+        const ai = indices[i];
+        if (ai === undefined)
+            return DEFAULT_PK;
+        return accountKeyToBase58(resolver.get(ai)) ?? DEFAULT_PK;
+    };
+}
+function getInstructionDataBytes(message, meta, invoke) {
+    const [outerIdx, innerIdx] = invoke;
+    if (innerIdx < 0) {
+        const ix = message.compiledInstructions[outerIdx];
+        if (!ix)
+            return null;
+        return decodeIxData(ix.data);
+    }
+    const g = meta?.innerInstructions?.find((x) => x.index === outerIdx);
+    const ix = g?.instructions[innerIdx];
+    if (!ix)
+        return null;
+    return decodeIxData(ix.data);
+}

package/dist/core/unified_parser.d.ts

@@ -0,0 +1,19 @@
+import type { DexEvent } from "./dex_event.js";
+import type { EventTypeFilter } from "../grpc/types.js";
+import { nowUs } from "./clock.js";
+export type EventListener = {
+    onDexEvent: (event: DexEvent) => void;
+};
+export type StreamingEventListener = {
+    onDexEventStreaming: (event: DexEvent) => void;
+};
+/** 从交易解析事件；当前主路径为日志解析 */
+export declare function parseTransactionEvents(_instructionData: Uint8Array, _accounts: string[], logs: string[], signature: string, slot: number, _txIndex: number, blockTimeUs: number | undefined, _programId: string): DexEvent[];
+export declare function parseLogsOnly(logs: string[], signature: string, slot: number, blockTimeUs: number | undefined): DexEvent[];
+export declare function parseTransactionWithListener(instructionData: Uint8Array, accounts: string[], logs: string[], signature: string, slot: number, txIndex: number, blockTimeUs: number | undefined, programId: string, listener: EventListener): void;
+export declare function parseTransactionEventsStreaming(_instructionData: Uint8Array, _accounts: string[], logs: string[], signature: string, slot: number, _txIndex: number, blockTimeUs: number | undefined, _programId: string, callback: (event: DexEvent) => void): void;
+export declare function parseLogsStreaming(logs: string[], signature: string, slot: number, blockTimeUs: number | undefined, callback: (event: DexEvent) => void): void;
+export declare function parseTransactionWithStreamingListener(instructionData: Uint8Array, accounts: string[], logs: string[], signature: string, slot: number, txIndex: number, blockTimeUs: number | undefined, programId: string, listener: StreamingEventListener): void;
+/** 带完整 gRPC 元数据字段的日志解析 */
+export declare function parseLog(log: string, signature: string, slot: number, txIndex: number, blockTimeUs: number | undefined, grpcRecvUs: number, eventTypeFilter: EventTypeFilter | undefined, isCreatedBuy: boolean, recentBlockhash?: Uint8Array): DexEvent | null;
+export { nowUs };

package/dist/core/unified_parser.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nowUs = void 0;
+exports.parseTransactionEvents = parseTransactionEvents;
+exports.parseLogsOnly = parseLogsOnly;
+exports.parseTransactionWithListener = parseTransactionWithListener;
+exports.parseTransactionEventsStreaming = parseTransactionEventsStreaming;
+exports.parseLogsStreaming = parseLogsStreaming;
+exports.parseTransactionWithStreamingListener = parseTransactionWithStreamingListener;
+exports.parseLog = parseLog;
+const optimized_matcher_js_1 = require("../logs/optimized_matcher.js");
+const clock_js_1 = require("./clock.js");
+Object.defineProperty(exports, "nowUs", { enumerable: true, get: function () { return clock_js_1.nowUs; } });
+/** 从交易解析事件；当前主路径为日志解析 */
+function parseTransactionEvents(_instructionData, _accounts, logs, signature, slot, _txIndex, blockTimeUs, _programId) {
+    return parseLogsOnly(logs, signature, slot, blockTimeUs);
+}
+function parseLogsOnly(logs, signature, slot, blockTimeUs) {
+    const out = [];
+    for (const log of logs) {
+        const e = (0, optimized_matcher_js_1.parseLogUnified)(log, signature, slot, blockTimeUs);
+        if (e)
+            out.push(e);
+    }
+    return out;
+}
+function parseTransactionWithListener(instructionData, accounts, logs, signature, slot, txIndex, blockTimeUs, programId, listener) {
+    for (const e of parseTransactionEvents(instructionData, accounts, logs, signature, slot, txIndex, blockTimeUs, programId)) {
+        listener.onDexEvent(e);
+    }
+}
+function parseTransactionEventsStreaming(_instructionData, _accounts, logs, signature, slot, _txIndex, blockTimeUs, _programId, callback) {
+    parseLogsStreaming(logs, signature, slot, blockTimeUs, callback);
+}
+function parseLogsStreaming(logs, signature, slot, blockTimeUs, callback) {
+    for (const log of logs) {
+        const e = (0, optimized_matcher_js_1.parseLogUnified)(log, signature, slot, blockTimeUs);
+        if (e)
+            callback(e);
+    }
+}
+function parseTransactionWithStreamingListener(instructionData, accounts, logs, signature, slot, txIndex, blockTimeUs, programId, listener) {
+    parseTransactionEventsStreaming(instructionData, accounts, logs, signature, slot, txIndex, blockTimeUs, programId, (ev) => listener.onDexEventStreaming(ev));
+}
+/** 带完整 gRPC 元数据字段的日志解析 */
+function parseLog(log, signature, slot, txIndex, blockTimeUs, grpcRecvUs, eventTypeFilter, isCreatedBuy, recentBlockhash) {
+    return (0, optimized_matcher_js_1.parseLogOptimized)(log, signature, slot, txIndex, blockTimeUs, grpcRecvUs, eventTypeFilter, isCreatedBuy, recentBlockhash);
+}

package/dist/grpc/client.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Yellowstone gRPC 客户端实现 - 基于 @triton-one/yellowstone-grpc
+ */
+import { CommitmentLevel } from "@triton-one/yellowstone-grpc";
+import { type ClientConfig, type TransactionFilter, type SubscribeCallbacks } from "./types.js";
+export { SubscribeCallbacks };
+/** Yellowstone gRPC 客户端包装器 */
+export declare class YellowstoneGrpc {
+    private client;
+    private config;
+    private connected;
+    private subscribers;
+    constructor(endpoint: string, xToken: string, config?: ClientConfig);
+    /** 连接到 gRPC 服务器 */
+    connect(): Promise<void>;
+    /** 断开连接 */
+    disconnect(): Promise<void>;
+    /** 检查是否已连接 */
+    isConnected(): boolean;
+    /** 获取客户端配置 */
+    getConfig(): ClientConfig;
+    /** 转换 SlotStatus */
+    private convertSlotStatus;
+    /** 转换订阅更新 */
+    private convertUpdate;
+    /** 订阅交易 */
+    subscribeTransactions(filter: TransactionFilter, callbacks: SubscribeCallbacks): Promise<{
+        id: string;
+        cancel: () => void;
+    }>;
+    /** 取消订阅 */
+    unsubscribe(subId: string): void;
+    /** 获取最新区块哈希 */
+    getLatestBlockhash(commitment?: CommitmentLevel): Promise<{
+        slot: number;
+        blockhash: string;
+        lastValidBlockHeight: number;
+    }>;
+    /** 获取区块高度 */
+    getBlockHeight(commitment?: CommitmentLevel): Promise<number>;
+    /** 获取当前 Slot */
+    getSlot(commitment?: CommitmentLevel): Promise<number>;
+    /** 获取服务器版本 */
+    getVersion(): Promise<string>;
+    /** 验证区块哈希是否有效 */
+    isBlockhashValid(blockhash: string, commitment?: CommitmentLevel): Promise<{
+        slot: number;
+        valid: boolean;
+    }>;
+    /** 发送 Ping 请求 */
+    ping(count: number): Promise<number>;
+}