9 releases
new 0.2.2 | Nov 27, 2024 |
---|---|
0.2.1 | Jun 21, 2024 |
0.1.5 | May 29, 2024 |
#330 in Magic Beans
136 downloads per month
190KB
3.5K
SLoC
Helius SDK
An asynchronous Helius Rust SDK for building the future of Solana
Documentation
The latest documentation can be found here on docs.rs
Contributions
Interested in contributing to the Helius Rust SDK? Read the following contributions guide before opening up a pull request!
Installation
To start using the Helius Rust SDK in your project, add it as a dependency via cargo
. Open your project's Cargo.toml
and add the following line under [dependencies]
:
helius = "x.y.z"
where x.y.z
is your desired version. Alternatively, use cargo add helius
to add the dependency directly via the command line. This will automatically find the latest version compatible with your project and add it to your Cargo.toml
.
Remember to run cargo update
regularly to fetch the latest version of the SDK.
TLS Options
The Helius Rust SDK uses the native TLS implementation by default via:
[dependencies]
helius = "x.y.z"
However, the SDK also supports rustls
. Add the following to your Cargo.toml
to use rustls
instead of the native TLS implementation:
[dependencies]
helius = { version = "x.y.z", default-features = false, features = ["rustls"] }
Using rustls
may be preferred in environments where OpenSSL is not available or when a pure Rust TLS implementation is desired. However, it may not support all the same features as the native TLS implementation
Usage
Helius
The SDK provides a Helius
instance that can be configured with an API key and a given Solana cluster. Developers can generate a new API key on the Helius Developer Dashboard. This instance acts as the main entry point for interacting with the SDK by providing methods to access different Solana and RPC client functionalities. The following code is an example of how to use the SDK to fetch info on Mad Lad #8420:
use helius::error::Result;
use helius::types::{Cluster, DisplayOptions, GetAssetRequest, GetAssetResponseForAsset};
#[tokio::main]
async fn main() -> Result<()> {
let api_key: &str = "YOUR_API_KEY";
let cluster: Cluster = Cluster::MainnetBeta;
let helius: Helius = Helius::new(api_key, cluster).unwrap();
let request: GetAssetRequest = GetAssetRequest {
id: "F9Lw3ki3hJ7PF9HQXsBzoY8GyE6sPoEZZdXJBsTTD2rk".to_string(),
display_options: None,
};
let response: Result<Option<GetAssetResponseForAsset>> = helius.rpc().get_asset(request).await;
match response {
Ok(Some(asset)) => {
println!("Asset: {:?}", asset);
},
Ok(None) => println!("No asset found."),
Err(e) => println!("Error retrieving asset: {:?}", e),
}
Ok(())
}
HeliusFactory
The SDK also comes equipped with HeliusFactory
, a factory for creating instances of Helius
. This factory allows for a centralized configuration and creation of Helius
clients so work can be done across multiple clusters at the same time. Using a factory simplifies client code and enhances maintainability by ensuring that all Helius
clients are configured consistently. It has the following functionality:
- A
new
method used to create a newHeliusFactory
capable of producingHelius
clients. Note this method does not create areqwest
client - A
with_client
method used to provide a givenHeliusFactory
created with thenew
method its ownreqwest
client - A
create
method used to create multipleHelius
clients in a thread-safe manner
Embedded Solana Client
The Helius
client has an embedded Solana client that can be accessed via helius.connection().request_name()
where request_name()
is a given RPC method. A full list of all Solana RPC HTTP methods can be found here.
Note that this Solana client is synchronous by default. An asynchronous client can be created using the new_with_async_solana
method in place of the new
method. The asynchronous client can be accessed via helius.async_connection()?.some_async_method().await?
where some_async_method()
is a given async RPC method.
Enhanced WebSockets
The Helius
client can also be created with the new_with_ws()
method in place of the new
method. This will create a WebSocket client, adding support for the Geyser Enhanced WebSocket methods transactionSubscribe
and accountSubscribe
Examples
More examples of how to use the SDK can be found in the examples
directory.
Error Handling
Common Error Codes
You may encounter several error codes when working with the Helius Rust SDK. Below is a table detailing some of the common error codes along with additional information to aid with troubleshooting:
Error Code | Error Message | More Information |
---|---|---|
401 | Unauthorized | This occurs when an invalid API key is provided or access is restricted |
429 | Too Many Requests | This indicates that the user has exceeded the request limit in a given timeframe or is out of credits |
5XX | Internal Server Error | This is a generic error message for server-side issues. Please contact Helius support for assistance |
If you encounter any of these errors:
- Refer to
errors.rs
for a list of all possible errors returned by theHelius
client - Refer to the Helius documentation for further guidance
- Reach out to the Helius support team for more detailed assistance
Result Type Alias
The SDK also has a handy type alias for Result
where Result<(some type), HeliusError>
and be simplified to Result<(some type)>
Methods
Our SDK is designed to provide a seamless developer experience when building on Solana. We've separated the core functionality into various segments:
DAS API
get_asset
- Gets an asset by its IDget_asset_batch
- Gets multiple assets by their IDget_asset_proof
- Gets a merkle proof for a compressed asset by its IDget_asset_proof_batch
- Gets multiple asset proofs by their IDsget_assets_by_owner
- Gets a list of assets owned by a given addressget_assets_by_authority
- Gets a list of assets of a given authorityget_assets_by_creator
- Gets a list of assets of a given creatorget_assets_by_group
- Gets a list of assets by a group key and valuesearch_assets
- Gets assets based on the custom search criteria passed inget_signatures_for_asset
- Gets transaction signatures for a given assetget_token_accounts
- Gets information about all token accounts for a specific mint or ownerget_nft_edition
- Gets all the NFT editions associated with a specific master NFTget_rwa_asset
- Gets a Real-World Asset (RWA) based on its mint address
Mint API
mint_compressed_nft
- The easiest way to mint a compressed NFT (cNFT)
Enhanced Transactions API
parse_transactions
- Parses transactions given an array of transaction IDsparsed_transaction_history
- Retrieves a parsed transaction history for a specific address
Webhooks
append_addresses_to_webhook
- Appends a set of addresses to a given webhookcreate_webhook
- Creates a webhook given account addressesdelete_webhook
- Deletes a given Helius webhook programmaticallyedit_webhook
- Edits a Helius webhook programmaticallyget_all_webhooks
- Retrieves all Helius webhooks programmaticallyget_webhook_by_id
- Gets a webhook config given a webhook IDremove_addresses_from_webhook
- Removes a list of addresses from an existing webhook by its ID
Smart Transactions
create_smart_transaction
- Creates an optimized transaction based on the provided configurationget_compute_units
- Simulates a transaction to get the total compute units consumedpoll_transaction_confirmation
- Polls a transaction to check whether it has been confirmed in 5 second intervals with a 15 second timeoutsend_smart_transaction
- Builds and sends an optimized transaction, and handles its confirmation statussend_and_confirm_transaction
- Sends a transaction and handles its confirmation status with retry logicsend_smart_transaction_with_seeds
- Sends a smart transaction using seed bytes
Jito Smart Transactions and Helper Methods
add_tip_instruction
- Adds a tip instruction to the instructions providedcreate_smart_transaction_with_tip
- Creates a smart transaction with a Jito tipget_bundle_statuses
- Get the status of Jito bundlessend_jito_bundle
- Sends a bundle of transactions to the Jito Block Enginesend_smart_transaction_with_tip
- Sends a smart transaction as a Jito bundle with a tip
Helper Methods
get_priority_fee_estimate
- Gets an estimate of the priority fees required for a transaction to be processed more quicklydeserialize_str_to_number
- Deserializes aString
to aNumber
is_valid_solana_address
- Returns whether a given string slice is a valid Solana addressmake_keypairs
- Generates a specified number of keypairs
Dependencies
~55–74MB
~1.5M SLoC