Skip to main content

hns_covenants/
lib.rs

1#![doc = "Handshake name covenants, authenticated state, and resource values."]
2
3mod name_state;
4mod name_transition;
5mod resource;
6
7pub use name_state::{
8    HSD_MAX_SAFE_INTEGER, MAX_NAME_STATE_SIZE, NameState, decode_name_state, encode_name_state,
9};
10pub use name_transition::{
11    FINALIZE_COVENANT_ITEMS, FinalizeCovenant, MAX_TRANSFER_ADDRESS_HASH_SIZE,
12    MIN_TRANSFER_ADDRESS_HASH_SIZE, TRANSFER_COVENANT_ITEMS, TransferCovenant,
13};
14pub use resource::{Resource, ResourceName, ResourceRecord};
15
16use blake2::Blake2bVar;
17use blake2::digest::{Update, VariableOutput};
18use hns_encoding::{Decoder, Encoder};
19use hns_primitives::NameHash;
20use sha3::{Digest, Sha3_256};
21use thiserror::Error;
22
23pub const MAX_COVENANT_ITEMS: usize = 1000;
24pub const MAX_COVENANT_ITEM_SIZE: usize = 1_000_000;
25pub const MAX_COVENANT_ENCODED_SIZE: usize = MAX_COVENANT_ITEM_SIZE + 9;
26pub const MAX_NAME_SIZE: usize = 63;
27pub const MAX_RESOURCE_SIZE: usize = 512;
28
29#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
30pub enum CovenantKind {
31    None,
32    Claim,
33    Open,
34    Bid,
35    Reveal,
36    Redeem,
37    Register,
38    Update,
39    Renew,
40    Transfer,
41    Finalize,
42    Revoke,
43    Unknown(u8),
44}
45
46impl CovenantKind {
47    pub const fn from_u8(value: u8) -> Self {
48        match value {
49            0 => Self::None,
50            1 => Self::Claim,
51            2 => Self::Open,
52            3 => Self::Bid,
53            4 => Self::Reveal,
54            5 => Self::Redeem,
55            6 => Self::Register,
56            7 => Self::Update,
57            8 => Self::Renew,
58            9 => Self::Transfer,
59            10 => Self::Finalize,
60            11 => Self::Revoke,
61            value => Self::Unknown(value),
62        }
63    }
64
65    pub const fn as_u8(self) -> u8 {
66        match self {
67            Self::None => 0,
68            Self::Claim => 1,
69            Self::Open => 2,
70            Self::Bid => 3,
71            Self::Reveal => 4,
72            Self::Redeem => 5,
73            Self::Register => 6,
74            Self::Update => 7,
75            Self::Renew => 8,
76            Self::Transfer => 9,
77            Self::Finalize => 10,
78            Self::Revoke => 11,
79            Self::Unknown(value) => value,
80        }
81    }
82
83    pub const fn is_name(self) -> bool {
84        !matches!(self, Self::None | Self::Unknown(_))
85    }
86
87    pub const fn is_linked(self) -> bool {
88        matches!(
89            self,
90            Self::Reveal
91                | Self::Redeem
92                | Self::Register
93                | Self::Update
94                | Self::Renew
95                | Self::Transfer
96                | Self::Finalize
97                | Self::Revoke
98        )
99    }
100
101    pub const fn is_unspendable(self) -> bool {
102        matches!(self, Self::Revoke)
103    }
104}
105
106#[derive(Clone, Debug, Eq, PartialEq)]
107pub struct Covenant {
108    pub kind: CovenantKind,
109    pub items: Vec<Vec<u8>>,
110}
111
112impl Covenant {
113    pub fn encode(&self) -> Result<Vec<u8>, CovenantError> {
114        let encoded_size = self.encoded_size()?;
115        let mut encoder = Encoder::with_capacity(encoded_size);
116        encoder.put_u8(self.kind.as_u8());
117        encoder.put_compact_size(self.items.len() as u64);
118        for item in &self.items {
119            encoder.put_varbytes(item);
120        }
121        Ok(encoder.into_bytes())
122    }
123
124    pub fn encoded_size(&self) -> Result<usize, CovenantError> {
125        if self.items.len() > MAX_COVENANT_ITEMS {
126            return Err(CovenantError::TooLarge {
127                actual: self.items.len(),
128                maximum: MAX_COVENANT_ITEMS,
129            });
130        }
131        let mut encoded_size = 1_usize
132            .checked_add(compact_size_len(self.items.len() as u64))
133            .ok_or(CovenantError::TooLarge {
134                actual: usize::MAX,
135                maximum: MAX_COVENANT_ENCODED_SIZE,
136            })?;
137        for item in &self.items {
138            if item.len() > MAX_COVENANT_ITEM_SIZE {
139                return Err(CovenantError::TooLarge {
140                    actual: item.len(),
141                    maximum: MAX_COVENANT_ITEM_SIZE,
142                });
143            }
144            encoded_size = encoded_size
145                .checked_add(compact_size_len(item.len() as u64))
146                .and_then(|size| size.checked_add(item.len()))
147                .ok_or(CovenantError::TooLarge {
148                    actual: usize::MAX,
149                    maximum: MAX_COVENANT_ENCODED_SIZE,
150                })?;
151            if encoded_size > MAX_COVENANT_ENCODED_SIZE {
152                return Err(CovenantError::TooLarge {
153                    actual: encoded_size,
154                    maximum: MAX_COVENANT_ENCODED_SIZE,
155                });
156            }
157        }
158        Ok(encoded_size)
159    }
160
161    pub fn decode(input: &[u8]) -> Result<Self, CovenantError> {
162        if input.len() > MAX_COVENANT_ENCODED_SIZE {
163            return Err(CovenantError::TooLarge {
164                actual: input.len(),
165                maximum: MAX_COVENANT_ENCODED_SIZE,
166            });
167        }
168        let mut decoder = Decoder::new(input);
169        let covenant = Self::decode_from(&mut decoder)?;
170        decoder.finish()?;
171        Ok(covenant)
172    }
173
174    pub fn decode_from(decoder: &mut Decoder<'_>) -> Result<Self, CovenantError> {
175        Self::decode_from_with_limit(decoder, MAX_COVENANT_ENCODED_SIZE)
176    }
177
178    pub fn decode_from_with_limit(
179        decoder: &mut Decoder<'_>,
180        maximum_encoded_size: usize,
181    ) -> Result<Self, CovenantError> {
182        let maximum_encoded_size = maximum_encoded_size.min(MAX_COVENANT_ENCODED_SIZE);
183        if maximum_encoded_size < 2 {
184            return Err(CovenantError::TooLarge {
185                actual: 2,
186                maximum: maximum_encoded_size,
187            });
188        }
189        let start = decoder.position();
190        let kind = CovenantKind::from_u8(decoder.read_u8()?);
191        let count = decoder.read_compact_usize(MAX_COVENANT_ITEMS, "covenant items")?;
192        ensure_decode_budget(decoder, start, maximum_encoded_size)?;
193        let mut items = Vec::with_capacity(count.min(64));
194        for _ in 0..count {
195            let length = decoder.read_compact_usize(MAX_COVENANT_ITEM_SIZE, "covenant item")?;
196            let remaining = ensure_decode_budget(decoder, start, maximum_encoded_size)?;
197            if length > remaining {
198                return Err(CovenantError::TooLarge {
199                    actual: decoder
200                        .position()
201                        .saturating_sub(start)
202                        .saturating_add(length),
203                    maximum: maximum_encoded_size,
204                });
205            }
206            items.push(decoder.read_bounded_vec(length, remaining)?);
207        }
208        Ok(Self { kind, items })
209    }
210
211    pub fn encode_to(&self, encoder: &mut Encoder) -> Result<(), CovenantError> {
212        self.validate_bounds()?;
213        encoder.put_u8(self.kind.as_u8());
214        encoder.put_compact_size(self.items.len() as u64);
215        for item in &self.items {
216            encoder.put_varbytes(item);
217        }
218        Ok(())
219    }
220
221    pub fn item(&self, index: usize) -> Option<&[u8]> {
222        self.items.get(index).map(Vec::as_slice)
223    }
224
225    pub fn item_u8(&self, index: usize) -> Option<u8> {
226        let item = self.item(index)?;
227        (item.len() == 1).then_some(item[0])
228    }
229
230    pub fn item_u32(&self, index: usize) -> Option<u32> {
231        Some(u32::from_le_bytes(self.item(index)?.try_into().ok()?))
232    }
233
234    pub fn item_u64(&self, index: usize) -> Option<u64> {
235        Some(u64::from_le_bytes(self.item(index)?.try_into().ok()?))
236    }
237
238    pub fn item_name_hash(&self, index: usize) -> Option<NameHash> {
239        Some(NameHash::new(self.item(index)?.try_into().ok()?))
240    }
241
242    fn validate_bounds(&self) -> Result<(), CovenantError> {
243        self.encoded_size()?;
244        Ok(())
245    }
246}
247
248fn ensure_decode_budget(
249    decoder: &Decoder<'_>,
250    start: usize,
251    maximum: usize,
252) -> Result<usize, CovenantError> {
253    let consumed = decoder.position().saturating_sub(start);
254    if consumed > maximum {
255        return Err(CovenantError::TooLarge {
256            actual: consumed,
257            maximum,
258        });
259    }
260    Ok(maximum - consumed)
261}
262
263fn compact_size_len(value: u64) -> usize {
264    match value {
265        0..=0xfc => 1,
266        0xfd..=0xffff => 3,
267        0x1_0000..=0xffff_ffff => 5,
268        _ => 9,
269    }
270}
271
272impl Default for Covenant {
273    fn default() -> Self {
274        Self {
275            kind: CovenantKind::None,
276            items: Vec::new(),
277        }
278    }
279}
280
281pub fn validate_name(name: &[u8]) -> bool {
282    if name.is_empty() || name.len() > MAX_NAME_SIZE {
283        return false;
284    }
285    if matches!(
286        name,
287        b"example" | b"invalid" | b"local" | b"localhost" | b"test"
288    ) {
289        return false;
290    }
291    name.iter().copied().enumerate().all(|(index, byte)| {
292        matches!(byte, b'0'..=b'9' | b'a'..=b'z')
293            || matches!(byte, b'-' | b'_') && index != 0 && index + 1 != name.len()
294    })
295}
296
297pub fn hash_name(name: &[u8]) -> Result<NameHash, CovenantError> {
298    if !validate_name(name) {
299        return Err(CovenantError::InvalidName);
300    }
301    let mut hasher = Sha3_256::new();
302    Digest::update(&mut hasher, name);
303    Ok(NameHash::new(hasher.finalize().into()))
304}
305
306pub fn blind_bid(value: u64, nonce: &[u8; 32]) -> [u8; 32] {
307    let mut hasher = Blake2bVar::new(32).expect("valid BLAKE2b output length");
308    Update::update(&mut hasher, &value.to_le_bytes());
309    Update::update(&mut hasher, nonce);
310    let mut output = [0_u8; 32];
311    hasher
312        .finalize_variable(&mut output)
313        .expect("valid BLAKE2b output buffer");
314    output
315}
316
317#[derive(Debug, Error)]
318pub enum CovenantError {
319    #[error(transparent)]
320    Decode(#[from] hns_encoding::DecodeError),
321    #[error("covenant field length {actual} exceeds maximum {maximum}")]
322    TooLarge { actual: usize, maximum: usize },
323    #[error("invalid Handshake name")]
324    InvalidName,
325    #[error("unsupported Handshake resource version")]
326    UnsupportedResourceVersion,
327    #[error("unsupported Handshake resource record type {kind}")]
328    UnsupportedResourceRecord { kind: u8 },
329    #[error("invalid Handshake resource: {0}")]
330    InvalidResource(&'static str),
331    #[error("invalid Handshake name state: {0}")]
332    InvalidNameState(&'static str),
333    #[error("noncanonical Handshake name-state encoding")]
334    NonCanonicalNameState,
335    #[error("name-state name does not match its authenticated-tree key")]
336    NameStateHashMismatch,
337    #[error("invalid TRANSFER covenant: {0}")]
338    InvalidTransferCovenant(&'static str),
339    #[error("invalid FINALIZE covenant: {0}")]
340    InvalidFinalizeCovenant(&'static str),
341    #[error("FINALIZE name does not match its covenant name hash")]
342    FinalizeNameHashMismatch,
343}
344
345#[cfg(test)]
346mod tests {
347    use super::*;
348
349    #[test]
350    fn all_assigned_covenant_types_round_trip() {
351        for value in 0_u8..=11 {
352            let covenant = Covenant {
353                kind: CovenantKind::from_u8(value),
354                items: vec![vec![value], vec![2; 253]],
355            };
356            let encoded = covenant.encode().expect("valid");
357            assert_eq!(Covenant::decode(&encoded).expect("valid"), covenant);
358        }
359    }
360
361    #[test]
362    fn names_and_bid_commitments_match_hsd_vectors() {
363        assert_eq!(
364            hex::encode(hash_name(b"handshake").expect("valid").into_bytes()),
365            "3aa2528576f96bd40fcff0bd6b60c44221d73c43b4e42d4b908ed20a93b8d1b6"
366        );
367        assert_eq!(
368            hex::encode(hash_name(b"hsd").expect("valid").into_bytes()),
369            "1adba96cde054383892a08bb53ab627fb2a2842914d53bc5312e4c69f5688de1"
370        );
371        for invalid in [
372            b"".as_slice(),
373            b"Example",
374            b"-bad",
375            b"bad-",
376            b"local",
377            b"name!",
378        ] {
379            assert!(!validate_name(invalid), "{invalid:?}");
380        }
381        assert_eq!(
382            hex::encode(blind_bid(700, &[0x21; 32])),
383            "c82876caf7bfa613c5b64bd421bbc35f8f0654bc645b340a56b0df0c09668f81"
384        );
385    }
386
387    #[test]
388    fn codec_matches_pinned_hsd_fixture() {
389        let raw = hex::decode(
390            "030220aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa046e616d65",
391        )
392        .expect("hex");
393        let covenant = Covenant::decode(&raw).expect("valid");
394        assert_eq!(covenant.kind, CovenantKind::Bid);
395        assert_eq!(covenant.items, vec![vec![0xaa; 32], b"name".to_vec()]);
396        assert_eq!(covenant.encode().expect("valid"), raw);
397    }
398
399    #[test]
400    fn parser_rejects_noncanonical_and_oversized_items() {
401        assert!(Covenant::decode(&[0, 0xfd, 0, 0]).is_err());
402        assert!(
403            Covenant {
404                kind: CovenantKind::None,
405                items: vec![vec![0; MAX_COVENANT_ITEM_SIZE + 1]],
406            }
407            .encode()
408            .is_err()
409        );
410        assert!(Resource::new(Vec::new()).is_err());
411    }
412
413    #[test]
414    fn bounded_stream_decode_rejects_claimed_item_before_copying() {
415        let encoded = [0, 1, 0xfd, 0xfd, 0];
416        let mut decoder = Decoder::new(&encoded);
417        assert!(matches!(
418            Covenant::decode_from_with_limit(&mut decoder, 10),
419            Err(CovenantError::TooLarge {
420                actual: 258,
421                maximum: 10
422            })
423        ));
424    }
425}