Skip to content

docs: add stellar cryptography architecture page#62

Merged
truthixify merged 4 commits into
wraith-protocol:developfrom
emarkees:feature/stellar-cryptography
Jun 27, 2026
Merged

docs: add stellar cryptography architecture page#62
truthixify merged 4 commits into
wraith-protocol:developfrom
emarkees:feature/stellar-cryptography

Conversation

@emarkees

@emarkees emarkees commented Jun 26, 2026

Copy link
Copy Markdown
Contributor

Closes #22


Description

This PR introduces the Stellar Cryptography Architecture documentation page (docs/architecture/stellar-cryptography.mdx). It serves to bridge the gap between the @wraith-protocol/sdk code and the cryptographic rationale behind it, allowing auditors and contributors to fully understand the protocol's stealth payment mechanisms on Stellar without having to reverse-engineer the source.

Changes Included

  • New Architecture Page: Created stellar-cryptography.mdx which maps high-level cryptographic concepts directly to their specific sdk/chains/stellar/* implementations.
  • Navigation Update: Registered the new page in docs.json under the Architecture navigation group.

Cryptographic Concepts Covered

  • Curve Selection: Explains the reliance on ed25519 over secp256k1 for Stellar network compatibility.
  • ECDH & Coordinate Conversions: Details the necessity of Edwards-to-Montgomery coordinate conversions for computing X25519 shared secrets, referencing RFC 7748.
  • Domain Separation: Catalogs all wraith: prefixes (spending:, viewing:, scalar:, tag:) and their exact collision-prevention boundaries.
  • View Tag Optimization: Documents the 1-byte view tag derivation logic and its 99.6% false-positive filtering performance value.
  • Custom Signing API: Clarifies the signWithScalar implementation for deriving signatures from a raw stealth scalar instead of a standard 32-byte seed while upholding RFC 8032.
  • Meta-address Structure: Explains the st:xlm: encoding prefix, payload concatenation, and Stellar's StrKey encoding.

Visual Documentation

Includes two Mermaid SVG diagrams for at-a-glance comprehension:

  1. View Tag Scanning: A sequence diagram mapping the announcement scan flow and cheap prefilter logic.
  2. Key Derivation Flow: A flowchart tracing ephemeral keys, ECDH operations, and point additions to form a final Stellar address.

emarkees added 3 commits June 26, 2026 16:09
s
Added a new architecture page (`stellar-cryptography.mdx`) detailing the design
decisions and cryptographic primitives powering Wraith Protocols Stellar stealth
@drips-wave

drips-wave Bot commented Jun 26, 2026

Copy link
Copy Markdown

@emarkees Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

@emarkees

Copy link
Copy Markdown
Contributor Author

@truthixify Kindly review branch

@truthixify

Copy link
Copy Markdown
Contributor

Architecture page content + docs.json + federation cross-link look good. The 2170-line package-lock.json shouldn't be in the PR (this repo is pnpm).

rm package-lock.json
git add package-lock.json
git commit --amend --no-edit
git push --force-with-lease

@emarkees emarkees force-pushed the feature/stellar-cryptography branch 2 times, most recently from 7222565 to 305fe9e Compare June 27, 2026 08:53
@emarkees

Copy link
Copy Markdown
Contributor Author

@truthixify Issue ahs been fixed but there is a compiled error

@emarkees emarkees force-pushed the feature/stellar-cryptography branch from 305fe9e to a83b59b Compare June 27, 2026 09:14
@truthixify

Copy link
Copy Markdown
Contributor

Lockfile gone, rebased cleanly. 98-line Stellar cryptography architecture page + federation cross-link + snippet-check script tweak. Thanks @emarkees.

@truthixify truthixify merged commit 877737c into wraith-protocol:develop Jun 27, 2026
0 of 2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Stellar stealth cryptography deep-dive page

2 participants