Test vectors as a standalone package

[truthixify]

Labels: Stellar Wave, stellar, crypto, test, drips, help-wanted
Tier: M (2–4 days)
Type: test / crypto

Context

Wraith's stealth math is going to be re-implemented in other languages over time (Go indexers, Rust agents outside Spectre, Swift mobile apps). Each reimplementation needs to be verified bit-for-bit identical to the reference TypeScript SDK. Without a shared test-vector corpus, every reimplementer is on their own to figure out edge cases.

We want a published vector package: @wraith-protocol/test-vectors.

Scope

Create a new workspace package packages/test-vectors/ containing JSON files (per chain) with vectors covering:

Per chain (start with Stellar)

1. Key derivation — array of { signature: hex, expected: { spendingKey, viewingKey, spendingPubKey, viewingPubKey } } covering ~100 random inputs + boundary cases (all-zero signature, all-FF signature, near-curve-order, etc.).
2. Stealth address generation — { spendingPubKey, viewingPubKey, ephemeralPrivateKey, expected: { stealthAddress, ephemeralPubKey, viewTag } }.
3. Scan match — { announcement, viewingKey, spendingPubKey, expected: { isMatch, stealthAddress, stealthPrivateKey } } covering match, near-miss (view tag false-positive), full miss.
4. Signing — { scalar, message, expected_signature } for the custom signWithScalar.
5. Encoding — meta-address encode/decode round-trip vectors.

Generation

• A script packages/test-vectors/scripts/generate.ts produces the vectors deterministically from a seed.
• Each vector file is committed in packages/test-vectors/dist/stellar/*.json.
• A checksum.json carries SHA-256 hashes of every vector file so other implementations can verify integrity.

Cross-validation

• The SDK's existing unit tests must be updated to consume these vectors as a sanity check.
• A README explains how to consume the vectors from another language — show snippets in Rust, Go, Python.

Acceptance criteria

• @wraith-protocol/test-vectors published to npm.
• Stellar vectors complete (≥ 100 per category).
• SDK consumes them in tests.
• README with cross-language consumption examples.
• Versioning: vectors are tagged 1.0.0 and bumped only on cryptographic / encoding changes.

Why this matters

Wraith's network effects depend on multiple compatible implementations. The bottleneck for those implementations is certainty that they got the math right. Shared test vectors are the cheapest possible insurance policy against ecosystem fragmentation.

[AlonsoFi]

@AlonsoFi has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

Hey! I'd like to take on this issue. The cross-language compatibility angle is exactly why this matters — my plan:

• Create packages/test-vectors/ workspace package with JSON vector files covering all five Stellar categories: key derivation (100+ inputs including boundary cases: all-zero, all-FF, near-curve-order), stealth address generation, scan match (match, view tag false-positive, full miss), signing, and encoding round-trips
• Write scripts/generate.ts to produce vectors deterministically from a seed and commit them to dist/stellar/*.json
• Add checksum.json with SHA-256 hashes per vector file for cross-implementation integrity verification
• Update existing SDK unit tests to consume the vectors
• Write a README with consumption snippets in Rust, Go, and Python
• Publish as @wraith-protocol/test-vectors at 1.0.0, versioned only on cryptographic/encoding changes

Can I get this assigned?

ℹ️ Repo Maintainers: To accept this application, review their application or assign @AlonsoFi to this issue.

[drips-wave]

Congratulations, @AlonsoFi! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 2, 2026.

🧑‍💻 @AlonsoFi: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊