quai_payments/lib.rs
1//! BIP47 payment-code and local channel foundations for Quai.
2//!
3//! Payment derivation uses the pinned Quai coin-969 account path. Notification
4//! transaction construction, network discovery and automatic sends are separate.
5mod channel;
6mod code;
7pub use channel::{
8 CHANNEL_SCHEME, MAX_CHANNEL_BYTES, MAX_SEARCH_ATTEMPTS, PaymentChannel, PaymentDirection,
9 PaymentSearch, PaymentSearchResult,
10};
11pub use code::{
12 HARDENED_INDEX, PAYMENT_CODE_PREFIX, PaymentCode, PrivatePaymentCode, QUAI_PAYMENT_COIN,
13};
14
15/// Payment errors omit secret inputs and backend diagnostics.
16#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
17#[non_exhaustive]
18pub enum PaymentError {
19 /// Seed must contain 16 through 64 bytes.
20 #[error("invalid payment seed length")]
21 InvalidSeed,
22 /// Invalid code length, prefix, checksum, version, features, reserved bytes or point.
23 #[error("invalid BIP47 payment code")]
24 InvalidCode,
25 /// Account/child index would be hardened or overflow the supported domain.
26 #[error("invalid payment derivation index")]
27 InvalidIndex,
28 /// A BIP32 child, shared-secret scalar or additive key result is invalid.
29 #[error("payment key derivation failed")]
30 Derivation,
31 /// Channel metadata is not owned by the supplied private account.
32 #[error("payment channel owner mismatch")]
33 OwnerMismatch,
34 /// Unrecognized, duplicate or malformed channel metadata.
35 #[error("invalid payment channel metadata")]
36 InvalidChannel,
37 /// Cancellation preserves the first unexamined candidate for safe resumption.
38 #[error("payment search cancelled after {attempts} candidates")]
39 SearchCancelled {
40 /// Number of candidates already examined.
41 attempts: u32,
42 /// First unexamined candidate, or None if the index space is exhausted.
43 next_index: Option<u32>,
44 },
45 /// Search budget or nonhardened index space was exhausted without a match.
46 #[error("payment search exhausted after {attempts} candidates")]
47 SearchExhausted {
48 /// Number of candidates already examined.
49 attempts: u32,
50 /// First unexamined candidate, or None if the index space is exhausted.
51 next_index: Option<u32>,
52 },
53 /// A local resource policy was exceeded.
54 #[error("payment resource limit exceeded")]
55 Limit,
56}