feat: added tx status, receipt and proof fetchers (#126)

* feat: added tx status, receipt and proof fetchers

* chore(examples): safer receipt_id extraction

* chore: set `ExecutedOptimistic` as a safer default for status fetch

* refactor: reduced code duplication by adding `to_final_execution_outcome` method and created a separate `is_critical_transaction_status_error`

* chore(examples): skip if `ci=true`

* fix: clippy

* fix: potential panic due to tx status in pending state

* chore: pinned `deflate64` crate

* chore: removed deflate64 version pin

* fix(example): use archival url for fetching

* refactor(examples): use `fetch_from_mainnet_archival()`

Author: frolvanya

Cargo.toml

@@ -1,9 +1,9 @@
 [workspace]
 resolver = "3"
 members = ["api", "types"]
-rust-version = "1.86"
 
 [workspace.package]
+rust-version = "1.86"
 edition = "2024"
 version = "0.8.5"
 authors = [

api/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "near-api"
-rust-version = "1.85"
+rust-version.workspace = true
 version.workspace = true
 authors.workspace = true
 license.workspace = true

api/examples/transaction_queries.rs

@@ -0,0 +1,79 @@
+use near_api::{
+    Chain, Transaction,
+    types::{AccountId, CryptoHash, Reference, TxExecutionStatus},
+};
+use testresult::TestResult;
+
+/// This example queries mainnet with a known finalized transaction.
+///
+/// Sandbox does not support `EXPERIMENTAL_receipt` or `light_client_proof`,
+/// so this example is skipped when `CI=true`.
+///
+/// The transaction hash and sender can be overridden via environment variables:
+///   TX_HASH  — the transaction hash to query
+///   TX_SENDER — the sender account ID
+#[tokio::main]
+async fn main() -> TestResult {
+    if std::env::var("CI").is_ok() {
+        println!("Skipping transaction_queries in CI (requires mainnet)");
+        return Ok(());
+    }
+
+    let sender: AccountId = std::env::var("TX_SENDER")
+        .unwrap_or_else(|_| "omni.bridge.near".to_string())
+        .parse()?;
+    let tx_hash: CryptoHash = std::env::var("TX_HASH")
+        .unwrap_or_else(|_| "GmvjRhbBwNCeekyZ4ezv43Zhs4U33kRTj6PRkFgKUKyJ".to_string())
+        .parse()?;
+
+    let status = Transaction::status(sender.clone(), tx_hash)
+        .fetch_from_mainnet_archival()
+        .await?;
+    println!(
+        "[status] is_success={}, is_failure={}, gas_burnt={}",
+        status.is_success(),
+        status.is_failure(),
+        status.total_gas_burnt,
+    );
+
+    let status_final =
+        Transaction::status_with_options(sender.clone(), tx_hash, TxExecutionStatus::Final)
+            .fetch_from_mainnet_archival()
+            .await?;
+    println!(
+        "[status_with_options(Final)] is_success={}, receipts={}",
+        status_final.is_success(),
+        status_final.receipt_outcomes().len(),
+    );
+
+    let receipt_id = *status_final
+        .outcome()
+        .receipt_ids
+        .first()
+        .expect("transaction should have at least one receipt");
+    let receipt = Transaction::receipt(receipt_id)
+        .fetch_from_mainnet_archival()
+        .await?;
+    println!(
+        "[receipt] id={}, receiver={}, predecessor={}",
+        receipt.receipt_id, receipt.receiver_id, receipt.predecessor_id,
+    );
+
+    let head_hash = Chain::block_hash()
+        .at(Reference::Final)
+        .fetch_from_mainnet_archival()
+        .await?;
+    let proof = Transaction::proof(sender, tx_hash, head_hash)
+        .fetch_from_mainnet_archival()
+        .await?;
+    println!(
+        "[proof] outcome_proof_id={}, block_proof_len={}, outcome_root_proof_len={}",
+        proof.outcome_proof.id,
+        proof.block_proof.len(),
+        proof.outcome_root_proof.len(),
+    );
+
+    println!("\nAll transaction query methods passed!");
+
+    Ok(())
+}

api/src/common/query/handlers/mod.rs

@@ -1,19 +1,22 @@
 use borsh::BorshDeserialize;
 use near_api_types::{
     AccessKey, Account, AccountView, ContractCodeView, Data, PublicKey, RpcBlockResponse,
-    RpcValidatorResponse, ViewStateResult, json::U64,
+    RpcValidatorResponse, ViewStateResult, json::U64, transaction::result::ExecutionFinalResult,
 };
-use near_openapi_client::types::RpcQueryResponse;
+use near_openapi_client::types::{RpcQueryResponse, RpcReceiptResponse, RpcTransactionResponse};
 use serde::de::DeserializeOwned;
 use std::marker::PhantomData;
 use tracing::{info, trace, warn};
 
 use crate::{
     advanced::{
         RpcType, block_rpc::SimpleBlockRpc, query_rpc::SimpleQueryRpc,
-        validator_rpc::SimpleValidatorRpc,
+        tx_rpc::TransactionStatusRpc, validator_rpc::SimpleValidatorRpc,
+    },
+    common::{
+        query::{QUERY_EXECUTOR_TARGET, ResultWithMethod},
+        send::to_final_execution_outcome,
     },
-    common::query::{QUERY_EXECUTOR_TARGET, ResultWithMethod},
     errors::QueryError,
 };
 pub mod transformers;
@@ -497,6 +500,67 @@ impl ResponseHandler for RpcBlockHandler {
     }
 }
 
+/// Handler that converts an [`RpcTransactionResponse`] into an [`ExecutionFinalResult`].
+///
+/// This reuses the same conversion logic from transaction sending: it extracts the
+/// `FinalExecutionOutcomeView` from the response and converts it using `TryFrom`.
+#[derive(Clone, Debug)]
+pub struct TransactionStatusHandler;
+
+impl ResponseHandler for TransactionStatusHandler {
+    type Response = ExecutionFinalResult;
+    type Query = TransactionStatusRpc;
+
+    fn process_response(
+        &self,
+        response: Vec<RpcTransactionResponse>,
+    ) -> ResultWithMethod<Self::Response, <Self::Query as RpcType>::Error> {
+        let response = response
+            .into_iter()
+            .next()
+            .ok_or(QueryError::InternalErrorNoResponse)?;
+
+        let final_execution_outcome_view = to_final_execution_outcome(response);
+
+        info!(
+            target: QUERY_EXECUTOR_TARGET,
+            "Processed TransactionStatus response, tx hash: {:?}",
+            final_execution_outcome_view.transaction_outcome.id,
+        );
+
+        ExecutionFinalResult::try_from(final_execution_outcome_view)
+            .map_err(|e| QueryError::ConversionError(Box::new(e)))
+    }
+}
+
+/// Handler that passes through the raw [`RpcReceiptResponse`] without transformation.
+#[derive(Clone, Debug)]
+pub struct ReceiptHandler;
+
+impl ResponseHandler for ReceiptHandler {
+    type Response = RpcReceiptResponse;
+    type Query = crate::advanced::tx_rpc::ReceiptRpc;
+
+    fn process_response(
+        &self,
+        response: Vec<RpcReceiptResponse>,
+    ) -> ResultWithMethod<Self::Response, <Self::Query as RpcType>::Error> {
+        let response = response
+            .into_iter()
+            .next()
+            .ok_or(QueryError::InternalErrorNoResponse)?;
+
+        info!(
+            target: QUERY_EXECUTOR_TARGET,
+            "Processed Receipt response, receipt_id: {:?}, receiver: {:?}",
+            response.receipt_id,
+            response.receiver_id,
+        );
+
+        Ok(response)
+    }
+}
+
 impl<T: RpcType> ResponseHandler for T {
     type Response = <T as RpcType>::Response;
     type Query = T;

api/src/common/query/mod.rs

@@ -14,6 +14,7 @@ pub mod block_rpc;
 pub mod handlers;
 pub mod query_request;
 pub mod query_rpc;
+pub mod tx_rpc;
 pub mod validator_rpc;
 
 pub use handlers::*;