stellar-shade 0.0.2 → 0.1.0

package/README.md

@@ -1,69 +1,165 @@
 # stellar-shade
 
-**Privacy-preserving stealth payments on Stellar** — a high-level client SDK built on
-DKSAP (Dual-Key Stealth Address Protocol) over ed25519.
-
-`stellar-shade` lets a sender pay a recipient's published *meta-address* while the
-on-chain destination looks unlinkable to outside observers. It bundles the underlying
-stealth-address cryptography, so you only need to install one package.
-
-## Installation
+High-level client for **stealth payments on Stellar** (DKSAP on ed25519). Wraps the
+`@shade/crypto` math and all Horizon/Soroban I/O behind a small `StealthClient`
+with pluggable **delivery methods**. You never touch DKSAP math or transaction
+serialization directly.
 
 ```bash
 npm install stellar-shade
 ```
 
-## Quick start
+## Quickstart
 
-```ts
+```typescript
 import { StealthClient } from 'stellar-shade';
 
+// `contractId` is REQUIRED whenever the pool method is enabled (mandatory on testnet
+// — there is no built-in default, and the constructor throws ContractIdRequiredError
+// otherwise).
 const client = new StealthClient({
   network: 'testnet',
-  contractId: 'CAZRCYBRYP3FEWJX4D5NO6FK4THZ5O5OQGEJ4RBOPQ4IS5IRBUGHBA26',
+  contractId: 'CXXX...',
+  methods: ['pool', 'account'],
+  relayer: 'http://localhost:3000', // optional
 });
 
-// Generate stealth keys (no network needed)
+// Recipient keys (offline; share metaAddress publicly).
 const bobKeys = StealthClient.keygen();
-// bobKeys.metaAddress → "st:stellar:..." (share this publicly)
 
-// Alice sends 100 XLM to Bob's stealth meta-address
-const receipt = await client.send(bobKeys.metaAddress, 100, aliceSecret);
-// receipt.stealthAddress, receipt.txHash
+// Send. A delivery method is REQUIRED — 'pool' | 'account' | 'auto'. There is no
+// implicit default; omitting it throws MethodRequiredError.
+const receipt = await client.send(bobKeys.metaAddress, 100, aliceSecret, {
+  method: 'auto',
+});
 
-// Bob scans for received payments
+// Scan (Payment[]). Use scanWithCursor(keys, { cursor }) for incremental rescans.
 const payments = await client.scan(bobKeys);
-// [{ stealthAddress, amount: 100, token: "C..." }]
+// [{ stealthAddress, amount: 100, asset: 'XLM', method: 'pool', ... }]
 
-// Bob withdraws to his real address
-const result = await client.withdraw(payments[0].stealthAddress, bobPublicKey, {
+// Claim a Payment to a real destination. `claim` branches on payment.method.
+const result = await client.claim(payments[0], bobPublicKey, {
   keys: bobKeys,
-  feePayer: feePayerSecret,
+  feePayer: feePayerSecret,          // pool claims need a fee payer for the Soroban fee
+  relay: 'http://localhost:3000',    // optional fee-bump for privacy
 });
 ```
 
-## Deployed testnet contract
+## Delivery methods — pick per privacy / cost trade-off
+
+`DeliveryMethod = 'pool' | 'account' | 'spp'`. All three use the same recipient
+meta-address; they differ in where funds sit, discovery, and claim.
+
+| | `pool` | `account` | `spp` |
+| --- | --- | --- | --- |
+| **Status** | Implemented | Implemented | Reserved (`MethodNotAvailableError`) |
+| **Where funds sit** | Soroban pool contract, keyed by `(stealth_pk, token)` | One-time stealth account: native XLM as balance; tokens in a `ClaimableBalance` | ZK shielded pool (future) |
+| **Sender↔recipient link** | Strong privacy: only touches the shared pool | Weaker: a `CreateAccount`/`CreateClaimableBalance` edge from sender to the one-time account | Strongest (planned) |
+| **Amount** | On-chain per announcement | On-chain (starting balance / CB amount) | Hidden (planned) |
+| **Minimum** | any `> 0` | native strictly `> 1 XLM`; token sender fronts ~1.5 XLM reserves (0.5 returns on claim) | N/A |
+| **Assets** | any SAC token | native XLM or any SAC/classic asset | N/A |
+| **Discovery** | contract announcements + view tag (~2x fast-scan) | `MemoHash(R)` on the funding tx via Horizon paging; destination match IS the verification | reserved |
+| **Relayer** | optional fee-bump so the recipient needs no funded account | optional fee-bump / sponsored claim | N/A |
+
+Rule of thumb: **`pool`** for best privacy + multi-token; **`account`** for the
+simplest path that works with vanilla Horizon tooling; **`spp`** is a
+forward-compatible slot (opt in later with zero API changes).
+
+## Errors are typed
+
+Public failures throw named subclasses of `Error` (all exported) so apps can branch:
+
+```typescript
+import { MethodRequiredError, ContractIdRequiredError, NoBalanceError,
+         AnnouncementNotFoundError, StealthAccountNotFoundError,
+         DestinationTrustlineError, FeePayerRequiredError,
+         SponsoredClaimMismatchError } from 'stellar-shade';
+
+try {
+  await client.claim(payment, dest, { keys });
+} catch (e) {
+  if (e instanceof DestinationTrustlineError) { /* add a trustline first */ }
+}
+```
+
+`SponsoredClaimMismatchError` is a **client-side safety control**: on a sponsored
+token claim the SDK re-derives the relayer-prepared operation list from your own
+inputs and refuses to sign if anything (payout destination/amount/asset, op source,
+extra ops, memo) does not match — a malicious relayer cannot redirect the payout.
+
+## Wallet-derived keys
 
-A registry contract is already live on the Stellar **testnet**, so you can try the SDK
-without deploying anything:
+`keysFromWalletSignature(signer, opts)` derives stealth keys from a wallet's
+SEP-53 signature (keyless recovery). Determinism is verified by **default**
+(`verifyDeterminism` defaults to `true`) so a randomized/non-canonical signer fails
+loudly instead of deriving unrecoverable keys. Scope keys with a matching
+`{ keyScope, appId }` across every tool that derives them (a mismatch yields
+different, non-interoperable keys). Wallet compromise equals stealth-key compromise —
+the accepted trade-off for keyless recovery.
 
-| | |
-|---|---|
-| **Contract ID** | `CAZRCYBRYP3FEWJX4D5NO6FK4THZ5O5OQGEJ4RBOPQ4IS5IRBUGHBA26` |
-| **Network** | Testnet (`Test SDF Network ; September 2015`) |
-| **Explorer** | https://stellar.expert/explorer/testnet/contract/CAZRCYBRYP3FEWJX4D5NO6FK4THZ5O5OQGEJ4RBOPQ4IS5IRBUGHBA26 |
+## External signing (Freighter)
 
-## API
+A dapp can let a browser wallet (Freighter) sign the **sender** and **fee-payer**
+legs so it never handles a raw Stellar secret. Pass a `signTransaction` function
+(Freighter's `signTransaction` shape) and, where a secret is normally expected,
+pass the corresponding **public** `G...` address instead.
 
-- `StealthClient.keygen()` — generate a stealth key pair + shareable meta-address.
-- `new StealthClient({ network, contractId })` — create a client (`network`: `testnet` | `local`).
-- `client.send(metaAddress, amount, sourceSecret)` — pay a meta-address.
-- `client.scan(keys)` — find payments received to your stealth addresses.
-- `client.balance(stealthAddress)` — check a stealth account balance.
-- `client.withdraw(stealthAddress, destination, opts)` — move funds out.
+`TransactionSigner` returns the signed XDR **string**, so wallets whose API
+returns an object (Freighter resolves to `{ signedTxXdr, signerAddress }`) must
+**unwrap** it inside the adapter:
 
-TypeScript type definitions are included.
+```typescript
+import freighterApi from '@stellar/freighter-api';
+import { StealthClient, type TransactionSigner } from 'stellar-shade';
 
-## License
+const signTransaction: TransactionSigner = async (xdr, { networkPassphrase }) => {
+  const { signedTxXdr } = await freighterApi.signTransaction(xdr, { networkPassphrase });
+  return signedTxXdr;
+};
+
+const client = new StealthClient({ network: 'testnet', contractId: 'C...' });
+
+// `senderSecret` positional carries the sender's G-ADDRESS when signing externally.
+await client.send(metaAddress, 100, senderGAddress, {
+  method: 'account',
+  signTransaction,
+});
+
+// A pool claim needs a fee payer — supply its G-address (never a secret).
+await client.claim(payment, destinationG, {
+  keys,
+  signTransaction,
+  feePayerAddress: feePayerGAddress,
+});
+```
 
-MIT
+The recovered **stealth-key** claim/withdraw legs still sign **locally**: Freighter
+cannot hold the derived stealth scalar, so `signTransaction` only ever applies to
+the sender / fee-payer legs. Omitting `signTransaction` keeps the existing
+secret-based behavior unchanged. Omitting `feePayerAddress` on a signed pool claim
+throws `FeePayerAddressRequiredError` rather than treating a public key as a secret.
+The CLI stays secret-based (no Freighter in the terminal).
+
+## Two fund-safety footguns
+
+- **The raw-scalar rule.** `recoverStealthPrivateKey` returns a **`StealthScalar`
+  wrapper** around the raw ed25519 scalar (not a seed). Sign directly on it —
+  `key.sign(message)` — verify with `key.publicKey()`, and `key.zeroize()` when
+  done. Because the wrapper is **not** a `Uint8Array`,
+  `Keypair.fromRawEd25519Seed(key)` is now a **compile error**, so the old
+  footgun — feeding the raw scalar to a seed-based API, which hashes it into a
+  *different* key and makes the funds **permanently unwithdrawable** — is gone.
+  The deprecated `recoverStealthPrivateKeyBytes()` (and `dangerouslyToRawBytes()`
+  on the wrapper) still return the old raw bytes for interop, carrying the same
+  seed-API warning. `client.claim()` does the signing correctly for you.
+- **Two types named `StealthKeys`.** `@shade/crypto` and `stellar-shade` both
+  export a type named `StealthKeys` with **different shapes**: crypto's holds
+  raw `Uint8Array` private keys plus a nested `metaAddress` object; the SDK's
+  holds hex strings plus a `metaAddress` string. Import from the package whose
+  functions you are calling.
+
+## Roadmap / known limitations
+
+Crypto is pending external audit (not for mainnet yet). The relayer's JSON credit
+ledger and bearer-vs-signed funding-account auth, and Horizon full-scan without an
+indexer, are scheduled hardening — see the repo root README.