ic-query 0.97.0

Internet Computer query library for CloudEngine, NNS, SNS, ICRC, system canisters, and public network metadata
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

#[must_use]
pub fn hex_bytes(bytes: &[u8]) -> String {
    const HEX: &[u8; 16] = b"0123456789abcdef";
    let mut out = String::with_capacity(bytes.len() * 2);
    for byte in bytes {
        out.push(HEX[usize::from(byte >> 4)] as char);
        out.push(HEX[usize::from(byte & 0x0f)] as char);
    }
    out
}

#[must_use]
#[cfg(any(
    test,
    feature = "dashboard-host",
    feature = "nns-host",
    feature = "sns-host",
    feature = "cmc-host"
))]
pub fn is_lowercase_hex(value: &str) -> bool {
    value
        .bytes()
        .all(|byte| byte.is_ascii_digit() || matches!(byte, b'a'..=b'f'))
}

#[must_use]
#[cfg(any(
    test,
    feature = "dashboard-host",
    feature = "nns-host",
    feature = "sns-host"
))]
pub fn is_lowercase_hex_32_bytes(value: &str) -> bool {
    value.len() == 64 && is_lowercase_hex(value)
}

///
/// decode_lowercase_hex
///
/// Decode even-length lowercase hexadecimal, including an empty byte string.
///

#[cfg(any(test, feature = "sns-host", feature = "subnet-catalog-host"))]
pub fn decode_lowercase_hex(value: &str) -> Option<Vec<u8>> {
    decode_hex_pairs(value, false)
}

/// Decode even-length ASCII hexadecimal with either letter case.
#[cfg(any(test, feature = "icrc-host"))]
pub fn decode_hex(value: &str) -> Option<Vec<u8>> {
    decode_hex_pairs(value, true)
}

#[cfg(any(
    test,
    feature = "icrc-host",
    feature = "sns-host",
    feature = "subnet-catalog-host"
))]
fn decode_hex_pairs(value: &str, allow_uppercase: bool) -> Option<Vec<u8>> {
    let (pairs, remainder) = value.as_bytes().as_chunks::<2>();
    if !remainder.is_empty() {
        return None;
    }
    let nibble = |byte| match byte {
        b'0'..=b'9' => Some(byte - b'0'),
        b'a'..=b'f' => Some(byte - b'a' + 10),
        b'A'..=b'F' if allow_uppercase => Some(byte - b'A' + 10),
        _ => None,
    };
    pairs
        .iter()
        .map(|pair| Some(nibble(pair[0])? * 16 + nibble(pair[1])?))
        .collect()
}

///
/// HexEvidenceError
///
/// Shape failure for nonempty, byte-counted lowercase hexadecimal evidence.
///

#[cfg(any(feature = "cmc-host", feature = "nns-host"))]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum HexEvidenceError {
    Empty,
    ByteCountOverflow,
    LengthMismatch,
    NonLowercaseHex,
}

/// Admit encoded evidence without decoding or allocating its bytes.
#[cfg(any(feature = "cmc-host", feature = "nns-host"))]
pub fn validate_nonempty_hex_evidence(
    value: &str,
    byte_count: usize,
) -> Result<(), HexEvidenceError> {
    if byte_count == 0 {
        return Err(HexEvidenceError::Empty);
    }
    let expected_length = byte_count
        .checked_mul(2)
        .ok_or(HexEvidenceError::ByteCountOverflow)?;
    if value.len() != expected_length {
        return Err(HexEvidenceError::LengthMismatch);
    }
    if !is_lowercase_hex(value) {
        return Err(HexEvidenceError::NonLowercaseHex);
    }
    Ok(())
}

#[cfg(test)]
mod tests;