Solana Primitives

npm install @wraith-protocol/sdk
# Solana Web3.js is an optional peer dependency — install it too
npm install @solana/web3.js

import {
  deriveStealthKeys,
  generateStealthAddress,
  computeSharedSecret,
  computeViewTag,
  checkStealthAddress,
  scanAnnouncements,
  deriveStealthPrivateScalar,
  signSolanaTransaction,
  signWithScalar,
  encodeStealthMetaAddress,
  decodeStealthMetaAddress,
  seedToScalar,
  hashToScalar,
  deriveStealthPubKey,
  pubKeyToSolanaAddress,
  bytesToHex,
  hexToBytes,
  fetchAnnouncements,
  getDeployment,
  DEPLOYMENTS,
  STEALTH_SIGNING_MESSAGE,
  SCHEME_ID,
  META_ADDRESS_PREFIX,
  L,
} from "@wraith-protocol/sdk/chains/solana";

interface StealthKeys {
  spendingKey: Uint8Array;       // 32-byte seed
  spendingScalar: bigint;        // clamped scalar 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;        // base58-encoded Solana address
  ephemeralPubKey: Uint8Array;   // 32-byte ed25519 public key
  viewTag: number;               // 0-255
}

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

interface MatchedAnnouncement extends Announcement {
  stealthPrivateScalar: bigint;
  stealthPubKeyBytes: Uint8Array;
}

const STEALTH_SIGNING_MESSAGE = "Sign this message to generate your Wraith stealth keys.\n\nChain: Solana\nNote: This signature is used for key derivation only and does not authorize any transaction.";
const SCHEME_ID = 1;
const META_ADDRESS_PREFIX = "st:sol:";
const L = 2n**252n + 27742317777372353535851937790883648493n;  // ed25519 group order

const signature = await wallet.signMessage(Buffer.from(STEALTH_SIGNING_MESSAGE));
const keys = deriveStealthKeys(signature);

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 scalar = seedToScalar(seed);
// bigint — the clamped scalar used for point multiplication

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

const tag = computeViewTag(sharedSecret);
// number (0-255)

const scalar = hashToScalar(sharedSecret);
// bigint (reduced mod L)

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

console.log(result.stealthAddress);  // "7xKX..." (base58 Solana address)
console.log(result.ephemeralPubKey); // Uint8Array (32 bytes)
console.log(result.viewTag);        // 0-255

const result = checkStealthAddress(
  ephemeralPubKey,
  keys.viewingKey,
  keys.spendingPubKey,
  viewTag
);

if (result.isMatch) {
  console.log(result.stealthAddress);     // "7xKX..."
  console.log(result.hashScalar);         // bigint
  console.log(result.stealthPubKeyBytes); // Uint8Array
}

const matched = scanAnnouncements(
  announcements,
  keys.viewingKey,
  keys.spendingPubKey,
  keys.spendingScalar
);

for (const m of matched) {
  console.log(m.stealthAddress);         // "7xKX..."
  console.log(m.stealthPrivateScalar);   // bigint
  console.log(m.stealthPubKeyBytes);     // Uint8Array
}

const scalar = deriveStealthPrivateScalar(
  keys.spendingScalar,
  keys.viewingKey,
  ephemeralPubKey
);
// bigint — (spendingScalar + hashScalar) mod L

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

const sig = signSolanaTransaction(txMessageBytes, stealthScalar, stealthPubKey);
// Uint8Array (64-byte signature)
// Add to the transaction before sending

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

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

const address = pubKeyToSolanaAddress(publicKeyBytes);
// "7xKXaJoV..."

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

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

import {
  deriveStealthKeys,
  generateStealthAddress,
  scanAnnouncements,
  deriveStealthPrivateScalar,
  signSolanaTransaction,
  encodeStealthMetaAddress,
  decodeStealthMetaAddress,
  pubKeyToSolanaAddress,
  fetchAnnouncements,
  STEALTH_SIGNING_MESSAGE,
} from "@wraith-protocol/sdk/chains/solana";
import { Connection, Transaction, SystemProgram, PublicKey } from "@solana/web3.js";

// 1. Recipient: derive keys from Solana wallet signature
const sig = await wallet.signMessage(Buffer.from(STEALTH_SIGNING_MESSAGE));
const keys = deriveStealthKeys(sig);

// 2. Recipient: publish stealth meta-address
const metaAddress = encodeStealthMetaAddress(keys.spendingPubKey, keys.viewingPubKey);
// Share "st:sol:..." or register as a .wraith name

// 3. Sender: generate stealth address from meta-address
const { spendingPubKey, viewingPubKey } = decodeStealthMetaAddress(metaAddress);
const stealth = generateStealthAddress(spendingPubKey, viewingPubKey);
// stealth.stealthAddress is a base58 Solana address

// 4. Sender: send SOL to stealth address + call announcer program

// 5. Recipient: scan announcements
const announcements = await fetchAnnouncements("solana");
const matched = scanAnnouncements(
  announcements,
  keys.viewingKey,
  keys.spendingPubKey,
  keys.spendingScalar
);

// 6. Recipient: withdraw from stealth address
for (const m of matched) {
  const stealthPubKey = new PublicKey(m.stealthPubKeyBytes);
  const tx = new Transaction().add(
    SystemProgram.transfer({
      fromPubkey: stealthPubKey,
      toPubkey: new PublicKey(destinationAddress),
      lamports: withdrawAmount,
    })
  );

  const messageBytes = tx.serializeMessage();
  const sig = signSolanaTransaction(messageBytes, m.stealthPrivateScalar, m.stealthPubKeyBytes);
  tx.addSignature(stealthPubKey, Buffer.from(sig));

  const connection = new Connection("https://api.devnet.solana.com");
  await connection.sendRawTransaction(tx.serialize());
}

const deployment = getDeployment("solana");
// {
//   cluster: "devnet",
//   rpcUrl: "https://api.devnet.solana.com",
//   explorerUrl: "https://explorer.solana.com",
//   contracts: {
//     announcer: "...",  // program ID
//     sender: "...",
//     names: "...",
//   },
// }

const announcements = await fetchAnnouncements("solana");
// Returns Announcement[] — ready to pass to scanAnnouncements()