tx-indexer 0.3.0 → 0.4.1

package/README.md

@@ -28,8 +28,42 @@ const txs = await indexer.getTransactions("YourWalletAddress...", {
   filterSpam: true
 });
 
-// Get single transaction
-const tx = await indexer.getTransaction("signature...", "walletAddress...");
+// Get single transaction (no wallet required)
+const tx = await indexer.getTransaction("signature...");
+
+// Classification includes sender/receiver
+console.log(tx.classification.primaryType); // "transfer", "swap", "nft_mint", etc.
+console.log(tx.classification.sender);      // sender address
+console.log(tx.classification.receiver);    // receiver address
+```
+
+## Transaction Types
+
+- `transfer` - Wallet-to-wallet transfers
+- `swap` - Token exchanges (Jupiter, Raydium, Orca)
+- `nft_mint` - NFT minting (Metaplex, Candy Machine, Bubblegum)
+- `stake_deposit` - SOL staking deposits
+- `stake_withdraw` - SOL staking withdrawals
+- `bridge_in` - Receiving from bridge (Wormhole, deBridge, Allbridge)
+- `bridge_out` - Sending to bridge
+- `airdrop` - Token distributions
+- `fee_only` - Transactions with only network fees
+
+## Frontend Integration
+
+Classification is wallet-agnostic. Determine perspective in your frontend:
+
+```typescript
+const { classification } = await indexer.getTransaction(signature);
+const connectedWallet = wallet?.address;
+
+if (connectedWallet === classification.sender) {
+  // "You sent..."
+} else if (connectedWallet === classification.receiver) {
+  // "You received..."
+} else {
+  // "Address X sent to Address Y"
+}
 ```
 
 ## Bundle Size
@@ -78,4 +112,3 @@ bun run size:why
 ## License
 
 MIT
-

package/dist/{classification.types-w82k4B1F.d.ts → classification.types-Cn9IGtEC.d.ts}

@@ -8,11 +8,11 @@ declare const TxDirectionSchema: z.ZodEnum<{
     neutral: "neutral";
 }>;
 declare const TxPrimaryTypeSchema: z.ZodEnum<{
-    transfer: "transfer";
-    swap: "swap";
+    nft_mint: "nft_mint";
     nft_purchase: "nft_purchase";
     nft_sale: "nft_sale";
-    nft_mint: "nft_mint";
+    transfer: "transfer";
+    swap: "swap";
     stake_deposit: "stake_deposit";
     stake_withdraw: "stake_withdraw";
     token_deposit: "token_deposit";
@@ -50,6 +50,7 @@ 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]>>;
+    fee: z.ZodOptional<z.ZodNumber>;
     err: z.ZodNullable<z.ZodAny>;
     programIds: z.ZodArray<z.ZodString>;
     protocol: z.ZodNullable<z.ZodObject<{
@@ -91,11 +92,11 @@ declare const TxLegSideSchema: z.ZodEnum<{
     credit: "credit";
 }>;
 declare const TxLegRoleSchema: z.ZodEnum<{
-    unknown: "unknown";
     reward: "reward";
+    unknown: "unknown";
+    fee: "fee";
     sent: "sent";
     received: "received";
-    fee: "fee";
     protocol_deposit: "protocol_deposit";
     protocol_withdraw: "protocol_withdraw";
     principal: "principal";
@@ -143,11 +144,11 @@ declare const TxLegSchema: z.ZodObject<{
         } | undefined;
     }>;
     role: z.ZodEnum<{
-        unknown: "unknown";
         reward: "reward";
+        unknown: "unknown";
+        fee: "fee";
         sent: "sent";
         received: "received";
-        fee: "fee";
         protocol_deposit: "protocol_deposit";
         protocol_withdraw: "protocol_withdraw";
         principal: "principal";
@@ -165,11 +166,11 @@ type TxLeg = z.infer<typeof TxLegSchema>;
 
 declare const TransactionClassificationSchema: z.ZodObject<{
     primaryType: z.ZodEnum<{
-        transfer: "transfer";
-        swap: "swap";
+        nft_mint: "nft_mint";
         nft_purchase: "nft_purchase";
         nft_sale: "nft_sale";
-        nft_mint: "nft_mint";
+        transfer: "transfer";
+        swap: "swap";
         stake_deposit: "stake_deposit";
         stake_withdraw: "stake_withdraw";
         token_deposit: "token_deposit";
@@ -181,22 +182,18 @@ declare const TransactionClassificationSchema: z.ZodObject<{
         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>>;
+    sender: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    receiver: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     counterparty: z.ZodNullable<z.ZodObject<{
         type: z.ZodEnum<{
-            unknown: "unknown";
-            protocol: "protocol";
             person: "person";
             merchant: "merchant";
             exchange: "exchange";
+            protocol: "protocol";
             own_wallet: "own_wallet";
+            unknown: "unknown";
         }>;
         address: z.ZodString;
         name: z.ZodOptional<z.ZodString>;

package/dist/{client-BS9KUBU7.d.ts → client-iLW2_DnL.d.ts}

@@ -1,5 +1,5 @@
 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';
+import { R as RawTransaction, T as TxLeg, a as TransactionClassification } from './classification.types-Cn9IGtEC.js';
 
 /**
  * Union type of all RPC APIs used by the transaction indexer.
@@ -72,12 +72,13 @@ declare function fetchTransactionsBatch(rpc: Rpc<GetTransactionApi>, signatures:
  * detecting and accounting for network fees. Each leg represents a debit or credit
  * for a specific account and token, enabling transaction classification and validation.
  *
+ * All accounts are tagged as "external:" - the classification layer determines
+ * the transaction type and direction from the initiator's (fee payer's) perspective.
+ *
  * @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[];
+declare function transactionToLegs(tx: RawTransaction): TxLeg[];
 
 interface SpamFilterConfig {
     minSolAmount?: number;
@@ -151,107 +152,67 @@ interface TokenAccountBalance {
  */
 declare function fetchWalletBalance(rpc: Rpc<GetBalanceApi & GetTokenAccountsByOwnerApi>, walletAddress: Address, tokenMints?: readonly string[]): Promise<WalletBalance>;
 
+interface NftMetadata {
+    mint: string;
+    name: string;
+    symbol: string;
+    image: string;
+    cdnImage?: string;
+    description?: string;
+    collection?: string;
+    attributes?: Array<{
+        trait_type: string;
+        value: string;
+    }>;
+}
+/**
+ * Fetches NFT metadata from Helius DAS API.
+ *
+ * @param rpcUrl - Helius RPC endpoint URL
+ * @param mintAddress - NFT mint address
+ * @returns NFT metadata including name, image, collection, and attributes, or null if not found
+ */
+declare function fetchNftMetadata(rpcUrl: string, mintAddress: string): Promise<NftMetadata | null>;
 /**
- * Configuration options for creating a transaction indexer.
+ * Fetches NFT metadata for multiple mints in parallel.
  *
- * Use either `rpcUrl` to let the SDK create a client, or provide an existing `client`
- * to share connections across your application.
+ * @param rpcUrl - Helius RPC endpoint URL
+ * @param mintAddresses - Array of NFT mint addresses
+ * @returns Map of mint address to NFT metadata (only includes successful fetches)
  */
+declare function fetchNftMetadataBatch(rpcUrl: string, mintAddresses: string[]): Promise<Map<string, NftMetadata>>;
+
 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;
+    enrichNftMetadata?: boolean;
+}
+interface GetTransactionOptions {
+    enrichNftMetadata?: boolean;
 }
-/**
- * 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
-     */
+    getTransaction(signature: Signature, options?: GetTransactionOptions): Promise<ClassifiedTransaction | null>;
     getRawTransaction(signature: Signature): Promise<RawTransaction | null>;
+    getNftMetadata(mintAddress: string): Promise<NftMetadata | null>;
+    getNftMetadataBatch(mintAddresses: string[]): Promise<Map<string, NftMetadata>>;
 }
-/**
- * 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 };
+export { type ClassifiedTransaction as C, type FetchTransactionsConfig as F, type GetTransactionsOptions as G, type IndexerRpcApi as I, type NftMetadata as N, type SolanaClient as S, type TxIndexer as T, type WalletBalance as W, type TxIndexerOptions as a, type GetTransactionOptions as b, createIndexer as c, createSolanaClient as d, parseSignature as e, fetchWalletBalance as f, type TokenAccountBalance as g, fetchWalletSignatures as h, fetchTransaction as i, fetchTransactionsBatch as j, isSpamTransaction as k, filterSpamTransactions as l, type SpamFilterConfig as m, fetchNftMetadata as n, fetchNftMetadataBatch as o, parseAddress as p, transactionToLegs as t };

package/dist/client.d.ts

@@ -1,4 +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';
+export { C as ClassifiedTransaction, F as FetchTransactionsConfig, b as GetTransactionOptions, G as GetTransactionsOptions, T as TxIndexer, a as TxIndexerOptions, c as createIndexer } from './client-iLW2_DnL.js';
+import './classification.types-Cn9IGtEC.js';
 import 'zod';