near_api/
chain.rs

1use near_api_types::{BlockHeight, CryptoHash, Reference};
2
3use crate::{
4    advanced::{block_rpc::SimpleBlockRpc, AndThenHandler},
5    common::query::{PostprocessHandler, RequestBuilder, RpcBlockHandler},
6};
7
8/// Chain-related interactions with the NEAR Protocol
9///
10/// The [`Chain`] struct provides methods to interact with the NEAR blockchain
11///
12/// # Examples
13///
14/// ```rust,no_run
15/// use near_api::*;
16///
17/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
18/// let block_number = Chain::block_number().fetch_from_testnet().await?;
19/// println!("Current block number: {}", block_number);
20/// # Ok(())
21/// # }
22/// ```
23#[derive(Debug, Clone, Copy)]
24pub struct Chain;
25
26impl Chain {
27    /// Set ups a query to fetch the [BlockHeight] of the current block
28    ///
29    /// ## Fetching the latest block number
30    ///
31    /// ```rust,no_run
32    /// use near_api::*;
33    ///
34    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
35    /// let block_number = Chain::block_number().fetch_from_testnet().await?;
36    /// println!("Current block number: {}", block_number);
37    /// # Ok(())
38    /// # }
39    /// ```
40    ///
41    /// ## Fetching the final block number
42    ///
43    /// ```rust,no_run
44    /// use near_api::*;
45    ///
46    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
47    /// let block_number = Chain::block_number().at(Reference::Final).fetch_from_testnet().await?;
48    /// println!("Final block number: {}", block_number);
49    /// # Ok(())
50    /// # }
51    /// ```
52    pub fn block_number() -> RequestBuilder<PostprocessHandler<BlockHeight, RpcBlockHandler>> {
53        RequestBuilder::new(SimpleBlockRpc, Reference::Optimistic, RpcBlockHandler)
54            .map(|data| data.header.height)
55    }
56
57    /// Set ups a query to fetch the [CryptoHash] of the block
58    ///
59    /// ## Fetching the latest block hash
60    ///
61    /// ```rust,no_run
62    /// use near_api::*;
63    ///
64    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
65    /// let block_hash = Chain::block_hash().fetch_from_testnet().await?;
66    /// println!("Current block hash: {}", block_hash);
67    /// # Ok(())
68    /// # }
69    /// ```
70    ///
71    /// ## Fetching the hash at a specific block number
72    ///
73    /// ```rust,no_run
74    /// use near_api::*;
75    ///
76    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
77    /// let block_hash = Chain::block_hash().at(Reference::AtBlock(1000000)).fetch_from_testnet().await?;
78    /// println!("Block hash at block number 1000000: {}", block_hash);
79    /// # Ok(())
80    /// # }
81    /// ```
82    pub fn block_hash() -> RequestBuilder<AndThenHandler<CryptoHash, RpcBlockHandler>> {
83        RequestBuilder::new(SimpleBlockRpc, Reference::Optimistic, RpcBlockHandler)
84            .and_then(|data| Ok(CryptoHash::try_from(data.header.hash)?))
85    }
86
87    /// Set ups a query to fetch the [RpcBlockResponse][near_api_types::RpcBlockResponse]
88    ///
89    /// ## Fetching the latest block
90    ///
91    /// ```rust,no_run
92    /// use near_api::*;
93    ///
94    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
95    /// let block = Chain::block().fetch_from_testnet().await?;
96    /// println!("Current block: {:?}", block);
97    /// # Ok(())
98    /// # }
99    /// ```
100    ///
101    /// ## Fetching the block at a specific block number
102    ///
103    /// ```rust,no_run
104    /// use near_api::*;
105    ///
106    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
107    /// let block = Chain::block().at(Reference::AtBlock(1000000)).fetch_from_testnet().await?;
108    /// println!("Block at block number 1000000: {:?}", block);
109    /// # Ok(())
110    /// # }
111    /// ```
112    ///
113    /// ## Fetching the block at a specific block hash
114    ///
115    /// ```rust,no_run
116    /// use near_api::*;
117    ///
118    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
119    /// # let block_hash = near_api::types::CryptoHash::default();       
120    /// let block = Chain::block().at(Reference::AtBlockHash(block_hash)).fetch_from_testnet().await?;
121    /// println!("Block at block hash: {:?}", block);
122    /// # Ok(())
123    /// # }
124    /// ```
125    pub fn block() -> RequestBuilder<RpcBlockHandler> {
126        RequestBuilder::new(SimpleBlockRpc, Reference::Optimistic, RpcBlockHandler)
127    }
128
129    // TODO: chunk info
130}
near_api/chain.rs

near_api/
chain.rs
