soAPI.hpp
Initialization, encryption, arithmetic, comparison, bitwise operations, serialization, packing, compression, and CT metadata helpers.
FHE16Ver6 API surface
One FHE16 method contract across C, Web Browser, Rust, and Python.
This page starts from the current FHE16Ver6 C ABI and turns it into the public SDK map. The raw source of truth is include/soAPI/soAPI.hpp; wrappers should keep one-to-one semantics while owning memory safely.
Docs structure
/docs/ is the overview route. API details live on this separate page so the overview stays short and each binding can have its own examples.Current Source Baseline
The current implementation exposes FHE16 through C symbols with int32_t* ciphertext handles. The browser demo calls the same runtime through Emscripten exports.
fhe16_wrapper.ts
TypeScript wrapper around WASM exports with Ciphertext.free() and worker-oriented usage.
Lifecycle
Public SDKs should hide the global runtime state behind a context object, but the raw ABI currently owns that lifecycle.
| Step | Raw symbols | Wrapper behavior |
|---|---|---|
| Thread setup | FHE16_SetThreadCount, FHE16_GetThreadCount | Set before key generation or memory allocation. |
| Initialize | FHE16_GenEval, FHE16_LoadEval, FHE16_MemoryAlloc | Create context and evaluation material. |
| Keys | FHE16_GetLWESK, FHE16_GetDecSK | Expose only in local/debug flows unless a product explicitly needs key export. |
| Release | FHE16_Free, FHE16_DeleteEval | Free returned ciphertexts and close the runtime context. |
Data Model
Ciphertexts are currently raw int32_t* buffers with metadata at the front. Wrappers should treat them as opaque handles.
| Header word | Meaning |
|---|---|
CT[0] | Encrypted bit width. Boolean ciphertexts use 1. |
CT[1] | Per-bit ciphertext length. |
CT[2] | Log-style bit-width metadata used by arithmetic routines. |
Ownership ruleReturned ciphertext pointers from encryption, compute, deserialize, or load functions are caller-owned and must be released with
FHE16_Free. Secret-key pointers returned by generation/accessor functions are runtime-owned.Operations
Each operation now has its own page. Use the Operations dropdown in the sidebar or open the Operations index.
| Family | Raw symbols | Public wrapper names |
|---|---|---|
| Encrypt/decrypt | FHE16_ENCInt, FHE16_ENCInt32, FHE16_ENCInt_Arr, FHE16_DECInt, FHE16_DECIntVec | encrypt_int, encrypt_bits, decrypt_int, decrypt_bits |
| Arithmetic | FHE16_ADD, FHE16_ADD3, FHE16_SUB, FHE16_SMULL, FHE16_FMULL, FHE16_NEG, FHE16_ABS | add, add3, sub, mul, full_mul, neg, abs |
| Comparison | FHE16_LT, FHE16_LE, FHE16_GT, FHE16_GE, FHE16_EQ, FHE16_NEQ | lt, le, gt, ge, eq, neq |
| Selection | FHE16_MAX, FHE16_MIN, FHE16_SELECT, FHE16_RELU | max, min, select, relu |
| Bitwise | FHE16_AND, FHE16_OR, FHE16_XOR, FHE16_ANDVEC, FHE16_ORVEC, FHE16_XORVEC | and_bool, or_bool, xor_bool, and_bits, or_bits, xor_bits |
| Constants | FHE16_ADD_CONSTANT_*, FHE16_SUB_CONSTANT_*, FHE16_SMULL_CONSTANT_*, FHE16_FMULL_CONSTANT_*, compare constant families | add_const, sub_const, mul_const, full_mul_const, lt_const |
Caller and Circuit Map
Each API method needs a caller definition and a circuit definition. The caller tells which SDK or product layer should invoke it; the circuit path tells what homomorphic structure actually runs.
| Methods | Primary caller | Circuit path |
|---|---|---|
FHE16_GenEval, LoadEval, DeleteEval | SDK context setup, browser worker init, benchmark harness. | No homomorphic circuit; runtime allocation, key generation, and key loading. |
FHE16_ENCInt, ENCInt32, ENCInt_Arr | Key-owning client, worker, native wrapper. | Integer-to-bit encryption path; not an evaluation circuit. |
FHE16_ADD, FHE16_SUB | Arithmetic API and product compute flows. | Parallel prefix adder via FHE16_PREFIX_Templete and PrefixAdder_V2. |
FHE16_LT, GT, LE, GE, EQ | Ranking, auction, threshold, and guard logic. | Prefix compare or equality reduction; LE/GE/NEQ compose compare or EQ with encrypted NOT. |
FHE16_SMULL, FMULL | Signed arithmetic and scoring logic. | DADDA partial-product reduction; FMULL returns full 2n-bit product. |
FHE16_AND/OR/XOR, *VEC | Boolean gates and integer bitwise SDK calls. | Single-bit gate path for boolean methods; GATE_VEC across bits for vector methods. |
FHE16_SELECT, MAX, MIN, RELU | Conditional product logic and private selection. | Selector, compare-select, or sign-gated selection circuits. |
*_CONSTANT_* | Browser constants, thresholds, fixed coefficients. | Plaintext bit-array path plus prefix add, compare, or DADDA constant multiply. |
DIV_*, MOD_*, shifts | Advanced arithmetic. | Shift-only fast paths, signed bias correction, magic-multiplier constant division, or non-restoring division. |
Web Browser
The browser wrapper should use the existing WASM exports and keep compute-heavy calls in a worker.
// Current wrapper direction
await FHE16.init("./test_wasm.js");
const sk = FHE16.genEval();
const a = FHE16.encrypt(42, 8);
const b = FHE16.encrypt(100, 8);
const less = FHE16.lt(a, b);
const opened = FHE16.decrypt(less);
less.free();
a.free();
b.free();
FHE16.cleanup();C ABI
#include <stdint.h>
#include "soAPI/soAPI.hpp"
int32_t* sk = FHE16_GenEval();
int32_t* a = FHE16_ENCInt(42, 8);
int32_t* b = FHE16_ENCInt(100, 8);
int32_t* out = FHE16_LT(a, b);
int64_t opened = FHE16_DECInt(out, sk);
FHE16_Free(out);
FHE16_Free(a);
FHE16_Free(b);
FHE16_DeleteEval();Binding Direction
Owned ciphertexts
Ciphertext should be move-only and call FHE16_Free from Drop. Low-level raw calls stay inside an unsafe module.
Context-managed runtime
with fhe16.Context() should release runtime state and all ciphertext objects should support explicit close().
Serialization
Use serialization for local files, browser transfers, and service boundaries. Keep secret-key serialization clearly marked as local debug or owner-only.
| Area | Raw symbols |
|---|---|
| Ciphertext | FHE16_LweToBytes, FHE16_LweFromBytes, FHE16_CTSave, FHE16_CTLoad |
| Params | FHE16_ParamsSave, FHE16_ParamsLoad, FHE16_GetParamHash, FHE16_VerifyCTParam |
| Keys | FHE16_EvalKeySave/Load, FHE16_PKSave/Load, FHE16_SKSave/Load, FHE16_ChainKSKSave/Load |