Skip to main content

Contributing

post-quantum-packages provides post-quantum cryptography building blocks used in production blockchain systems. Correctness, consistency, and minimal dependencies are the top priorities.

Prerequisites​

LanguageRuntimeMinimum versionTools
TypeScriptBun1.0+—
Rustrustup1.78+rustfmt, clippy

You only need the toolchain for the language you're contributing to.

Setup​

git clone https://github.com/multivmlabs/post-quantum-packages.git
cd post-quantum-packages

# TypeScript
bun install

# Rust
cargo build

Before you start​

  • Non-trivial changes (new features, API changes, new packages) — open an issue or discussion first to align on the approach before writing code.
  • Bug fixes and small improvements — open a PR directly.

Running tests​

# All TypeScript packages
npm test

# All Rust packages
cargo test

# Single package
cd packages/<package>/ts && bun test
cd packages/<package>/rust && cargo test

Package structure​

Every package follows the same tri-language layout:

packages/<package>/
├── ts/              # TypeScript implementation
│   ├── package.json
│   ├── tsconfig.json
│   ├── src/
│   ├── tests/
│   └── README.md
├── rust/            # Rust implementation
│   ├── Cargo.toml
│   ├── src/
│   └── README.md
└── python/          # Python implementation (planned)
    ├── pyproject.toml
    ├── src/
    └── tests/

All implementations of a package must expose the same public API and produce identical outputs for the same inputs. Current priority is TypeScript and Rust.

Coding standards​

TypeScript​

  • Formatter and linter: Biome (configured in the root biome.json).
  • Target: ES2022, ESNext modules, strict mode.
  • Style: no any, explicit return types preferred, single quotes, semicolons, trailing commas.
cd packages/<package>/ts
bunx biome check --write .
bun run build
bun test

Rust​

  • Edition: 2021.
  • MSRV: 1.78.
  • clippy with warnings treated as errors.
  • rustfmt formatting.
  • no_std capable where applicable.
cd packages/<package>/rust
cargo fmt -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
cargo build --no-default-features

Implementation guidelines​

  • Minimize allocations on hot paths (encoding / decoding).
  • Prefer two-pass encode: compute total size first, then write directly to the output buffer.
  • Use zero-copy (&[u8] borrowing, Uint8Array views) on decode paths where possible.
  • Match raw bytes over string intermediates (e.g., OID lookup by DER bytes, not dotted-decimal strings).
  • Keep packages lean — every dependency is attack surface.

Making changes​

1. Branch​

git checkout -b feat/pq-oid-add-new-algorithm

Naming: feat/<package>-<description>, fix/<package>-<description>, or docs/<description>.

2. Implement​

  • If you change behavior, update both language implementations to keep them in sync.
  • If you add a feature to only one language, note in the PR that the other language needs corresponding changes.
  • Add or update tests for any behavior changes.
  • Update the package README if the public API changes.

3. Verify locally​

Run the checks listed in the Coding standards section above.

4. Commit​

Use Conventional Commits. The scope is the package name:

feat(pq-oid): add SLH-DSA-SHA2-128s algorithm support
fix(pq-key-encoder): correct PKCS#8 version field encoding
docs(pq-jws): update usage examples for v2 API
test(pq-cert-verify): add chain validation edge cases
refactor(pq-spki): reduce allocations in encode path

5. Open a PR​

  • One logical change per PR.
  • Fill out the PR template and link any related issues.
  • CI must pass before review.
  • PRs are squash-merged into main.

Review criteria​

  1. Correctness — does it produce the right output? Are edge cases handled?
  2. Consistency — do both language implementations agree?
  3. Performance — no unnecessary allocations or copies on hot paths?
  4. Standards compliance — does it follow the relevant RFCs and NIST specifications?
  5. Test coverage — are there tests for new behavior and edge cases?
  6. Minimal dependencies — does it introduce new external dependencies? If so, why?

Reporting issues​

  • Bugs: open a GitHub issue with reproduction steps.
  • Security vulnerabilities: see the Security policy — do not open public issues.
  • Feature requests: open a GitHub issue describing the use case.

License​

By contributing, you agree your contributions will be licensed under the MIT License.