sealed-lattice

This project is under active implementation. It has not been audited or externally reviewed.

sealed-lattice is a browser-first, mobile-first, post-quantum threshold homomorphic voting library workspace. Every roster participant is intended to act as both voter and trustee. Untrusted services may store and distribute transcript objects, but the verification path is participant mobile browsers, not servers or dedicated heavy verifier machines.

The published npm package is intentionally narrow while the protocol implementation is still being built and checked. Use it for development verification, package integration, transcript helpers, and foundation checks. It is not a complete voting library and must not be used for real ballots or ballot secrecy. The canonical public security posture lives in SECURITY.md.

Selected direction

The selected construction is:

active-static secure-with-abort collective BGV setup
-> direct BGV-encrypted ballots
-> ballot validity proofs for the fixed encrypted-ballot relation
-> public ciphertext aggregation
-> bounded-domain encrypted evaluator replay on mobile
-> unanimous target finality for the first profile
-> one-shot target-bound threshold decryption of C_target only

The first target profile is planned around n = 10, m = 20, every 1 <= K_top <= 20, q_setup_complete = 10, q_ballot_release = 10, q_final = 10, and q_dec = 4. Current security limitations, profile caveats, HE evidence, and target-decryption boundaries are not repeated here; see SECURITY.md.

Current package boundary

The public package currently exposes development verification helpers while the full voting API is being built and checked. These cover poll validation, threshold derivation, lifecycle and capability checks, foundation transcript checks, and narrow setup-development verification helpers. Reserved complete-protocol entry points fail closed until the matching implementation and verification work is complete.

Current package tests are development evidence only. They do not replace supported mobile runtime evidence, production hardening, or the complete protocol security boundary in SECURITY.md.

Installation

npm install sealed-lattice

pnpm add sealed-lattice

Basic usage

import { deriveThresholdProfile, validatePollSpec } from "sealed-lattice";

const pollValidation = validatePollSpec({
    pollId: "board-election-2026",
    question: "Which proposal should be adopted?",
    options: ["Proposal A", "Proposal B"],
    topOptionCount: 1,
});

if (!pollValidation.ok) {
    throw new Error(
        pollValidation.errors[0]?.message ?? "Invalid poll specification.",
    );
}

const thresholdProfile = deriveThresholdProfile({
    rosterSize: 10,
});

pollValidation.normalized contains the validated poll with defaults applied. thresholdProfile contains the derived threshold, quorum, corruption-bound, and warning fields for the frozen roster size.

What you can use today

• poll specification validation and canonical hash derivation;
• threshold and frozen roster profile derivation;
• lifecycle transition and action capability checks;
• board consistency, cast receipt, close record, target finality, roster manifest, recovery epoch, first-valid ordering, and foundation transcript checks;
• setup-development verification helpers for local share checks, setup package verification input construction, setup package verification, and accepted setup handoff handling;
• foundation transcript verification through the packaged kernel;
• package-boundary and public API smoke coverage for development integration.

What is not available yet

• a complete threshold voting workflow;
• production-ready setup ceremony, ballot generation, or casting APIs;
• public encrypted ballot package creation, verification, or accepted proof transport APIs;
• public encrypted ballot aggregation APIs;
• public bounded-domain mobile evaluator replay APIs;
• production target-bound decryption, target recombination, or result release APIs;
• production security claims; see SECURITY.md.

The public package must not expose raw BGV decryption, arbitrary threshold decryption, individual ballot decryption, aggregate score decryption, rank or comparison opening, evaluator intermediate opening, raw VSS share export, secret-share export, ballot proof witness export, encryption randomness export, or test-only plaintext oracle access.

Security

Read SECURITY.md before treating any verification result as security evidence. That file owns the public threat model, retry policy, audit status, and cryptographic caveats.

Repository layout

sealed-lattice/
  crates/
    sealed-lattice-kernel/      Rust transcript-core and proof-verifier kernel
  docs/                         Public documentation site and API documentation tools
  packages/
    crypto/                     Internal canonical JSON, hashes, signatures
    protocol/                   Internal protocol logic and reference paths
    sdk/                        Published sealed-lattice package
    types/                      Shared TypeScript type declarations
    wasm/                       Internal WASM loader package
  test-vectors/                 Canonical public regression vectors
  tools/                        CI, vector, packaging, and documentation tools

Documentation

• Documentation site
• Guides
• Protocol spec
• API reference

Development

Install dependencies:

pnpm install

Run the main local validation gate:

pnpm run check

pnpm run check builds the workspace once, runs the type-check, then runs lint, docs verification, package smoke verification, public package policy verification, package-boundary verification, test vector verification, dead-code scan, Rust formatting, Rust clippy, fast Rust kernel tests, fast Node tests, and the non-heavy kernel Node tests through the repository check runner.

For public SDK API changes, run pnpm run api-surface:generate and review the compact summary diff manually in the PR. API surface review is not part of pnpm run check.

Run focused verification:

pnpm run vectors
pnpm run test:rust:kernel:heavy
pnpm run test:node:fast
pnpm run test:node:protocol
pnpm run test:node:kernel
pnpm run test:node:kernel:heavy
pnpm run test:node
pnpm run test:browser
pnpm run test:lattigo-oracle
pnpm run verify:docs
pnpm run smoke:pack:npm

The native Rust heavy lane now has constrained free-runner-knob evidence. On June 21, 2026, pnpm run test:rust:kernel:heavy -- --no-run-log completed with 57 passed; 0 failed under CARGO_INCREMENTAL=0, RAYON_NUM_THREADS=4, SEALED_LATTICE_HEAVY_TEST_THREAD_COUNT=1, SEALED_LATTICE_TRUSTEE_PROOF_BATCH_SIZE=1, SEALED_LATTICE_TRUSTEE_PROOF_LIMB_BATCH_SIZE=2, and no checkpoint resume. The run finished in 17978.14s and the measured process-tree peak RSS was 9.97 GiB. This is native CI-runner setup/proof/key-transport evidence only; it is not browser, WASM, or supported-phone mobile runtime evidence.

Keep default and release gates focused on the selected direct path and shared substrate. Heavy proof, browser, and mobile evidence lanes should be added only when they measure accepted direct-path evidence.

Build and package-smoke the published SDK:

pnpm run build
pnpm run smoke:pack:npm

Install browser engines before the first local browser test run:

pnpm exec playwright install chromium firefox webkit

License

This project is licensed under MPL-2.0. See LICENSE.