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}