poulpy/README.md
README.mdRaw
1# 🐙 Poulpy
2
3<p align="center">
4<img src="poulpy.png" />
5</p>
6
7**Poulpy** is a fast & modular FHE library that implements Ring-Learning-With-Errors based homomorphic encryption. It adopts the bivariate polynomial representation proposed in [Revisiting Key Decomposition Techniques for FHE: Simpler, Faster and More Generic](https://eprint.iacr.org/2023/771). In addition to simpler and more efficient arithmetic than the residue number system (RNS), this representation provides a common plaintext space for all schemes and allows easy switching between any two schemes. Poulpy also decouples the schemes implementations from the polynomial arithmetic backend by being built around a hardware abstraction layer (HAL). This enables user to easily provide or use a custom backend.
8
9### Bivariate Polynomial Representation
10
11Existing FHE implementations (such as [Lattigo](https://github.com/tuneinsight/lattigo) or [OpenFHE](https://github.com/openfheorg/openfhe-development)) use the [residue-number-system](https://en.wikipedia.org/wiki/Residue_number_system) (RNS) to represent large integers. Although the parallelism and carry-less arithmetic provided by the RNS representation provides a very efficient modular arithmetic over large-integers, it suffers from various drawbacks when used in the context of FHE. The main idea behind the bivariate representation is to decouple the cyclotomic arithmetic from the large number arithmetic. Instead of using the RNS representation for large integer, integers are decomposed in base $2^{-K}$ over the Torus $\mathbb{T}_{N}[X]$.
12
13This provides the following benefits:
14
15- **Intuitive, efficient and reusable parameterization & instances:** Only the bit-size of the modulus is required from the user (i.e. Torus precision). As such, parameterization is natural and generic, and instances can be reused for any circuit consuming the same homomorphic capacity, without loss of efficiency. With the RNS representation, individual NTT friendly primes needs to be specified for each level, making the parameterization not user friendly and circuit-specific.
16
17- **Optimal and granular rescaling:** Ciphertext rescaling is carried out with bit-shifting, enabling a bit-level granular rescaling and optimal noise/homomorphic capacity management. In the RNS representation, ciphertext division can only be done by one of the primes composing the modulus, leading to difficult scaling management and frequent inefficient noise/homomorphic capacity management.
18
19- **Linear number of DFT in the half external product:** The bivariate representation of the coefficients implicitly provides the digit decomposition, as such the number of DFT is linear in the number of limbs, contrary to the RNS representation where it is quadratic due to the RNS basis conversion. This enables a much more efficient key-switching, which is the **most used and expensive** FHE operation.
20
21- **Unified plaintext space:** The bivariate polynomial representation is by essence a high precision discretized representation of the Torus $\mathbb{T}_{N}[X]$. Using the Torus as the common plaintext space for all schemes achieves the vision of [CHIMERA: Combining Ring-LWE-based Fully Homomorphic Encryption Schemes](https://eprint.iacr.org/2018/758) which is to unify all RLWE-based FHE schemes (TFHE, FHEW, BGV, BFV, CLPX, GBFV, CKKS, ...) under a single scheme with different encodings, enabling native and efficient scheme-switching functionalities.
22
23- **Simpler implementation**: Since the cyclotomic arithmetic is decoupled from the coefficient representation, the same pipeline (including DFT) can be reused for all limbs (unlike in the RNS representation), making this representation a prime target for hardware acceleration.
24
25- **Deterministic computation**: Although being defined on the Torus, bivariate arithmetic remains integer polynomial arithmetic, ensuring all computations are deterministic, the contract being that output should be reproducible and identical, regardless of the backend or hardware.
26
27### Hardware Abstraction Layer
28
29In addition to providing a general purpose FHE library over a unified plaintext space, Poulpy is also designed from the ground up around a **hardware abstraction layer** that closely matches the API of [spqlios-arithmetic](https://github.com/tfhe/spqlios-arithmetic). The bivariate representation is by itself hardware friendly as it uses flat, aligned & vectorized memory layout. Finally, generic opaque write only structs (prepared versions) are provided, making it easy for developers to provide hardware focused/optimized operations. This makes possible for anyone to provide or use a custom backend.
30
31## Library Overview
32
33- **`backend/hal`**: hardware abstraction layer. This layer targets users that want to provide their own backend or use a third party backend.
34
35 - **`api`**: fixed public low-level polynomial level arithmetic API closely matching spqlios-arithmetic. The goal is to eventually freeze this API, in order to decouple it from the OEP traits, ensuring that changes to implementations do not affect the front end API.
36
37 ```rust
38 pub trait SvpPrepare<B: Backend> {
39 fn svp_prepare<R, A>(&self, res: &mut R, res_col: usize, a: &A, a_col: usize)
40 where
41 R: SvpPPolToMut<B>,
42 A: ScalarZnxToRef;
43 }
44 ````
45
46 - **`delegates`**: link between the user facing API and implementation OEP. Each trait of `api` is implemented by calling its corresponding trait on the `oep`.
47
48 ```rust
49 impl<B> SvpPrepare<B> for Module<B>
50 where
51 B: Backend + SvpPrepareImpl<B>,
52 {
53 fn svp_prepare<R, A>(&self, res: &mut R, res_col: usize, a: &A, a_col: usize)
54 where
55 R: SvpPPolToMut<B>,
56 A: ScalarZnxToRef,
57 {
58 B::svp_prepare_impl(self, res, res_col, a, a_col);
59 }
60 }
61 ```
62
63 - **`layouts`**: defines the layouts of the front-end algebraic structs matching spqlios-arithmetic definitions, such as `ScalarZnx`, `VecZnx` or opaque backend prepared struct such as `SvpPPol` and `VmpPMat`.
64
65 ```rust
66 pub struct SvpPPol<D: Data, B: Backend> {
67 data: D,
68 n: usize,
69 cols: usize,
70 _phantom: PhantomData<B>,
71 }
72 ```
73
74 - **`oep`**: open extension points, which can be implemented by the user to provide a custom backend.
75
76 ```rust
77 pub unsafe trait SvpPrepareImpl<B: Backend> {
78 fn svp_prepare_impl<R, A>(module: &Module<B>, res: &mut R, res_col: usize, a: &A, a_col: usize)
79 where
80 R: SvpPPolToMut<B>,
81 A: ScalarZnxToRef;
82 }
83 ```
84
85 - **`tests`**: exported generic tests for the OEP/structs. Their goal is to enable a user to automatically be able to test its backend implementation, without having to re-implement any tests.
86
87- **`backend/implementation`**:
88 - **`cpu_spqlios`**: concrete cpu implementation of the hal through the oep using bindings on spqlios-arithmetic. This implementation currently supports the `FFT64` backend and will be extended to support the `NTT120` backend once it is available in spqlios-arithmetic.
89
90 ```rust
91 unsafe impl SvpPrepareImpl<Self> for FFT64 {
92 fn svp_prepare_impl<R, A>(module: &Module<Self>, res: &mut R, res_col: usize, a: &A, a_col: usize)
93 where
94 R: SvpPPolToMut<Self>,
95 A: ScalarZnxToRef,
96 {
97 unsafe {
98 svp::svp_prepare(
99 module.ptr(),
100 res.to_mut().at_mut_ptr(res_col, 0) as *mut svp::svp_ppol_t,
101 a.to_ref().at_ptr(a_col, 0),
102 )
103 }
104 }
105 }
106 ```
107
108- **`core`**: core of the FHE library, implementing scheme agnostic RLWE arithmetic for LWE, GLWE, GGLWE and GGSW ciphertexts. It notably includes all possible cross-ciphertext operations, for example applying an external product on a GGLWE or an automorphism on a GGSW, as well as blind rotation. This crate is entirely implemented using the hardware abstraction layer API, and is thus solely defined over generic and traits (including tests). As such it will work over any backend, as long as it implements the necessary traits defined in the OEP.
109
110 ```rust
111 pub struct GLWESecret<D: Data> {
112 pub(crate) data: ScalarZnx<D>,
113 pub(crate) dist: Distribution,
114 }
115
116 pub struct GLWESecretExec<D: Data, B: Backend> {
117 pub(crate) data: SvpPPol<D, B>,
118 pub(crate) dist: Distribution,
119 }
120
121 impl<D: DataMut, B: Backend> GLWESecretExec<D, B> {
122 pub fn prepare<O>(&mut self, module: &Module<B>, sk: &GLWESecret<O>)
123 where
124 O: DataRef,
125 Module<B>: SvpPrepare<B>,
126 {
127 (0..self.rank()).for_each(|i| {
128 module.svp_prepare(&mut self.data, i, &sk.data, i);
129 });
130 self.dist = sk.dist
131 }
132 }
133 ```
134
135## Installation
136
137TBD — currently not published on crates.io. Clone the repository and use via path-based dependencies.
138
139## Documentation
140
141* Full `cargo doc` documentation is coming soon.
142* Architecture diagrams and design notes will be added in the [`/doc`](./doc) folder.
143
144## Contributing
145
146We welcome external contributions, please see [CONTRIBUTING](./CONTRIBUTING.md).
147
148## Security
149
150Please see [SECURITY](./SECURITY.md).
151
152## License
153
154Poulpy is licensed under the Apache 2.0 License. See [NOTICE](./NOTICE) & [LICENSE](./LICENSE).
155
156## Acknowledgement
157
158**Poulpy** is inspired by the modular architecture of [Lattigo](https://github.com/tuneinsight/lattigo) and [TFHE-go](https://github.com/sp301415/tfhe-go), and its development is lead by Lattigo’s co-author and main contributor [@Pro7ech](https://github.com/Pro7ech). Poulpy reflects the experience gained from over five years of designing and maintaining Lattigo, and represents the next evolution in architecture, performance, and backend philosophy.
159
160## Citing
161Please use the following BibTex entry for citing Lattigo
162
163 @misc{poulpy,
164 title = {Poulpy v0.1.0},
165 howpublished = {Online: \url{https://github.com/phantomzone-org/poulpy}},
166 month = Aug,
167 year = 2025,
168 note = {Phantom Zone}
169 }