Skip to main content

zk_encryption/
lib.rs

1//! The post-quantum envelope channel of the folded eid + Emit V2 transfer,
2//! for wallets and receiver services: the complement to the circuits in
3//! `noir/`. `PROTOCOL.md` is the protocol; `README.md` the flows.
4//!
5//! - Primitives the circuits match: [`poseidon`] (Poseidon2 over BN254 and
6//!   the domain tags), [`grumpkin`] (points and keys), [`lattice`] (K-PKE
7//!   over a real ML-KEM-768 key with bounded noise, the key and ciphertext
8//!   commitments), [`duplex`] (the keyed Poseidon2 duplex).
9//! - The channel: [`ratchet`] (the handshake, the chain step, keyed sealing,
10//!   the receiver's sessions).
11//! - The parties: [`receiver`] (long-term keys, [`bundle`], scanning and
12//!   opening) and [`sender`] (accepting a bundle, the handshake and ratchet
13//!   witnesses). Both states serialise behind the `serde` feature.
14//! - What travels: [`emit`] (the Emit V2 hashes, the `Envelope` event, note
15//!   openings, DG1's encoding) and [`witness`] (the values as the session
16//!   and envelope apps' Noir inputs).
17
18pub mod bundle;
19pub mod duplex;
20pub mod emit;
21pub mod grumpkin;
22pub mod lattice;
23pub mod poseidon;
24pub mod ratchet;
25pub mod receiver;
26pub mod sender;
27pub mod witness;
28
29#[cfg(feature = "serde")]
30mod persist;
31
32/// BN254's scalar field: Noir's `Field`, and Grumpkin's base field.
33pub use ark_bn254::Fr;
34
35#[derive(Clone, Debug, PartialEq, Eq)]
36pub enum Error {
37    /// A scalar was zero where a key or ephemeral is needed.
38    ZeroScalar,
39    /// A point isn't on Grumpkin (or is the identity).
40    NotOnCurve,
41    /// A payload isn't whole blocks of 3 fields, or bytes have the wrong length.
42    BadLength,
43    /// The ML-KEM encapsulation key fails the FIPS 203 modulus check.
44    BadPqKey,
45    /// SampleNTT needs more than the circuit's bound of SHAKE128 blocks (2^-102 per key).
46    KeyNeedsMoreBlocks,
47    /// A noise coefficient is outside [-2, 2].
48    NoiseOutOfRange,
49    /// The carried lattice ciphertext doesn't open its commitment.
50    CiphertextMismatch,
51    /// A handshake's tag doesn't match this receiver's keys.
52    NotForUs,
53    /// The handshake's root doesn't match its commitment, or a note opening
54    /// doesn't match the transfer's C0.
55    HandshakeMismatch,
56    /// No held chain key matches the transfer's commitment.
57    UnknownCommitment,
58    /// C_t was already consumed (a reused chain index) or the handshake was
59    /// already opened (a replay).
60    ReusedIndex,
61    /// The sender's channel has no handshake yet, or already has one.
62    ChannelNotOpen,
63    ChannelAlreadyOpen,
64}
65
66impl std::fmt::Display for Error {
67    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
68        write!(f, "{self:?}")
69    }
70}
71
72impl std::error::Error for Error {}
73
74#[cfg(test)]
75mod tests;