stellar-shade 0.0.1

package/README.md

@@ -0,0 +1,69 @@
+# 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
+
+```bash
+npm install stellar-shade
+```
+
+## Quick start
+
+```ts
+import { StealthClient } from 'stellar-shade';
+
+const client = new StealthClient({
+  network: 'testnet',
+  contractId: 'CAZRCYBRYP3FEWJX4D5NO6FK4THZ5O5OQGEJ4RBOPQ4IS5IRBUGHBA26',
+});
+
+// Generate stealth keys (no network needed)
+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
+
+// Bob scans for received payments
+const payments = await client.scan(bobKeys);
+// [{ stealthAddress, amount: 100, token: "C..." }]
+
+// Bob withdraws to his real address
+const result = await client.withdraw(payments[0].stealthAddress, bobPublicKey, {
+  keys: bobKeys,
+  feePayer: feePayerSecret,
+});
+```
+
+## Deployed testnet contract
+
+A registry contract is already live on the Stellar **testnet**, so you can try the SDK
+without deploying anything:
+
+| | |
+|---|---|
+| **Contract ID** | `CAZRCYBRYP3FEWJX4D5NO6FK4THZ5O5OQGEJ4RBOPQ4IS5IRBUGHBA26` |
+| **Network** | Testnet (`Test SDF Network ; September 2015`) |
+| **Explorer** | https://stellar.expert/explorer/testnet/contract/CAZRCYBRYP3FEWJX4D5NO6FK4THZ5O5OQGEJ4RBOPQ4IS5IRBUGHBA26 |
+
+## API
+
+- `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.
+
+TypeScript type definitions are included.
+
+## License
+
+MIT