bitcoin_onchain 0.10.2

Bitcoin descriptors library (part of descriptor-wallet)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158

// Wallet-level libraries for bitcoin protocol by LNP/BP Association
//
// Written in 2020-2022 by
//     Dr. Maxim Orlovsky <orlovsky@lnp-bp.org>
//
// This software is distributed without any warranty.
//
// You should have received a copy of the Apache-2.0 License
// along with this software.
// If not, see <https://opensource.org/licenses/Apache-2.0>.

//! Blockchain-specific data types useful for wallets

use std::fmt::Debug;
use std::hash::Hash;
use std::str::FromStr;

use bitcoin::blockdata::constants;
use bitcoin::{BlockHash, Network, OutPoint};
use chrono::{DateTime, NaiveDateTime};
#[cfg(feature = "electrum")]
use electrum_client::ListUnspentRes;
use strict_encoding::{StrictDecode, StrictEncode};

/// Error parsing string representation of wallet data/structure
#[derive(
    Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Debug, Display, From, Error
)]
#[display(doc_comments)]
#[from(bitcoin::hashes::hex::Error)]
#[from(chrono::ParseError)]
#[from(std::num::ParseIntError)]
#[from(bitcoin::consensus::encode::Error)]
#[from(bitcoin::util::amount::ParseAmountError)]
#[from(bitcoin::blockdata::transaction::ParseOutPointError)]
pub struct ParseError;

/// Block mining information
#[derive(Getters, Clone, Ord, PartialOrd, Eq, PartialEq, Hash, Debug, Display)]
#[derive(StrictEncode, StrictDecode)]
#[display("{block_height}#{block_hash}@{timestamp}")]
pub struct TimeHeight {
    timestamp: NaiveDateTime,
    block_height: u32,
    block_hash: BlockHash,
}

impl Default for TimeHeight {
    fn default() -> Self {
        TimeHeight {
            timestamp: DateTime::from_timestamp_millis(1231006500)
                .expect("hardcoded value")
                .naive_utc(),
            block_height: 0,
            block_hash: constants::genesis_block(Network::Bitcoin).block_hash(),
        }
    }
}

impl FromStr for TimeHeight {
    type Err = ParseError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        let mut data = s.split(&['#', '@'][..]);
        let me = Self {
            timestamp: data.next().ok_or(ParseError)?.parse()?,
            block_height: data.next().ok_or(ParseError)?.parse()?,
            block_hash: data.next().ok_or(ParseError)?.parse()?,
        };
        if data.next().is_some() {
            Err(ParseError)
        } else {
            Ok(me)
        }
    }
}

/// Information about transaction mining status
#[cfg_attr(
    feature = "serde",
    derive(Serialize, Deserialize),
    serde(crate = "serde_crate")
)]
#[derive(
    Copy, Clone, Ord, PartialOrd, Eq, PartialEq, Hash, Default, Debug, Display
)]
#[derive(StrictEncode, StrictDecode)]
pub enum MiningStatus {
    /// Transaction mining status is undefined
    #[default]
    #[display("undefined")]
    Undefined,

    /// Transaction is unknown
    #[display("unknown_tx")]
    UnknownTx,

    /// Transaction is not mined but present in mempool
    #[display("mempool")]
    Mempool,

    /// Transaction is mined onchain at a block with a given height
    #[display(inner)]
    Blockchain(u64),
}

/// Full UTXO information
#[cfg_attr(
    feature = "serde",
    derive(Serialize, Deserialize),
    serde(crate = "serde_crate")
)]
#[derive(Getters, Clone, Ord, PartialOrd, Eq, PartialEq, Hash, Debug, Display)]
#[derive(StrictEncode, StrictDecode)]
#[display("{amount}@{outpoint}")]
pub struct Utxo {
    /// Status of the transaction containing this UTXO
    mined: MiningStatus,
    /// UTXO outpoint
    outpoint: OutPoint,
    /// Value stored in the UTXO
    #[cfg_attr(
        feature = "serde",
        serde(with = "bitcoin::util::amount::serde::as_btc")
    )]
    amount: bitcoin::Amount,
}

impl FromStr for Utxo {
    type Err = ParseError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        let mut split = s.split('@');
        match (split.next(), split.next(), split.next()) {
            (Some(amount), Some(outpoint), None) => Ok(Utxo {
                mined: MiningStatus::Undefined,
                amount: amount.parse()?,
                outpoint: outpoint.parse()?,
            }),
            _ => Err(ParseError),
        }
    }
}

#[cfg(feature = "electrum")]
impl From<ListUnspentRes> for Utxo {
    fn from(res: ListUnspentRes) -> Self {
        Utxo {
            mined: if res.height == 0 {
                MiningStatus::Mempool
            } else {
                MiningStatus::Blockchain(res.height as u64)
            },
            outpoint: OutPoint::new(res.tx_hash, res.tx_pos as u32),
            amount: bitcoin::Amount::from_sat(res.value),
        }
    }
}