# LaserStream — High-Performance gRPC Streaming

## What LaserStream Is

LaserStream is a next-generation gRPC streaming service for Solana data. It is a drop-in replacement for Yellowstone gRPC with significant advantages:

- **Ultra-low latency**: taps directly into Solana leaders to receive shreds as they're produced
- **24-hour historical replay**: replay up to 216,000 slots (~24 hours) of data after disconnections via `from_slot`
- **Auto-reconnect**: built-in reconnection with automatic replay of missed data via the SDKs
- **Multi-node failover**: redundant node clusters with automatic load balancing
- **40x faster** than JavaScript Yellowstone clients (Rust core with zero-copy NAPI bindings)
- **9 global regions** for minimal latency
- **Mainnet requires Professional plan** ($999/mo); Devnet available on Developer+ plans
- 3 credits per 0.1 MB of streamed data (uncompressed)

## MCP Tools and SDK Workflow

LaserStream has two MCP tools that work together with the SDK:

1. **`getLaserstreamInfo`** — Returns current capabilities, regional endpoints, pricing, and SDK info. Use this first to check plan requirements and choose the right region.
2. **`laserstreamSubscribe`** — Validates subscription parameters and generates the correct subscription config JSON + ready-to-use SDK code example. Use this to build the subscription.

**Important**: The MCP tools are config generators, not live streams. gRPC streams cannot run over MCP's stdio protocol. The workflow is:

1. Use `getLaserstreamInfo` to get endpoint and capability details
2. Use `laserstreamSubscribe` with the user's requirements to generate the correct subscription config and SDK code
3. The generated code uses the `helius-laserstream` SDK — place it in the user's application code where the actual gRPC stream will run

ALWAYS use the MCP tools first to generate correct configs, then embed the SDK code they produce into the user's project.

## Endpoints

Choose the region closest to your infrastructure:

### Mainnet

| Region | Location | Endpoint |
|---|---|---|
| ewr | Newark, NJ | `https://laserstream-mainnet-ewr.helius-rpc.com` |
| pitt | Pittsburgh | `https://laserstream-mainnet-pitt.helius-rpc.com` |
| slc | Salt Lake City | `https://laserstream-mainnet-slc.helius-rpc.com` |
| lax | Los Angeles | `https://laserstream-mainnet-lax.helius-rpc.com` |
| lon | London | `https://laserstream-mainnet-lon.helius-rpc.com` |
| ams | Amsterdam | `https://laserstream-mainnet-ams.helius-rpc.com` |
| fra | Frankfurt | `https://laserstream-mainnet-fra.helius-rpc.com` |
| tyo | Tokyo | `https://laserstream-mainnet-tyo.helius-rpc.com` |
| sgp | Singapore | `https://laserstream-mainnet-sgp.helius-rpc.com` |

### Devnet

```
https://laserstream-devnet-ewr.helius-rpc.com
```

## Subscription Types

LaserStream supports 7 subscription types that can be combined in a single request:

| Type | What It Streams | Key Filters |
|---|---|---|
| **accounts** | Account data changes | `account` (pubkey list), `owner` (program list), `filters` (memcmp, datasize, lamports) |
| **transactions** | Full transaction data | `account_include`, `account_exclude`, `account_required`, `vote`, `failed` |
| **transactions_status** | Tx status only (lighter) | Same filters as transactions |
| **slots** | Slot progress | `filter_by_commitment`, `interslot_updates` |
| **blocks** | Full block data | `account_include`, `include_transactions`, `include_accounts`, `include_entries` |
| **blocks_meta** | Block metadata only (lighter) | None (all blocks) |
| **entry** | Block entries | None (all entries) |

### Commitment Levels

All subscriptions support:
- `PROCESSED` (0): processed by current node — fastest, least certainty
- `CONFIRMED` (1): confirmed by supermajority — good default
- `FINALIZED` (2): finalized by cluster — most certain, higher latency

### Historical Replay

Set `from_slot` to replay data from a past slot (up to 216,000 slots / ~24 hours back). The SDK handles this automatically on reconnection.

## Implementation Pattern — Using the LaserStream SDK

ALWAYS start by calling the `laserstreamSubscribe` MCP tool with the user's requirements. It will generate validated config and SDK code. The example below shows what the generated code looks like.

The `helius-laserstream` SDK is the recommended way to connect. It handles reconnection, historical replay, and optimized data handling automatically.

```typescript
import { subscribe, CommitmentLevel } from 'helius-laserstream';

const config = {
  apiKey: "your-helius-api-key",
  endpoint: "https://laserstream-mainnet-ewr.helius-rpc.com",
};

// Subscribe to transactions for specific accounts
const request = {
  transactions: {
    client: "my-app",
    accountInclude: ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"],
    accountExclude: [],
    accountRequired: [],
    vote: false,
    failed: false,
  },
  commitment: CommitmentLevel.CONFIRMED,
};

await subscribe(
  config,
  request,
  (data) => {
    console.log("Update:", data);
  },
  (error) => {
    console.error("Error:", error);
  }
);
```

SDK repo: `https://github.com/helius-labs/laserstream-sdk`

## Transaction Filtering

Transaction subscriptions support three address filter types:

- **`account_include`**: transactions must involve ANY of these addresses (OR logic, up to 10M pubkeys)
- **`account_exclude`**: exclude transactions involving these addresses
- **`account_required`**: transactions must involve ALL of these addresses (AND logic)

```json
{
  "transactions": {
    "account_include": ["PROGRAM_ID_1", "PROGRAM_ID_2"],
    "account_exclude": ["VOTE_PROGRAM"],
    "account_required": ["MUST_HAVE_THIS_ACCOUNT"],
    "vote": false,
    "failed": false
  },
  "commitment": 1
}
```

## Account Filtering

Account subscriptions support:

- **`account`**: specific pubkeys to monitor
- **`owner`**: monitor all accounts owned by these programs
- **`filters`**: advanced filtering on account data
  - `memcmp`: match bytes at a specific offset
  - `datasize`: exact account data size in bytes
  - `token_account_state`: filter to only token accounts
  - `lamports`: filter by SOL balance (`eq`, `ne`, `lt`, `gt`)

```json
{
  "accounts": {
    "my-label": {
      "account": ["SPECIFIC_PUBKEY"],
      "owner": ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"],
      "filters": {
        "datasize": 165,
        "token_account_state": true
      },
      "nonempty_txn_signature": true
    }
  },
  "commitment": 1
}
```

## Migrating from Yellowstone gRPC

LaserStream is a drop-in replacement. Just change the endpoint and auth token:

```typescript
// Before: Yellowstone gRPC
const connection = new GeyserConnection(
  "your-current-endpoint.com",
  { token: "your-current-token" }
);

// After: LaserStream
const connection = new GeyserConnection(
  "https://laserstream-mainnet-ewr.helius-rpc.com",
  { token: "your-helius-api-key" }
);
```

All existing Yellowstone gRPC code works unchanged.

## Utility Methods

LaserStream also provides standard gRPC utility methods:

| Method | Description |
|---|---|
| `GetBlockHeight` | Current block height |
| `GetLatestBlockhash` | Latest blockhash + last valid block height |
| `GetSlot` | Current slot number |
| `GetVersion` | API and Solana node version info |
| `IsBlockhashValid` | Check if a blockhash is still valid |
| `Ping` | Connection health check |

## LaserStream vs Enhanced WebSockets

| Feature | LaserStream | Enhanced WebSockets |
|---|---|---|
| Protocol | gRPC | WebSocket |
| Latency | Lowest (shred-level) | Low (1.5-2x faster than standard WS) |
| Historical replay | Yes (24 hours) | No |
| Auto-reconnect | Built-in with replay | Manual |
| Plan required | Professional (mainnet) | Business+ |
| Max pubkeys | 10M | 50K |
| Best for | Indexers, bots, high-throughput pipelines | Real-time UIs, dashboards, monitoring |
| SDK | `helius-laserstream` | Raw WebSocket |
| Yellowstone compatible | Yes (drop-in) | No |

**Use LaserStream when**: you're building an indexer, high-frequency trading system, or anything that needs the lowest possible latency, historical replay, or processes high data volumes.

**Use Enhanced WebSockets when**: you're building a real-time UI, dashboard, or monitoring tool that needs simpler WebSocket-based integration and doesn't need historical replay.

Use the `getLatencyComparison` MCP tool to show the user detailed tradeoffs.

## Common Patterns

### Monitor a specific program

```json
{
  "transactions": {
    "account_include": ["YOUR_PROGRAM_ID"],
    "vote": false,
    "failed": false
  },
  "commitment": 1
}
```

### Stream all token transfers

```json
{
  "transactions": {
    "account_include": ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"],
    "vote": false,
    "failed": false
  },
  "commitment": 1
}
```

### Track account balance changes

```json
{
  "accounts": {
    "balance-watch": {
      "account": ["WALLET_ADDRESS_1", "WALLET_ADDRESS_2"],
      "nonempty_txn_signature": true
    }
  },
  "commitment": 1
}
```

### Combined subscription with historical replay

```json
{
  "accounts": {
    "my-accounts": {
      "account": ["PUBKEY"],
      "nonempty_txn_signature": true
    }
  },
  "slots": {
    "filter_by_commitment": true
  },
  "commitment": 2,
  "from_slot": 139000000,
  "ping": { "id": 123 }
}
```

## Best Practices

- ALWAYS use the `laserstreamSubscribe` MCP tool to generate subscription configs — it validates parameters and produces correct SDK code
- Choose the closest regional endpoint to minimize latency
- Use the LaserStream SDK (`helius-laserstream`) — it handles reconnection and replay automatically
- Filter aggressively — only subscribe to accounts/transactions you need to minimize data transfer and credit usage
- Use `CONFIRMED` commitment for most use cases; `FINALIZED` only when absolute certainty is required
- For partial account data, use `accounts_data_slice` to reduce bandwidth (specify offset + length)
- Implement ping messages for connection health monitoring in long-running subscriptions
- Use `transactions_status` instead of `transactions` when you only need status (lighter payload)

## Common Mistakes

- Using LaserStream for simple real-time features that Enhanced WebSockets can handle (unnecessary complexity)
- Not setting `from_slot` after reconnection (misses data during the disconnect gap)
- Subscribing to all transactions without filters (massive data volume and credit burn)
- Forgetting that mainnet requires the Professional plan
- Using `PROCESSED` commitment for financial decisions (can be rolled back)
- Not choosing the closest regional endpoint (adds unnecessary latency)