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.is_ascii() {
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            format!("aé{}", "0".repeat(61)),
152            format!(" {}", "0".repeat(64)),
153            format!("0X{}", "0".repeat(64)),
154        ] {
155            assert_eq!(
156                Subaccount::from_hex(&text),
157                Err(SchemaContractError::InvalidLiteral)
158            );
159        }
160    }
161
162    #[test]
163    fn binary_serde_and_wire_preserve_exact_subaccount_bytes() {
164        for byte in [0, 23, 24, 128, 255] {
165            let value = Subaccount::from_array([byte; 32]);
166            let mut encoded = Vec::new();
167            serde_cbor::to_writer(&mut encoded, &value).unwrap();
168            assert_eq!(encoded.len(), 34);
169            let wire: serde_cbor::Value = serde_cbor::from_slice(encoded.as_slice()).unwrap();
170            assert_eq!(wire, serde_cbor::Value::Bytes(value.to_bytes().to_vec()));
171            assert_eq!(
172                serde_cbor::from_slice::<Subaccount>(encoded.as_slice()).unwrap(),
173                value
174            );
175
176            let json = serde_json::to_string(&value).unwrap();
177            assert_eq!(json, serde_json::to_string(&value.to_array()).unwrap());
178            assert_eq!(serde_json::from_str::<Subaccount>(&json).unwrap(), value);
179
180            let wire = crate::wire::encode_one(value).unwrap();
181            assert_eq!(
182                wire,
183                crate::wire::encode_one(serde_bytes::Bytes::new(&value.to_array())).unwrap()
184            );
185            assert_eq!(wire.len(), 33);
186            assert_eq!(crate::wire::decode_one::<Subaccount>(&wire).unwrap(), value);
187
188            let batch = vec![value; 1_000];
189            encoded.clear();
190            serde_cbor::to_writer(&mut encoded, &batch).unwrap();
191            assert_eq!(encoded.len(), 34_003);
192            assert_eq!(
193                serde_cbor::from_slice::<Vec<Subaccount>>(encoded.as_slice()).unwrap(),
194                batch
195            );
196        }
197    }
198
199    #[test]
200    fn binary_subaccount_ingress_enforces_width_and_byte_elements() {
201        for len in [0, 31, 33, 1_024] {
202            let wire = crate::wire::encode_one(vec![0_u8; len]).unwrap();
203            assert!(crate::wire::decode_one::<Subaccount>(&wire).is_err());
204            let mut encoded = Vec::new();
205            serde_cbor::to_writer(&mut encoded, &serde_bytes::Bytes::new(&vec![0; len])).unwrap();
206            assert!(serde_cbor::from_slice::<Subaccount>(encoded.as_slice()).is_err());
207        }
208        // Postcard carries values without source integer-type tags: use a value
209        // outside the byte domain rather than zero, which also encodes as u8.
210        let wire = crate::wire::encode_one(vec![256_u16; 32]).unwrap();
211        assert!(crate::wire::decode_one::<Subaccount>(&wire).is_err());
212
213        // Self-describing binary formats may present bytes as a byte string or
214        // an array. Both retain the exact width and byte-element contract.
215        let array = serde_cbor::to_vec(&vec![255_u8; 32]).unwrap();
216        assert_eq!(
217            serde_cbor::from_slice::<Subaccount>(&array).unwrap(),
218            Subaccount::MAX
219        );
220        for array in [vec![0_u16; 31], vec![0; 33], vec![256; 32]] {
221            let encoded = serde_cbor::to_vec(&array).unwrap();
222            assert!(serde_cbor::from_slice::<Subaccount>(&encoded).is_err());
223        }
224
225        let mut encoded = Vec::new();
226        serde_cbor::to_writer(&mut encoded, &Subaccount::MAX).unwrap();
227        for end in 0..encoded.len() {
228            assert!(serde_cbor::from_slice::<Subaccount>(&encoded[..end]).is_err());
229        }
230    }
231
232    #[test]
233    fn accounts_roundtrip_optional_subaccounts_in_all_transports() {
234        for subaccount in [None, Some(Subaccount::MIN), Some(Subaccount::MAX)] {
235            let account = Account::from_owner_and_subaccount(Principal::anonymous(), subaccount);
236            let mut encoded = Vec::new();
237            serde_cbor::to_writer(&mut encoded, &account).unwrap();
238            assert_eq!(encoded.len(), if subaccount.is_some() { 54 } else { 21 });
239            assert_eq!(
240                serde_cbor::from_slice::<Account>(encoded.as_slice()).unwrap(),
241                account
242            );
243            let json = serde_json::to_string(&account).unwrap();
244            assert_eq!(serde_json::from_str::<Account>(&json).unwrap(), account);
245            let wire = crate::wire::encode_one(account).unwrap();
246            // Native account projection is the ordered owner/optional-bytes pair.
247            assert_eq!(
248                wire,
249                crate::wire::encode_one((account.owner(), subaccount)).unwrap()
250            );
251            assert_eq!(crate::wire::decode_one::<Account>(&wire).unwrap(), account);
252        }
253    }
254}
icydb_schema/subaccount.rs

icydb_schema/
subaccount.rs
