Stellar stealth address crypto primitives

npm install @wraith-protocol/sdk @stellar/stellar-sdk

import {
  deriveStealthKeys,
  generateStealthAddress,
  scanAnnouncements,
  deriveStealthPrivateScalar,
  signStellarTransaction,
  signWithScalar,
  encodeStealthMetaAddress,
  decodeStealthMetaAddress,
  pubKeyToStellarAddress,
  computeSharedSecret,
  computeViewTag,
  checkStealthAddress,
  seedToScalar,
  hashToScalar,
  deriveStealthPubKey,
  bytesToHex,
  hexToBytes,
  STEALTH_SIGNING_MESSAGE,
  SCHEME_ID,
  META_ADDRESS_PREFIX,
  L,
} from "@wraith-protocol/sdk/chains/stellar";
import type {
  StealthKeys,
  GeneratedStealthAddress,
  Announcement,
  MatchedAnnouncement,
} from "@wraith-protocol/sdk/chains/stellar";

const STEALTH_SIGNING_MESSAGE =
  "Sign this message to generate your Wraith stealth keys.\n\nChain: Stellar\nNote: This signature is used for key derivation only and does not authorize any transaction.";

const SCHEME_ID = 1;                // number (not bigint like EVM)
const META_ADDRESS_PREFIX = "st:xlm:";
const L = 2n**252n + 27742317777372353535851937790883648493n; // ed25519 group order

interface StealthKeys {
  spendingKey:    Uint8Array;  // 32-byte seed
  spendingScalar: bigint;      // clamped scalar derived from SHA-512(seed)
  viewingKey:     Uint8Array;  // 32-byte seed
  viewingScalar:  bigint;      // clamped scalar
  spendingPubKey: Uint8Array;  // 32-byte ed25519 public key
  viewingPubKey:  Uint8Array;  // 32-byte ed25519 public key
}

interface GeneratedStealthAddress {
  stealthAddress:  string;      // Stellar G... address
  ephemeralPubKey: Uint8Array;  // 32-byte ed25519 public key
  viewTag:         number;      // 0-255
}

interface Announcement {
  schemeId:        number;
  stealthAddress:  string;  // G... address
  caller:          string;  // G... address
  ephemeralPubKey: string;  // hex-encoded 32 bytes
  metadata:        string;  // hex-encoded; first byte = view tag
}

interface MatchedAnnouncement extends Announcement {
  stealthPrivateScalar: bigint;      // scalar for signing from this address
  stealthPubKeyBytes:   Uint8Array;  // 32-byte ed25519 public key
}

const sig = stellarKeypair.sign(Buffer.from(STEALTH_SIGNING_MESSAGE));
const keys = deriveStealthKeys(sig);

console.log(keys.spendingKey);    // Uint8Array (32-byte seed)
console.log(keys.spendingScalar); // bigint (clamped scalar)
console.log(keys.viewingKey);     // Uint8Array (32-byte seed)
console.log(keys.viewingScalar);  // bigint (clamped scalar)
console.log(keys.spendingPubKey); // Uint8Array (32-byte public key)
console.log(keys.viewingPubKey);  // Uint8Array (32-byte public key)

const result = generateStealthAddress(
  recipientKeys.spendingPubKey,
  recipientKeys.viewingPubKey,
);

console.log(result.stealthAddress);  // "G..." — send XLM here
console.log(result.ephemeralPubKey); // Uint8Array — publish in announcement
console.log(result.viewTag);         // 0-255 — publish in announcement

// Fetch from Soroban events via sorobanServer.getEvents()
const announcements: Announcement[] = [/* ... */];

const matched = scanAnnouncements(
  announcements,
  keys.viewingKey,
  keys.spendingPubKey,
  keys.spendingScalar,  // bigint, not spendingKey!
);

for (const m of matched) {
  console.log(m.stealthAddress);        // "G..."
  console.log(m.stealthPrivateScalar);  // bigint — use for signing
  console.log(m.stealthPubKeyBytes);    // Uint8Array — use for signing
}

const scalar = deriveStealthPrivateScalar(
  keys.spendingScalar,
  keys.viewingKey,
  ephemeralPubKey,  // Uint8Array — from the announcement
);
// scalar is (spendingScalar + hashScalar) mod L

const txHash = transaction.hash(); // 32-byte Buffer from @stellar/stellar-sdk
const sig = signStellarTransaction(txHash, m.stealthPrivateScalar, m.stealthPubKeyBytes);

// Add the signature to the transaction envelope
transaction.addSignature(
  pubKeyToStellarAddress(m.stealthPubKeyBytes),
  sig.toString("base64"),
);
// Then submit to Horizon

const signature = signWithScalar(messageBytes, stealthScalar, stealthPubKeyBytes);
// Uint8Array (64-byte ed25519 signature)

const metaAddress = encodeStealthMetaAddress(
  keys.spendingPubKey,
  keys.viewingPubKey,
);
// "st:xlm:abc123...def456..."

const { spendingPubKey, viewingPubKey } = decodeStealthMetaAddress(
  "st:xlm:abc123...def456...",
);
// Both are Uint8Array (32 bytes)

const address = pubKeyToStellarAddress(m.stealthPubKeyBytes);
// "GABC..."

const hex = bytesToHex(new Uint8Array([0xab, 0xcd]));
// "abcd"

const bytes = hexToBytes("abcd");
// Uint8Array [0xab, 0xcd]

const scalar = seedToScalar(keys.spendingKey);
// bigint — clamped scalar used for ed25519 point multiplication

const scalar = hashToScalar(sharedSecret);
// bigint — SHA-256("wraith:scalar:" || sharedSecret) reduced mod L

const shared = computeSharedSecret(keys.viewingKey, ephemeralPubKey);
// Uint8Array (32 bytes)

import {
  deriveStealthKeys,
  generateStealthAddress,
  scanAnnouncements,
  signStellarTransaction,
  encodeStealthMetaAddress,
  decodeStealthMetaAddress,
  pubKeyToStellarAddress,
  STEALTH_SIGNING_MESSAGE,
} from "@wraith-protocol/sdk/chains/stellar";
import type { Announcement } from "@wraith-protocol/sdk/chains/stellar";

// ── Recipient setup ──────────────────────────────────────────────────

// 1. Derive keys from Stellar wallet signature
const sig = stellarKeypair.sign(Buffer.from(STEALTH_SIGNING_MESSAGE));
const keys = deriveStealthKeys(sig);

// 2. Publish the stealth meta-address so senders can find you
const metaAddress = encodeStealthMetaAddress(
  keys.spendingPubKey,
  keys.viewingPubKey,
);
// Share "st:xlm:..." publicly or register a .wraith name

// ── Sender ───────────────────────────────────────────────────────────

// 3. Decode the recipient's meta-address
const { spendingPubKey, viewingPubKey } = decodeStealthMetaAddress(metaAddress);

// 4. Generate a fresh one-time stealth address
const stealth = generateStealthAddress(spendingPubKey, viewingPubKey);
// stealth.stealthAddress — send XLM via Operation.createAccount (new accounts require 1 XLM minimum)
// stealth.ephemeralPubKey + stealth.viewTag — publish via Soroban announcer contract

// ── Recipient scanning ───────────────────────────────────────────────

// 5. Fetch announcements from Soroban events
const announcements: Announcement[] = [
  /* await sorobanServer.getEvents({ ... }) */
];

const matched = scanAnnouncements(
  announcements,
  keys.viewingKey,
  keys.spendingPubKey,
  keys.spendingScalar,  // pass spendingScalar, not spendingKey
);

// ── Recipient spending ───────────────────────────────────────────────

// 6. Sign and submit transactions from matched stealth addresses
for (const m of matched) {
  const transaction = buildYourTransaction(/* ... */);
  const txHash = transaction.hash();

  const sig = signStellarTransaction(
    txHash,
    m.stealthPrivateScalar,
    m.stealthPubKeyBytes,
  );

  transaction.addSignature(
    pubKeyToStellarAddress(m.stealthPubKeyBytes),
    Buffer.from(sig).toString("base64"),
  );

  await server.submitTransaction(transaction);
}