Cliente RPC

El RpcClient es la capa de transporte principal para comunicarse con los nodos Savitri mediante JSON-RPC 2.0.

Crear un Cliente

use savitri_sdk::RpcClient;

// Desde URL (HTTP local permitido)
let client = RpcClient::from_url("http://localhost:8545")?;

// Desde URL (HTTPS requerido para conexiones remotas)
let client = RpcClient::from_url("https://rpc.savitrinetwork.com")?;

// Con configuración personalizada
use savitri_sdk::client::rpc_client::RpcClientConfig;

let client = RpcClient::new(RpcClientConfig {
    url: "http://localhost:8545".to_string(),
    timeout: Some(60),          // 60 second timeout
    allow_insecure: false,      // enforce HTTPS for remote
})?;

Consultas de Cadena

// Altura del bloque
let height: u64 = client.get_block_number().await?;

// Bloque por altura
let block = client.get_block_by_height(42).await?;
println!("Block {} hash: {}", block.height, block.hash);
println!("Proposer: {}", block.proposer);
println!("TX count: {}", block.transaction_count);

// Hash del bloque
let hash: String = client.get_block_hash(42).await?;

Consultas de Cuenta

// Información completa de la cuenta
let account = client.get_account("aabbcc...64chars").await?;
println!("Balance: {}", account.balance);  // u128 como string decimal
println!("Nonce: {}", account.nonce);

// Solo el saldo
let balance: String = client.get_balance("aabbcc...").await?;

// Solo el nonce
let nonce: u64 = client.get_nonce("aabbcc...").await?;

Operaciones de Transacción

// Obtener transacción por hash
let tx = client.get_transaction("tx_hash_hex").await?;
println!("From: {} To: {} Amount: {}", tx.from, tx.to, tx.amount);

// Enviar transacción firmada
let result = client.send_raw_transaction("signed_tx_hex").await?;
println!("TX hash: {}", result.tx_hash);

// Reclamar faucet del testnet
let claim = client.faucet_claim("your_address_64hex").await?;
println!("Received: {} (tx: {})", claim.amount, claim.tx_hash);

Consultas de Consenso

// Estado PoU local
let pou = client.pou_local().await?;
println!("My score: {:?}", pou.local_score);
println!("Leader: {:?} (score: {:?})", pou.leader, pou.leader_score);
println!("Am I leader? {}", pou.local_is_leader);

// Puntuaciones de todos los pares
let peers = client.pou_peers().await?;
for (peer_id, score) in &peers.peers {
    println!("{}: {}", peer_id, score);
}

// Grupos (solo masternode)
let groups = client.pou_groups().await?;
for group in &groups.groups {
    println!("Group {}: {} members", group.group_id, group.members.len());
}

// Masternodes (solo masternode)
let mns = client.pou_masternodes().await?;
for mn in &mns.masternodes {
    println!("{}: PoU={} Health={}", mn.node_id, mn.pou_score, mn.health_score);
}

Solicitudes en Lote

Envía múltiples llamadas RPC en una sola solicitud HTTP (máximo 100):

let responses = client.batch(vec![
    ("savitri_blockNumber", serde_json::json!([])),
    ("savitri_health", serde_json::json!([])),
    ("savitri_getAccount", serde_json::json!(["aabbcc..."])),
]).await?;

for resp in &responses {
    println!("{}", resp);
}

Llamadas sin Formato

Para métodos no cubiertos por los helpers tipados:

let result: serde_json::Value = client
    .call_raw("custom_method", serde_json::json!(["param1", 42]))
    .await?;

Verificación de Estado

// Verificación de estado tipada
let health = client.health().await?;
assert_eq!(health.status, "ok");

// Ping simple (devuelve bool)
let is_alive = client.ping().await?;

Manejo de Errores

use savitri_sdk::SdkError;

match client.get_account("invalid").await {
    Ok(account) => println!("Balance: {}", account.balance),
    Err(SdkError::RpcError { code, message, .. }) => {
        println!("RPC error {}: {}", code, message);
    }
    Err(SdkError::HttpError(e)) => {
        println!("Network error: {}", e);
    }
    Err(e) => println!("Other error: {}", e),
}

Tipos de error:

Error	Descripción
SdkError::RpcError	Error JSON-RPC del servidor (código, mensaje, datos)
SdkError::HttpError	Error de red/transporte
SdkError::JsonError	Error de serialización JSON
SdkError::InvalidResponse	Formato de respuesta inesperado
SdkError::NoRpcClient	Método de billetera llamado sin conexión RPC