Skip to main content

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}