LaserStream gRPC
Highly configurable low-latency data streams using gRPC.
Overview
LaserStream’s gRPC offering builds on a Yellowstone-based interface and enhances it with features like historical replay, multi-node failover, and a fully managed environment. LaserStream uses the open source gRPC protocol, ensuring no vendor lock-in and maximum compatibility with existing gRPC implementations.
You can connect either directly with @yellowstone-grpc
or use the higher-level Helius LaserStream SDK for added benefits (auto-reconnect, subscription management, error handling, etc.).
Performance Notice: If you experience any lag or performance issues with your LaserStream connection, please refer to the Troubleshooting section for common causes and solutions related to client performance and network optimization.
Endpoints & Regions
LaserStream is available in multiple regions worldwide. Choose the endpoint closest to your application for optimal performance:
Mainnet Endpoints
Region | Location | Endpoint |
---|---|---|
ewr | New York, US (East Coast) | https://laserstream-mainnet-ewr.helius-rpc.com |
pitt | Pittsburgh, US (Central) | https://laserstream-mainnet-pitt.helius-rpc.com |
slc | Salt Lake City, US (West Coast) | https://laserstream-mainnet-slc.helius-rpc.com |
ams | Amsterdam, Europe | https://laserstream-mainnet-ams.helius-rpc.com |
fra | Frankfurt, Europe | https://laserstream-mainnet-fra.helius-rpc.com |
tyo | Tokyo, Asia | https://laserstream-mainnet-tyo.helius-rpc.com |
sgp | Singapore, Asia | https://laserstream-mainnet-sgp.helius-rpc.com |
Devnet Endpoint
Network | Location | Endpoint |
---|---|---|
Devnet | New York, US (East Coast) | https://laserstream-devnet-ewr.helius-rpc.com |
Network & Region Selection:
- For production applications, choose the mainnet endpoint closest to your server for best performance. For example, if deploying in Europe, use either the Amsterdam (
ams
) or Frankfurt (fra
) endpoint. - For development and testing, use the devnet endpoint:
https://laserstream-devnet-ewr.helius-rpc.com
.
Quickstart
Create a New Project
Install Dependencies
Obtain Your API Key
Generate a key from the Helius Dashboard. This key will serve as your authentication token for LaserStream.
Professional Plan Required: LaserStream requires a Professional plan. Ensure your Helius account is upgraded to access LaserStream features.
Create a Subscription Script
Create index.ts
with the following:
Replace Your API Key and Choose Your Region
In index.ts
, update the config
object with:
- Your actual API key from the Helius Dashboard
- The LaserStream endpoint closest to your server location
Network & Region Selection Examples:
- For Production (Mainnet):
- Europe: Use
fra
(Frankfurt) orams
(Amsterdam) - US East: Use
ewr
(New York) - US West: Use
slc
(Salt Lake City) - Asia: Use
tyo
(Tokyo) orsgp
(Singapore)
- Europe: Use
- For Development (Devnet): Use
https://laserstream-devnet-ewr.helius-rpc.com
Run and View Results
Whenever a confirmed
token transaction involves TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
, you’ll see the data in your console.
Subscribe Request
In the subscribe request, you need to include the following general parameters:
Historical Replay: You can optionally include a fromSlot: string
field in the main SubscribeRequest
object to replay data from a specific slot onwards. Currently, replay is supported for up to 3000 slots in the past.
Next, you’ll need to specify the filters for the data you want to subscribe to, such as accounts, blocks, slots, or transactions.
Slots
Slots
Define filters for slot updates. The key you use (e.g., mySlotLabel
) is a user-defined label for this specific filter configuration, allowing you to potentially define multiple named configurations if needed (though typically one is sufficient).
Accounts
Accounts
Define filters for account data updates. The key you use (e.g., tokenAccounts
) is a user-defined label for this specific filter configuration.
If all fields are empty, all accounts are broadcasted. Otherwise:
- Fields operate as a logical AND.
- Values within arrays act as a logical OR (except within
filters
, which operate as a logical AND).
Transaction
Transaction
Define filters for transaction updates. The key you use (e.g., myTxSubscription
) is a user-defined label for this specific filter configuration.
If all fields are left empty, all transactions are broadcasted. Otherwise:
- Fields operate as a logical AND.
- Values within arrays are treated as a logical OR (except for
accountRequired
, where all must match).
Block
Block
Define filters for block updates. The key you use (e.g., myBlockLabel
) is a user-defined label for this specific filter configuration.
Blocks Meta
Blocks Meta
This functions similarly to Blocks but excludes transactions, accounts, and entries. The key you use (e.g., blockmetadata
) is a user-defined label for this subscription. Currently, no filters are available for block metadata—all messages are broadcasted by default.
Entries
Entries
Subscribe to ledger entries. The key you use (e.g., entrySubscribe
) is a user-defined label for this subscription. Currently, there are no filters available for entries; all entries are broadcasted.
Code Examples (LaserStream SDK)
Troubleshooting / FAQ
Q: I'm experiencing lag or slow performance with my LaserStream connection. What could be causing this?
Q: I'm experiencing lag or slow performance with my LaserStream connection. What could be causing this?
A: Performance issues with LaserStream connections are typically caused by:
-
Javascript Client Slowness: The JavaScript client may lag behind when processing too many messages or consuming too much bandwidth. Consider filtering your subscriptions more narrowly to reduce message volume or using another language.
-
Limited local bandwidth: Heavy subscriptions can overwhelm clients with limited network bandwidth. Monitor your network usage and consider upgrading your connection or reducing subscription scope.
-
Geographic distance: Running subscriptions against servers that are geographically far away can cause performance issues. TCP packets may get dropped on long routes, and you’re limited by the slowest intermediate network path. Solution: Choose the LaserStream endpoint closest to your server location from our available regions (see Endpoints & Regions above).
-
Client-side processing bottlenecks: Ensure your message processing logic is optimized and doesn’t block the main thread for extended periods.
Debugging Client Lag: To help you debug client, we built a tool to test for the max bandwidth from your node to a Laserstream gRPC server. To use it run:
The output returns the max network capacity between your server and the Laserstream server. At a minimum, you need 10MB/s to subscribe to all transaction data and 80MB/s to subscribe to all account data. We recommend having at least 2x the required capacity for optimal performance.
Q: I'm getting connection errors. What should I check?
Q: I'm getting connection errors. What should I check?
A: Verify your API key and endpoint are correct and that your network allows outbound gRPC connections to the specified endpoint. Check the Helius status page for any ongoing incidents.
Q: Why aren't my filters working as expected?
Q: Why aren't my filters working as expected?
A: Double-check the logical operators (AND/OR) described in the filter sections. Ensure public keys are correct. Review the commitment level specified in your request.
Q: Can I subscribe to multiple types of data (e.g., accounts and transactions) in one request?
Q: Can I subscribe to multiple types of data (e.g., accounts and transactions) in one request?
A: Yes, you can define filter configurations under multiple keys (e.g., accounts
, transactions
) within the same SubscribeRequest
object.