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;