tx-indexer 0.4.0 → 0.5.0

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 (pattern-based detection works with any DEX, higher confidence for known protocols like 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-DlJe6bDZ.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";
@@ -187,12 +188,12 @@ declare const TransactionClassificationSchema: z.ZodObject<{
     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-yGDWPKKf.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-DlJe6bDZ.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.
@@ -152,6 +152,36 @@ 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>;
+/**
+ * Fetches NFT metadata for multiple mints in parallel.
+ *
+ * @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 = {
     rpcUrl: string;
     wsUrl?: string;
@@ -164,6 +194,10 @@ interface GetTransactionsOptions {
     until?: Signature;
     filterSpam?: boolean;
     spamConfig?: SpamFilterConfig;
+    enrichNftMetadata?: boolean;
+}
+interface GetTransactionOptions {
+    enrichNftMetadata?: boolean;
 }
 interface ClassifiedTransaction {
     tx: RawTransaction;
@@ -174,9 +208,11 @@ interface TxIndexer {
     rpc: ReturnType<typeof createSolanaClient>["rpc"];
     getBalance(walletAddress: Address, tokenMints?: readonly string[]): Promise<WalletBalance>;
     getTransactions(walletAddress: Address, options?: GetTransactionsOptions): Promise<ClassifiedTransaction[]>;
-    getTransaction(signature: Signature): Promise<ClassifiedTransaction | null>;
+    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>>;
 }
 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-yGDWPKKf.js';
-import './classification.types-DlJe6bDZ.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';

package/dist/client.js

@@ -416,6 +416,7 @@ async function fetchTransaction(rpc, signature2, commitment = "confirmed") {
     signature: signature2,
     slot: response.slot,
     blockTime: response.blockTime,
+    fee: Number(response.meta?.fee ?? 0),
     err: response.meta?.err ?? null,
     programIds: extractProgramIds(response.transaction),
     protocol: null,
@@ -705,7 +706,7 @@ var TransferClassifier = class {
       sender,
       receiver,
       counterparty: {
-        type: "wallet",
+        type: "unknown",
         address: receiver,
         name: `${receiver.slice(0, 8)}...`
       },
@@ -876,19 +877,19 @@ var SwapClassifier = class {
   priority = 80;
   classify(context) {
     const { legs, tx } = context;
-    const hasDexProtocol = isDexProtocolById(tx.protocol?.id);
-    if (!hasDexProtocol) {
-      return null;
-    }
     const feeLeg = legs.find(
       (leg) => leg.role === "fee" && leg.side === "debit"
     );
     const initiator = feeLeg?.accountId.replace("external:", "") ?? null;
+    if (!initiator) {
+      return null;
+    }
+    const initiatorAccountId = `external:${initiator}`;
     const tokensOut = legs.filter(
-      (leg) => leg.accountId.startsWith("external:") && leg.side === "debit" && (leg.role === "sent" || leg.role === "protocol_deposit")
+      (leg) => leg.accountId === initiatorAccountId && leg.side === "debit" && (leg.role === "sent" || leg.role === "protocol_deposit")
     );
     const tokensIn = legs.filter(
-      (leg) => leg.accountId.startsWith("external:") && leg.side === "credit" && (leg.role === "received" || leg.role === "protocol_withdraw")
+      (leg) => leg.accountId === initiatorAccountId && leg.side === "credit" && (leg.role === "received" || leg.role === "protocol_withdraw")
     );
     if (tokensOut.length === 0 || tokensIn.length === 0) {
       return null;
@@ -898,6 +899,8 @@ var SwapClassifier = class {
     if (tokenOut.amount.token.symbol === tokenIn.amount.token.symbol) {
       return null;
     }
+    const hasDexProtocol = isDexProtocolById(tx.protocol?.id);
+    const confidence = hasDexProtocol ? 0.95 : 0.75;
     return {
       primaryType: "swap",
       primaryAmount: tokenOut.amount,
@@ -905,7 +908,7 @@ var SwapClassifier = class {
       sender: initiator,
       receiver: initiator,
       counterparty: null,
-      confidence: 0.9,
+      confidence,
       isRelevant: true,
       metadata: {
         swap_type: "token_to_token",
@@ -1037,7 +1040,7 @@ var SolanaPayClassifier = class {
       counterparty: receiver ? {
         address: receiver,
         name: memo.merchant ?? void 0,
-        type: memo.merchant ? "merchant" : "wallet"
+        type: memo.merchant ? "merchant" : "unknown"
       } : null,
       confidence: 0.98,
       isRelevant: true,
@@ -1314,8 +1317,81 @@ function filterSpamTransactions(transactions, config) {
   );
 }
 
+// src/nft.ts
+async function fetchNftMetadata(rpcUrl, mintAddress) {
+  const response = await fetch(rpcUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: "get-asset",
+      method: "getAsset",
+      params: { id: mintAddress }
+    })
+  });
+  const data = await response.json();
+  if (data.error || !data.result?.content?.metadata) {
+    return null;
+  }
+  const { result } = data;
+  const { content, grouping } = result;
+  return {
+    mint: mintAddress,
+    name: content.metadata.name,
+    symbol: content.metadata.symbol,
+    image: content.links.image ?? content.files?.[0]?.uri ?? "",
+    cdnImage: content.files?.[0]?.cdn_uri,
+    description: content.metadata.description,
+    collection: grouping?.find((g) => g.group_key === "collection")?.group_value,
+    attributes: content.metadata.attributes
+  };
+}
+async function fetchNftMetadataBatch(rpcUrl, mintAddresses) {
+  const results = await Promise.all(
+    mintAddresses.map((mint) => fetchNftMetadata(rpcUrl, mint))
+  );
+  const map = /* @__PURE__ */ new Map();
+  results.forEach((metadata, index) => {
+    if (metadata) {
+      map.set(mintAddresses[index], metadata);
+    }
+  });
+  return map;
+}
+
 // src/client.ts
+var NFT_TRANSACTION_TYPES = ["nft_mint", "nft_purchase", "nft_sale"];
+async function enrichNftClassification(rpcUrl, classified) {
+  const { classification } = classified;
+  if (!NFT_TRANSACTION_TYPES.includes(classification.primaryType)) {
+    return classified;
+  }
+  const nftMint = classification.metadata?.nft_mint;
+  if (!nftMint) {
+    return classified;
+  }
+  const nftData = await fetchNftMetadata(rpcUrl, nftMint);
+  if (!nftData) {
+    return classified;
+  }
+  return {
+    ...classified,
+    classification: {
+      ...classification,
+      metadata: {
+        ...classification.metadata,
+        nft_name: nftData.name,
+        nft_image: nftData.image,
+        nft_cdn_image: nftData.cdnImage,
+        nft_collection: nftData.collection,
+        nft_symbol: nftData.symbol,
+        nft_attributes: nftData.attributes
+      }
+    }
+  };
+}
 function createIndexer(options) {
+  const rpcUrl = "client" in options ? "" : options.rpcUrl;
   const client = "client" in options ? options.client : createSolanaClient(options.rpcUrl, options.wsUrl);
   return {
     rpc: client.rpc,
@@ -1323,7 +1399,39 @@ function createIndexer(options) {
       return fetchWalletBalance(client.rpc, walletAddress, tokenMints);
     },
     async getTransactions(walletAddress, options2 = {}) {
-      const { limit = 10, before, until, filterSpam = true, spamConfig } = options2;
+      const { limit = 10, before, until, filterSpam = true, spamConfig, enrichNftMetadata = true } = options2;
+      async function enrichBatch(transactions) {
+        if (!enrichNftMetadata || !rpcUrl) {
+          return transactions;
+        }
+        const nftMints = transactions.filter((t) => NFT_TRANSACTION_TYPES.includes(t.classification.primaryType)).map((t) => t.classification.metadata?.nft_mint).filter(Boolean);
+        if (nftMints.length === 0) {
+          return transactions;
+        }
+        const nftMetadataMap = await fetchNftMetadataBatch(rpcUrl, nftMints);
+        return transactions.map((t) => {
+          const nftMint = t.classification.metadata?.nft_mint;
+          if (!nftMint || !nftMetadataMap.has(nftMint)) {
+            return t;
+          }
+          const nftData = nftMetadataMap.get(nftMint);
+          return {
+            ...t,
+            classification: {
+              ...t.classification,
+              metadata: {
+                ...t.classification.metadata,
+                nft_name: nftData.name,
+                nft_image: nftData.image,
+                nft_cdn_image: nftData.cdnImage,
+                nft_collection: nftData.collection,
+                nft_symbol: nftData.symbol,
+                nft_attributes: nftData.attributes
+              }
+            }
+          };
+        });
+      }
       if (!filterSpam) {
         const signatures = await fetchWalletSignatures(client.rpc, walletAddress, {
           limit,
@@ -1346,7 +1454,7 @@ function createIndexer(options) {
           const classification = classifyTransaction(legs, tx);
           return { tx, classification, legs };
         });
-        return classified;
+        return enrichBatch(classified);
       }
       const accumulated = [];
       let currentBefore = before;
@@ -1385,9 +1493,11 @@ function createIndexer(options) {
           break;
         }
       }
-      return accumulated.slice(0, limit);
+      const result = accumulated.slice(0, limit);
+      return enrichBatch(result);
     },
-    async getTransaction(signature2) {
+    async getTransaction(signature2, options2 = {}) {
+      const { enrichNftMetadata = true } = options2;
       const tx = await fetchTransaction(client.rpc, signature2);
       if (!tx) {
         return null;
@@ -1395,10 +1505,26 @@ function createIndexer(options) {
       tx.protocol = detectProtocol(tx.programIds);
       const legs = transactionToLegs(tx);
       const classification = classifyTransaction(legs, tx);
-      return { tx, classification, legs };
+      let classified = { tx, classification, legs };
+      if (enrichNftMetadata && rpcUrl) {
+        classified = await enrichNftClassification(rpcUrl, classified);
+      }
+      return classified;
     },
     async getRawTransaction(signature2) {
       return fetchTransaction(client.rpc, signature2);
+    },
+    async getNftMetadata(mintAddress) {
+      if (!rpcUrl) {
+        throw new Error("getNftMetadata requires rpcUrl to be set");
+      }
+      return fetchNftMetadata(rpcUrl, mintAddress);
+    },
+    async getNftMetadataBatch(mintAddresses) {
+      if (!rpcUrl) {
+        throw new Error("getNftMetadataBatch requires rpcUrl to be set");
+      }
+      return fetchNftMetadataBatch(rpcUrl, mintAddresses);
     }
   };
 }