wraith-protocol · Hallab7 · Jul 26, 2026
diff --git a/examples/stellar-svelte-receive/README.md b/examples/stellar-svelte-receive/README.md
@@ -0,0 +1,12 @@
+# Stellar Svelte receive
+
+A minimal Svelte 5 app that uses `@wraith-protocol/sdk-svelte` to derive a Stellar
+stealth meta-address and scan recent on-chain announcements.
+
+```bash
+pnpm --filter @wraith-protocol/sdk-svelte build
+pnpm --filter @wraith-protocol/example-stellar-svelte-receive dev
+```
+
+Set `VITE_STELLAR_SECRET_KEY` to prefill the 64-byte hexadecimal secret, or paste
+one in the app. Scanning uses the Stellar deployment configured by the core SDK.
diff --git a/examples/stellar-svelte-receive/index.html b/examples/stellar-svelte-receive/index.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="description" content="Receive and scan Stellar stealth payments with Wraith." />
+    <title>Wraith Stellar Receive</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
diff --git a/examples/stellar-svelte-receive/package.json b/examples/stellar-svelte-receive/package.json
@@ -0,0 +1,21 @@
+{
+  "name": "@wraith-protocol/example-stellar-svelte-receive",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@stellar/stellar-sdk": "^13.1.0",
+    "@wraith-protocol/sdk-svelte": "workspace:*",
+    "svelte": "^5.0.0"
+  },
+  "devDependencies": {
+    "@sveltejs/vite-plugin-svelte": "^5.0.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0"
+  }
+}
diff --git a/examples/stellar-svelte-receive/src/App.svelte b/examples/stellar-svelte-receive/src/App.svelte
@@ -0,0 +1,293 @@
+<script lang="ts">
+  import {
+    useStellarAnnouncementScan,
+    useStellarStealthKeys,
+  } from '@wraith-protocol/sdk-svelte';
+
+  const {
+    keys,
+    metaAddress,
+    error: keyError,
+    generate,
+    encodeMetaAddress,
+  } = useStellarStealthKeys();
+  const { announcements, scanning, error: scanError, scan } = useStellarAnnouncementScan();
+
+  let secret = $state(import.meta.env.VITE_STELLAR_SECRET_KEY ?? '');
+  let validationError = $state<string | null>(null);
+
+  function parseSecret(value: string): Uint8Array | null {
+    const hex = value.trim().replace(/^0x/i, '');
+    if (!/^[0-9a-fA-F]+$/.test(hex) || hex.length % 2 !== 0) return null;
+    return new Uint8Array(hex.match(/.{2}/g)!.map((byte) => Number.parseInt(byte, 16)));
+  }
+
+  function derive() {
+    validationError = null;
+    const signature = parseSecret(secret);
+    if (!signature) {
+      validationError = 'Enter an even-length hexadecimal secret.';
+      return;
+    }
+    if (signature.length !== 64) {
+      validationError = `Expected 64 bytes, received ${signature.length}.`;
+      return;
+    }
+
+    const derived = generate(signature);
+    encodeMetaAddress(derived.spendingPubKey, derived.viewingPubKey);
+  }
+
+  async function scanPayments() {
+    try {
+      await scan({});
+    } catch {
+      // The error store renders the actionable network or RPC message.
+    }
+  }
+
+  function hex(bytes: Uint8Array): string {
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+  }
+</script>
+
+<svelte:head>
+  <title>Wraith Stellar Receive</title>
+</svelte:head>
+
+<main>
+  <p class="eyebrow">Wraith Protocol · Svelte</p>
+  <h1>Receive Stellar stealth payments</h1>
+  <p class="intro">
+    Derive a shareable stealth meta-address, then scan Stellar for payments announced to it.
+  </p>
+
+  <section>
+    <h2>1. Derive your receive address</h2>
+    <label for="secret">64-byte secret (hex)</label>
+    <textarea
+      id="secret"
+      bind:value={secret}
+      rows="4"
+      spellcheck="false"
+      placeholder="128 hexadecimal characters"
+    ></textarea>
+    <button type="button" onclick={derive}>Derive stealth keys</button>
+
+    {#if validationError || $keyError}
+      <p class="error" role="alert">{validationError ?? $keyError}</p>
+    {/if}
+
+    {#if $keys && $metaAddress}
+      <div class="result">
+        <span>Stealth meta-address</span>
+        <code>{$metaAddress}</code>
+        <details>
+          <summary>View public keys</summary>
+          <dl>
+            <dt>Spending</dt>
+            <dd>{hex($keys.spendingPubKey)}</dd>
+            <dt>Viewing</dt>
+            <dd>{hex($keys.viewingPubKey)}</dd>
+          </dl>
+        </details>
+      </div>
+    {/if}
+  </section>
+
+  <section>
+    <div class="section-heading">
+      <div>
+        <h2>2. Scan announcements</h2>
+        <p>Read recent announcements from the configured Stellar deployment.</p>
+      </div>
+      <button type="button" onclick={scanPayments} disabled={$scanning}>
+        {$scanning ? 'Scanning…' : 'Scan now'}
+      </button>
+    </div>
+
+    {#if $scanError}
+      <p class="error" role="alert">{$scanError.message}</p>
+    {:else if $announcements.length}
+      <ul>
+        {#each $announcements as announcement}
+          <li>
+            <code>{announcement.stealthAddress}</code>
+            <span>scheme {announcement.schemeId} · ledger {announcement.ledger ?? 'pending'}</span>
+          </li>
+        {/each}
+      </ul>
+    {:else}
+      <p class="empty">No announcements loaded yet.</p>
+    {/if}
+  </section>
+</main>
+
+<style>
+  :global(*) {
+    box-sizing: border-box;
+  }
+  :global(body) {
+    margin: 0;
+    min-width: 320px;
+    min-height: 100vh;
+    color: #e8ecf3;
+    background:
+      radial-gradient(circle at 15% 10%, rgba(84, 95, 255, 0.2), transparent 28rem),
+      #090b11;
+    font-family: Inter, ui-sans-serif, system-ui, sans-serif;
+  }
+  main {
+    width: min(760px, calc(100% - 32px));
+    margin: 0 auto;
+    padding: 72px 0;
+  }
+  .eyebrow {
+    margin: 0 0 12px;
+    color: #9ba7ff;
+    font-size: 0.78rem;
+    font-weight: 700;
+    letter-spacing: 0.14em;
+    text-transform: uppercase;
+  }
+  h1 {
+    max-width: 650px;
+    margin: 0;
+    font-size: clamp(2.4rem, 7vw, 4.8rem);
+    line-height: 0.98;
+    letter-spacing: -0.055em;
+  }
+  .intro {
+    max-width: 590px;
+    margin: 24px 0 42px;
+    color: #aeb6c7;
+    font-size: 1.08rem;
+    line-height: 1.65;
+  }
+  section {
+    margin-top: 18px;
+    padding: 26px;
+    border: 1px solid #242a39;
+    border-radius: 18px;
+    background: rgba(17, 20, 29, 0.88);
+  }
+  h2 {
+    margin: 0 0 18px;
+    font-size: 1.15rem;
+  }
+  label,
+  .result span {
+    display: block;
+    margin-bottom: 8px;
+    color: #aeb6c7;
+    font-size: 0.82rem;
+    font-weight: 650;
+  }
+  textarea {
+    width: 100%;
+    resize: vertical;
+    padding: 14px;
+    border: 1px solid #30384b;
+    border-radius: 10px;
+    outline: none;
+    color: #eff2fa;
+    background: #0c0f16;
+    font: 0.85rem/1.5 ui-monospace, SFMono-Regular, Consolas, monospace;
+  }
+  textarea:focus {
+    border-color: #737fff;
+    box-shadow: 0 0 0 3px rgba(115, 127, 255, 0.12);
+  }
+  button {
+    margin-top: 14px;
+    padding: 10px 16px;
+    border: 0;
+    border-radius: 9px;
+    color: white;
+    background: #5966e9;
+    font: inherit;
+    font-weight: 700;
+    cursor: pointer;
+  }
+  button:disabled {
+    cursor: wait;
+    opacity: 0.65;
+  }
+  .result {
+    margin-top: 22px;
+    padding: 16px;
+    border-radius: 12px;
+    background: #0c0f16;
+  }
+  code,
+  dd {
+    overflow-wrap: anywhere;
+    color: #bec5ff;
+    font-family: ui-monospace, SFMono-Regular, Consolas, monospace;
+  }
+  details {
+    margin-top: 16px;
+    color: #aeb6c7;
+  }
+  dl {
+    display: grid;
+    grid-template-columns: auto 1fr;
+    gap: 8px 14px;
+    font-size: 0.78rem;
+  }
+  dd {
+    margin: 0;
+  }
+  .section-heading {
+    display: flex;
+    align-items: start;
+    justify-content: space-between;
+    gap: 24px;
+  }
+  .section-heading h2 {
+    margin-bottom: 5px;
+  }
+  .section-heading p,
+  .empty {
+    margin: 0;
+    color: #858fa3;
+  }
+  .section-heading button {
+    flex: 0 0 auto;
+    margin-top: 0;
+  }
+  .error {
+    color: #ff9b9b;
+  }
+  ul {
+    display: grid;
+    gap: 8px;
+    padding: 0;
+    list-style: none;
+  }
+  li {
+    display: flex;
+    justify-content: space-between;
+    gap: 14px;
+    padding: 12px;
+    border-radius: 9px;
+    background: #0c0f16;
+  }
+  li span {
+    flex: 0 0 auto;
+    color: #858fa3;
+    font-size: 0.8rem;
+  }
+  @media (max-width: 560px) {
+    main {
+      padding: 42px 0;
+    }
+    section {
+      padding: 20px;
+    }
+    .section-heading,
+    li {
+      flex-direction: column;
+    }
+  }
+</style>
diff --git a/examples/stellar-svelte-receive/src/main.ts b/examples/stellar-svelte-receive/src/main.ts
@@ -0,0 +1,6 @@
+import { mount } from 'svelte';
+import App from './App.svelte';
+
+mount(App, {
+  target: document.getElementById('app')!,
+});
diff --git a/examples/stellar-svelte-receive/src/vite-env.d.ts b/examples/stellar-svelte-receive/src/vite-env.d.ts
@@ -0,0 +1 @@
+/// <reference types="vite/client" />
diff --git a/examples/stellar-svelte-receive/svelte.config.js b/examples/stellar-svelte-receive/svelte.config.js
@@ -0,0 +1,5 @@
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+
+export default {
+  preprocess: vitePreprocess(),
+};
diff --git a/examples/stellar-svelte-receive/tsconfig.json b/examples/stellar-svelte-receive/tsconfig.json
@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "isolatedModules": true
+  },
+  "include": ["src/**/*.ts", "src/**/*.svelte"]
+}
diff --git a/examples/stellar-svelte-receive/vite.config.ts b/examples/stellar-svelte-receive/vite.config.ts
@@ -0,0 +1,6 @@
+import { defineConfig } from 'vite';
+import { svelte } from '@sveltejs/vite-plugin-svelte';
+
+export default defineConfig({
+  plugins: [svelte()],
+});
diff --git a/packages/sdk-svelte/package.json b/packages/sdk-svelte/package.json
@@ -25,9 +25,13 @@
     "@wraith-protocol/sdk": "workspace:*"
   },
   "peerDependencies": {
+    "@stellar/stellar-sdk": "^13.1.0",
     "svelte": "^5.0.0"
   },
   "devDependencies": {
+    "@stellar/stellar-sdk": "^13.1.0",
+    "@testing-library/svelte": "^5.2.0",
+    "jsdom": "^25.0.0",
     "svelte": "^5.0.0",
     "tsup": "^8.4.0",
     "typescript": "^5.7.0",