icydb_schema/
subaccount.rs

1//! Canonical fixed-width subaccount atom.
2
3use crate::{Principal, SchemaContractError, atom::deserialize_fixed_bytes};
4
5use serde::{Deserialize, Deserializer, Serialize};
6use std::fmt::{self, Display};
7
8//
9// Subaccount
10//
11
12type SubaccountBytes = [u8; 32];
13
14#[derive(Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
15/// A canonical 32-byte ICRC account subaccount.
16pub struct Subaccount(SubaccountBytes);
17
18impl Subaccount {
19    /// The lexicographically smallest subaccount.
20    pub const MIN: Self = Self::from_array([0x00; 32]);
21    /// The lexicographically largest subaccount.
22    pub const MAX: Self = Self::from_array([0xFF; 32]);
23
24    /// Return the fixed-width byte array.
25    #[must_use]
26    pub const fn to_array(&self) -> [u8; 32] {
27        self.0
28    }
29
30    /// Construct from the exact fixed-width byte array.
31    #[must_use]
32    pub const fn from_array(array: [u8; 32]) -> Self {
33        Self(array)
34    }
35
36    /// Parse 64 ASCII hex digits, optionally prefixed by lowercase `0x`.
37    ///
38    /// # Errors
39    /// Returns [`SchemaContractError::InvalidLiteral`] for invalid width,
40    /// non-ASCII input or non-hex characters. No trimming is performed.
41    pub fn from_hex(text: &str) -> Result<Self, SchemaContractError> {
42        let text = text.strip_prefix("0x").unwrap_or(text);
43        if text.len() != 64 || !text.bytes().all(|byte| byte.is_ascii_hexdigit()) {
44            return Err(SchemaContractError::InvalidLiteral);
45        }
46        let mut bytes = [0; 32];
47        for (index, pair) in text.as_bytes().as_chunks::<2>().0.iter().enumerate() {
48            let pair =
49                std::str::from_utf8(pair).map_err(|_| SchemaContractError::InvalidLiteral)?;
50            bytes[index] =
51                u8::from_str_radix(pair, 16).map_err(|_| SchemaContractError::InvalidLiteral)?;
52        }
53        Ok(Self::from_array(bytes))
54    }
55
56    /// Borrow the fixed-width bytes.
57    #[must_use]
58    pub const fn as_slice(&self) -> &[u8] {
59        &self.0
60    }
61
62    /// Consume the value and return its fixed-width bytes.
63    #[must_use]
64    pub const fn to_bytes(self) -> [u8; 32] {
65        self.0
66    }
67}
68
69impl<'de> Deserialize<'de> for Subaccount {
70    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
71    where
72        D: Deserializer<'de>,
73    {
74        if deserializer.is_human_readable() {
75            return SubaccountBytes::deserialize(deserializer).map(Self);
76        }
77
78        deserialize_fixed_bytes(deserializer).map(Self::from_array)
79    }
80}
81
82impl Display for Subaccount {
83    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
84        for byte in &self.0 {
85            write!(f, "{byte:02x}")?;
86        }
87
88        Ok(())
89    }
90}
91
92// code taken from
93// <https://docs.rs/ic-ledger-types/latest/src/ic_ledger_types/lib.rs.html#140-148>
94#[expect(clippy::cast_possible_truncation)]
95impl From<Principal> for Subaccount {
96    fn from(principal: Principal) -> Self {
97        let mut bytes = [0u8; 32];
98        let p = principal.as_slice();
99
100        // Defensive check: Principals are currently <= 29 bytes
101        let len = p.len().min(31); // reserve 1 byte for the length prefix
102        bytes[0] = len as u8;
103
104        // Copy safely without panic risk
105        bytes[1..=len].copy_from_slice(&p[..len]);
106
107        Self(bytes)
108    }
109}
110
111impl Serialize for Subaccount {
112    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
113    where
114        S: serde::Serializer,
115    {
116        if serializer.is_human_readable() {
117            self.0.serialize(serializer)
118        } else {
119            serializer.serialize_bytes(&self.0)
120        }
121    }
122}
123
124#[cfg(test)]
125mod tests {
126    use super::*;
127    use crate::Account;
128
129    #[test]
130    fn hex_text_preserves_every_byte_with_optional_prefix() {
131        for byte in 0..=u8::MAX {
132            let expected = Subaccount::from_array([byte; 32]);
133            for text in [
134                format!("{byte:02x}").repeat(32),
135                format!("{byte:02X}").repeat(32),
136            ] {
137                assert_eq!(Subaccount::from_hex(&text), Ok(expected));
138                assert_eq!(Subaccount::from_hex(&format!("0x{text}")), Ok(expected));
139            }
140        }
141    }
142
143    #[test]
144    fn hex_text_rejects_width_unicode_and_nonhex_boundaries() {
145        for text in [
146            String::new(),
147            "0x".into(),
148            "0".repeat(63),
149            "0".repeat(65),
150            "g".repeat(64),
151            "+1".repeat(32),
152            "-1".repeat(32),
153            format!("aé{}", "0".repeat(61)),
154            format!(" {}", "0".repeat(64)),
155            format!("0X{}", "0".repeat(64)),
156        ] {
157            assert_eq!(
158                Subaccount::from_hex(&text),
159                Err(SchemaContractError::InvalidLiteral)
160            );
161        }
162    }
163
164    #[test]
165    fn binary_serde_and_wire_preserve_exact_subaccount_bytes() {
166        for byte in [0, 23, 24, 128, 255] {
167            let value = Subaccount::from_array([byte; 32]);
168            let json = serde_json::to_string(&value).unwrap();
169            assert_eq!(json, serde_json::to_string(&value.to_array()).unwrap());
170            assert_eq!(serde_json::from_str::<Subaccount>(&json).unwrap(), value);
171
172            let wire = crate::wire::encode_one(value).unwrap();
173            assert_eq!(
174                wire,
175                crate::wire::encode_one(serde_bytes::Bytes::new(&value.to_array())).unwrap()
176            );
177            assert_eq!(wire.len(), 33);
178            assert_eq!(crate::wire::decode_one::<Subaccount>(&wire).unwrap(), value);
179
180            let batch = vec![value; 1_000];
181            let encoded = crate::wire::encode_one(&batch).unwrap();
182            assert_eq!(encoded.len(), 33_002);
183            assert_eq!(
184                crate::wire::decode_one::<Vec<Subaccount>>(&encoded).unwrap(),
185                batch
186            );
187        }
188    }
189
190    #[test]
191    fn binary_subaccount_ingress_enforces_width_and_byte_elements() {
192        for len in [0, 31, 33, 1_024] {
193            let wire = crate::wire::encode_one(vec![0_u8; len]).unwrap();
194            assert!(crate::wire::decode_one::<Subaccount>(&wire).is_err());
195            let bytes = vec![0_u8; len];
196            let encoded = crate::wire::encode_one(serde_bytes::Bytes::new(&bytes)).unwrap();
197            assert!(crate::wire::decode_one::<Subaccount>(&encoded).is_err());
198        }
199        // Postcard carries values without source integer-type tags: use a value
200        // outside the byte domain rather than zero, which also encodes as u8.
201        let wire = crate::wire::encode_one(vec![256_u16; 32]).unwrap();
202        assert!(crate::wire::decode_one::<Subaccount>(&wire).is_err());
203
204        // Keep sequence width and element admission covered through Serde's
205        // sequence adapter. Wire itself carries no source-type tags.
206        let array = serde::de::value::SeqDeserializer::<_, serde::de::value::Error>::new(
207            vec![255_u8; 32].into_iter(),
208        );
209        assert_eq!(Subaccount::deserialize(array).unwrap(), Subaccount::MAX);
210        for array in [vec![0_u16; 31], vec![0; 33], vec![256; 32]] {
211            let array = serde::de::value::SeqDeserializer::<_, serde::de::value::Error>::new(
212                array.into_iter(),
213            );
214            assert!(Subaccount::deserialize(array).is_err());
215        }
216
217        let encoded = crate::wire::encode_one(Subaccount::MAX).unwrap();
218        for end in 0..encoded.len() {
219            assert!(crate::wire::decode_one::<Subaccount>(&encoded[..end]).is_err());
220        }
221    }
222
223    #[test]
224    fn accounts_roundtrip_optional_subaccounts_on_wire_and_json() {
225        for subaccount in [None, Some(Subaccount::MIN), Some(Subaccount::MAX)] {
226            let account = Account::from_owner_and_subaccount(Principal::anonymous(), subaccount);
227            let json = serde_json::to_string(&account).unwrap();
228            assert_eq!(serde_json::from_str::<Account>(&json).unwrap(), account);
229            let wire = crate::wire::encode_one(account).unwrap();
230            // Native account projection is the ordered owner/optional-bytes pair.
231            assert_eq!(
232                wire,
233                crate::wire::encode_one((account.owner(), subaccount)).unwrap()
234            );
235            assert_eq!(crate::wire::decode_one::<Account>(&wire).unwrap(), account);
236        }
237    }
238}
icydb_schema/subaccount.rs

icydb_schema/
subaccount.rs
