tx-indexer 0.1.0

package/README.md

@@ -0,0 +1,81 @@
+# tx-indexer SDK
+
+Solana transaction indexer and classification SDK.
+
+## Installation
+
+```bash
+bun add tx-indexer
+# or
+npm install tx-indexer
+```
+
+## Quick Start
+
+```typescript
+import { createIndexer } from "tx-indexer";
+
+const indexer = createIndexer({ 
+  rpcUrl: "https://api.mainnet-beta.solana.com" 
+});
+
+// Get wallet balance
+const balance = await indexer.getBalance("YourWalletAddress...");
+
+// Get classified transactions
+const txs = await indexer.getTransactions("YourWalletAddress...", {
+  limit: 10,
+  filterSpam: true
+});
+
+// Get single transaction
+const tx = await indexer.getTransaction("signature...", "walletAddress...");
+```
+
+## Bundle Size
+
+The SDK is lightweight and tree-shakeable:
+
+| Import | Size (minified + brotli) |
+|--------|----------|
+| Full SDK | ~20 KB |
+| `createIndexer` only | ~20 KB |
+| `classifyTransaction` | ~3 KB |
+| `fetchTransaction` | ~4 KB |
+| `transactionToLegs` | ~4 KB |
+
+Check current sizes:
+```bash
+bun run size
+```
+
+Analyze why a bundle is large:
+```bash
+bun run size:why
+```
+
+## Documentation
+
+See the main [project README](../../README.md) for:
+- Complete API reference
+- Architecture details
+- Exported functions
+- Usage examples
+
+## Development
+
+```bash
+# Type check
+bun run check-types
+
+# Check bundle size
+bun run size
+
+# Analyze bundle composition
+bun run size:why
+```
+
+## License
+
+MIT
+

package/dist/classification.types-w82k4B1F.d.ts

@@ -0,0 +1,212 @@
+import { z } from 'zod';
+import { Signature } from '@solana/kit';
+
+declare const TxDirectionSchema: z.ZodEnum<{
+    incoming: "incoming";
+    outgoing: "outgoing";
+    self: "self";
+    neutral: "neutral";
+}>;
+declare const TxPrimaryTypeSchema: z.ZodEnum<{
+    transfer: "transfer";
+    swap: "swap";
+    nft_purchase: "nft_purchase";
+    nft_sale: "nft_sale";
+    nft_mint: "nft_mint";
+    stake_deposit: "stake_deposit";
+    stake_withdraw: "stake_withdraw";
+    token_deposit: "token_deposit";
+    token_withdraw: "token_withdraw";
+    airdrop: "airdrop";
+    bridge_in: "bridge_in";
+    bridge_out: "bridge_out";
+    reward: "reward";
+    fee_only: "fee_only";
+    other: "other";
+}>;
+declare const TxCategorySchema: z.ZodEnum<{
+    transfer: "transfer";
+    other: "other";
+    fee: "fee";
+    income: "income";
+    expense: "expense";
+    investment: "investment";
+    savings: "savings";
+    refund: "refund";
+    tax: "tax";
+}>;
+declare const TokenBalanceSchema: z.ZodObject<{
+    accountIndex: z.ZodNumber;
+    mint: z.ZodString;
+    owner: z.ZodOptional<z.ZodString>;
+    programId: z.ZodOptional<z.ZodString>;
+    uiTokenAmount: z.ZodObject<{
+        amount: z.ZodString;
+        decimals: z.ZodNumber;
+        uiAmountString: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+declare const RawTransactionSchema: z.ZodObject<{
+    signature: z.ZodCustom<Signature, Signature>;
+    slot: z.ZodUnion<readonly [z.ZodNumber, z.ZodBigInt]>;
+    blockTime: z.ZodNullable<z.ZodUnion<readonly [z.ZodNumber, z.ZodBigInt]>>;
+    err: z.ZodNullable<z.ZodAny>;
+    programIds: z.ZodArray<z.ZodString>;
+    protocol: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        iconUrl: z.ZodOptional<z.ZodURL>;
+        programIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        url: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strip>>;
+    preTokenBalances: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        accountIndex: z.ZodNumber;
+        mint: z.ZodString;
+        owner: z.ZodOptional<z.ZodString>;
+        programId: z.ZodOptional<z.ZodString>;
+        uiTokenAmount: z.ZodObject<{
+            amount: z.ZodString;
+            decimals: z.ZodNumber;
+            uiAmountString: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>>>;
+    postTokenBalances: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        accountIndex: z.ZodNumber;
+        mint: z.ZodString;
+        owner: z.ZodOptional<z.ZodString>;
+        programId: z.ZodOptional<z.ZodString>;
+        uiTokenAmount: z.ZodObject<{
+            amount: z.ZodString;
+            decimals: z.ZodNumber;
+            uiAmountString: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>>>;
+    preBalances: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodBigInt]>>>;
+    postBalances: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodBigInt]>>>;
+    accountKeys: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    memo: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+declare const TxLegSideSchema: z.ZodEnum<{
+    debit: "debit";
+    credit: "credit";
+}>;
+declare const TxLegRoleSchema: z.ZodEnum<{
+    unknown: "unknown";
+    reward: "reward";
+    sent: "sent";
+    received: "received";
+    fee: "fee";
+    protocol_deposit: "protocol_deposit";
+    protocol_withdraw: "protocol_withdraw";
+    principal: "principal";
+    interest: "interest";
+}>;
+declare const TxLegSchema: z.ZodObject<{
+    accountId: z.ZodString;
+    side: z.ZodEnum<{
+        debit: "debit";
+        credit: "credit";
+    }>;
+    amount: z.ZodCustom<{
+        token: {
+            mint: string;
+            symbol: string;
+            decimals: number;
+            name?: string | undefined;
+            logoURI?: string | undefined;
+        };
+        amountRaw: string;
+        amountUi: number;
+        fiat?: {
+            currency: "USD" | "EUR";
+            amount: number;
+            pricePerUnit: number;
+            at: Date;
+            source?: string | undefined;
+        } | undefined;
+    }, {
+        token: {
+            mint: string;
+            symbol: string;
+            decimals: number;
+            name?: string | undefined;
+            logoURI?: string | undefined;
+        };
+        amountRaw: string;
+        amountUi: number;
+        fiat?: {
+            currency: "USD" | "EUR";
+            amount: number;
+            pricePerUnit: number;
+            at: Date;
+            source?: string | undefined;
+        } | undefined;
+    }>;
+    role: z.ZodEnum<{
+        unknown: "unknown";
+        reward: "reward";
+        sent: "sent";
+        received: "received";
+        fee: "fee";
+        protocol_deposit: "protocol_deposit";
+        protocol_withdraw: "protocol_withdraw";
+        principal: "principal";
+        interest: "interest";
+    }>;
+}, z.core.$strip>;
+type TxDirection = z.infer<typeof TxDirectionSchema>;
+type TxPrimaryType = z.infer<typeof TxPrimaryTypeSchema>;
+type TxCategory = z.infer<typeof TxCategorySchema>;
+type TokenBalance = z.infer<typeof TokenBalanceSchema>;
+type RawTransaction = z.infer<typeof RawTransactionSchema>;
+type TxLegSide = z.infer<typeof TxLegSideSchema>;
+type TxLegRole = z.infer<typeof TxLegRoleSchema>;
+type TxLeg = z.infer<typeof TxLegSchema>;
+
+declare const TransactionClassificationSchema: z.ZodObject<{
+    primaryType: z.ZodEnum<{
+        transfer: "transfer";
+        swap: "swap";
+        nft_purchase: "nft_purchase";
+        nft_sale: "nft_sale";
+        nft_mint: "nft_mint";
+        stake_deposit: "stake_deposit";
+        stake_withdraw: "stake_withdraw";
+        token_deposit: "token_deposit";
+        token_withdraw: "token_withdraw";
+        airdrop: "airdrop";
+        bridge_in: "bridge_in";
+        bridge_out: "bridge_out";
+        reward: "reward";
+        fee_only: "fee_only";
+        other: "other";
+    }>;
+    direction: z.ZodEnum<{
+        incoming: "incoming";
+        outgoing: "outgoing";
+        self: "self";
+        neutral: "neutral";
+    }>;
+    primaryAmount: z.ZodNullable<z.ZodAny>;
+    secondaryAmount: z.ZodOptional<z.ZodNullable<z.ZodAny>>;
+    counterparty: z.ZodNullable<z.ZodObject<{
+        type: z.ZodEnum<{
+            unknown: "unknown";
+            protocol: "protocol";
+            person: "person";
+            merchant: "merchant";
+            exchange: "exchange";
+            own_wallet: "own_wallet";
+        }>;
+        address: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        avatarUrl: z.ZodOptional<z.ZodURL>;
+        refCode: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    confidence: z.ZodNumber;
+    isRelevant: z.ZodOptional<z.ZodBoolean>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.core.$strip>;
+type TransactionClassification = z.infer<typeof TransactionClassificationSchema>;
+
+export { type RawTransaction as R, type TxLeg as T, type TransactionClassification as a, TxDirectionSchema as b, TxPrimaryTypeSchema as c, TxCategorySchema as d, TokenBalanceSchema as e, RawTransactionSchema as f, TxLegSchema as g, type TxDirection as h, type TxPrimaryType as i, type TxCategory as j, type TokenBalance as k, type TxLegSide as l, type TxLegRole as m, TransactionClassificationSchema as n };

package/dist/client-BS9KUBU7.d.ts

@@ -0,0 +1,257 @@
+import { Rpc, GetBalanceApi, GetTokenAccountsByOwnerApi, GetSignaturesForAddressApi, GetTransactionApi, RpcSubscriptions, Address, Signature } from '@solana/kit';
+import { R as RawTransaction, T as TxLeg, a as TransactionClassification } from './classification.types-w82k4B1F.js';
+
+/**
+ * Union type of all RPC APIs used by the transaction indexer.
+ *
+ * This ensures type safety when calling RPC methods while maintaining
+ * flexibility for the complete indexer API surface.
+ */
+type IndexerRpcApi = GetBalanceApi & GetTokenAccountsByOwnerApi & GetSignaturesForAddressApi & GetTransactionApi;
+interface SolanaClient {
+    rpc: Rpc<IndexerRpcApi>;
+    rpcSubscriptions: RpcSubscriptions<any>;
+}
+/**
+ * Creates a Solana RPC client with both regular RPC and WebSocket subscriptions.
+ *
+ * @param rpcUrl - HTTP RPC endpoint URL
+ * @param wsUrl - Optional WebSocket URL (defaults to rpcUrl with wss:// protocol)
+ */
+declare function createSolanaClient(rpcUrl: string, wsUrl?: string): SolanaClient;
+/**
+ * Parses and validates a Solana address string.
+ *
+ * @param addr - Base58-encoded Solana address
+ */
+declare function parseAddress(addr: string): Address;
+/**
+ * Parses and validates a Solana transaction signature string.
+ *
+ * @param sig - Base58-encoded transaction signature
+ */
+declare function parseSignature(sig: string): Signature;
+
+interface FetchTransactionsConfig {
+    limit?: number;
+    before?: Signature;
+    until?: Signature;
+}
+/**
+ * Fetches transaction signatures for a wallet address.
+ *
+ * @param rpc - Solana RPC client
+ * @param walletAddress - Wallet address to fetch signatures for
+ * @param config - Optional pagination and limit configuration
+ * @returns Array of raw transactions with basic metadata only
+ */
+declare function fetchWalletSignatures(rpc: Rpc<GetSignaturesForAddressApi>, walletAddress: Address, config?: FetchTransactionsConfig): Promise<RawTransaction[]>;
+/**
+ * Fetches a single transaction with full details including program IDs.
+ *
+ * @param rpc - Solana RPC client
+ * @param signature - Transaction signature
+ * @param commitment - Commitment level for fetching
+ * @returns Full raw transaction with program IDs
+ */
+declare function fetchTransaction(rpc: Rpc<GetTransactionApi>, signature: Signature, commitment?: "confirmed" | "finalized"): Promise<RawTransaction | null>;
+/**
+ * Fetches multiple transactions in parallel.
+ *
+ * @param rpc - Solana RPC client
+ * @param signatures - Array of transaction signatures
+ * @param commitment - Commitment level for fetching
+ * @returns Array of full raw transactions (nulls filtered out)
+ */
+declare function fetchTransactionsBatch(rpc: Rpc<GetTransactionApi>, signatures: Signature[], commitment?: "confirmed" | "finalized"): Promise<RawTransaction[]>;
+
+/**
+ * Converts a raw Solana transaction into a double-entry accounting ledger.
+ *
+ * Creates TxLeg entries for all SOL and token balance changes, automatically
+ * detecting and accounting for network fees. Each leg represents a debit or credit
+ * for a specific account and token, enabling transaction classification and validation.
+ *
+ * @param tx - Raw transaction data with balance changes
+ * @param walletAddress - Optional wallet address for perspective. When provided, legs are tagged
+ *   as "wallet:" or "external:". When omitted (observer mode), all legs are tagged as "external:".
+ * @returns Array of transaction legs representing all balance movements
+ */
+declare function transactionToLegs(tx: RawTransaction, walletAddress?: Address): TxLeg[];
+
+interface SpamFilterConfig {
+    minSolAmount?: number;
+    minTokenAmountUsd?: number;
+    minConfidence?: number;
+    allowFailed?: boolean;
+}
+/**
+ * Determines if a transaction should be filtered as spam or dust.
+ *
+ * A transaction is considered spam if it:
+ * - Failed (and allowFailed is false)
+ * - Has low classification confidence
+ * - Is not relevant to the wallet
+ * - Involves dust amounts below configured thresholds
+ *
+ * @param tx - Raw transaction data
+ * @param classification - Transaction classification result
+ * @param config - Optional spam filter configuration (uses defaults if omitted)
+ * @returns True if the transaction should be filtered as spam
+ */
+declare function isSpamTransaction(tx: RawTransaction, classification: TransactionClassification, config?: SpamFilterConfig): boolean;
+/**
+ * Filters an array of transactions to remove spam and dust transactions.
+ *
+ * Applies spam detection criteria to each transaction while preserving
+ * additional properties in the returned array items.
+ *
+ * @param transactions - Array of transaction objects with tx and classification
+ * @param config - Optional spam filter configuration
+ * @returns Filtered array with spam transactions removed
+ */
+declare function filterSpamTransactions<T extends {
+    tx: RawTransaction;
+    classification: TransactionClassification;
+}>(transactions: T[], config?: SpamFilterConfig): T[];
+
+interface WalletBalance {
+    address: string;
+    sol: {
+        lamports: bigint;
+        ui: number;
+    };
+    tokens: TokenAccountBalance[];
+}
+interface TokenAccountBalance {
+    mint: string;
+    tokenAccount?: string;
+    amount: {
+        raw: string;
+        ui: number;
+    };
+    decimals: number;
+    symbol: string;
+}
+/**
+ * Fetches wallet balance including SOL and SPL tokens
+ *
+ * @param rpc - Solana RPC client
+ * @param walletAddress - Wallet address to query
+ * @param tokenMints - Optional array of token mint addresses to track. If omitted, returns all tokens in wallet
+ * @returns Wallet balance data with SOL and token balances
+ *
+ * @example
+ * // Fetch all tokens
+ * const allBalances = await fetchWalletBalance(rpc, address);
+ *
+ * @example
+ * // Fetch specific tokens only
+ * const usdcOnly = await fetchWalletBalance(rpc, address, ["EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"]);
+ */
+declare function fetchWalletBalance(rpc: Rpc<GetBalanceApi & GetTokenAccountsByOwnerApi>, walletAddress: Address, tokenMints?: readonly string[]): Promise<WalletBalance>;
+
+/**
+ * Configuration options for creating a transaction indexer.
+ *
+ * Use either `rpcUrl` to let the SDK create a client, or provide an existing `client`
+ * to share connections across your application.
+ */
+type TxIndexerOptions = {
+    /** Solana RPC URL (SDK creates a new client) */
+    rpcUrl: string;
+    /** Optional WebSocket URL for subscriptions */
+    wsUrl?: string;
+} | {
+    /** Existing Solana client to reuse (shares connections) */
+    client: SolanaClient;
+};
+/**
+ * Options for fetching and filtering transaction history.
+ */
+interface GetTransactionsOptions {
+    /** Maximum number of transactions to return (default: 10) */
+    limit?: number;
+    /** Fetch transactions before this signature (for pagination) */
+    before?: Signature;
+    /** Fetch transactions until this signature (for pagination) */
+    until?: Signature;
+    /** Whether to filter out spam transactions (default: true) */
+    filterSpam?: boolean;
+    /** Custom spam filter configuration */
+    spamConfig?: SpamFilterConfig;
+}
+/**
+ * A fully classified transaction with raw data, classification metadata, and accounting legs.
+ */
+interface ClassifiedTransaction {
+    /** Raw transaction data from the blockchain */
+    tx: RawTransaction;
+    /** Classification metadata (type, direction, amounts, counterparty) */
+    classification: TransactionClassification;
+    /** Accounting legs representing all balance movements */
+    legs: ReturnType<typeof transactionToLegs>;
+}
+/**
+ * Transaction indexer client for querying and classifying Solana transactions.
+ *
+ * Provides methods to fetch wallet balances, transaction history, and individual transactions
+ * with automatic protocol detection and classification.
+ */
+interface TxIndexer {
+    /** Direct access to the underlying Solana RPC client */
+    rpc: ReturnType<typeof createSolanaClient>["rpc"];
+    /**
+     * Fetches the SOL and SPL token balances for a wallet.
+     *
+     * @param walletAddress - Wallet address to query balances for
+     * @param tokenMints - Optional array of token mint addresses to filter
+     * @returns Wallet balance data including SOL and token balances
+     */
+    getBalance(walletAddress: Address, tokenMints?: readonly string[]): Promise<WalletBalance>;
+    /**
+     * Fetches and classifies transaction history for a wallet.
+     *
+     * @param walletAddress - Wallet address to fetch transaction history for
+     * @param options - Configuration options for fetching and filtering
+     * @returns Array of classified transactions with full metadata
+     */
+    getTransactions(walletAddress: Address, options?: GetTransactionsOptions): Promise<ClassifiedTransaction[]>;
+    /**
+     * Fetches and classifies a single transaction by its signature.
+     *
+     * @param signature - Transaction signature to fetch
+     * @param walletAddress - Optional wallet address for classification perspective.
+     *   When omitted, returns classification from observer mode (neutral perspective).
+     * @returns Classified transaction with full metadata, or null if transaction not found
+     */
+    getTransaction(signature: Signature, walletAddress?: Address): Promise<ClassifiedTransaction | null>;
+    /**
+     * Fetches a raw transaction without classification.
+     *
+     * @param signature - Transaction signature to fetch
+     * @returns Raw transaction data from the blockchain, or null if not found
+     */
+    getRawTransaction(signature: Signature): Promise<RawTransaction | null>;
+}
+/**
+ * Creates a transaction indexer client for querying and classifying Solana transactions.
+ *
+ * Accepts either an RPC URL (SDK creates client) or an existing SolanaClient (for sharing
+ * connections across your app or with React providers).
+ *
+ * @param options - Configuration with RPC URL or existing client
+ * @returns Transaction indexer client
+ *
+ * @example
+ * // Option 1: SDK creates client
+ * const indexer = createIndexer({ rpcUrl: "https://api.mainnet-beta.solana.com" });
+ *
+ * @example
+ * // Option 2: Provide existing client (share connections)
+ * const myClient = createSolanaClient("https://...");
+ * const indexer = createIndexer({ client: myClient });
+ */
+declare function createIndexer(options: TxIndexerOptions): TxIndexer;
+
+export { type ClassifiedTransaction as C, type FetchTransactionsConfig as F, type GetTransactionsOptions as G, type IndexerRpcApi as I, type SolanaClient as S, type TxIndexer as T, type WalletBalance as W, type TxIndexerOptions as a, createSolanaClient as b, createIndexer as c, parseSignature as d, type TokenAccountBalance as e, fetchWalletBalance as f, fetchWalletSignatures as g, fetchTransaction as h, fetchTransactionsBatch as i, isSpamTransaction as j, filterSpamTransactions as k, type SpamFilterConfig as l, parseAddress as p, transactionToLegs as t };

package/dist/client.d.ts

@@ -0,0 +1,4 @@
+import '@solana/kit';
+export { C as ClassifiedTransaction, F as FetchTransactionsConfig, G as GetTransactionsOptions, T as TxIndexer, a as TxIndexerOptions, c as createIndexer } from './client-BS9KUBU7.js';
+import './classification.types-w82k4B1F.js';
+import 'zod';