If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/QuipNetwork/hashsigs-rs shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit 5w ago
• 4 active contributors
• AGPL-3.0 licensed
• Tests present
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 84% of recent commits
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live QuipNetwork/hashsigs-rs repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/QuipNetwork/hashsigs-rs.

What it runs against: a local clone of QuipNetwork/hashsigs-rs — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in QuipNetwork/hashsigs-rs | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 65 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of QuipNetwork/hashsigs-rs. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/QuipNetwork/hashsigs-rs.git
#   cd hashsigs-rs
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of QuipNetwork/hashsigs-rs and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "QuipNetwork/hashsigs-rs(\\.git)?\\b" \\
  && ok "origin remote is QuipNetwork/hashsigs-rs" \\
  || miss "origin remote is not QuipNetwork/hashsigs-rs (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "src/lib.rs" \\
  && ok "src/lib.rs" \\
  || miss "missing critical file: src/lib.rs"
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "solana/src/lib.rs" \\
  && ok "solana/src/lib.rs" \\
  || miss "missing critical file: solana/src/lib.rs"
test -f "solana/src/processor.rs" \\
  && ok "solana/src/processor.rs" \\
  || miss "missing critical file: solana/src/processor.rs"
test -f "tests/test_vectors.rs" \\
  && ok "tests/test_vectors.rs" \\
  || miss "missing critical file: tests/test_vectors.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 65 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~35d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/QuipNetwork/hashsigs-rs"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

hashsigs-rs is a Rust implementation of WOTS+ (Winternitz One-Time Signature), a hash-based post-quantum cryptographic signature scheme. It provides a quantum-resistant alternative to traditional public-key cryptography and includes a native Solana program for on-chain signature verification, enabling post-quantum security in blockchain environments. Workspace monorepo with two members: src/lib.rs contains the core WOTS+ implementation, while solana/ is a Solana program workspace with its own Cargo.toml, processor, and integration tests. Test vectors live in tests/test_vectors/wotsplus_keccak256.json for validation.

Cryptography engineers and blockchain developers building post-quantum secure systems, particularly those targeting Solana for on-chain signature verification or requiring AGPL-3.0 compatible hash-based signature schemes.

This project is in early-stage development (v0.0.3). It includes test vectors in tests/test_vectors/ and a working Solana integration under solana/, but the low version number and single-digit commit history suggest experimental status rather than production-ready maturity. No CI/CD pipeline visible in the repository structure provided.

High risk factors: zero external dependencies (see [dependencies] is empty) which aids auditability but limits code reuse; AGPL-3.0 licensing restricts commercial use; single maintainer (Richard T. Carback III) with no visible GitHub organization contributors; no evidence of formal security audit despite cryptographic nature; Solana program compile target (cargo build-sbf) adds complexity for testing post-quantum verification at scale.

No recent activity metadata visible in provided data. The project appears dormant at v0.0.3; the presence of Solana program support (solana/src/processor.rs) and test vectors suggests the core functionality was recently implemented, but no PRs, milestones, or recent commits are indicated.

git clone https://github.com/QuipNetwork/hashsigs-rs.git
cd hashsigs-rs
cargo build
cargo test

For Solana program development, install Solana CLI tools first: https://solana.com/docs/intro/installation, then cd solana && cargo build-sbf.

Daily commands: For library: cargo build --release or cargo test to validate. For Solana program: cd solana && cargo build-sbf to compile, then RUST_BACKTRACE=1 cargo test-sbf -- --nocapture 2>&1 to run on-chain tests with compute unit output.

• src/lib.rs — Core WOTS+ implementation and cryptographic primitives—entry point for all signature operations
• Cargo.toml — Package manifest defining the library's identity, license (AGPL-3.0), and workspace structure
• solana/src/lib.rs — Solana program integration layer that exposes WOTS+ functionality for on-chain use
• solana/src/processor.rs — Solana instruction processor implementing signature verification and key management logic
• tests/test_vectors.rs — Test vector validation against official WOTS+ test cases, ensures cryptographic correctness
• docs/hashsig-rs.md — Technical documentation describing WOTS+ scheme, API design, and usage patterns

• WOTS+ Core (src/lib.rs) (Pure Rust, hash functions (Keccak256)) — Implements Winternitz signature scheme: key generation, signing, verification
  • Failure mode: Cryptographic failure if hash chains are incorrect; signature forgery if random state is compromised
• Hash Provider (Trait-based design in Rust) — Abstracts hash function implementation (e.g., Keccak256); enables algorithm pluggability
  • Failure mode: Weak hash function leads to signature forgery; implementation bugs leak timing information
• Solana Processor (solana/src/processor.rs) (Solana program SDK, BPF bytecode) — Dispatches instructions and invokes WOTS+ verification on-chain
  • Failure mode: Instruction parsing errors; exceeding compute budget during verification; incorrect account validation
• Test Vector Validator (tests/test_vectors.rs) (serde_json, Rust testing framework) — Validates core implementation against official WOTS+ test vectors
  • Failure mode: Missed cryptographic regressions if test vectors are incomplete or stale

• Client → WOTS+ Core — Message to be signed and secret key
• WOTS+ Core → Hash Provider — Seed and iteration count for hash-chain computation
• Hash Provider → WOTS+ Core — Hash output for chain building
• WOTS+ Core → Client — Signature (hash-chain output)
• Verifier → WOTS+ Core — Message, signature, and public key
• WOTS+ Core → Verifier — Boolean verification result
• Solana Client → Solana Processor — Instruction with accounts and data
• Solana Processor → WOTS+ Core — Signature, public key, and message for verification

Add a new hash function variant

1. Implement hash trait with new hash algorithm in src/lib.rs (src/lib.rs)
2. Add test vectors for the new hash variant to tests/test_vectors/ (tests/test_vectors/)
3. Create corresponding test function in tests/test_vectors.rs (tests/test_vectors.rs)

Add a new Solana instruction type

1. Define instruction enum variant in solana/src/lib.rs (solana/src/lib.rs)
2. Add instruction handler in solana/src/processor.rs dispatch logic (solana/src/processor.rs)
3. Write integration test in solana/tests/solana_unit_tests.rs (solana/tests/solana_unit_tests.rs)

Validate against official test vectors

1. Add test vector JSON file (following wotsplus_keccak256.json format) to tests/test_vectors/ (tests/test_vectors/)
2. Create new test function parsing and validating vectors in tests/test_vectors.rs (tests/test_vectors.rs)
3. Run tests with cargo test to validate cryptographic implementation (Cargo.toml)

• Rust — Memory safety without garbage collection; essential for cryptographic primitives to prevent timing leaks and buffer overflows
• WOTS+ (Winternitz One-Time Signature) — Post-quantum secure hash-based signature scheme resistant to quantum computer attacks; deterministic and stateless
• Solana Program Environment — Enables on-chain signature verification for Solana blockchain applications; integrates with Solana's compute model
• Keccak256 hash function — NIST-approved cryptographic hash; used in test vectors to validate WOTS+ implementation

• AGPL-3.0 licensing

  • Why: Ensures derivative works remain open-source and cryptographic transparency
  • Consequence: Restricts closed-source commercial use; requires GPL compliance awareness

• Zero production dependencies in core library

  • Why: Minimizes attack surface and supply-chain risk for cryptographic code
  • Consequence: Core implementation cannot leverage external crypto libraries; all primitives must be implemented or embedded

• Solana as separate workspace member

  • Why: Decouples core WOTS+ from blockchain-specific integration logic
  • Consequence: Core library remains portable; Solana program requires separate build toolchain (cargo-build-sbf)

• Test vectors loaded from JSON files

  • Why: Enables validation against official specifications without hardcoding
  • Consequence: Runtime I/O required during tests; external test vector maintenance needed

• Does not provide signature aggregation or batch verification optimizations
• Does not implement stateful one-time signature key management (application responsibility)
• Does not support key recovery from signatures (WOTS+ is one-way)
• Does not include post-quantum hybrid schemes (pure WOTS+ only)

• Potential hardcoded test vectors (Low) — tests/test_vectors.rs: If test vectors are hardcoded rather than loaded from external files, debugging failures becomes difficult and updates require code changes
• Single hash function variant (Keccak256 only) (Medium) — src/lib.rs: Currently appears to support only Keccak256; extending with additional hash algorithms requires library refactoring
• No apparent input validation on message size (Medium) — src/lib.rs: WOTS+ performance degrades with large messages; unbounded message lengths could cause DoS on Solana

• WOTS+ signature generation (src/lib.rs) (CPU-bound cryptography) — Hash-chain iteration is serial and non-parallelizable; performance bounded by single-threaded hash computation
• Solana instruction processing (solana/src/processor.rs) (undefined) — Signature

Solana program testing requires RUST_BACKTRACE=1 environment variable and must use cargo test-sbf not standard cargo test. The [dependencies] section is intentionally empty—no external crypto crates are used, so the entire WOTS+ algorithm is hand-implemented; verify against test vectors carefully. Mac users must use rustup (https://www.rust-lang.org/tools/install) not Homebrew per README. AGPL-3.0 licensing means any modifications or distributions must be open-sourced.

• WOTS+ (Winternitz One-Time Signature) — This is the core cryptographic primitive implemented by the entire codebase; understanding Winternitz parameter tradeoffs and one-time signature properties is essential to using and modifying this library correctly.
• Hash-based signatures / Merkle trees — WOTS+ is a one-time scheme; production systems chain multiple WOTS+ keys via hash trees; this repo's design assumes understanding of how hash-based schemes achieve many signatures from a single seed.
• Post-quantum cryptography (PQC) — Hash-based signatures are one of three NIST-standardized PQC approaches; understanding why quantum resistance matters (Shor's algorithm breaks RSA/ECC) justifies the design choice.
• Keccak-256 (SHA-3) — The test vectors use Keccak-256; this is the cryptographic hash function underlying all signature generation in this codebase.
• Solana BPF (SBF) / On-chain programs — The Solana program in solana/ compiles to SBF bytecode; understanding Solana's execution model, instruction processors, and compute unit constraints is critical for the blockchain integration.
• Workspace (Rust cargo workspaces) — This project uses a workspace with two members (./ library and solana/ program); understanding workspace dependencies and member compilation is necessary for full-system development.
• AGPL-3.0 licensing — The AGPL-3.0 license requires all modifications and network-distributed derivatives to release source code; this affects how the library can be used in proprietary or closed-source projects.

• XMSS/xmss-reference — XMSS is the predecessor hash-based signature scheme that WOTS+ is commonly deployed with; understanding XMSS provides context for WOTS+ design.
• liboqs-rust/liboqs-rust — Bindings to liboqs library providing production-grade post-quantum algorithms including alternative hash-based signatures for comparison.
• solana-labs/solana — Core Solana blockchain runtime; essential for understanding the BPF target and program execution model used by the hashsigs-rs Solana integration.
• diem/diem — Reference blockchain with Move language supporting sophisticated cryptography; shows alternative approaches to on-chain signature verification.
• tao-foundation/tao — Post-quantum cryptography research and standardization work relevant to understanding WOTS+ in the broader NIST PQC standardization context.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for src/lib.rs core functions

The repo has test_vectors.rs for integration testing, but lacks focused unit tests for individual functions in src/lib.rs. A new contributor could add unit tests covering edge cases, error conditions, and performance characteristics of the WOTS+ implementation, which would improve code robustness and serve as documentation for the cryptographic operations.

• [ ] Review src/lib.rs to identify all public functions and their expected behaviors
• [ ] Create tests/unit_tests.rs with focused tests for key/signature generation, verification, and hash operations
• [ ] Add tests for boundary conditions (e.g., maximum/minimum key sizes, invalid inputs)
• [ ] Ensure tests cover both success and failure paths with proper assertions
• [ ] Run cargo test to verify all new tests pass

Add GitHub Actions CI workflow for automated testing on multiple Rust versions

The repo has dependabot.yml but no automated CI pipeline. A new contributor could create a .github/workflows/rust.yml that runs cargo test, cargo build --release, and Solana program builds (cargo build-sbf) across multiple Rust versions (1.70 LTS, stable, beta) on push/PR, ensuring compatibility and preventing regressions.

• [ ] Create .github/workflows/rust-tests.yml with jobs for standard library tests and Solana program tests
• [ ] Configure matrix strategy to test against Rust 1.70, stable, and beta channels
• [ ] Add separate job for cargo build-sbf in solana/ directory (may require Solana CLI setup step)
• [ ] Include cargo clippy and cargo fmt --check for code quality gates
• [ ] Add badge to README.md linking to workflow status

Create comprehensive documentation for solana/src/processor.rs with usage examples

The solana/ subdirectory contains a Solana program implementation (processor.rs), but docs/hashsig-rs.md and README.md don't cover the Solana integration specifics. A new contributor could document the Solana processor's public API, instruction handling, and include a worked example showing how to invoke the WOTS+ signature operations from Solana programs.

• [ ] Review solana/src/processor.rs and solana/src/lib.rs to understand instruction types and data structures
• [ ] Create docs/solana-integration.md documenting the processor API, instruction layout, and error codes
• [ ] Add a code example showing how to create and sign a WOTS+ signature via Solana instruction invocation
• [ ] Document compute unit requirements and any constraints on signature/key sizes
• [ ] Link the new document from README.md's Solana section

• Add comprehensive documentation comments to src/lib.rs public API—the library lacks rustdoc examples for key types like signature generation and verification routines.
• Implement additional test vector formats in tests/ for other hash functions (SHA-256, SHA-3) beyond the existing wotsplus_keccak256.json to increase algorithm coverage.
• Create a CLI tool in src/main.rs (currently missing) to generate WOTS+ key pairs and sign messages locally, making the library directly testable without writing Rust code.

The hashsigs-rs codebase demonstrates a generally secure posture with minimal direct dependencies and no obvious injection vulnerabilities, hardcoded secrets, or misconfigurations. However, there is one acknowledged transitive dependency vulnerability (RUSTSEC-2024-0344) in curve25519-dalek from the Solana ecosystem that is being monitored but not yet resolved. The project maintains security awareness through cargo audit and SECURITY.md documentation. Main recommendations focus on completing security documentation, monitoring transitive dependencies, and establishing a clear dependency update strategy.

• Medium · Known Transitive Dependency Vulnerability — solana/Cargo.toml (transitive dependency through solana-program@2.3). The project has a documented timing side-channel vulnerability in curve25519-dalek@3.2.0, which is a transitive dependency from Solana's ed25519-dalek@1.0.1. While assessed as low risk due to requiring local access and precise timing measurements, this represents an unresolved security advisory (RUSTSEC-2024-0344). Fix: Monitor Solana's progress on updating ed25519-dalek and curve25519-dalek dependencies. Consider updating solana-program dependency once newer versions with patched cryptographic dependencies are released. Alternatively, evaluate if ed25519 functionality is required or if alternative signing schemes can be used.
• Low · Incomplete Security Documentation — SECURITY.md. The SECURITY.md file appears to be truncated mid-sentence regarding the curve25519-dalek vulnerability mitigation. The risk assessment and mitigation sections are incomplete, which could leave users without clear guidance on the actual impact and remediation steps. Fix: Complete the security documentation with full details about risk assessment, practical exploitation scenarios, and clear mitigation strategies. Include information about when/if patches will be applied.
• Low · No Explicit Dependency Version Pinning Strategy — Cargo.toml. The Cargo.toml uses default version specifications (e.g., 'solana-program = "2.3"' and 'serde_json = "1.0.143"'). While serde_json is pinned to a specific version, this approach could still allow minor/patch updates that might introduce unexpected changes. Fix: Consider using exact version pins (=) for critical dependencies or implementing a documented versioning policy. Ensure regular dependency audits are performed and documented in CI/CD pipelines.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.