NiobiumInc/niobium-client
GitHub: NiobiumInc/niobium-client
Niobium Client 是一个开源的全同态加密客户端工具链，通过提供统一的中间表示追踪和多前端接入方式，帮助开发者构建并部署 FHE 应用至专用硬件加速器。
Stars: 20 | Forks: 0
# Niobium Client
**Niobium Mistic** FHE 加速器的开源客户端技术栈。无论你通过哪种前端接入，路径都是一样的：你的全同态计算会被记录为未优化的 **FHETCH Polynomial IR** 追踪记录 (`.fhetch`)，你可以通过内置的本地模拟器进行重放以进行验证，或者提交给 Niobium 编译服务以进行优化并部署到硬件。所有优化逻辑都位于服务器端——这个客户端保持轻量、开源 (Apache 2.0) 且独立运行。
## 支持矩阵
构建 (`make release`) 和运行客户端所需的外部依赖项：
| 依赖项 | 最低版本 |
|--------------------------|-----------------|
| CMake | 3.16.3 |
| GCC | 9.0 |
| Clang (GCC 的替代方案) | 10.0 |
| GNU make | 3.82 |
| bash | 3.0 |
| Git | 任意 |
| pthreads | 任意 |
| yaml-cpp | 0.8.0 |
| OpenSSL | 3.0.0 |
| BoringSSL / LibreSSL (OpenSSL 的替代方案) | 1.1.1 |
| python3 | 3.7 |
| certifi (Python 包) | 任意 |
python3 和 certifi 是 `fog` CLI 的运行时依赖（而 python3 是 `nbc` DSL 编译器的依赖）——在默认配置下，C++ 构建本身完全不涉及 Python。只有在操作系统/Python 安装未提供可用 CA 存储的情况下（例如 python.org 的 macOS 版本），才严格需要 certifi；在其他情况下，`fog` 会回退到使用系统信任存储。
## 选择你的入口点
按受众划分，共有四种接入方式：
| 你是… | 入口点 | 从这里开始 |
|---|---|---|
| **AI 编程助手**（或与 AI 结对编程） | **nb DSL + design skill** —— 一套分阶段的 FHE 设计方法论，可为 Claude Code、OpenAI Codex 及其他兼容 agentskills.io 的智能体自动加载，并配有一个紧凑的 DSL，其编译器会生成所有基础架构代码 | [`dsl_fhe/`](dsl_fhe/README.md), [`.claude/skills/`](.claude/skills/fhe-application-design) & [`.agents/skills/`](.agents/skills/fhe-application-design) |
| **应用开发者**（使用 OpenFHE C++） | **Instrumented OpenFHE** —— 编写标准的 `EvalMult`/`EvalAdd`/… 代码，用 `niobium::compiler()` 调用将其括起；探针会记录一切 | [Instrumenting an OpenFHE application](#entry-point-2--openfhe-for-application-developers), [`examples/`](examples/) |
| **编译器 / 代码生成器作者** | **FHETCH Polynomial IR** —— 通过记录 API（或文本追踪格式）直接发出 IR，并使用会话、重放和传输机制作为你的后端 | [`niobium-fhetch`](https://github.com/NiobiumInc/niobium-fhetch), [`src/fhetch_transport/`](src/fhetch_transport/) |
| **FHE 库集成商**（GPU/加速器后端） | **HAZE** —— 一个 CUDA 风格的 C API (`hazeMalloc`/`hazeMemcpy`/`hazeNTT`/…)：每次调用都会记录一个多项式级别的 IR 操作，因此针对 CUDA 的 FHE 库只需极少的精力即可完成移植 | [`vendor/niobium-haze`](https://github.com/NiobiumInc/niobium-haze) |
以上四种方式最终都会汇聚到同一个记录器和同一份追踪记录：
```
AI agents End users FHE compilers FHE libraries
(Claude Code + (OpenFHE C++ (emit Polynomial (CUDA-shaped code,
design skill) applications) IR directly) e.g. FIDESlib)
| | | |
v | | v
+---------------+ | | +---------------+
| nb DSL | | | | HAZE |
| dsl_fhe/ |--generates--->| | | libhaze |
| (nbc) | OpenFHE C++ | | | hazeAdd, |
+---------------+ v | | hazeNTT, ... |
+---------------------+ | +---------------+
| Niobium- | | |
| instrumented | | |
| OpenFHE (probes.h) | | |
+---------------------+ | |
| openfhe_cprobe_* | fhetch_api.h | one IR op
| fires on every | (sr_addp, | per haze
| NTT, ADD, MUL, ... | sr_ntt, ...) | call
v v v
+----------------------------------------------------------------+
| libnbfhetch — FHETCH Polynomial IR recorder |
| niobium::compiler() session API: init / start / probe / stop |
| cooperative auto-tagging · cache · replay · result |
+----------------------------------------------------------------+
|
| unoptimized .fhetch trace
| + fhetch_replay.json manifest
v
+---------------+--------------------+
| |
v v
+-----------------------+ +--------------------------+
| fhetch_sim (local) | | Niobium compilation |
| replays the trace, | | service (proprietary) |
| reconstructs result | | optimizes and deploys |
| ciphertexts — for | | to Mistic hardware |
| validation | | |
+-----------------------+ +--------------------------+
```
有关 FHETCH 指令集、会话 API、追踪格式和模拟器内部原理，请参阅伴随仓库：
[`niobium-fhetch`](https://github.com/NiobiumInc/niobium-fhetch)。
## 入口点 1 —— 适用于 AI 智能体的 DSL + design skill
这种组合的设计使得 AI 编程助手能够在一个会话中完成从*隐私模型*到*经验证的加密流水线*的应用开发：
- **design skill**（通过 `make sync-skill` 从
[`niobium-skills`](https://github.com/NiobiumInc/niobium-skills)
目录安装到 [`.claude/skills/fhe-application-design`](.claude/skills/fhe-application-design)
和 [`.agents/skills/fhe-application-design`](.agents/skills/fhe-application-design)
中）可在此仓库中为 Claude Code（从 `.claude/skills/` 加载）、OpenAI Codex 和其他兼容 agentskills.io 的智能体（从 `.agents/skills/` 加载）自动加载。它引导你走过分阶段的方法论——隐私模型、可行性、明文基准、方案选择、电路设计、参数选择、实现、协议规范——其第 7 阶段的“Track A”即针对下方的 DSL。
- **nb DSL** ([`dsl_fhe/`](dsl_fhe/README.md)) 将 `.niob` 源代码编译为链接此客户端的 OpenFHE C++ 代码。信任边界 (`@client`/`@server`，`@encryptors(independent)`) 由编译器强制执行；序列化、密钥生成以及记录/重放插桩均会自动生成；加密属性在类型流中完全是结构化的；每个阶段都会生成一个**明文参考孪生体**（基准）；编译时的建议涵盖了切比雪夫多项式次数选择 (`max_error:`)、深度预算以及安全/参数边界（logQ 与环维度，以及固定 N 的裕量）。
```
cd dsl_fhe
make test-compiler # compiler unit tests
make examples # build + run all self-contained examples
```
七个实践示例（`simple`、`fetch-by-similarity`、`password-retrieval`、`set-membership`、`fraud-flag`、`ml-inference-fhe`、`fhe-NetworkMonitor`）与该 skill 的设计参考相配合——其中三个是该 skill 自身设计方案的落地实现。
| 文件 | 用途 |
|---|---|
| [`dsl_fhe/README.md`](dsl_fhe/README.md) | 概述、构建说明、示例演练 |
| [`dsl_fhe/CLAUDE.md`](dsl_fhe/CLAUDE.md) | 设计原理、代码生成内部机制 |
| [`dsl_fhe/NB_LANGUAGE.md`](dsl_fhe/NB_LANGUAGE.md) | 语言参考 |
| [`dsl_fhe/GRAMMAR.md`](dsl_fhe/GRAMMAR.md) | 形式化 EBNF 语法 |
| [`dsl_fhe/HOWTO.md`](dsl_fhe/HOWTO.md) | 逐步演示如何添加新示例 |
## 入口点 2 —— 适用于应用开发者的 OpenFHE
你只需编写标准的 OpenFHE 代码，并添加 `niobium::compiler()` 调用来包裹计算过程。带有插桩的 OpenFHE 分支会在探针级别拦截每一个多项式操作——你**永远**不需要直接调用 FHETCH API。
### 步骤说明
1. **编译与链接** —— 针对 `libnbfhetch` 和 Niobium 插桩的 OpenFHE 分支构建你的 OpenFHE 应用程序。在计算过程前后添加 `niobium::compiler().init()`，`start()`，`stop()`。无需更改 FHE 算法代码。
2. **执行** —— 每一个 OpenFHE 多项式操作（`NTT`、`INTT`、`ADD`、`SUB`、`MUL`、`MULI`、`ADDI`、`MORPH`、…）都会触发一个 C 探针（`openfhe_cprobe_add`、`openfhe_cprobe_ntt`、…），该探针会在追踪记录中记录一条或多条 FHETCH 指令。
3. **捕获** —— 在调用 `compiler().stop()` 时，追踪记录会被最终确定为 `.fhetch` 文本文件以及 `fhetch_replay.json` 清单（加密上下文、模数链、密钥 ID 范围、输入/输出布局）。
4. **重放（本地）** —— `compiler().replay()` 通过内置的 FHETCH 模拟器执行记录的追踪记录；`compiler().result(cc, name, ct)` 从探针重新还原出 `Ciphertext`，以便应用程序的其余部分（解密、验证）能够继续正常执行。在缓存有效运行的情况下，主机执行的 FHE 操作数量为**零**——并且记录的追踪记录可以使用**重新生成的密钥/输入**进行重放（更改的输入文件会自动刷新）。
5. **提交** —— 将追踪记录（连同序列化的输入和元数据）发送给 Niobium 编译服务，该服务会对其进行降级和优化，以适应 Mistic 加速器。
### 最小示例
```
#include "openfhe.h"
#include "niobium/compiler.h"
using namespace lbcrypto;
int main(int argc, char* argv[]) {
niobium::compiler().init(argc, argv);
niobium::compiler().set_program_info("my_app", "1.0", "CKKS multiply example");
niobium::compiler().set_build_info(__FILE__, __LINE__, __TIMESTAMP__);
niobium::Compiler::CacheParameters params;
params.push_back({"workload", "ckks_mul"});
niobium::compiler().cache_parameters(params);
// Load previously-generated crypto context, keys, and ciphertexts.
CryptoContext cc;
Serial::DeserializeFromFile("keys/cc.bin", cc, SerType::BINARY);
Ciphertext ct_a, ct_b;
Serial::DeserializeFromFile("keys/ct_a.bin", ct_a, SerType::BINARY);
Serial::DeserializeFromFile("keys/ct_b.bin", ct_b, SerType::BINARY);
// ... load mk.bin, rk.bin ...
niobium::compiler().capture_crypto_context(cc);
niobium::compiler().tag_input("ct_a", ct_a);
niobium::compiler().tag_input("ct_b", ct_b);
niobium::compiler().tag_keys(cc);
if (!niobium::compiler().is_cache_valid()) {
// ---- RECORDING ----
// Probes fire automatically during this OpenFHE call.
niobium::compiler().start();
auto result = cc->EvalMult(ct_a, ct_b);
niobium::compiler().probe("result", result);
niobium::compiler().stop();
// .fhetch + fhetch_replay.json are now written to disk.
} else {
// ---- REPLAY (cache hit: zero FHE ops on the host) ----
niobium::compiler().replay();
}
Ciphertext ct_result;
niobium::compiler().result(cc, "result", ct_result);
Serial::SerializeToFile("keys/ct_result.bin", ct_result, SerType::BINARY);
return 0;
}
```
不想手动添加标签？`niobium::compiler().enable_auto_tagging()` 可切换至**协作式自动标记**：插桩的反序列化钩子会捕获加密上下文，对求值密钥进行标记，并在你的代码加载每个输入密文时对其进行标记（这正是 DSL 生成的逻辑）。详见
[`docs/AUTO_FACADE.md`](docs/AUTO_FACADE.md)。
### 标记输入、密钥和输出（手动模式）
- `capture_crypto_context(cc)` —— 使用环维度、模数链和逆链在清单中盖上时间戳；注册 bootstrap 预计算钩子。
- `tag_input(name, ct)` —— 将密文的多项式锚定为具有稳定 FHETCH 地址范围的命名输入，并序列化以供重放。
- `tag_keys(cc)` —— 标记所有求值密钥（eval-mult + eval-automorphism）。
- `probe(name, ct)` —— 标记一个可观察的输出；重放后，`result(cc, name, ct)` 会将其重构出来。
地址布局：输入占据较低的 FHETCH 地址范围（从 1 开始；地址 0 是复制哨兵），接下来是求值密钥，随后是 bootstrap 预计算明文。
### 手写示例
| 示例 | 功能说明 |
|---|---|
| `examples/bootstrap/` | 空心记录下的 CKKS bootstrap（大型追踪，完全重放） |
| `examples/mult/` | CKKS `EvalMult` —— 客户端/服务端/解密切分，包含重放与重构 |
| `examples/simple_ops/` | 由一个测试驱动程序驱动的 13 个操作（ADD、SUB、MUL、NEG、ADDI/SUBI/MULI、复合链、MORPH） |
```
make test-simple-ops-release
make test-mult-release
make test-bootstrap-release
make test-op-release OP=MORPH A=5 B=6 # one specific op
```
## 入口点 3 —— 适用于编译器编写者的 FHETCH
如果你正在构建 FHE 编译器、转译器或代码生成器，请直接针对 **FHETCH Polynomial IR**，并让这套技术栈作为你的后端：
- **记录 API** —— 位于
[`niobium-fhetch`](https://github.com/NiobiumInc/niobium-fhetch) 中的 `fhetch_api.h`：每个 IR 操作对应一次调用（`sr_addp`、`sr_mulp`、`sr_ntt`、`mr_mulp`、…），由 `niobium::compiler()` 会话（init / start / probe / stop / replay / result / cache）封装。
- **追踪格式** —— `.fhetch` 是一种文本格式；你也可以直接输出它。`fhetch_replay.json` 清单包含加密上下文、模数链和 I/O 布局。
- **验证** —— 内置的 `fhetch_sim` 使用确定性的 OpenFHE 原生数学运算重放任何追踪记录；`fhetch_driver` 通过 API 重新驱动追踪记录，作为往返检查。
- **传输** —— [`src/fhetch_transport/`](src/fhetch_transport/) 提供了一个客户端/服务端对及归档格式，用于将追踪记录（连同输入和元数据）交付至编译目标。传入 `--target FOG` 即可在 Niobium 稳定的 FPGA 设备上运行：服务器会将该别名解析为当前绑定的硬件 ID，因此客户端永远不会依赖于内部设备名称。任何其他目标 ID 都将原样转发。
追踪记录的是 FHETCH 操作名称，而不是硬件指令——服务器端编译器会执行底层转换（NTT 拆分、加载/存储插入、寄存器分配）。
## 入口点 4 —— 适用于 FHE 库集成商的 HAZE
[`niobium-haze`](https://github.com/NiobiumInc/niobium-haze)（位于 `vendor/niobium-haze` 目录下）在比 OpenFHE 更低的层级提供了一个 **CUDA 风格的 C API**：`hazeMalloc` / `hazeMemcpy` / `hazeAdd` / `hazeNTT` / … —— 每个公共入口点都是一个单一的多项式级 IR 操作，通过相同的 `libnbfhetch` 核心进行记录。其风格刻意设计为 CUDA 风格，这样一来，基于 CUDA 编写的 GPU FHE 库——例如 [FIDESlib](https://github.com/CKKS-Community/FIDESlib)——只需极少的移植工作即可重新定向到 Niobium 硬件：将 `cuda*` 调用替换为 `haze*` 调用，然后 `hazeFlush()` 会完成追踪记录并调度重放（本地或远程），`azeMemcpy` D2H 会读回重构的结果。
## 构建
### 全新构建
```
make sync # git submodule update --init --recursive
make release # configure + build everything (Release)
make config && make build # same, Debug (config once, then build)
```
### 增量构建
```
make sync
make build-release # build OpenFHE + libnbfhetch + examples (Release)
make build # same, Debug
```
### 构建流水线
顶层 `Makefile` 会构建 OpenFHE（位于 `vendor/niobium-fhetch/vendor/openfhe` 下），将其安装在 `vendor/lib/openfhe` 下，然后在同一个目录树中构建 `libnbfhetch` 和示例二进制文件。
### 前置条件
- C++17 编译器
- CMake 3.16+
- OpenFHE（Niobium 插桩分支，通过 `vendor/niobium-fhetch/vendor/openfhe` 间接获取）
- Python 3（DSL 编译器 + 示例测试驱动程序）
### 安装 design skill
FHE design skill 是**按需安装**的，并未提交到仓库中。它位于上游目录的 `skills//` 子目录中（子模块无法挂载该目录），因此 `make sync-skill` 会将其复制到 `.claude/skills/fhe-application-design/` 和 `.agents/skills/fhe-application-design/` 中（两者均在 gitignore 忽略列表内）。每个副本都会在一个 `.vendored-from` 文件中记录其来源的上游提交。
随时运行此命令以进行安装或更新——它会重新拉取目录并原地覆盖已安装的副本：
```
make sync-skill # install or update from the default branch
scripts/update-fhe-skill.sh # install or update from a specific commit, tag, or branch
```
目录的最终用户也可以选择使用 skills.sh CLI 进行安装：
```
npx skills add NiobiumInc/niobium-skills --skill fhe-application-design
```
## Fog 快速入门
**Niobium Fog** 是托管的*任务即服务*重放路径：你无需在本地 `fhetch_sim` 上重放追踪记录，而是通过 TLS 将其提交给 Fog worker（一个 Mistic FPGA，或托管的函数模拟器）。**`fog`** CLI (`scripts/fog`) 会准备任务，等待分配 worker，将 worker 的端点配置到环境中，并针对该端点运行你的 OpenFHE 应用——该应用的 `replay()` 会透明地分发到远程 worker，而不是本地模拟器。
### 1. 申请账户
Fog 的访问受到限制。请在 **** 申请账户。你将收到一封包含账户邮箱和密码的邮件——`fog login` 会使用它们生成一个长期有效的 API 密钥，并存储在本地 (`~/.fog/credentials`，权限模式 `0600`)。
### 2. 安装构建先决条件
构建过程需要 C++17 工具链、CMake ≥ 3.16、OpenSSL 头文件（Fog 传输层通过 HTTPS 与 worker 通信）以及 Python 3（`fog` CLI 和示例测试驱动程序）。需要 `git` 来获取子模块。
**macOS** —— 安装 Apple 的命令行工具，接着安装 [Homebrew](https://brew.sh)，然后安装 CMake 和 OpenSSL：
```
xcode-select --install # clang, make, git
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install cmake openssl@3 python3
# 在此 shell 中将 CMake 指向 Homebrew 的 OpenSSL（Apple 仅附带 LibreSSL）：
export OPENSSL_ROOT_DIR="$(brew --prefix openssl@3)"
```
**Ubuntu / Debian**:
```
sudo apt update
sudo apt install -y build-essential cmake libssl-dev python3 git
```
### 3. 构建并安装 CLI
```
make sync # fetch submodules: niobium-fhetch + nested OpenFHE + json + niobium-haze
make release # build OpenFHE + libnbfhetch + transport client + examples (Release)
make install-cli # install fog + nbcc_fhetch_replay to ~/.local/bin
make sync-skill # install the FHE design skill into .claude + .agents
```
使用 `make sync-fhetch` 替代 `make sync` 可以仅拉取 niobium-fhetch 及其内嵌的 OpenFHE，跳过面向 GPU 的 `niobium-haze` 子模块（默认构建中的任何内容都不需要它）。`make sync-haze` 则单独为面向 GPU 的应用程序拉取 haze。
`make install-cli` 会复制独立的 `fog` 脚本，以及 `fog` 在提交任务时交接给的 `nbcc_fhetch_replay` 传输客户端（由 `make release` 构建）。可以通过 `make install-cli CLI_PREFIX=/usr/local` 安装到其他位置（安装至 `$CLI_PREFIX/bin`）。
确保安装目录在你的 `PATH` 中：
```
# zsh（macOS 默认）：~/.zshrc · bash：~/.bashrc（Linux） / ~/.bash_profile（macOS）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && exec $SHELL
fog --help
```
### 4. 登录并提交示例任务
```
fog init # optional: write ~/.fog/config with defaults
fog login -u you@example.com # prompts for password; mints + stores an API key
cd build/examples
./mult_client mult_keys 7 13 65536 # will create the mult_keys directory, generate keys, and encrypt(ring dimension of 2^16)
fog submit ./mult_server mult_keys --target=FOG
fog list # watch your jobs
./mult_decrypt mult_keys #decrypt the results
```
`fog submit ./app --target=FOG …` 会准备一个 Fog 任务，阻塞等待直到分配了 worker，然后 `exec` 执行 `./app`，同时设置好 `NBCC_FHETCH_SERVER`/`NBCC_FHETCH_TOKEN`，以便其 `replay()` 在该 worker 上运行。程序名之后的所有内容都会直接传递给你的应用。
`mult_*` 示例是一个分为三步的 客户端 → 服务端 → 解密 的切分过程。客户端生成密钥并加密两个整数，服务端在 Fog worker 上将它们相乘，解密后会显示乘积。`mult_client` 的最后一个参数是环维度（`65536` = 2^16）；在它之前的两个整数是操作数。`fog submit` 封装了 `mult_server`，使其 `replay()` 分发到分配的 worker，而不是本地模拟器。
### `fog` 命令参考
运行 `fog`（或 `fog --help`）查看摘要。所有命令都会读取下文描述的配置和凭证。
| 命令 | 功能说明 |
|---|---|
| `fog init [-f\|--force]` | 写入带有默认值的 `~/.fog/config`（可根据需要编辑）。`--force` 会覆盖现有文件。 |
| `fog login [-u\|--username EMAIL] [-n\|--name NAME]` | 进行身份验证（OAuth2 密码模式）并准备一个**命名的** API 密钥，保存至 `~/.fog/credentials` (`0600`)。如果未提供，则会提示输入邮箱/密码；`-n` 用于为密钥添加标签（默认为 `fog@`）。该操作会添加一个密钥——现有密钥依然有效。它还会将原始令牌打印到标准输出，因此可以使用 `export FOG_API_TOKEN=$(fog login)`。 |
| `fog submit ./app --target=T [args…]` | **包装模式** —— 为目标 `T` 准备任务，等待 worker，然后针对它运行你的 OpenFHE 应用 `./app`（额外的参数会传递给应用）。 |
| `fog list` | 以表格形式列出你的所有任务（ID、状态、模式、目标、worker、入队时间）以及处理中的数量。 |
| `fog get ID [ID…]` | 获取一个或多个任务 ID 的完整 JSON 详细信息。 |
| `fog cancel ID [ID…]` | 取消/释放特定任务。 |
| `fog cancel --pending` | 取消所有处理中的任务（`queued`/`assigned`/`running`/`reserved`）——释放 worker。 |
**`--target` 值** —— `FOG` 在 Niobium 稳定的 FPGA 别名上运行（服务器会将其解析为当前绑定的硬件 ID） `--target` 对于 `submit` 是必需的。
### 配置
`fog` 会读取两个可选的 INI 文件（使用 `$FOG_HOME` 覆盖该目录，默认为 `~/.fog`）。每个设置的优先级依次为 **环境变量 → 配置文件 → 内置默认值**。
| 文件 | 节 / 键 | 写入者 |
|---|---|---|
| `~/.fog/config` | `[fog]` `api_url`, `mode`, `wait`, `maxwait` | `fog init`（之后可手动编辑） |
| `~/.fog/credentials` | `[fog]` `api_token` | `fog login` (权限模式 `0600`) |
**环境变量**（每一个都会覆盖配置文件中的设置）：
| 变量 | 含义 | 默认值 |
|---|---|---|
| `FOG_API_URL` | fog-api 的基础 URL | `https://api.niobium.co` |
| `FOG_API_TOKEN` | API 令牌（作为 `X-Api-Token` 发送） | 从 `credentials` 读取 |
| `FOG_JOB_MODE` | `batch` 或 `persistent` | `batch` |
| `FOG_JOB_WAIT` | 每个请求的长轮询秒数 | `20` |
| `FOG_JOB_MAXWAIT` | 保持轮询队列的总秒数 | `600` |
| `FOG_HOME` | 配置/凭证目录 | `~/.fog` |
| `NBCC_FHETCH_REPLAY_BIN` | `fog` 移交给的 `nbcc_fhetch_replay` 客户端的路径 | 查找 `PATH`，然后是 `build/` |
| `NBCC_FHETCH_REPLAY` | 设置为 `fog` 以启用驱动程序模式（见上文） | 未设置 |
**TLS 说明** —— `fog` 仅使用 Python 标准库。在没有内置 CA 存储的构建版本上（例如某些 python.org 的 macOS 版本），可以通过 `pip install certifi` 为其提供一个用于校验的证书包；否则，它将使用操作系统信任存储，并遵循 `$SSL_CERT_FILE` 的设置。
## 项目结构
```
niobium-client/
.claude/skills/ # installed by `make sync-skill` (gitignored)
fhe-application-design/ # the FHE design skill (AI agents)
.agents/skills/ # same skill, .agents/ convention (Codex / agentskills.io)
fhe-application-design/
dsl_fhe/ # nb DSL + cross-compiler (nbc) — entry point 1
xcomp/ # the compiler: lexer, parser, semantic, codegen
tools/ # replay-integrity verifier, ...
examples/ # simple, fetch-by-similarity, password-retrieval,
# set-membership, fraud-flag, ml-inference-fhe,
# fhe-NetworkMonitor
examples/ # hand-written OpenFHE examples — entry point 2
bootstrap/ # CKKS bootstrap (hollow recording)
mult/ # CKKS EvalMult (client / server / decrypt)
simple_ops/ # 13 elementary ops, one harness
include/niobium/ # public client headers (Utils/ScopedPause.h, ...)
src/
auto_facade/ # cooperative auto-tagging (deserialize hooks)
fhetch_transport/ # trace transport client/server + archive — entry point 3
docs/
AUTO_FACADE.md # transparent/cooperative record-replay design
vendor/
niobium-fhetch/ # submodule: libnbfhetch + fhetch_sim + API headers
vendor/openfhe/ # nested submodule: Niobium-instrumented OpenFHE
niobium-haze/ # submodule: CUDA-shaped C API — entry point 4
lib/openfhe/ # installed OpenFHE (built by the Makefile)
CMakeLists.txt Makefile README.md CLAUDE.md LICENSE (Apache 2.0)
```
## 架构决策
- **多前端，单一 IR** —— DSL、带插桩的 OpenFHE、直接 FHETCH 输出以及 HAZE 最终都会汇聚到同一个 FHETCH Polynomial IR 和相同的 `niobium::compiler()` 会话机制上。任何记录了有效追踪记录的程序，都可以免费获得模拟器、缓存、使用新输入重放以及编译服务。
- **设计上的瘦客户端** —— 所有优化逻辑都位于服务器端的专有编译器中。客户端只负责记录和传输未优化的指令追踪，从而将开源层面的代码保持在最小限度。
- **基于探针的记录** —— 应用程序代码保持为标准的 OpenFHE；插桩分支中的 C 探针 (`probes.h`) 会在每次多项式操作时触发，FHETCH 库会将它们转换为追踪指令。
- **FHETCH 级别的追踪格式** —— 追踪使用多项式 IR 操作名称（`sr_addp`、`sr_ntt`、`mr_mulp`、…），而不是硬件指令；服务器端编译器会对其进行降级处理（NTT 拆分、加载/存储插入、寄存器分配）。
- **缓存 + 使用新数据重放** —— 追踪记录由 `CacheParameters` 进行缓存。缓存有效运行时，主机上执行的 FHE 操作数量为零：追踪记录会使用当前的输入文件进行重放（更改的输入和密钥会自动刷新），并且记录的追踪记录本身永远不会重新生成（受测试限制，包括时间戳）。
- **用于验证的本地模拟器** —— `fhetch_sim` 使用确定性的 OpenFHE 原生数学运算重放 `.fhetch` 文件，为硬件的计算结果提供参考基准，可通过 `replay()` + `result()` 从用户代码中访问，而无需脱离 OpenFHE 对象模型。
## 许可证
Apache 2.0 —— 详见 [LICENSE](LICENSE)。
## 贡献
我们正在积极制定贡献政策和贡献者许可协议（CLA）。在此流程落实之前，我们还无法接受外部贡献。如果你有错误报告、功能请求或问题，请直接[联系我们](https://niobium.co/contact)。
关注此仓库，以便在贡献政策发布时获取通知。
标签：Bash脚本, C++, Python, SOC Prime, 全同态加密, 安全测试工具, 密码学, 开发工具, 手动系统调用, 数据擦除, 无后门, 硬件加速器, 编译器, 逆向工具