mirror of
https://github.com/luxfi/pulsar.git
synced 2026-07-27 06:55:04 +00:00
Hanzo AI
ac293cbe49
Single repo, one canonical impl + spec + proofs + KAT + cut tool.
Per "ONE and ONLY ONE way to do things" the prior dual-repo split
(luxfi/pulsar = production library, luxfi/pulsar-mptc = NIST MPTC
submission framework) is collapsed into a single canonical home at
github.com/luxfi/pulsar. SINGLE-IMPL-PLAN.md (now marked COMPLETED)
describes the steps; this commit lands the final step.
Files moved (89 new):
16 submission docs (SUBMISSION, NIST-SUBMISSION, SPEC, SUITE,
PATENTS, AXIOM-INVENTORY, PROOF-CLAIMS, FIPS-TRACEABILITY,
TRUSTED-COMPUTING-BASE, HANZO-CRYPTO-SUITE, INFORMATION-
ARCHITECTURE, ROADMAP, CHANGELOG, SYNC-STATUS, STATUS-
SUBMISSION-READINESS, SINGLE-IMPL-PLAN)
10 docs/ supplements (ietf-draft-skeleton, magnetar, evaluation,
patent-claims, x-wing-sig, design-decisions, family-architecture,
threat-model, nist-mptc-category, patent-notes-draft)
19 proofs/ (13 EC theories + 2 EC lemmas + 4 metadata/READMEs +
lean-easycrypt-bridge.md)
14 jasmin/ (lib/* + ml-dsa-65 fetch + threshold/{combine,round1,
round2}.jazz + READMEs)
10 ct/dudect/ (Makefile, combine_ct.go, dudect_combine.c,
dudect_compat.h, dudect_verify.c, fetch.sh, README, run-
submission.sh, verify_ct.go) + ct/jasmin-ct-libjade.md
1 .github/workflows/ci.yml
1 test/interoperability/n1_class_test.go (19/19 N1 subtests)
1 bench/results/REPORT.md
11 scripts/ (cut-submission, check-high-assurance, check-lean-
bridge, nightly, extract-jasmin-ec, checks/{ec-admits, ec-
compile, ec-refinement-scaffold, ec-regressions, extraction,
jasmin}, checks/test/{go-unit, interop, kat, no-secret-logs})
Files merged (16 overlapping, mptc-canonical chosen because newer +
post-rewire-correct; pulsar versions still bore stale "Pulsar-M" /
"pulsarm" branding):
README.md, BLOCKERS.md, CONTRIBUTING.md, LICENSE, LICENSING.md,
SECURITY.md, .gitignore, bench/run_all.sh, vectors/dkg.json (v1.0.7
regen), scripts/{bench,build,gen_vectors,sbom,test}.sh,
spec/{pulsar,parameters,system-model}.tex,
CRYPTOGRAPHER-SIGN-OFF.md (path refs).
Pulsar-only spec supplements preserved:
spec/{blockers,design-decisions,family-architecture,nist-mptc-
category,patent-notes,threat-model}.tex.
Path rewrites applied: 158 occurrences across 26 files
github.com/luxfi/pulsar-mptc -> github.com/luxfi/pulsar
~/work/lux/pulsar-mptc/ -> ~/work/lux/pulsar/
luxfi/pulsar-mptc -> luxfi/pulsar
pulsar-mptc/ -> ./
Narrative collapses (no more two-repo framing):
SUBMISSION.md "At a glance" — single Repository row
SYNC-STATUS.md — rewritten to single-repo state
SINGLE-IMPL-PLAN.md — marked COMPLETED 2026-05-18
HANZO-CRYPTO-SUITE.md — tier 1 row = single canonical home
scripts/cut-submission.sh — replace/vendor dance removed; cuts
directly from in-tree canonical sources
go.mod: dropped mptc's replace directive (no longer needed since this
IS the canonical pulsar repo). Module path is github.com/luxfi/pulsar.
Deps: cloudflare/circl v1.6.3, golang.org/x/crypto v0.32.0.
Verification:
GOWORK=off go build ./... PASS
GOWORK=off go test -count=1 ./... PASS (1.4s)
GOWORK=off go test -race ./ref/... PASS (14.7s)
go test ./test/interoperability/ PASS (19/19 N1 subtests)
scripts/check-high-assurance.sh PASS
scripts/check-lean-bridge.sh PASS (5/5 bridges)
scripts/gen_vectors.sh byte-identical replay
scripts/cut-submission.sh --help PASS
74 lines
2.5 KiB
Markdown
74 lines
2.5 KiB
Markdown
# Contributing to Pulsar
|
|
|
|
## What we accept
|
|
|
|
This is a NIST-MPTC-track repository. Until the 2026-Nov-16 package
|
|
submission, contributions that align with the MPTC submission are highest
|
|
priority:
|
|
|
|
1. **Specification clarity** — text edits that disambiguate `spec/*.tex`.
|
|
2. **Reference implementation** — `ref/go/`. Boring, clear, no assembly,
|
|
no clever abstractions. Match the spec section-by-section.
|
|
3. **Test vectors** — `vectors/*.json`. Cross-validate against the FIPS 204
|
|
reference (output interchangeability is the headline claim).
|
|
4. **Constant-time analysis** — `ct/dudect/`. Show, don't claim.
|
|
5. **Lattice-estimator runs** — `estimator/`. Concrete classical + quantum
|
|
security-strength tables.
|
|
6. **Cryptanalysis** — open an issue. We track external review explicitly.
|
|
|
|
## What we don't accept
|
|
|
|
Until after the MPTC submission lands:
|
|
|
|
- New protocol features. Spec freeze is hard.
|
|
- Optimized implementations (AVX2, SIMD, hand-rolled assembly).
|
|
- HSM integration patches.
|
|
- Production-deployment patches.
|
|
- BLAKE3 hash-suite changes — the NIST profile uses SHAKE/cSHAKE/KMAC
|
|
exclusively. BLAKE3 deltas land in upstream `luxfi/pulsar`, not here.
|
|
|
|
These reopen post-submission.
|
|
|
|
## Process
|
|
|
|
1. **Open an issue first.** Discuss the change before implementing.
|
|
2. **One concern per PR.** Don't bundle spec edits with implementation
|
|
changes. The MPTC review process treats them as separate artifacts.
|
|
3. **CI must pass.** Build, test, KAT regeneration, dudect, lattice-estimator
|
|
all green before merge.
|
|
4. **Sign your commits.** GPG-signed, real name in `Signed-off-by`.
|
|
Patent-claim disclosures attach to commits.
|
|
|
|
## Development setup
|
|
|
|
```bash
|
|
git clone https://github.com/luxfi/pulsar
|
|
cd pulsar
|
|
./scripts/build.sh
|
|
./scripts/test.sh
|
|
```
|
|
|
|
Spec build requires LaTeX (TeX Live 2024+):
|
|
```bash
|
|
cd spec/
|
|
latexmk -pdf pulsar.tex
|
|
```
|
|
|
|
## Coding standards (Go reference)
|
|
|
|
- Go 1.22+.
|
|
- All logging via `github.com/luxfi/log`. **No `log.Println`, `log.Fatalf`,
|
|
`fmt.Printf`** in code that touches a secret.
|
|
- All secret comparison via `crypto/subtle` or local constant-time helpers.
|
|
- All sampling via the central `pkg/sampling` interface. Direct
|
|
`math/rand` is forbidden.
|
|
- Errors carry context via `fmt.Errorf("%w", err)` not bare panics.
|
|
|
|
## License
|
|
|
|
By contributing, you agree your contribution is licensed under Apache-2.0
|
|
and grant the patent license described in the Apache 2.0 §3.
|
|
|
|
For NIST MPTC submission: contributions are subject to the patent-claim
|
|
disclosures collected in `docs/patent-notes-draft.md`.
|