Skip to main content

hns_hnsr_protocol/
lib.rs

1#![doc = "Runtime-independent wire types for draft HIP #78 HNSR."]
2
3pub mod body;
4pub mod circuit;
5pub mod envelope;
6pub mod named;
7pub mod named_hrm;
8mod persistent_routing;
9pub mod record;
10pub mod requester_hrm;
11pub mod routing;
12pub mod runtime;
13
14pub use body::{
15    AcceptBody, CloseBody, ConfirmBody, ConfirmedBody, DataBody, ErrorBody, FindNodeBody,
16    GetRouteBody, HnsrErrorCode, IncomingBody, NodesBody, OpenBody, OpenedBody, PutResultBody,
17    PutRouteBody, RenewBody, RoutesBody, SampleRoutesBody, WindowBody, WithdrawBody,
18};
19pub use circuit::{
20    HnsrActionId, HnsrPeerId, HnsrRequester, HnsrRequesterConfig, HnsrRequesterEvent,
21    HnsrRequesterSnapshot, HnsrRoute, HnsrRuntimeError, HnsrRuntimeStatus, OpaqueRelayConfig,
22    OpaqueRelayRuntime, OpaqueRelaySnapshot, QueuedHnsrRoute,
23};
24pub use envelope::{HnsrOpcode, HnsrPacket};
25pub use named::{NamedRoutePolicy, NamedRouteRecordV2, NamedRouteTrust, named_route_key};
26pub use named::{OwnerBoundChatRouteTrust, verify_owner_bound_chat_route};
27#[doc(hidden)]
28pub use named_hrm::select_named_route_v3_uncommitted;
29pub use named_hrm::{HrmNamedRoutePolicy, NamedRouteRecordV3, named_route_key_v3};
30pub use persistent_routing::{
31    LeasedPersistentRendezvousError, LeasedPersistentRendezvousService,
32    LeasedPersistentRouteMutationError, NamedRouteV3Emission, NamedRouteV3GuardedCallbackError,
33    NamedRouteV3LeaseContext, NamedRouteV3LeaseLost, NamedRouteV3LedgerExpectation,
34    NamedRouteV3LedgerStorageState, NamedRouteV3OpenError, NamedRouteV3SoleOwnerLease,
35    NamedRouteV3StorageNamespace,
36};
37pub use record::{
38    EndpointDelegation, RelayTicket, ReserveRequest, RouteRecord, public_key, sign_withdrawal,
39    verify_withdrawal,
40};
41pub use requester_hrm::{
42    CurrentNamedRouteV3, HeldNamedRouteV3OperationLeases, HeldNamedRouteV3RequesterLease,
43    NamedRouteV3LeaseAcquireError, NamedRouteV3LeaseScopeError, NamedRouteV3OperationLeaseWitness,
44    NamedRouteV3RequesterExpectation, NamedRouteV3RequesterLeaseKey,
45    NamedRouteV3RequesterLeaseWitness, NamedRouteV3RequesterOperationError,
46    NamedRouteV3RequesterSnapshot, NamedRouteV3RequesterState, NamedRouteV3RequesterStorageState,
47    ReconfirmedNamedRouteV3RequesterState,
48};
49pub use routing::{
50    NamedRouteV3LedgerSnapshot, RendezvousContact, RouteRecordModel, RouteStore, RouteStoreLimits,
51    compare_distance, rendezvous_node_id, route_key, sample_score,
52};
53pub use runtime::{
54    ConfirmedReservation, EndpointReservation, HnsrService, RelayConfig, RelayLimits, RelayService,
55    RendezvousService,
56};
57
58use hns_encoding::DecodeError;
59use thiserror::Error;
60
61pub const HNSR_RENDEZVOUS_SERVICE: u64 = 0x0400_0000;
62pub const HNSR_RELAY_SERVICE: u64 = 0x0800_0000;
63pub const HNSR_PACKET_TYPE: u8 = 0xf3;
64pub const HNSR_VERSION: u8 = 1;
65pub const HNS_NODE_V1: u16 = 1;
66pub const HNS_WEB_V1: u16 = 2;
67pub const HNS_CHAT_V1: u16 = hns_chat_protocol::HNS_CHAT_PROFILE_V1;
68/// Opaque, end-to-end authenticated Shakescape atomic-swap sessions.
69pub const HNS_SHAKESCAPE_SWAP_V1: u16 = 4;
70
71pub const MAX_PACKET_SIZE: usize = 65_535;
72pub const MAX_RECORD_SIZE: usize = 8192;
73pub const MAX_RECORDS_PER_KEY: usize = 16;
74pub const MAX_STORED_RECORDS: usize = 50_000;
75pub const MAX_CONTACTS: usize = 16;
76pub const MAX_ROUTING_CONTACTS: usize = 2048;
77pub const MAX_FIND_QUERIES: usize = 32;
78pub const ROUTE_REPLICATION: usize = 8;
79pub const MIN_ROUTE_STORES: usize = 3;
80pub const MAX_DATA_SIZE: usize = 16_384;
81pub const MAX_CIRCUIT_QUEUE: usize = 65_536;
82pub const MIN_WINDOW: u32 = 16_384;
83pub const DEFAULT_WINDOW: u32 = 65_536;
84pub const MAX_WINDOW: u32 = 1_048_576;
85pub const MAX_TICKET_LIFETIME: u64 = 7200;
86pub const MAX_ROUTE_LIFETIME: u64 = 7200;
87pub const MAX_DELEGATION_LIFETIME: u64 = 604_800;
88pub const MAX_CIRCUITS: u16 = 32;
89pub const MAX_SIGNATURE_SIZE: usize = 80;
90
91#[derive(Debug, Error)]
92pub enum HnsrProtocolError {
93    #[error(transparent)]
94    Decode(#[from] DecodeError),
95    #[error("invalid HNSR value: {0}")]
96    Invalid(&'static str),
97    #[error("HNSR field length {actual} exceeds maximum {maximum}")]
98    TooLarge { actual: usize, maximum: usize },
99    #[error("HNSR signature operation failed")]
100    Cryptography,
101    #[error("invalid owner-bound HNS Chat identity: {0}")]
102    OwnerBinding(#[from] hns_chat_protocol::ChatProtocolError),
103    #[error("HNSR route store capacity reached")]
104    Capacity,
105    #[error("HNSR signature verification rate limit reached")]
106    VerificationRateLimited,
107    #[error("stale HNSR endpoint-delegation or route sequence")]
108    StaleSequence,
109    #[error("conflicting canonical HNSR endpoint delegations or routes have the same sequence")]
110    ConflictingSequence,
111    #[error("corrupt HNSR named-route replay-ledger snapshot")]
112    CorruptNamedRouteLedgerSnapshot,
113    #[error("incompatible HNSR named-route replay-ledger snapshot")]
114    IncompatibleNamedRouteLedgerSnapshot,
115    #[error("HNSR named-route replay-ledger revision space exhausted")]
116    NamedRouteLedgerRevisionExhausted,
117    #[error("corrupt HNSR named-route requester snapshot")]
118    CorruptNamedRouteRequesterSnapshot,
119    #[error("incompatible HNSR named-route requester snapshot")]
120    IncompatibleNamedRouteRequesterSnapshot,
121    #[error("HNSR named-route requester revision space exhausted")]
122    NamedRouteRequesterRevisionExhausted,
123    #[error("HNSR trusted clock rollback detected")]
124    ClockRollback,
125}
126
127pub(crate) fn is_zero(value: &[u8]) -> bool {
128    value.iter().all(|byte| *byte == 0)
129}