Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added documentation for some functions and methods. #123

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 37 additions & 3 deletions src/api.rs
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,19 @@ pub use bitcoin::{

use serde::Deserialize;

/// It contains the value and scriptpubkey of a
/// previous transaction output that a transaction
/// input can reference.
#[derive(Deserialize, Clone, Debug, PartialEq, Eq)]
pub struct PrevOut {
pub value: u64,
pub scriptpubkey: ScriptBuf,
}

/// Represents the transaction input containing
/// a Previous output (or none if coinbase) and includes
/// the unlocking script, witness data, sequence number,
/// and a flag indicating if it is a coinbase input.
#[derive(Deserialize, Clone, Debug, PartialEq, Eq)]
pub struct Vin {
pub txid: Txid,
Expand All @@ -30,12 +37,15 @@ pub struct Vin {
pub is_coinbase: bool,
}

/// Represents the transaction output containing a value and
/// a scriptpubkey.
#[derive(Deserialize, Clone, Debug, PartialEq, Eq)]
pub struct Vout {
pub value: u64,
pub scriptpubkey: ScriptBuf,
}

/// Represents Transaction Status.
#[derive(Deserialize, Clone, Debug, PartialEq, Eq)]
pub struct TxStatus {
pub confirmed: bool,
Expand All @@ -44,13 +54,18 @@ pub struct TxStatus {
pub block_time: Option<u64>,
}

/// It holds the block height, a Merkle path of
/// transaction IDs, and the position of the
/// transaction in the tree to verify its inclusion
/// in a block.
#[derive(Deserialize, Clone, Debug, PartialEq, Eq)]
pub struct MerkleProof {
pub block_height: u32,
pub merkle: Vec<Txid>,
pub pos: usize,
}

/// Struct that contains the status of an output in a transaction.
#[derive(Deserialize, Clone, Debug, PartialEq, Eq)]
pub struct OutputStatus {
pub spent: bool,
Expand All @@ -59,13 +74,19 @@ pub struct OutputStatus {
pub status: Option<TxStatus>,
}

/// This Struct represents the status of a block in the blockchain.
/// `in_best_chain` - a boolean that shows whether the block is part of the main chain.
/// `height` - Optional field that shows the height of the block if block is in main chain.
/// `next_best` - Optional field that contains `BlockHash` of the next block that may represent
/// the next block in the best chain.
#[derive(Deserialize, Clone, Debug, PartialEq, Eq)]
pub struct BlockStatus {
pub in_best_chain: bool,
pub height: Option<u32>,
pub next_best: Option<BlockHash>,
}

/// Structure represents a complete transaction
#[derive(Deserialize, Clone, Debug, PartialEq, Eq)]
pub struct Tx {
pub txid: Txid,
Expand All @@ -81,12 +102,15 @@ pub struct Tx {
pub fee: u64,
}

/// Returns timing information of a Block
/// containg `timestamp` and `height` of block
#[derive(Deserialize, Clone, Debug, PartialEq, Eq)]
pub struct BlockTime {
pub timestamp: u64,
pub height: u32,
}

/// Provides a Summary of a Bitcoin block which includes
/// `BlockHash`, `BlockTime`, `previousblockhash`, `merkle_root`.
#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
pub struct BlockSummary {
pub id: BlockHash,
Expand Down Expand Up @@ -124,6 +148,7 @@ pub struct AddressTxsSummary {
}

impl Tx {
/// Converts a transaction into a standard `Bitcoin transaction`.
pub fn to_tx(&self) -> Transaction {
Transaction {
version: transaction::Version::non_standard(self.version),
Expand Down Expand Up @@ -154,6 +179,9 @@ impl Tx {
}
}

/// Checks Transaction status, returns a `BlockTime` struct contaning
/// `height` and `timestamp` if transaction has been confirmed or
/// `None` otherwise.
pub fn confirmation_time(&self) -> Option<BlockTime> {
match self.status {
TxStatus {
Expand All @@ -166,6 +194,10 @@ impl Tx {
}
}

/// Takes Transaction as input
/// iterates through all the inputs present in the transaction
/// and checks for prevout field and creates a `TxOut` Struct for each input if it exists
/// then returns all optional TxOut values as a vector.
pub fn previous_outputs(&self) -> Vec<Option<TxOut>> {
self.vin
.iter()
Expand All @@ -178,11 +210,13 @@ impl Tx {
})
.collect()
}

/// Takes Transaction as input and returns
/// the `Weight instance` of the weight present in Transaction.
pub fn weight(&self) -> Weight {
Weight::from_wu(self.weight)
}

/// Takes Transaction as input and returns
/// the `Amount instance` of the satoshis present in Transaction.
pub fn fee(&self) -> Amount {
Amount::from_sat(self.fee)
}
Expand Down
8 changes: 7 additions & 1 deletion src/async.rs
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,9 @@ use crate::{
BASE_BACKOFF_MILLIS, RETRYABLE_ERROR_CODES,
};

/// Struct that an HTTP client configured with an
/// Esplora server URL, max retries, and a type
/// marker for asynchronous sleep behavior.
#[derive(Debug, Clone)]
pub struct AsyncClient<S = DefaultSleeper> {
/// The URL of the Esplora Server.
Expand Down Expand Up @@ -81,7 +84,7 @@ impl<S: Sleeper> AsyncClient<S> {
marker: PhantomData,
})
}

/// A constructor for creating a new instance of `AsyncClient`.
pub fn from_client(url: String, client: Client) -> Self {
AsyncClient {
url,
Expand Down Expand Up @@ -482,6 +485,9 @@ fn is_status_retryable(status: reqwest::StatusCode) -> bool {
RETRYABLE_ERROR_CODES.contains(&status.as_u16())
}

/// The Sleeper trait defines an asynchronous
/// sleep mechanism with an associated future
/// type that completes after a given duration.
pub trait Sleeper: 'static {
type Sleep: std::future::Future<Output = ()>;
fn sleep(dur: std::time::Duration) -> Self::Sleep;
Expand Down