scope-bca-core 0.8.2

Scope Blockchain Analysis - Core library for blockchain data analysis
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

//! Shared formatting utilities for consistent presentation across all chains.

/// Formats a USD value with K, M, B suffixes.
///
/// # Examples
///
/// ```
/// use scope::display::format::format_usd;
///
/// assert_eq!(format_usd(1_500_000_000.0), "$1.50B");
/// assert_eq!(format_usd(1_500_000.0), "$1.50M");
/// assert_eq!(format_usd(1_500.0), "$1.50K");
/// assert_eq!(format_usd(15.50), "$15.50");
/// ```
/// Decimals for prices near `reference`: the one precision rule for
/// every surface (M3). 2 from 1000, 6 near a USD peg (stablecoins), 4 from
/// 1, 6 from 0.01, 8 from 0.0001, else 10. A list of prices (a book) takes
/// its decimals from one reference, so its rows line up.
pub fn price_decimals(reference: f64) -> usize {
    let a = reference.abs();
    if a >= 1000.0 {
        2
    } else if crate::tokens::is_stablecoin_price(a) {
        6
    } else if a >= 1.0 {
        4
    } else if a >= 0.01 {
        6
    } else if a >= 0.0001 {
        8
    } else {
        10
    }
}

/// A price at the decimals of its own size ([`price_decimals`]).
pub fn format_price(price: f64) -> String {
    format!("{price:.*}", price_decimals(price))
}

/// [`format_price`] in USD.
pub fn format_price_usd(price: f64) -> String {
    format!("${}", format_price(price))
}

pub fn format_usd(value: f64) -> String {
    format!("${}", format_large_number(value))
}

/// Formats a large number with K, M, B suffixes (no currency prefix).
///
/// # Examples
///
/// ```
/// use scope::display::format::format_large_number;
///
/// assert_eq!(format_large_number(1_500_000_000.0), "1.50B");
/// assert_eq!(format_large_number(1_500_000.0), "1.50M");
/// assert_eq!(format_large_number(1_500.0), "1.50K");
/// assert_eq!(format_large_number(500.0), "500.00");
/// ```
pub fn format_large_number(value: f64) -> String {
    if value >= 1_000_000_000.0 {
        format!("{:.2}B", value / 1_000_000_000.0)
    } else if value >= 1_000_000.0 {
        format!("{:.2}M", value / 1_000_000.0)
    } else if value >= 1_000.0 {
        format!("{:.2}K", value / 1_000.0)
    } else {
        format!("{:.2}", value)
    }
}

/// Formats a raw token balance string with proper decimals and K/M/B suffixes.
///
/// # Arguments
///
/// * `balance` - Raw balance in smallest units (e.g., wei, lamports)
/// * `decimals` - Token decimal places
///
/// # Examples
///
/// ```
/// use scope::display::format::format_token_balance;
///
/// assert!(format_token_balance("1000000000000000000", 18).starts_with("1.00"));
/// assert!(format_token_balance("5000000000000000000000000", 18).contains("M"));
/// ```
pub fn format_token_balance(balance: &str, decimals: u8) -> String {
    let balance_f64: f64 = balance.parse().unwrap_or(0.0);
    let divisor = 10_f64.powi(decimals as i32);
    let formatted = balance_f64 / divisor;

    if formatted >= 1_000_000_000.0 {
        format!("{:.2}B", formatted / 1_000_000_000.0)
    } else if formatted >= 1_000_000.0 {
        format!("{:.2}M", formatted / 1_000_000.0)
    } else if formatted >= 1_000.0 {
        format!("{:.2}K", formatted / 1_000.0)
    } else {
        format!("{:.4}", formatted)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_format_usd() {
        assert_eq!(format_usd(1_500_000_000.0), "$1.50B");
        assert_eq!(format_usd(1_500_000.0), "$1.50M");
        assert_eq!(format_usd(1_500.0), "$1.50K");
        assert_eq!(format_usd(15.50), "$15.50");
        assert_eq!(format_usd(0.0), "$0.00");
    }

    #[test]
    fn test_format_large_number() {
        assert_eq!(format_large_number(500.0), "500.00");
        assert_eq!(format_large_number(1_500.0), "1.50K");
        assert_eq!(format_large_number(1_500_000.0), "1.50M");
        assert_eq!(format_large_number(1_500_000_000.0), "1.50B");
    }

    #[test]
    fn test_format_token_balance() {
        assert!(format_token_balance("1000000000000000000", 18).starts_with("1.00"));
        assert!(format_token_balance("5000000000000000000", 18).contains("5.00"));
        assert!(format_token_balance("0", 18).starts_with("0.00"));
    }
}