tx-indexer 1.4.1 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 1.5.0
+
+### Minor Changes
+
+- Add NFT transfer classification for marketplace and P2P transactions:
+  - New transaction types:
+    - `nft_purchase` - NFT bought on marketplace
+    - `nft_sale` - NFT sold on marketplace
+    - `nft_receive` - NFT received via direct transfer
+    - `nft_send` - NFT sent via direct transfer
+
+  - NFT marketplace detection for:
+    - Magic Eden (v2, MMM)
+    - Tensor (swap, marketplace, AMM)
+    - Hadeswap
+    - Metaplex Auction House
+    - Formfunction
+
+  - Smart classification logic:
+    - Direct NFT transfers detected by decimals=0 token movements
+    - Marketplace buy/sell determined by wallet perspective
+    - Escrow pattern handling (falls back to SOL flow analysis)
+    - Confidence levels: 0.9 for direct, 0.85 for SOL-flow based
+
+  ```typescript
+  const tx = await indexer.getTransaction(signature);
+
+  if (tx.classification.primaryType === "nft_sale") {
+    console.log(
+      "Sold NFT for",
+      tx.classification.secondaryAmount?.amountUi,
+      "SOL",
+    );
+  }
+
+  if (tx.classification.primaryType === "nft_receive") {
+    console.log("Received NFT:", tx.classification.metadata?.nft_name);
+  }
+  ```
+
 ## 1.4.0
 
 ### Minor Changes

package/README.md

@@ -205,20 +205,34 @@ interface ClassifiedTransaction {
 
 ## Transaction Types
 
-| Type             | Description                                      |
-| ---------------- | ------------------------------------------------ |
-| `transfer`       | Wallet-to-wallet transfers                       |
-| `swap`           | Token exchanges (Jupiter, Raydium, Orca, etc.)   |
-| `nft_mint`       | NFT minting (Metaplex, Candy Machine, Bubblegum) |
-| `nft_purchase`   | NFT purchase                                     |
-| `nft_sale`       | NFT sale                                         |
-| `stake_deposit`  | SOL staking deposits                             |
-| `stake_withdraw` | SOL staking withdrawals                          |
-| `bridge_in`      | Receiving from bridge (Wormhole, deBridge)       |
-| `bridge_out`     | Sending to bridge                                |
-| `airdrop`        | Token distributions                              |
-| `fee_only`       | Transactions with only network fees              |
-| `other`          | Unclassified transactions                        |
+| Type             | Description                                              |
+| ---------------- | -------------------------------------------------------- |
+| `transfer`       | Wallet-to-wallet transfers                               |
+| `swap`           | Token exchanges (Jupiter, Raydium, Orca, etc.)           |
+| `nft_mint`       | NFT minting (Metaplex, Candy Machine, Bubblegum)         |
+| `nft_purchase`   | NFT bought on marketplace (Magic Eden, Tensor, Hadeswap) |
+| `nft_sale`       | NFT sold on marketplace                                  |
+| `nft_receive`    | NFT received via direct P2P transfer                     |
+| `nft_send`       | NFT sent via direct P2P transfer                         |
+| `stake_deposit`  | SOL staking deposits                                     |
+| `stake_withdraw` | SOL staking withdrawals                                  |
+| `bridge_in`      | Receiving from bridge (Wormhole, deBridge)               |
+| `bridge_out`     | Sending to bridge                                        |
+| `airdrop`        | Token distributions                                      |
+| `fee_only`       | Transactions with only network fees                      |
+| `other`          | Unclassified transactions                                |
+
+### NFT Marketplace Support
+
+The SDK detects and classifies NFT transactions from major Solana marketplaces:
+
+- **Magic Eden** - v2 and MMM (Market Making) programs
+- **Tensor** - Swap, Marketplace, and AMM programs
+- **Hadeswap** - AMM-based NFT trading
+- **Metaplex Auction House** - Decentralized auction protocol
+- **Formfunction** - Art-focused marketplace
+
+For marketplace transactions, the classifier uses wallet perspective to determine if a transaction is a purchase or sale. When the wallet isn't directly involved in the NFT token movement (common with escrow patterns), it falls back to analyzing SOL/token flow.
 
 ## Entry Points
 

package/dist/advanced.d.ts

@@ -24,7 +24,7 @@ declare class ClassificationService {
 /**
  * Classifies a transaction based on its accounting legs and context.
  *
- * Uses a priority-ordered chain of classifiers (Solana Pay > Privacy Cash > Bridge > NFT Mint > Stake Deposit > Stake Withdraw > Swap > Airdrop > Transfer > Fee-only)
+ * Uses a priority-ordered chain of classifiers (Solana Pay > Privacy Cash > Bridge > NFT Mint > NFT Transfer > Stake Deposit > Stake Withdraw > Swap > Airdrop > Transfer > Fee-only)
  * to determine the transaction type, direction, amounts, sender, and receiver.
  *
  * @param legs - Transaction legs representing all balance movements

package/dist/advanced.js

@@ -70,8 +70,9 @@ var TOKEN_INFO = {
   [KNOWN_TOKENS.USDG]: {
     mint: KNOWN_TOKENS.USDG,
     symbol: "USDG",
-    name: "USD Glitter",
-    decimals: 6
+    name: "Global Dollar",
+    decimals: 6,
+    logoURI: "https://arweave.net/dMKl9vRAYD5V1_9aLGXk5K4EuFKNdzRWgN_5FgnPmYY"
   },
   [KNOWN_TOKENS.USDC_BRIDGED]: {
     mint: KNOWN_TOKENS.USDC_BRIDGED,
@@ -317,6 +318,14 @@ var CANDY_MACHINE_V3_PROGRAM_ID = "CndyV3LdqHUfDLmE5naZjVN8rBZz4tqhdefbAnjHG3JR"
 var CANDY_GUARD_PROGRAM_ID = "Guard1JwRhJkVH6XZhzoYxeBVQe872VH6QggF4BWmS9g";
 var BUBBLEGUM_PROGRAM_ID = "BGUMAp9Gq7iTEuizy4pqaxsTyUCBK68MDfK752saRPUY";
 var MAGIC_EDEN_CANDY_MACHINE_ID = "CMZYPASGWeTz7RNGHaRJfCq2XQ5pYK6nDvVQxzkH51zb";
+var MAGIC_EDEN_V2_PROGRAM_ID = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K";
+var MAGIC_EDEN_MMM_PROGRAM_ID = "mmm3XBJg5gk8XJxEKBvdgptZz6SgK4tXvn36sodowMc";
+var TENSOR_SWAP_PROGRAM_ID = "TSWAPaqyCSx2KABk68Shruf4rp7CxcNi8hAsbdwmHbN";
+var TENSOR_MARKETPLACE_PROGRAM_ID = "TCMPhJdwDryooaGtiocG1u3xcYbRpiJzb283XfCZsDp";
+var TENSOR_AMM_PROGRAM_ID = "TAMM6ub33ij1mbetoMyVBLeKY5iP41i4UPUJQGkhfsg";
+var HADESWAP_PROGRAM_ID = "hadeK9DLv9eA7ya5KCTqSvSvRZeJC3JgD5a9Y3CNbvu";
+var METAPLEX_AUCTION_HOUSE_PROGRAM_ID = "hausS13jsjafwWwGqZTUQRmWyvyxn9EQpqMwV1PBBmk";
+var FORMFUNCTION_PROGRAM_ID = "formn3hJtt8gvVKxpCfzCJGuoz6CNUFcULFZW18iTpC";
 var PRIVACY_CASH_PROGRAM_ID = "9fhQBbumKEFuXtMBDw8AaQyAjCorLGJQiS3skWZdQyQD";
 var PRIVACY_CASH_SPL_POOL = "2vV7xhCMWRrcLiwGoTaTRgvx98ku98TRJKPXhsS8jvBV";
 var PRIVACY_CASH_FEE_RECIPIENT = "AWexibGxNFKTa1b5R5MN4PJr9HWnWRwf8EW9g8cLx3dM";
@@ -1446,6 +1455,39 @@ var KNOWN_PROGRAMS = {
     id: "magic-eden-candy-machine",
     name: "Nft Candy Machine Program (Magic Eden)"
   },
+  // NFT Marketplaces
+  [MAGIC_EDEN_V2_PROGRAM_ID]: {
+    id: "magic-eden",
+    name: "Magic Eden"
+  },
+  [MAGIC_EDEN_MMM_PROGRAM_ID]: {
+    id: "magic-eden-mmm",
+    name: "Magic Eden MMM"
+  },
+  [TENSOR_SWAP_PROGRAM_ID]: {
+    id: "tensor",
+    name: "Tensor"
+  },
+  [TENSOR_MARKETPLACE_PROGRAM_ID]: {
+    id: "tensor-marketplace",
+    name: "Tensor Marketplace"
+  },
+  [TENSOR_AMM_PROGRAM_ID]: {
+    id: "tensor-amm",
+    name: "Tensor AMM"
+  },
+  [HADESWAP_PROGRAM_ID]: {
+    id: "hadeswap",
+    name: "Hadeswap"
+  },
+  [METAPLEX_AUCTION_HOUSE_PROGRAM_ID]: {
+    id: "auction-house",
+    name: "Metaplex Auction House"
+  },
+  [FORMFUNCTION_PROGRAM_ID]: {
+    id: "formfunction",
+    name: "Formfunction"
+  },
   // Staking programs
   [STAKE_PROGRAM_ID]: {
     id: "stake",
@@ -1513,12 +1555,21 @@ var PRIORITY_ORDER = [
   // Stableswap
   "saber",
   "mercurial",
-  // NFT
+  // NFT Minting
   "metaplex",
   "candy-guard",
   "candy-machine-v3",
   "bubblegum",
   "magic-eden-candy-machine",
+  // NFT Marketplaces
+  "magic-eden",
+  "magic-eden-mmm",
+  "tensor",
+  "tensor-marketplace",
+  "tensor-amm",
+  "hadeswap",
+  "auction-house",
+  "formfunction",
   // Staking
   "stake",
   "stake-pool",
@@ -1566,6 +1617,16 @@ var NFT_MINT_PROTOCOL_IDS = /* @__PURE__ */ new Set([
   "bubblegum",
   "magic-eden-candy-machine"
 ]);
+var NFT_MARKETPLACE_PROTOCOL_IDS = /* @__PURE__ */ new Set([
+  "magic-eden",
+  "magic-eden-mmm",
+  "tensor",
+  "tensor-marketplace",
+  "tensor-amm",
+  "hadeswap",
+  "auction-house",
+  "formfunction"
+]);
 var STAKE_PROTOCOL_IDS = /* @__PURE__ */ new Set(["stake", "stake-pool"]);
 var BRIDGE_PROTOCOL_IDS = /* @__PURE__ */ new Set([
   "wormhole",
@@ -1581,6 +1642,9 @@ function isDexProtocolById(protocolId) {
 function isNftMintProtocolById(protocolId) {
   return protocolId !== void 0 && NFT_MINT_PROTOCOL_IDS.has(protocolId);
 }
+function isNftMarketplaceProtocolById(protocolId) {
+  return protocolId !== void 0 && NFT_MARKETPLACE_PROTOCOL_IDS.has(protocolId);
+}
 function isStakeProtocolById(protocolId) {
   return protocolId !== void 0 && STAKE_PROTOCOL_IDS.has(protocolId);
 }
@@ -1894,6 +1958,342 @@ var NftMintClassifier = class {
   }
 };
 
+// ../classification/src/classifiers/nft-transfer-classifier.ts
+function isNftLeg(leg) {
+  return leg.amount.token.decimals === 0 && leg.amount.amountUi >= 1 && leg.accountId.startsWith("external:");
+}
+function findNftLegs(legs) {
+  const nftLegs = legs.filter(isNftLeg);
+  return {
+    credits: nftLegs.filter((l) => l.side === "credit"),
+    debits: nftLegs.filter((l) => l.side === "debit")
+  };
+}
+function findWalletNftLegs(legs, walletAddress) {
+  if (!walletAddress) {
+    return { walletCredits: [], walletDebits: [] };
+  }
+  const walletAccountId = `external:${walletAddress}`;
+  const nftLegs = legs.filter(isNftLeg);
+  return {
+    walletCredits: nftLegs.filter(
+      (l) => l.side === "credit" && l.accountId === walletAccountId
+    ),
+    walletDebits: nftLegs.filter(
+      (l) => l.side === "debit" && l.accountId === walletAccountId
+    )
+  };
+}
+function findPaymentLeg(legs, side) {
+  return legs.find(
+    (leg) => leg.side === side && leg.amount.token.decimals > 0 && (leg.role === "sent" || leg.role === "received") && leg.accountId.startsWith("external:")
+  );
+}
+function findWalletPaymentLeg(legs, walletAddress, side) {
+  if (!walletAddress) return void 0;
+  const walletAccountId = `external:${walletAddress}`;
+  return legs.find(
+    (leg) => leg.accountId === walletAccountId && leg.side === side && leg.amount.token.decimals > 0 && (leg.role === "sent" || leg.role === "received")
+  );
+}
+var NftTransferClassifier = class {
+  name = "nft-transfer";
+  priority = 80;
+  classify(context) {
+    const { legs, tx, walletAddress } = context;
+    if (isNftMintProtocolById(tx.protocol?.id)) {
+      return null;
+    }
+    if (isDexProtocolById(tx.protocol?.id)) {
+      return null;
+    }
+    const { credits: nftCredits, debits: nftDebits } = findNftLegs(legs);
+    if (nftCredits.length === 0 && nftDebits.length === 0) {
+      return null;
+    }
+    const isMarketplace = isNftMarketplaceProtocolById(tx.protocol?.id);
+    if (isMarketplace) {
+      const { walletCredits, walletDebits } = findWalletNftLegs(
+        legs,
+        walletAddress
+      );
+      if (walletCredits.length > 0) {
+        const paymentLeg = findPaymentLeg(legs, "debit");
+        const primaryNft = walletCredits[0];
+        const buyer = primaryNft.accountId.replace("external:", "");
+        return {
+          primaryType: "nft_purchase",
+          primaryAmount: primaryNft.amount,
+          secondaryAmount: paymentLeg?.amount ?? null,
+          sender: null,
+          receiver: buyer,
+          counterparty: {
+            type: "protocol",
+            address: tx.protocol?.id ?? "marketplace",
+            name: tx.protocol?.name ?? "NFT Marketplace"
+          },
+          confidence: 0.9,
+          isRelevant: true,
+          metadata: {
+            nft_mint: primaryNft.amount.token.mint,
+            nft_name: primaryNft.amount.token.name,
+            quantity: walletCredits.length,
+            purchase_price: paymentLeg?.amount.amountUi,
+            purchase_token: paymentLeg?.amount.token.symbol,
+            marketplace: tx.protocol?.id
+          }
+        };
+      }
+      if (walletDebits.length > 0) {
+        const proceedsLeg = findPaymentLeg(legs, "credit");
+        const primaryNft = walletDebits[0];
+        const seller = primaryNft.accountId.replace("external:", "");
+        return {
+          primaryType: "nft_sale",
+          primaryAmount: primaryNft.amount,
+          secondaryAmount: proceedsLeg?.amount ?? null,
+          sender: seller,
+          receiver: null,
+          counterparty: {
+            type: "protocol",
+            address: tx.protocol?.id ?? "marketplace",
+            name: tx.protocol?.name ?? "NFT Marketplace"
+          },
+          confidence: 0.9,
+          isRelevant: true,
+          metadata: {
+            nft_mint: primaryNft.amount.token.mint,
+            nft_name: primaryNft.amount.token.name,
+            quantity: walletDebits.length,
+            sale_price: proceedsLeg?.amount.amountUi,
+            sale_token: proceedsLeg?.amount.token.symbol,
+            marketplace: tx.protocol?.id
+          }
+        };
+      }
+      const walletPaidLeg = findWalletPaymentLeg(legs, walletAddress, "debit");
+      const walletReceivedLeg = findWalletPaymentLeg(
+        legs,
+        walletAddress,
+        "credit"
+      );
+      if (walletReceivedLeg && (nftDebits.length > 0 || nftCredits.length > 0)) {
+        const primaryNft = nftDebits[0] ?? nftCredits[0];
+        return {
+          primaryType: "nft_sale",
+          primaryAmount: primaryNft.amount,
+          secondaryAmount: walletReceivedLeg.amount,
+          sender: walletAddress ?? null,
+          receiver: nftCredits[0]?.accountId.replace("external:", "") ?? null,
+          counterparty: {
+            type: "protocol",
+            address: tx.protocol?.id ?? "marketplace",
+            name: tx.protocol?.name ?? "NFT Marketplace"
+          },
+          confidence: 0.85,
+          // Good confidence based on SOL flow
+          isRelevant: true,
+          metadata: {
+            nft_mint: primaryNft.amount.token.mint,
+            nft_name: primaryNft.amount.token.name,
+            quantity: nftDebits.length || nftCredits.length,
+            sale_price: walletReceivedLeg.amount.amountUi,
+            sale_token: walletReceivedLeg.amount.token.symbol,
+            marketplace: tx.protocol?.id
+          }
+        };
+      }
+      if (walletPaidLeg && (nftCredits.length > 0 || nftDebits.length > 0)) {
+        const primaryNft = nftCredits[0] ?? nftDebits[0];
+        return {
+          primaryType: "nft_purchase",
+          primaryAmount: primaryNft.amount,
+          secondaryAmount: walletPaidLeg.amount,
+          sender: nftDebits[0]?.accountId.replace("external:", "") ?? null,
+          receiver: walletAddress ?? null,
+          counterparty: {
+            type: "protocol",
+            address: tx.protocol?.id ?? "marketplace",
+            name: tx.protocol?.name ?? "NFT Marketplace"
+          },
+          confidence: 0.85,
+          // Good confidence based on SOL flow
+          isRelevant: true,
+          metadata: {
+            nft_mint: primaryNft.amount.token.mint,
+            nft_name: primaryNft.amount.token.name,
+            quantity: nftCredits.length || nftDebits.length,
+            purchase_price: walletPaidLeg.amount.amountUi,
+            purchase_token: walletPaidLeg.amount.token.symbol,
+            marketplace: tx.protocol?.id
+          }
+        };
+      }
+      if (walletPaidLeg && nftCredits.length > 0) {
+        const primaryNft = nftCredits[0];
+        return {
+          primaryType: "nft_purchase",
+          primaryAmount: primaryNft.amount,
+          secondaryAmount: walletPaidLeg.amount,
+          sender: null,
+          receiver: walletAddress ?? primaryNft.accountId.replace("external:", ""),
+          counterparty: {
+            type: "protocol",
+            address: tx.protocol?.id ?? "marketplace",
+            name: tx.protocol?.name ?? "NFT Marketplace"
+          },
+          confidence: 0.85,
+          // Good confidence based on SOL flow
+          isRelevant: true,
+          metadata: {
+            nft_mint: primaryNft.amount.token.mint,
+            nft_name: primaryNft.amount.token.name,
+            quantity: nftCredits.length,
+            purchase_price: walletPaidLeg.amount.amountUi,
+            purchase_token: walletPaidLeg.amount.token.symbol,
+            marketplace: tx.protocol?.id
+          }
+        };
+      }
+      if (nftCredits.length > 0) {
+        const primaryNft = nftCredits[0];
+        return {
+          primaryType: "nft_purchase",
+          primaryAmount: primaryNft.amount,
+          secondaryAmount: null,
+          sender: null,
+          receiver: primaryNft.accountId.replace("external:", ""),
+          counterparty: {
+            type: "protocol",
+            address: tx.protocol?.id ?? "marketplace",
+            name: tx.protocol?.name ?? "NFT Marketplace"
+          },
+          confidence: 0.7,
+          // Lower confidence when wallet not directly involved
+          isRelevant: true,
+          metadata: {
+            nft_mint: primaryNft.amount.token.mint,
+            nft_name: primaryNft.amount.token.name,
+            quantity: nftCredits.length,
+            marketplace: tx.protocol?.id
+          }
+        };
+      }
+      if (nftDebits.length > 0) {
+        const primaryNft = nftDebits[0];
+        return {
+          primaryType: "nft_sale",
+          primaryAmount: primaryNft.amount,
+          secondaryAmount: null,
+          sender: primaryNft.accountId.replace("external:", ""),
+          receiver: null,
+          counterparty: {
+            type: "protocol",
+            address: tx.protocol?.id ?? "marketplace",
+            name: tx.protocol?.name ?? "NFT Marketplace"
+          },
+          confidence: 0.7,
+          // Lower confidence when wallet not directly involved
+          isRelevant: true,
+          metadata: {
+            nft_mint: primaryNft.amount.token.mint,
+            nft_name: primaryNft.amount.token.name,
+            quantity: nftDebits.length,
+            marketplace: tx.protocol?.id
+          }
+        };
+      }
+    }
+    if (nftCredits.length > 0 && nftDebits.length > 0) {
+      const creditAccount = nftCredits[0].accountId.replace("external:", "");
+      const debitAccount = nftDebits[0].accountId.replace("external:", "");
+      const isSending = walletAddress === debitAccount;
+      if (isSending) {
+        const primaryNft = nftDebits[0];
+        return {
+          primaryType: "nft_send",
+          primaryAmount: primaryNft.amount,
+          secondaryAmount: null,
+          sender: debitAccount,
+          receiver: creditAccount,
+          counterparty: {
+            type: "unknown",
+            address: creditAccount,
+            name: `${creditAccount.slice(0, 8)}...`
+          },
+          confidence: 0.85,
+          isRelevant: true,
+          metadata: {
+            nft_mint: primaryNft.amount.token.mint,
+            nft_name: primaryNft.amount.token.name,
+            quantity: nftDebits.length
+          }
+        };
+      } else {
+        const primaryNft = nftCredits[0];
+        return {
+          primaryType: "nft_receive",
+          primaryAmount: primaryNft.amount,
+          secondaryAmount: null,
+          sender: debitAccount,
+          receiver: creditAccount,
+          counterparty: {
+            type: "unknown",
+            address: debitAccount,
+            name: `${debitAccount.slice(0, 8)}...`
+          },
+          confidence: 0.85,
+          isRelevant: true,
+          metadata: {
+            nft_mint: primaryNft.amount.token.mint,
+            nft_name: primaryNft.amount.token.name,
+            quantity: nftCredits.length
+          }
+        };
+      }
+    }
+    if (nftCredits.length > 0 && nftDebits.length === 0) {
+      const primaryNft = nftCredits[0];
+      const receiver = primaryNft.accountId.replace("external:", "");
+      return {
+        primaryType: "nft_receive",
+        primaryAmount: primaryNft.amount,
+        secondaryAmount: null,
+        sender: null,
+        receiver,
+        counterparty: null,
+        confidence: 0.85,
+        isRelevant: true,
+        metadata: {
+          nft_mint: primaryNft.amount.token.mint,
+          nft_name: primaryNft.amount.token.name,
+          quantity: nftCredits.length
+        }
+      };
+    }
+    if (nftDebits.length > 0 && nftCredits.length === 0) {
+      const primaryNft = nftDebits[0];
+      const sender = primaryNft.accountId.replace("external:", "");
+      return {
+        primaryType: "nft_send",
+        primaryAmount: primaryNft.amount,
+        secondaryAmount: null,
+        sender,
+        receiver: null,
+        counterparty: null,
+        confidence: 0.85,
+        isRelevant: true,
+        metadata: {
+          nft_mint: primaryNft.amount.token.mint,
+          nft_name: primaryNft.amount.token.name,
+          quantity: nftDebits.length
+        }
+      };
+    }
+    return null;
+  }
+};
+
 // ../classification/src/classifiers/stake-deposit-classifier.ts
 var StakeDepositClassifier = class {
   name = "stake-deposit";
@@ -2160,6 +2560,7 @@ var ClassificationService = class {
     this.registerClassifier(new PrivacyCashClassifier());
     this.registerClassifier(new BridgeClassifier());
     this.registerClassifier(new NftMintClassifier());
+    this.registerClassifier(new NftTransferClassifier());
     this.registerClassifier(new StakeDepositClassifier());
     this.registerClassifier(new StakeWithdrawClassifier());
     this.registerClassifier(new SwapClassifier());