regit-web3 1.0.1

Modular Web3 primitives for exact values, chain and provider reads, swap quotes, and transaction preparation
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
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
// SPDX-License-Identifier: Apache-2.0
// Copyright (c) 2026 Regit

use std::collections::BTreeSet;

use serde::{Deserialize, Serialize};

use crate::{
    domain::{
        ExactDecimal,
        bitcoin::{Satoshis, Txid},
    },
    error::{Error, ValidationError},
};

fn invalid() -> Error {
    ValidationError::InvalidMempoolRecord.into()
}

/// An exact nonnegative source fee rate in satoshis per virtual byte.
/// Suggestions are not a confirmation-time guarantee or a transaction fee.
#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd, Serialize, Deserialize)]
#[serde(try_from = "ExactDecimal", into = "ExactDecimal")]
pub struct FeeRate(ExactDecimal);
impl FeeRate {
    /// Requires a finite exact zero or positive sat/vB value.
    /// # Errors
    /// Rejects negative rates without rounding or input-bearing diagnostics.
    pub fn new(value: ExactDecimal) -> Result<Self, Error> {
        if value.is_negative() {
            return Err(invalid());
        }
        Ok(Self(value))
    }
    /// Parses exact decimal notation in sat/vB, without floating point.
    /// # Errors
    /// Rejects malformed, negative or resource-exceeding values.
    pub fn parse(value: &str) -> Result<Self, Error> {
        Self::new(ExactDecimal::parse(value).map_err(|_| invalid())?)
    }
    /// Returns the exact source fee rate; serde uses a decimal string.
    #[must_use]
    pub const fn value(&self) -> &ExactDecimal {
        &self.0
    }
}
impl TryFrom<ExactDecimal> for FeeRate {
    type Error = Error;
    fn try_from(value: ExactDecimal) -> Result<Self, Error> {
        Self::new(value)
    }
}
impl From<FeeRate> for ExactDecimal {
    fn from(value: FeeRate) -> Self {
        value.0
    }
}

/// A positive source-reported transaction size in virtual bytes.
/// Some sources report fractional weight/4; quarter-byte increments are retained,
/// never rounded. An integer ceiling reported by another source also remains exact.
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(try_from = "ExactDecimal", into = "ExactDecimal")]
pub struct VirtualSize(ExactDecimal);
impl VirtualSize {
    /// Requires a positive size within the four-million-weight-unit block bound.
    /// # Errors
    /// Rejects zero, negative, non-quarter increments or more than one million virtual bytes.
    pub fn new(value: ExactDecimal) -> Result<Self, Error> {
        let quarter_increment = value
            .canonical()
            .split_once('.')
            .is_none_or(|(_, fraction)| matches!(fraction, "25" | "5" | "75"));
        if value.is_negative()
            || value.is_zero()
            || !quarter_increment
            || value > ExactDecimal::parse("1000000")?
        {
            return Err(invalid());
        }
        Ok(Self(value))
    }
    /// Returns exact virtual bytes, including a supplied fractional value.
    #[must_use]
    pub const fn value(&self) -> &ExactDecimal {
        &self.0
    }
}
impl TryFrom<ExactDecimal> for VirtualSize {
    type Error = Error;
    fn try_from(value: ExactDecimal) -> Result<Self, Error> {
        Self::new(value)
    }
}
impl From<VirtualSize> for ExactDecimal {
    fn from(value: VirtualSize) -> Self {
        value.0
    }
}

/// One fee-distribution bin with an exact lower fee-rate boundary and bin vbytes.
/// Vbytes belong to this bin, not a cumulative total. The first bin has no upper
/// boundary; later bins use the previous bin's lower boundary as their upper bound.
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct FeeHistogramBin {
    lower_rate: FeeRate,
    virtual_bytes: u64,
}
impl FeeHistogramBin {
    /// Records exact source boundaries and the individual bin's virtual-byte count.
    #[must_use]
    pub const fn new(lower_rate: FeeRate, virtual_bytes: u64) -> Self {
        Self {
            lower_rate,
            virtual_bytes,
        }
    }
    /// Returns the source-reported lower rate in sat/vB.
    #[must_use]
    pub const fn lower_rate(&self) -> &FeeRate {
        &self.lower_rate
    }
    /// Returns this bin's virtual-byte total, not a cumulative quantity.
    #[must_use]
    pub const fn virtual_bytes(&self) -> u64 {
        self.virtual_bytes
    }
}

/// Source-reported backlog totals and a possibly empty or partial fee histogram.
/// An empty histogram does not mean an empty mempool.
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(try_from = "SummaryFields")]
pub struct MempoolSummary {
    transaction_count: u64,
    virtual_bytes: u64,
    total_fee: Satoshis,
    histogram: Vec<FeeHistogramBin>,
}
impl MempoolSummary {
    /// Hard collection bound independent of configured HTTP response bytes.
    pub const MAX_HISTOGRAM_BINS: usize = 100_000;
    /// Records source totals and strictly descending individual histogram bins.
    /// # Errors
    /// Rejects excessive bins, duplicate/ascending rates, overflowing or excess
    /// bin totals, and a zero transaction count with nonzero totals/bins.
    pub fn new(
        transaction_count: u64,
        virtual_bytes: u64,
        total_fee: Satoshis,
        histogram: Vec<FeeHistogramBin>,
    ) -> Result<Self, Error> {
        let sum = histogram
            .iter()
            .try_fold(0_u64, |sum, bin| sum.checked_add(bin.virtual_bytes()));
        if histogram.len() > Self::MAX_HISTOGRAM_BINS
            || histogram
                .windows(2)
                .any(|bins| bins[0].lower_rate() <= bins[1].lower_rate())
            || sum.is_none_or(|sum| sum > virtual_bytes)
            || (transaction_count == 0
                && (virtual_bytes != 0 || total_fee.raw() != 0 || !histogram.is_empty()))
            || (transaction_count != 0 && virtual_bytes == 0)
        {
            return Err(invalid());
        }
        Ok(Self {
            transaction_count,
            virtual_bytes,
            total_fee,
            histogram,
        })
    }
    /// Returns the source's mempool transaction count at this retrieval.
    #[must_use]
    pub const fn transaction_count(&self) -> u64 {
        self.transaction_count
    }
    /// Returns total virtual bytes reported by the source.
    #[must_use]
    pub const fn virtual_bytes(&self) -> u64 {
        self.virtual_bytes
    }
    /// Returns the exact aggregate fees in satoshis.
    #[must_use]
    pub const fn total_fee(&self) -> Satoshis {
        self.total_fee
    }
    /// Returns the source's individual bins, which may cover only part of the pool.
    #[must_use]
    pub fn histogram(&self) -> &[FeeHistogramBin] {
        &self.histogram
    }
}
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct SummaryFields {
    transaction_count: u64,
    virtual_bytes: u64,
    total_fee: Satoshis,
    histogram: Vec<FeeHistogramBin>,
}
impl TryFrom<SummaryFields> for MempoolSummary {
    type Error = Error;
    fn try_from(v: SummaryFields) -> Result<Self, Error> {
        Self::new(
            v.transaction_count,
            v.virtual_bytes,
            v.total_fee,
            v.histogram,
        )
    }
}

/// A simplified source-reported transaction that recently entered its mempool.
/// No raw transaction, membership proof or continuing unconfirmed state is implied.
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(try_from = "RecentFields")]
pub struct RecentTransaction {
    txid: Txid,
    fee: Satoshis,
    virtual_size: VirtualSize,
    output_value: Satoshis,
}
impl RecentTransaction {
    /// Records identity, fee, source virtual size and sum of outputs in satoshis.
    /// # Errors
    /// Rejects an output-plus-fee total above Bitcoin's maximum money range.
    pub fn new(
        txid: Txid,
        fee: Satoshis,
        virtual_size: VirtualSize,
        output_value: Satoshis,
    ) -> Result<Self, Error> {
        if output_value
            .raw()
            .checked_add(fee.raw())
            .is_none_or(|sum| sum > bitcoin::Amount::MAX_MONEY.to_sat())
        {
            return Err(invalid());
        }
        Ok(Self {
            txid,
            fee,
            virtual_size,
            output_value,
        })
    }
    /// Returns the source-reported transaction ID.
    #[must_use]
    pub const fn txid(&self) -> Txid {
        self.txid
    }
    /// Returns the transaction's source-reported fee in satoshis.
    #[must_use]
    pub const fn fee(&self) -> Satoshis {
        self.fee
    }
    /// Returns exact source virtual bytes, without rounding weight/4.
    #[must_use]
    pub const fn virtual_size(&self) -> &VirtualSize {
        &self.virtual_size
    }
    /// Returns the source-reported total value of outputs in satoshis.
    #[must_use]
    pub const fn output_value(&self) -> Satoshis {
        self.output_value
    }
}
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct RecentFields {
    txid: Txid,
    fee: Satoshis,
    virtual_size: VirtualSize,
    output_value: Satoshis,
}
impl TryFrom<RecentFields> for RecentTransaction {
    type Error = Error;
    fn try_from(v: RecentFields) -> Result<Self, Error> {
        Self::new(v.txid, v.fee, v.virtual_size, v.output_value)
    }
}

/// The source's last at most ten arrivals, never an exhaustive mempool listing.
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(try_from = "Vec<RecentTransaction>", into = "Vec<RecentTransaction>")]
pub struct RecentTransactions(Vec<RecentTransaction>);
impl RecentTransactions {
    /// Maximum number of entries supported by the documented recent endpoint.
    pub const MAX_ENTRIES: usize = 10;
    /// Retains supplied order without inventing arrival timestamps.
    /// # Errors
    /// Rejects more than ten entries or duplicate transaction IDs.
    pub fn new(values: Vec<RecentTransaction>) -> Result<Self, Error> {
        let mut ids = BTreeSet::new();
        if values.len() > Self::MAX_ENTRIES || values.iter().any(|value| !ids.insert(value.txid()))
        {
            return Err(invalid());
        }
        Ok(Self(values))
    }
    /// Returns source order; an empty list remains empty.
    #[must_use]
    pub fn transactions(&self) -> &[RecentTransaction] {
        &self.0
    }
}
impl TryFrom<Vec<RecentTransaction>> for RecentTransactions {
    type Error = Error;
    fn try_from(v: Vec<RecentTransaction>) -> Result<Self, Error> {
        Self::new(v)
    }
}
impl From<RecentTransactions> for Vec<RecentTransaction> {
    fn from(v: RecentTransactions) -> Self {
        v.0
    }
}

/// An explicit local bound for a full, unpaged mempool transaction-ID response.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(try_from = "u32", into = "u32")]
pub struct TransactionLimit(u32);
impl TransactionLimit {
    /// Largest accepted transaction-ID collection; exceedance fails wholly.
    pub const MAXIMUM: u32 = 100_000;
    /// Records an explicit bound in 1..=100000, without changing the endpoint.
    /// # Errors
    /// Rejects zero or an excessive bound.
    pub fn new(value: u32) -> Result<Self, Error> {
        if value == 0 || value > Self::MAXIMUM {
            return Err(ValidationError::InvalidPageRequest.into());
        }
        Ok(Self(value))
    }
    /// Returns the maximum entries the caller permits in this response.
    #[must_use]
    pub const fn get(self) -> u32 {
        self.0
    }
}
impl TryFrom<u32> for TransactionLimit {
    type Error = Error;
    fn try_from(v: u32) -> Result<Self, Error> {
        Self::new(v)
    }
}
impl From<TransactionLimit> for u32 {
    fn from(v: TransactionLimit) -> Self {
        v.0
    }
}

/// A bounded full source mempool ID list in arbitrary source order.
/// No pagination, sorted order or atomic agreement with another read is implied.
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(try_from = "IdsFields")]
pub struct TransactionIds {
    limit: TransactionLimit,
    txids: Vec<Txid>,
}
impl TransactionIds {
    /// Retains every returned ID or rejects the response wholly at the supplied cap.
    /// # Errors
    /// Rejects too many IDs or duplicates; never truncates or manufactures a cursor.
    pub fn new(limit: TransactionLimit, txids: Vec<Txid>) -> Result<Self, Error> {
        let mut ids = BTreeSet::new();
        if txids.len() > limit.get() as usize || txids.iter().any(|id| !ids.insert(*id)) {
            return Err(invalid());
        }
        Ok(Self { limit, txids })
    }
    /// Returns the caller's explicit local collection cap.
    #[must_use]
    pub const fn limit(&self) -> TransactionLimit {
        self.limit
    }
    /// Returns every source ID in its original arbitrary order.
    #[must_use]
    pub fn txids(&self) -> &[Txid] {
        &self.txids
    }
}
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct IdsFields {
    limit: TransactionLimit,
    txids: Vec<Txid>,
}
impl TryFrom<IdsFields> for TransactionIds {
    type Error = Error;
    fn try_from(v: IdsFields) -> Result<Self, Error> {
        Self::new(v.limit, v.txids)
    }
}

/// Five exact sat/vB suggestions, retaining the source's named time/economy classes.
/// No recommendation ordering or confirmation-time promise is inferred.
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RecommendedFees {
    fastest: FeeRate,
    half_hour: FeeRate,
    hour: FeeRate,
    economy: FeeRate,
    minimum: FeeRate,
}
impl RecommendedFees {
    /// Records the source's five independent nonnegative suggestions.
    #[must_use]
    pub const fn new(
        fastest: FeeRate,
        half_hour: FeeRate,
        hour: FeeRate,
        economy: FeeRate,
        minimum: FeeRate,
    ) -> Self {
        Self {
            fastest,
            half_hour,
            hour,
            economy,
            minimum,
        }
    }
    /// Returns the source's fastest-confirmation suggestion in sat/vB.
    #[must_use]
    pub const fn fastest(&self) -> &FeeRate {
        &self.fastest
    }
    /// Returns the source's half-hour suggestion in sat/vB.
    #[must_use]
    pub const fn half_hour(&self) -> &FeeRate {
        &self.half_hour
    }
    /// Returns the source's hour suggestion in sat/vB.
    #[must_use]
    pub const fn hour(&self) -> &FeeRate {
        &self.hour
    }
    /// Returns the source's economy suggestion in sat/vB.
    #[must_use]
    pub const fn economy(&self) -> &FeeRate {
        &self.economy
    }
    /// Returns the source's minimum recommendation in sat/vB, not an acceptance guarantee.
    #[must_use]
    pub const fn minimum(&self) -> &FeeRate {
        &self.minimum
    }
}