> ## Documentation Index > Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Melhores Práticas do Rust SDK > Padrões recomendados para agentes de IA usando o Helius Rust SDK. Cobre histórico de transações, envio de transações, agrupamento, webhooks, paginação, busca incremental, erros comuns e tratamento de erros. Melhores práticas e padrões recomendados para agentes usando o [Helius Rust SDK](https://github.com/helius-labs/helius-rust-sdk). Para instalação e início, veja a [visão geral](/docs/pt-BR/agents/rust-sdk). ## Recomendações para Agentes ### Use `get_transactions_for_address` em vez de pesquisa em dois passos `get_transactions_for_address` combina a pesquisa de assinatura e busca de transação em uma única chamada com filtragem no servidor. ```rust theme={"system"} // GOOD: Single call, server-side filtering let txs = helius.rpc().get_transactions_for_address( "address".to_string(), GetTransactionsForAddressOptions { transaction_details: Some(TransactionDetails::Full), limit: Some(100), filters: Some(GetTransactionsFilters { token_accounts: Some(TokenAccountsFilter::BalanceChanged), ..Default::default() }), ..Default::default() }, ).await?; // BAD: Two calls, client-side filtering let sigs = helius.connection().get_signatures_for_address(&address)?; ``` ### Use `send_smart_transaction` para envios padrão Simula automaticamente, estima unidades de computação, busca taxas de prioridade e confirma. Não construa manualmente as instruções `ComputeBudget` — o SDK as adiciona automaticamente. ```rust theme={"system"} let sig = helius.send_smart_transaction(SmartTransactionConfig { create_config: CreateSmartTransactionConfig { instructions: vec![your_instruction], signers: vec![wallet_signer], priority_fee_cap: Some(100_000), cu_buffer_multiplier: Some(1.1), ..Default::default() }, ..Default::default() }).await?; ``` ### Use Helius Sender para latência ultra-baixa Para transações sensíveis ao tempo (arbitragem, sniping, liquidações), use `send_smart_transaction_with_sender`. Ele roteia pela infraestrutura multi-região do Helius e Jito. ```rust theme={"system"} let sig = helius.send_smart_transaction_with_sender( SmartTransactionConfig { create_config: CreateSmartTransactionConfig { instructions: vec![your_instruction], signers: vec![wallet_signer], ..Default::default() }, ..Default::default() }, SenderSendOptions { region: "US_EAST".to_string(), // Default, US_SLC, US_EAST, EU_WEST, EU_CENTRAL, EU_NORTH, AP_SINGAPORE, AP_TOKYO swqos_only: false, // true = SWQOS only (lower tip), false = Dual (SWQOS + Jito) poll_timeout_ms: 60_000, poll_interval_ms: 2_000, }, ).await?; ``` ### Use `get_asset_batch` para múltiplos ativos Ao buscar mais de um ativo, agrupe-os. Não chame `get_asset` em um loop. ```rust theme={"system"} // GOOD: Single request let assets = helius.rpc().get_asset_batch(GetAssetBatch { ids: vec!["mint1".to_string(), "mint2".to_string(), "mint3".to_string()], ..Default::default() }).await?; // BAD: N requests for id in mints { let asset = helius.rpc().get_asset(GetAsset { id, ..Default::default() }).await?; } ``` ### Use webhooks em vez de polling Não faça polling em `get_transactions_for_address` em um loop. Use webhooks para notificações de servidor para servidor. ```rust theme={"system"} let webhook = helius.create_webhook(CreateWebhookRequest { webhook_url: "https://your-server.com/webhook".to_string(), webhook_type: WebhookType::Enhanced, transaction_types: vec![TransactionType::Transfer, TransactionType::NftSale, TransactionType::Swap], account_addresses: vec!["address_to_monitor".to_string()], auth_header: Some("Bearer your-secret".to_string()), ..Default::default() }).await?; ``` ## Paginação ### Baseada em Token/Cursor (Métodos RPC V2) ```rust theme={"system"} // get_transactions_for_address uses pagination_token let mut pagination_token: Option = None; let mut all_txs = Vec::new(); loop { let result = helius.rpc().get_transactions_for_address( "address".to_string(), GetTransactionsForAddressOptions { limit: Some(100), pagination_token: pagination_token.clone(), ..Default::default() }, ).await?; all_txs.extend(result.data); pagination_token = result.pagination_token; if pagination_token.is_none() { break; } } // Or use auto-paginating variants: let all_accounts = helius.rpc().get_all_program_accounts( program_id.to_string(), GetProgramAccountsV2Config::default(), ).await?; ``` ### Baseada em Página (API DAS) ```rust theme={"system"} let mut page = 1; let mut all_assets = Vec::new(); loop { let result = helius.rpc().get_assets_by_owner(GetAssetsByOwner { owner_address: "...".to_string(), page, limit: Some(1000), ..Default::default() }).await?; let count = result.items.len(); all_assets.extend(result.items); if count < 1000 { break; } page += 1; } ``` ## Filtro `token_accounts` Ao consultar `get_transactions_for_address`, o filtro `token_accounts` controla se a atividade da conta de token é incluída: | Valor | Comportamento | Use Quando | | ---------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | `None` | Apenas transações envolvendo diretamente o endereço | Você só se preocupa com transferências de SOL e chamadas de programa | | `BalanceChanged` | Inclui também transações de token que alteraram um saldo | **Recomendado para a maioria dos agentes** — mostra envios/recebimentos de tokens sem ruído | | `All` | Inclui todas as transações da conta de token | Você precisa de atividade completa de tokens (pode retornar muitos resultados) | ## `changed_since_slot` — Busca Incremental de Conta `changed_since_slot` retorna apenas contas modificadas após um determinado slot. Útil para fluxos de trabalho de sincronização ou indexação. Suportado por `get_program_accounts_v2`, `get_token_accounts_by_owner_v2`, `get_account_info`, `get_multiple_accounts`, `get_program_accounts`, e `get_token_accounts_by_owner`. ```rust theme={"system"} // First fetch: get all accounts let baseline = helius.rpc().get_program_accounts_v2( program_id.to_string(), GetProgramAccountsV2Config { limit: Some(10_000), ..Default::default() }, ).await?; let last_slot = current_slot; // Later: only get accounts that changed since your last fetch let updates = helius.rpc().get_program_accounts_v2( program_id.to_string(), GetProgramAccountsV2Config { limit: Some(10_000), changed_since_slot: Some(last_slot), ..Default::default() }, ).await?; ``` ## Erros Comuns 1. **`transaction_details: Some(TransactionDetails::Full)` não é o padrão** — Por padrão, `get_transactions_for_address` retorna apenas assinaturas. Defina `TransactionDetails::Full` para obter dados completos da transação. 2. **Não adicione instruções ComputeBudget com `send_smart_transaction`** — O SDK as adiciona automaticamente. Adicionar suas próprias causa um erro `HeliusError::InvalidInput`. 3. **As taxas de prioridade estão em microlamports por unidade de computação** — Não em lamports. Os valores de `get_priority_fee_estimate` já estão na unidade correta. 4. **A paginação DAS é indexada em 1** — `page: 1` é a primeira página, não `page: 0`. 5. **`async_connection()` requer `new_async` ou `HeliusBuilder`** — Chamar `helius.async_connection()` em um cliente criado com `Helius::new()` retorna `Err(HeliusError::ClientNotInitialized)`. 6. **`get_asset` retorna `Option`** — Uma resposta bem-sucedida ainda pode ser `None` se o ativo não existir. Lide explicitamente com `Option`. 7. **Gorjetas do remetente são obrigatórias** — `send_smart_transaction_with_sender` determina e adiciona automaticamente gorjetas. Mínimo de 0,0002 SOL (modo duplo) ou 0,000005 SOL (apenas SWQOS). 8. **Flags de recurso TLS** — O crate por padrão usa `native-tls`. Use `features = ["rustls"]` (e `default-features = false`) para TLS puro em Rust quando OpenSSL não estiver disponível. ## Tratamento de Erros e Retentativas O SDK fornece variantes de erro tipadas através do enum `HeliusError`, para que você possa fazer correspondência diretamente: ```rust theme={"system"} use helius::error::{HeliusError, Result}; match helius.rpc().get_asset(request).await { Ok(asset) => { /* success */ } Err(HeliusError::Unauthorized { .. }) => { /* 401: invalid or missing API key */ } Err(HeliusError::RateLimitExceeded { .. }) => { /* 429: too many requests or out of credits */ } Err(HeliusError::InternalError { .. }) => { /* 5xx: server error, retry with backoff */ } Err(HeliusError::NotFound { .. }) => { /* 404: resource not found */ } Err(HeliusError::BadRequest { .. }) => { /* 400: malformed request */ } Err(HeliusError::Timeout { .. }) => { /* transaction confirmation timed out */ } Err(e) => { /* other errors: Network, SerdeJson, etc. */ } } ``` ### Estratégia de Retentativa Retente em `RateLimitExceeded` e `InternalError` com backoff exponencial: ```rust theme={"system"} async fn with_retry(f: F, max_retries: u32) -> Result where F: Fn() -> Fut, Fut: std::future::Future>, { for attempt in 0..=max_retries { match f().await { Ok(val) => return Ok(val), Err(HeliusError::RateLimitExceeded { .. }) | Err(HeliusError::InternalError { .. }) if attempt < max_retries => { tokio::time::sleep(std::time::Duration::from_millis(1000 * 2u64.pow(attempt))).await; } Err(e) => return Err(e), } } unreachable!() } ``` | Variante de Erro | Status HTTP | Ação | | ------------------- | ----------- | ----------------------------------------- | | `Unauthorized` | 401 | Verifique a chave da API | | `RateLimitExceeded` | 429 | Faça uma pausa e tente novamente | | `InternalError` | 5xx | Tente novamente com backoff exponencial | | `BadRequest` | 400 | Corrija os parâmetros da solicitação | | `NotFound` | 404 | Verifique se o recurso existe | | `Timeout` | — | Aumente o tempo limite ou tente novamente |