Solana Compressed NFT Event Listening

1. Understanding cNFTs and Their Event Lifecycle

On Solana, Compressed NFTs (cNFTs) differ from traditional NFTs in a crucial way:

Traditional NFTs each have their own mint address and token account.
Compressed NFTs store data within a Merkle tree managed by the related cNFT program. This single on-chain account holds the Merkle tree root, and each NFT is represented as a leaf in that tree.

Key Points:

A cNFT mint adds a new leaf.
A cNFT transfer updates the ownership data in the existing leaf.
A cNFT burn removes or invalidates the leaf from the tree.

Because cNFTs lack typical token accounts, standard Solana NFT tracking methods (e.g., “watch the mint address” or “subscribe to a token account”) won’t work. Instead, you focus on program instructions or the Merkle tree account.

2. Why listen for cNFT Events?

Imagine building a marketplace, wallet, or analytics dashboard around cNFTs. You need to know:

When new cNFTs are minted.
Which cNFTs are transferred to or from a user.
Whether a cNFT was burned.

Receiving these updates in real time helps you keep your interface or data layer in perfect sync with on-chain state. Combined with historical lookups, you gain a complete timeline of cNFT activity, from the moment it was created to its current status.

3. Event Listening Methods

Helius offers three major ways to listen for cNFT events:

Standard WebSockets: Simple persistent connection for basic program monitoring
Enhanced WebSockets: Advanced filtering with better transaction targeting
gRPC (Yellowstone): Maximum performance and flexibility via LaserStream or Dedicated Nodes

Choose based on your needs: Standard WebSockets for simplicity, Enhanced WebSockets for better filtering, or gRPC for enterprise-scale applications with the highest performance.

3.1 Standard WebSockets

Standard WebSockets

Persistent connection: You subscribe to accounts or programs, and Solana pushes updates.

const WebSocket = require('ws');

// Replace <API_KEY> with your actual API key
const HELIUS_WS_URL = 'wss://mainnet.helius-rpc.com/?api-key=<API_KEY>';
const ws = new WebSocket(HELIUS_WS_URL);

// Keep connection alive with periodic pings
function startPing(ws) {
  setInterval(() => {
    if (ws.readyState === WebSocket.OPEN) {
      ws.ping();
    }
  }, 30000); // Ping every 30 seconds
}

ws.on('open', () => {
  console.log('Connected to Helius WebSocket');
  
  // Start pinging to keep connection alive
  startPing(ws);

  // Subscribe to the Bubblegum program to catch cNFT events
  const subscribeMsg = {
    jsonrpc: '2.0',
    id: 1,
    method: 'programSubscribe',
    params: [
      'BGUMAp9Gq7iTEuizy4pqaxsTyUCBK68MDfK752saRPUY', // Bubblegum program ID
      { 
        commitment: 'confirmed',
        encoding: 'jsonParsed'
      }
    ]
  };

  ws.send(JSON.stringify(subscribeMsg));
});

ws.on('message', (rawData) => {
  try {
    const data = JSON.parse(rawData);
    console.log('New cNFT event:', data);
    
    // Check if this is a subscription result or notification
    if (data.method === 'programNotification') {
      console.log('Program notification received:', data.params);
      // Parse for mints/transfers/burns in the instruction data
    }
  } catch (err) {
    console.error('Failed to parse WS message:', err);
  }
});

ws.on('error', (err) => {
  console.error('WebSocket error:', err);
});

ws.on('close', () => {
  console.log('WebSocket closed');
});

3.2 Enhanced WebSockets

Enhanced WebSockets

Enhanced WebSocket with advanced filters (accountInclude, accountRequired, etc.).
Reduces parsing overhead because you only receive transactions relevant to your addresses.
Real-time filtering ensures you only get the transactions you care about.

const WebSocket = require('ws');

// Note: No /? in the URL, just ?
const HELIUS_ENHANCED_WS_URL = 'wss://atlas-mainnet.helius-rpc.com?api-key=<API_KEY>';
const ws = new WebSocket(HELIUS_ENHANCED_WS_URL);

ws.on('open', () => {
  console.log('Connected to Enhanced WebSocket');
  
  // Send subscription request
  const subscribeRequest = {
    jsonrpc: '2.0',
    id: 420,
    method: 'transactionSubscribe',
    params: [
      // Filter object
      {
        failed: false,
        vote: false,
        accountInclude: ['MERKLE_TREE_ADDRESS'] // Replace with your Merkle tree address
      },
      // Options object
      {
        commitment: 'confirmed',
        encoding: 'jsonParsed',
        transactionDetails: 'full',
        showRewards: false,
        maxSupportedTransactionVersion: 0
      }
    ]
  };

  ws.send(JSON.stringify(subscribeRequest));
  
  // Keep connection alive with periodic pings
  setInterval(() => {
    if (ws.readyState === WebSocket.OPEN) {
      ws.ping();
      console.log('Ping sent');
    }
  }, 30000); // Ping every 30 seconds
});

ws.on('message', (data) => {
  const messageStr = data.toString('utf8');
  try {
    const payload = JSON.parse(messageStr);
    const result = payload.params?.result;
    
    if (!result) {
      console.log('Subscription confirmation:', payload);
      return;
    }

    console.log('Enhanced cNFT transaction detected!');
    console.log('Signature:', result.signature);
    console.log('Slot:', result.slot);
    
    // Check transaction logs for cNFT operations
    const logs = result.transaction?.meta?.logMessages || [];
    const hasBubblegumLogs = logs.some(log => 
      log.includes('BGUMAp9Gq7iTEuizy4pqaxsTyUCBK68MDfK752saRPUY')
    );
    
    if (hasBubblegumLogs) {
      console.log('Bubblegum program interaction detected - likely cNFT operation');
      console.log('Transaction logs:', logs);
    }

    // Access transaction instructions
    const instructions = result.transaction?.transaction?.message?.instructions || [];
    instructions.forEach((instruction, index) => {
      console.log(`Instruction ${index}:`, instruction);
    });

  } catch (err) {
    console.error('Failed to parse Enhanced WS message:', err);
  }
});

ws.on('error', (err) => {
  console.error('Enhanced WebSocket error:', err);
});

ws.on('close', () => {
  console.log('Enhanced WebSocket closed');
});

For monitoring specific cNFT programs:

// Monitor Bubblegum program directly
const BUBBLEGUM_PROGRAM_ID = 'BGUMAp9Gq7iTEuizy4pqaxsTyUCBK68MDfK752saRPUY';

const subscribeRequest = {
  jsonrpc: '2.0',
  id: 420,
  method: 'transactionSubscribe',
  params: [
    {
      failed: false,
      vote: false,
      accountInclude: [BUBBLEGUM_PROGRAM_ID] // Monitor all Bubblegum transactions
    },
    {
      commitment: 'confirmed',
      encoding: 'jsonParsed',
      transactionDetails: 'full',
      maxSupportedTransactionVersion: 0
    }
  ]
};

3.3 Webhooks

Webhooks let Helius notify your server via HTTP POST whenever an on-chain event occurs. Ideal if you don’t want a persistent connection.

Create the webhook via API, SDK or Dashboard.
Specify addresses to watch (Merkle tree address, user wallet, etc.).
Receive transaction data on your server endpoint; parse for cNFT instructions.

Creating a Webhook (API Example):

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "webhookURL": "https://myapp.com/cnft-webhook",
    "transactionTypes": ["ANY"],
    "accountAddresses": ["MERKLE_TREE_ADDRESS"],
    "webhookType": "enhanced",
    "authHeader": "Bearer your-auth-token",
    "txnStatus": "all",
    "encoding": "jsonParsed"
  }' \
  "https://api.helius.xyz/v0/webhooks?api-key=<YOUR_API_KEY>"

JavaScript Example:

const fetch = require('node-fetch');

async function createCNFTWebhook() {
  const webhookData = {
    webhookURL: 'https://myapp.com/cnft-webhook',
    transactionTypes: ['ANY'], // Monitor all transaction types
    accountAddresses: ['MERKLE_TREE_ADDRESS'], // Replace with your Merkle tree address
    webhookType: 'enhanced', // Get parsed transaction data
    authHeader: 'Bearer your-auth-token', // Optional: secure your webhook
    txnStatus: 'all', // Monitor both success and failed transactions
    encoding: 'jsonParsed'
  };

  const response = await fetch('https://api.helius.xyz/v0/webhooks?api-key=<YOUR_API_KEY>', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(webhookData),
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const webhook = await response.json();
  console.log('Webhook created:', webhook);
  return webhook;
}

createCNFTWebhook().catch(console.error);

Webhook Payload Structure: When your webhook endpoint receives a notification, it will contain structured data like:

{
  "accountData": [
    {
      "account": "MERKLE_TREE_ADDRESS",
      "nativeBalanceChange": 0,
      "tokenBalanceChanges": []
    }
  ],
  "description": "Compressed NFT Mint",
  "events": {
    "compressed": {
      "type": "COMPRESSED_NFT_MINT",
      "treeId": "MERKLE_TREE_ADDRESS",
      "assetId": "...",
      "leafIndex": 12,
      "instructionIndex": 1,
      "newLeafOwner": "UserWalletAddress"
    }
  },
  "fee": 5000,
  "feePayer": "PAYER_ADDRESS",
  "signature": "TRANSACTION_SIGNATURE",
  "slot": 1234567,
  "timestamp": 1234567890000,
  "type": "COMPRESSED_NFT_MINT"
}

3.4 gRPC (Yellowstone)

gRPC is the most flexible and high-performance event listening solution, available through LaserStream or Dedicated Nodes.

Advanced filtering (memcmp, owners, accounts, etc.).
Enterprise-level throughput for large-scale apps.
LaserStream: Multi-tenant gRPC service with automatic failover and historical replay.
Dedicated Nodes: Exclusive gRPC endpoint with guaranteed resource isolation.

Complete Example (TypeScript with robust stream management):

# First install dependencies
npm install @triton-one/yellowstone-grpc
npm install typescript @types/node --save-dev

import Client, { CommitmentLevel, SubscribeRequest } from "@triton-one/yellowstone-grpc";

class CNFTStreamManager {
  private client: Client;
  private stream: any;
  private isConnected = false;
  private reconnectAttempts = 0;
  private readonly maxReconnectAttempts = 10;
  private readonly baseReconnectDelay = 1000;

  constructor(
    private endpoint: string,
    private apiKey: string,
    private onCNFTEvent: (data: any) => void
  ) {
    this.client = new Client(endpoint, apiKey, {
      "grpc.max_receive_message_length": 64 * 1024 * 1024
    });
  }

  async connect(merkleTreeAddress: string): Promise<void> {
    try {
      console.log(`Connecting to gRPC endpoint: ${this.endpoint}`);
      
      const subscribeRequest: SubscribeRequest = {
        commitment: CommitmentLevel.CONFIRMED,
        accounts: {
          merkleTreeAccount: {
            account: [merkleTreeAddress],
            owner: [],
            filters: []
          }
        },
        accountsDataSlice: [],
        transactions: {
          cnftTransactions: {
            accountInclude: [merkleTreeAddress],
            accountExclude: [],
            accountRequired: [],
            vote: false,
            failed: false
          }
        },
        blocks: {},
        blocksMeta: {},
        entry: {},
        slots: {},
        transactionsStatus: {},
        ping: { id: 1 } // Keep connection alive
      };

      this.stream = await this.client.subscribe();
      
      this.stream.on("data", (data: any) => {
        if (data.account) {
          console.log("Merkle tree account update:", data.account);
          this.onCNFTEvent({
            type: 'account_update',
            account: data.account
          });
        }
        
        if (data.transaction) {
          console.log("Transaction involving cNFT:", data.transaction.signature);
          this.onCNFTEvent({
            type: 'transaction',
            transaction: data.transaction
          });
        }
      });

      this.stream.on("error", (error: any) => {
        console.error("Stream error:", error);
        this.handleReconnect();
      });

      this.stream.on("close", () => {
        console.log("Stream closed");
        this.isConnected = false;
      });

      // Send subscription request
      await this.writeRequest(subscribeRequest);
      this.isConnected = true;
      this.reconnectAttempts = 0;
      
      console.log("Successfully connected to gRPC stream");
      
    } catch (error) {
      console.error("Failed to connect:", error);
      this.handleReconnect();
    }
  }

  private async writeRequest(request: SubscribeRequest): Promise<void> {
    return new Promise((resolve, reject) => {
      this.stream.write(request, (err: any) => {
        if (err) {
          reject(err);
        } else {
          resolve();
        }
      });
    });
  }

  private async handleReconnect(): Promise<void> {
    if (this.reconnectAttempts >= this.maxReconnectAttempts) {
      console.error("Max reconnection attempts reached");
      return;
    }

    this.reconnectAttempts++;
    const delay = this.baseReconnectDelay * Math.pow(2, this.reconnectAttempts - 1);
    
    console.log(`Reconnecting in ${delay}ms... (attempt ${this.reconnectAttempts})`);
    
    setTimeout(() => {
      this.connect("MERKLE_TREE_ADDRESS").catch(console.error);
    }, delay);
  }

  disconnect(): void {
    if (this.stream) {
      this.stream.end();
    }
    this.client.close();
    this.isConnected = false;
  }
}

// Usage example
async function monitorCNFTTree() {
  const endpoint = "https://laserstream-mainnet-ewr.helius-rpc.com"; // Choose your region
  const apiKey = "your-api-key";
  const merkleTreeAddress = "MERKLE_TREE_ADDRESS";

  const manager = new CNFTStreamManager(
    endpoint,
    apiKey,
    (eventData) => {
      console.log("cNFT Event received:", eventData);
      
      // Process different event types
      if (eventData.type === 'account_update') {
        console.log("Merkle tree state changed");
        // Handle account update - tree root may have changed
      } else if (eventData.type === 'transaction') {
        console.log("Transaction affecting cNFT detected");
        // Parse transaction for mint/transfer/burn operations
      }
    }
  );

  await manager.connect(merkleTreeAddress);
  
  // Keep running until interrupted
  process.on('SIGINT', () => {
    console.log("Shutting down...");
    manager.disconnect();
    process.exit(0);
  });
}

monitorCNFTTree().catch(console.error);

4. Retrieving Historical cNFT Data

Real-time event feeds are great for capturing future events. But what if you need the past—the entire lifetime of a cNFT or all transactions that impacted a Merkle tree or wallet? In this section, we’ll explore two primary methods for historical lookups:

Helius’ Parsed Transaction API
Normal Solana RPC Calls: getSignaturesForAddress + getParsedTransaction or getTransaction

4.1 Helius’ Enhanced Transaction API

Helius offers an Enhanced Transaction API. It automatically decodes NFT, SPL, and Swap transactions into a human-readable format. This saves you from manually parsing raw data. 4.1.1 Single or Batched Transactions (/v0/transactions) Endpoint:

Mainnet: https://api.helius.xyz/v0/transactions?api-key=<YOUR_API_KEY>
Devnet: https://api-devnet.helius.xyz/v0/transactions?api-key=<YOUR_API_KEY>

You send up to 100 transaction signatures in the request body, and Helius returns an array of parsed transactions. Example:

async function parseMultipleTransactions(signatures) {
  const url = 'https://api.helius.xyz/v0/transactions?api-key=<YOUR_API_KEY>';

  const response = await fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ 
      transactions: signatures,
      commitment: 'confirmed' // Optional: specify commitment level
    })
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const parsedTxs = await response.json();
  
  // Filter for cNFT-related transactions
  const cnftTransactions = parsedTxs.filter(tx => {
    return tx.events && tx.events.compressed;
  });

  console.log("Parsed cNFT transactions:", JSON.stringify(cnftTransactions, null, 2));
  return cnftTransactions;
}

// Usage with error handling
parseMultipleTransactions([
  "5rfFLBUp5YPr6rC2g1KBBW8LGZBcZ8Lvs7gKAdgrBjmQvFf6EKkgc5cpAQUTwGxDJbNqtLYkjV5vS5zVK4tb6JtP",
  "4jzQxVTaJ4Fe4Fct9y1aaT9hmVyEjpCqE2bL8JMnuLZbzHZwaL4kZZvNEZ6bEj6fGmiAdCPjmNQHCf8v994PAgDf"
]).catch(console.error);

Within each parsed transaction, you may find a compressed object under events, indicating a cNFT mint, transfer, or burn:

"compressed": {
  "type": "COMPRESSED_NFT_MINT",
  "treeId": "MERKLE_TREE_ADDRESS",
  "assetId": "...",
  "leafIndex": 12,
  "instructionIndex": 1,
  "newLeafOwner": "UserWalletAddress",
  ...
}

4.1.2 Parsed Transactions by Address (/v0/addresses/{address}/transactions) If you want parsed transactions for a specific address—say a Merkle tree or user wallet—you can call:

Mainnet: https://api.helius.xyz/v0/addresses/{address}/transactions?api-key=<YOUR_API_KEY>
Devnet: https://api-devnet.helius.xyz/v0/addresses/{address}/transactions?api-key=<YOUR_API_KEY>

Example:

async function getParsedHistoryForAddress(address) {
  // Add pagination support and error handling
  const url = `https://api.helius.xyz/v0/addresses/${address}/transactions?api-key=<YOUR_API_KEY>&limit=50`;

  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const parsedHistory = await response.json();
  
  // Filter for cNFT-related transactions
  const cnftTransactions = parsedHistory.filter(tx => {
    return tx.events && tx.events.compressed;
  });

  console.log("Parsed cNFT history:", JSON.stringify(cnftTransactions, null, 2));

  // Example of pagination - get next page if needed
  if (parsedHistory.length === 50) {
    const lastSignature = parsedHistory[parsedHistory.length - 1].signature;
    console.log(`More transactions available. Use before=${lastSignature} for next page`);
  }

  return cnftTransactions;
}

// Usage with error handling
getParsedHistoryForAddress("MERKLE_TREE_ADDRESS_OR_USER_WALLET").catch(console.error);

4.2 Normal Methods: `getSignaturesForAddress` + `getParsedTransaction` / `getTransaction`

If you prefer the traditional Solana approach or want maximum control, you can call Solana’s native RPC methods:

getSignaturesForAddress: Returns an array of transaction signatures involving the given address (e.g., the Merkle tree or user’s wallet).
getParsedTransaction: Returns a Solana-parsed JSON for a given signature.
getTransaction: Returns the raw binary-encoded transaction, which you can parse using an external library (e.g., Blockbuster) if you need specialized cNFT decoding.

4.2.1 getSignaturesForAddress This is a pagination-friendly method. You can pass before or until parameters. Example:

async function fetchSignatures(address, limit = 10) {
  const rpcUrl = "https://mainnet.helius-rpc.com/?api-key=<YOUR_API_KEY>";
  const body = {
    jsonrpc: "2.0",
    id: 1,
    method: "getSignaturesForAddress",
    params: [
      address,
      { 
        limit: limit,
        commitment: "confirmed"
      }
    ]
  };

  const response = await fetch(rpcUrl, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body)
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const data = await response.json();
  
  if (data.error) {
    throw new Error(`RPC error: ${data.error.message}`);
  }

  console.log("Signatures for address:", data.result);
  return data.result;
}

// Usage with error handling
fetchSignatures("MERKLE_TREE_ADDRESS").catch(console.error);

4.2.2 getParsedTransaction or getTransaction Once you have the signatures, retrieve each transaction’s details:

async function fetchTransaction(signature, encoding = "jsonParsed") {
  const rpcUrl = "https://mainnet.helius-rpc.com/?api-key=<YOUR_API_KEY>";
  const body = {
    jsonrpc: "2.0",
    id: 1,
    method: "getTransaction",
    params: [
      signature, 
      {
        encoding: encoding,
        commitment: "confirmed",
        maxSupportedTransactionVersion: 0
      }
    ]
  };

  const response = await fetch(rpcUrl, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body)
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const data = await response.json();
  
  if (data.error) {
    throw new Error(`RPC error: ${data.error.message}`);
  }

  console.log("Transaction:", JSON.stringify(data.result, null, 2));
  return data.result;
}

// Usage:
fetchTransaction("TransactionSignature").catch(console.error);

Look for instructions referencing the cNFT program or the Merkle tree. If you use getTransaction instead, you’ll get raw data (e.g., base64), which you’d decode with a specialized parser.

5. Putting It All Together

Listen for cNFT Events
- Pick a method: WebSockets, Webhooks, or gRPC.
- Filter for the cNFT program or a Merkle tree address.
- Parse instructions in real time to track mints, transfers, and burns.
Retrieve Historical Data
- Helius Enhanced Transaction API: The easiest way to get a human-readable breakdown of cNFT actions.
- Normal RPC: getSignaturesForAddress + getParsedTransaction (or getTransaction + manual parsing) for maximum flexibility or if you already rely on standard Solana RPC calls.
Build a Complete Timeline
- Merge future (real-time) events with past (historical) data.
- If your event listening solution ever goes down, fill gaps by pulling recent transaction signatures for your Merkle tree or user address.

6. Next Steps and Best Practices

Leverage Helius: The Enhanced Transaction API is particularly handy if you want cNFT events (mints, transfers, burns) in a straightforward JSON format.
Pagination: For addresses with a lot of activity, you may need to iterate with before or until to get older data.
Verification: For extra security, you can verify Merkle proofs to confirm a cNFT leaf is valid under the on-chain root.
Indexing: If you’re building a large-scale solution, consider storing parsed cNFT events in your own database for quick queries.
Performance: For high-volume event listening, gRPC (via LaserStream or Dedicated Nodes) offers top performance and advanced filters.
Error Handling: Always implement proper error handling and retry logic for production applications.
Connection Management: For WebSocket connections, implement heartbeat/ping mechanisms to maintain connections.
Rate Limiting: Be aware of API rate limits and implement appropriate throttling in your applications.

Happy building!

Get Started

Solana RPC Nodes

Data Streaming & Event Listening

How to Send Transactions

Getting Data

Dedicated Nodes

Compression

Staking

Billing

Resources

Solana Compressed NFT Event Listening

1. Understanding cNFTs and Their Event Lifecycle

Key Points:

2. Why listen for cNFT Events?

3. Event Listening Methods

3.1 Standard WebSockets

3.2 Enhanced WebSockets

3.3 Webhooks

3.4 gRPC (Yellowstone)

4. Retrieving Historical cNFT Data

4.1 Helius’ Enhanced Transaction API

4.2 Normal Methods: `getSignaturesForAddress` + `getParsedTransaction` / `getTransaction`

5. Putting It All Together

6. Next Steps and Best Practices

Get Started

Solana RPC Nodes

Data Streaming & Event Listening

How to Send Transactions

Getting Data

Dedicated Nodes

Compression

Staking

Billing

Resources

​1. Understanding cNFTs and Their Event Lifecycle

​Key Points:

​2. Why listen for cNFT Events?

​3. Event Listening Methods

​3.1 Standard WebSockets

​3.2 Enhanced WebSockets

​3.3 Webhooks

​3.4 gRPC (Yellowstone)

​4. Retrieving Historical cNFT Data

​4.1 Helius’ Enhanced Transaction API

​4.2 Normal Methods: getSignaturesForAddress + getParsedTransaction / getTransaction

​5. Putting It All Together

​6. Next Steps and Best Practices

1. Understanding cNFTs and Their Event Lifecycle

Key Points:

2. Why listen for cNFT Events?

3. Event Listening Methods

3.1 Standard WebSockets

3.2 Enhanced WebSockets

3.3 Webhooks

3.4 gRPC (Yellowstone)

4. Retrieving Historical cNFT Data

4.1 Helius’ Enhanced Transaction API

4.2 Normal Methods: `getSignaturesForAddress` + `getParsedTransaction` / `getTransaction`

5. Putting It All Together

6. Next Steps and Best Practices