Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
100 lines (77 loc) · 4.51 KB

CONTRIBUTING.md

File metadata and controls

100 lines (77 loc) · 4.51 KB
Raw

Contributing to specter-sdk

Thanks for your interest. This SDK is the browser-facing face of the SPECTER post-quantum stealth address protocol, so the bar for changes is high. Read this whole file before opening a PR.

Layout

specter-sdk/
  rust/specter-wasm/    # wasm-bindgen bridge crate
  vendor/               # synced from pranshurastogi/SPECTER (pinned SHA)
    specter-core/
    specter-crypto/
    VENDORED_AT.json
  packages/sdk/         # @specterpq/sdk TypeScript package
  scripts/              # sync + verify + pre-publish helpers
  .github/workflows/    # CI, release, sync

The crates under vendor/ are read-only mirrors of the SPECTER backend. Do not edit them by hand. Open a PR against pranshurastogi/SPECTER, then bump the pin here via scripts/sync-backend.sh.

Prerequisites

  • Node.js 20 or 22 (LTS). See package.json engines.
  • pnpm 10. Install via corepack enable or npm i -g pnpm.
  • Rust pinned by rust-toolchain.toml (currently 1.82.0). rustup will install it automatically on first build.
  • wasm-pack for WASM builds: cargo install wasm-pack or brew install wasm-pack.
  • For browser tests: a recent Chrome and Firefox installation. wasm-pack test --headless drives them via WebDriver.

First-time setup

pnpm install
pnpm vendor:verify   # confirm vendor/ matches the pinned upstream SHA
pnpm build:wasm      # builds rust/specter-wasm and emits to packages/sdk/src/wasm/{web,node}
pnpm build           # tsup-builds the TypeScript package
pnpm test            # vitest

Day-to-day commands

Command What it does
pnpm build:wasm Compile the WASM bridge (web + nodejs targets).
pnpm build Build everything (wasm + ts).
pnpm test Run vitest in packages/sdk.
pnpm test:browser Run wasm-bindgen-test in headless Chrome + Firefox.
pnpm lint ESLint + cargo fmt --check.
pnpm clippy cargo clippy -- -D warnings.
pnpm rust:test cargo test on the bridge crate.
pnpm vendor:verify Fail if vendor/ drifts from the pinned upstream SHA.
pnpm vendor:sync [SHA] Re-sync vendor/ from upstream at the given SHA (or update to latest main if omitted).
pnpm ci:full Run the full local matrix (vendor verify + clippy + rust tests + build + ts tests + lint).

Branch and commit policy

  • main is always releasable.
  • Use Conventional Commits: feat:, fix:, chore:, docs:, refactor:, test:, ci:, build:, perf:, revert:.
  • Each user-facing change requires a Changeset: pnpm changeset and commit the generated note.
  • Squash-merge PRs into main. The merge commit message becomes the changelog source for that change.

PR checklist (paste into the PR description)

- [ ] CI is green (rust fmt/clippy/test, wasm build, browser tests, ts build/test/lint, vendor-verify)
- [ ] Test evidence attached (screenshots or terminal logs for new behavior)
- [ ] No new secret-leaking surface (no logging of secret_key, eth_private_key, shared_secret)
- [ ] Compatibility impact assessed (any signature change of an exported function = changeset MINOR or MAJOR)
- [ ] Security impact assessed (any change to crypto bridge requires a SECURITY.md review)
- [ ] Changeset added (pnpm changeset)

Bumping the backend pin

# From repo root
pnpm vendor:sync <commit-sha-from-pranshurastogi-SPECTER>
pnpm ci:full
git checkout -b chore/vendor-sync-<short-sha>
git add vendor/
git commit -m "chore(vendor): sync backend to <sha>"
gh pr create --fill

The nightly sync-backend.yml workflow does this automatically against the latest main of the backend.

Release flow

  1. Land changes on main with changesets.
  2. The release.yml workflow opens a "Version Packages" PR or directly publishes.
  3. Merging the Version Packages PR triggers pnpm changeset publish --provenance on a GitHub-hosted runner using OIDC. The published artifact carries an attestation linking it back to this repo and commit.

Code style

  • TypeScript: strict + strictTypeChecked ESLint config. Branded Hex<T> types are not optional for cryptographic byte strings.
  • Rust: cargo fmt. Clippy clean. forbid(unsafe_code) is non-negotiable for the bridge crate.
  • No emojis in code. No marketing copy in comments. Comments explain non-obvious intent only.

Reporting security issues

Security issues do not go in GitHub issues or PRs. Email hello@specterpq.com. See SECURITY.md.