inspiring 0.1.0-rc.3

InspiRING.Pack: a single-primitive ring-packing crate (eprint 2025/1352, Algorithm 1) on top of spiral-rs.
Documentation

inspiring — InspiRING.Pack ring-packing crate

A standalone Rust implementation of Algorithm 1 (InspiRING.Pack) from the InsPIRe paper:

R. A. Mahdavi, S. Patel, J. Y. Seo, K. Yeo. InsPIRe: Communication-Efficient PIR with Server-side Preprocessing. ePrint 2025/1352. https://eprint.iacr.org/2025/1352

The crate exposes one primitive:

pub fn pack<'a>(b: &LweBatch, pre: &'a PackPreprocessed<'a>)
    -> Result<RlweCiphertext<'a>, InspiringError>;

which compresses d LWE ciphertexts (each of LWE dim d) into a single RLWE ciphertext of degree d, using exactly two key-switching matrices K_g and K_h. Built on Valar's spiral-rs fork pinned to rev = 6f5b66c6a5a639827c6486c59d31c7ec2d4399a8.

Status

This crate now implements the planned InspiRING.Pack surface. Phase tracking:

Phase Concept Status
1 SPEC.md — paper-to-code contract done
2 Python reference oracle (tools/python-oracle/) done
3 spiral-rs primitive audit (docs/spiral-rs-mapping.md) done
4 Crate skeleton (Cargo.toml, src/, tests/, …) done
5 Stage 1 (intermediate::transform) done
6 Stage 2 (intermediate::aggregate) done
7 Stage 3 (collapse::*, key_switching::*) done
8 pack + offline / online split done
9 Test suite (Lemma 1, oracle match, Theorem 2, …) done
10 Benchmarks (paper Table 5) done
11 Production hardening (rustdoc, fuzz, CI, security) done

See SPEC.md for the mathematical contract and docs/spiral-rs-mapping.md for the spiral-rs primitive audit.

Locked-in scope

  • Algorithm 1 only — full d → 1 packing of d LWE ciphertexts into one RLWE ciphertext, using exactly two key-switching matrices.
  • No PartialPack, no PIR layers (InsPIRe, InsPIRe^(2), InsPIRe_0), no homomorphic polynomial evaluation.
  • Production posture: offline/online split, full unit and integration tests, statistical noise validation against Theorem 2, benchmarks reproducing paper Table 5, CI, rustdoc.

Toolchain & platform requirements

Valar's spiral-rs fork removes the old nightly feature gate and the AVX-512-only correctness requirement:

  • Stable Rust: pinned by the workspace rust-toolchain.toml to 1.89.0. rustup will install the right toolchain when you cd inspiring && cargo build (or build from the repo root with cargo build -p inspiring).
  • CPU target: no crate-level target-cpu override is required. The fork keeps the scalar single-CRT multiply path correct and provides a non-AVX-512 NTT path.

See docs/spiral-rs-mapping.md §1 for the full constraint list.

Layout

ipir-sp/                        # workspace root — open this folder in the IDE for rust-analyzer
|-- Cargo.toml
|-- rust-toolchain.toml
`-- inspiring/
    |-- Cargo.toml
    |-- .cargo/config.toml
    |-- README.md
    |-- SPEC.md                     # Phase 1 (paper-to-code contract)
    |-- docs/
    |   `-- spiral-rs-mapping.md    # Phase 3 (primitive audit)
    |-- src/
    |   |-- lib.rs                  # public API + crate docs
    |   |-- params.rs               # RlweParams, GadgetParams, validators
    |   |-- lwe.rs                  # LweCiphertext, LweBatch, embedding
    |   |-- automorph.rs            # tau_g, tau_h, tau_g^j, trace
    |   |-- intermediate.rs         # IRCtx, transform, aggregate
    |   |-- collapse.rs             # collapse_one, collapse_half, collapse
    |   |-- key_switching.rs        # KS.Setup, KS.Switch, automorphic images
    |   |-- preprocess.rs           # PackPreprocessed (CRS-side cache)
    |   |-- pack.rs                 # top-level Algorithm 1
    |   `-- error.rs                # InspiringError
    |-- tests/                      # Phase 9 lives here
    |-- benches/
    |   `-- pack.rs                 # Phase 10 lives here
    |-- examples/
    |   `-- roundtrip.rs            # Phase 9 worked example
    |-- tools/
    |   `-- python-oracle/          # Phase 2 reference oracle (sympy)
    `-- fixtures/                   # JSON fixtures generated by the oracle

Build

On a supported Rust host:

cd inspiring
cargo build --release           # stable 1.89.0 via workspace rust-toolchain.toml (repo root)
cargo test
cargo clippy --all-targets --all-features -- -D warnings
cargo doc --no-deps --open

Benchmarks

cd inspiring
cargo bench --bench pack

See bench/REPORT.md for the Table 5 parameter sets and reporting format.

Fuzzing

cd inspiring
cargo install cargo-fuzz
cargo fuzz run pack_no_panic

Non-x86 devs

The Valar fork removes the x86_64-only AVX-512 dependency from the NTT path. If a target-specific issue appears, treat it as drift in the fork's portability surface and capture it in docs/spiral-rs-mapping.md.

To run a target-specific smoke check:

cd inspiring
cargo check --target <target-triple>

Python reference oracle

make oracle-test                 # see Makefile

Attribution and License

This crate implements Algorithm 1 from:

R. A. Mahdavi, S. Patel, J. Y. Seo, K. Yeo. InsPIRe: Communication-Efficient PIR with Server-side Preprocessing. ePrint 2025/1352. https://eprint.iacr.org/2025/1352

It is cross-checked against the public Google reference implementation: https://github.com/google/private-membership/tree/main/research/InsPIRe.

MIT OR Apache-2.0, at your option. See SECURITY.md for the parameter-set security checklist, circular-security assumptions, and Theorem 2 noise-budget notes.