Skip to content

docs: add view-tag scanner architecture page - #118

Merged
truthixify merged 1 commit into
wraith-protocol:developfrom
brooksdevon001-star:docs/view-tag-scanner-architecture
Jul 29, 2026
Merged

docs: add view-tag scanner architecture page#118
truthixify merged 1 commit into
wraith-protocol:developfrom
brooksdevon001-star:docs/view-tag-scanner-architecture

Conversation

@brooksdevon001-star

Copy link
Copy Markdown
Contributor

View-tag scanner architecture documentation

Adds architecture/view-tag-scanner.mdx — a dedicated architecture page explaining how the
1-byte view tag optimization works, written in response to repeated researcher questions about
scan performance.

What's in the page:

  • Problem statement: naive scanning costs O(N) X25519 ECDH operations as the announcement log
    grows
  • Derivation spec for both Stellar v2 (SHA-256("wraith:stellar:view-tag:v2:" || R || V)[0]) and
    EVM (keccak256(sharedSecret)[0])
  • False-positive analysis: 1/256 rate, zero false-negatives, meaning no payments are ever
    missed
  • Before/after cost structure diagram (view-tag-comparison.svg)
  • Mermaid sequence diagram of the full scan loop with the tag-check branch
  • Announcement batching: single-pass scanAnnouncements + batch_send sender-side grouping
  • Benchmark methodology: full TypeScript harness using node:perf_hooks to reproduce the speedup
    measurement against a synthetic no-match set, with expected 200–280× range derived from first
    principles
  • Domain separation table (v1 vs v2 prefixes with source line references to stealth.ts:8/9/99
    and scan.ts:12)
  • Cross-chain comparison: Stellar, EVM, Solana, and CKB (which uses RPC-level pre-filtering
    instead)

Supporting changes:

  • architecture/stellar-cryptography.mdx — forward link to the new page below the existing view
    tag diagram
  • sdk/chains/stellar.mdx — note on scanAnnouncements pointing to the new page
  • docs.json — page registered in the Architecture navigation group

Known gap: The acceptance criterion calls for a cross-reference from an SDK WebGPU guide, but
no such guide exists in the repo. That link should be added once the WebGPU guide is written.
closes #89

- New architecture/view-tag-scanner.mdx explaining the 1-byte view
  tag prefilter: problem statement, derivation spec (Stellar v2 +
  EVM), false-positive analysis, detailed scan flow, batching,
  benchmark methodology, domain separation, and cross-chain table
- New assets/diagrams/view-tag-comparison.svg — before/after cost
  structure diagram
- Add forward link from architecture/stellar-cryptography.mdx
- Add scanAnnouncements note in sdk/chains/stellar.mdx
- Register page in docs.json Architecture navigation group
@drips-wave

drips-wave Bot commented Jul 29, 2026

Copy link
Copy Markdown

@brooksdevon001-star 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

@truthixify
truthixify merged commit f05a0c0 into wraith-protocol:develop Jul 29, 2026
2 checks passed
@truthixify

Copy link
Copy Markdown
Contributor

Merged. View-tag scanner architecture page is exactly what third-party indexers were asking for, nice work.

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.

Architecture: view-tag scanner internals

2 participants