zcashname-sdk 0.5.1 → 0.6.0

package/README.md

@@ -1,8 +1,6 @@
-# Zcash Name System (ZNS) SDK
+# ZNS SDK
 
-TypeScript SDK for interacting with the Zcash Name System — a decentralized naming system built on Zcash.
-
-## Install
+TypeScript SDK for the Zcash Name System. Register names, manage listings, and resolve addresses on Zcash.
 
 ```bash
 npm install zcashname-sdk
@@ -13,81 +11,234 @@ npm install zcashname-sdk
 ```ts
 import { ZNS } from "zcashname-sdk";
 
-const zns = await ZNS.create();
+// Create client (synchronous, no network calls)
+const zns = new ZNS();
 
-const name = "alice";
-const resolved = await zns.resolve(name);
-if (resolved === null) {
-  console.log(`${name} is available`);
-} else {
-  console.log(`${name} resolves to ${resolved.address}`);
-}
+// Resolve a name to get its Zcash address
+const reg = await zns.resolveName("alice");
+if (reg) console.log(`alice.zcash → ${reg.address}`);
+
+// Check availability
+const available = await zns.isAvailable("bob");
+
+// Verify server identity (optional but recommended)
+await zns.verify();
 ```
 
-## API
+## Actions Flow
 
-### `ZNS.create(options?)`
-Create a new ZNS instance connected to the default testnet endpoint.
+Every state-changing action follows the same pattern: **prepare → sign → complete**.
 
 ```ts
-const zns = await ZNS.create();
-const znsMainnet = await ZNS.create({ url: "https://light.zcash.me/zns-mainnet" });
+import * as ed25519 from "@noble/ed25519";
+
+// 1. Fetch status to get current pricing
+const status = await zns.status();
+const cost = zns.claimCost(5, status.pricing);
+
+// 2. Prepare the action
+const claim = zns.prepareClaim("myname", "u1qqlzrf9...", status.address, cost);
+
+// 3. Sign the payload with your Ed25519 private key
+const privateKey = ed25519.utils.randomPrivateKey();
+const signature = await ed25519.signAsync(
+  new TextEncoder().encode(claim.payload),
+  privateKey
+);
+
+// 4. Complete and get the payment URI
+const { memo, uri } = claim.complete(
+  Buffer.from(signature).toString("base64"),
+  Buffer.from(ed25519.getPublicKey(privateKey)).toString("base64")
+);
+
+// 5. Send the transaction using your Zcash wallet
+console.log("Payment URI:", uri);
+console.log("Memo:", memo);
 ```
 
-### `zns.resolve(query)`
-Resolve a name to its registered address. Returns `null` if the name is available.
+## Available Actions
 
-```ts
-const result = await zns.resolve("alice");
-```
+| Action | Description |
+|--------|-------------|
+| `prepareClaim(name, address, registryAddress, cost)` | Register a new name |
+| `prepareList(name, price, nonce, registryAddress)` | List name for sale |
+| `prepareDelist(name, nonce, registryAddress)` | Remove listing |
+| `prepareUpdate(name, newAddress, nonce, registryAddress)` | Change address |
+| `prepareBuy(name, buyerAddress, registryAddress)` | Buy a listed name |
+| `prepareRelease(name, nonce, registryAddress)` | Release name (burn) |
+| `prepareSetPrice(prices, nonce, registryAddress)` | Admin: set pricing tiers |
 
-### `zns.isAvailable(name)`
-Check if a name is available for registration.
+## Reading Data
 
 ```ts
+// Resolve name → address
+const reg = await zns.resolveName("alice");
+
+// Resolve address → names (reverse lookup)
+const names = await zns.resolveAddress("u1qqlzrf9...");
+
+// Check availability
 const available = await zns.isAvailable("bob");
+
+// Get all listings
+const listings = await zns.listings();
+
+// Query events
+const { events, total } = await zns.events({ action: "CLAIM", limit: 10 });
+
+// Get current pricing from status
+const status = await zns.status();
+const cost = zns.claimCost(5, status.pricing); // cost for 5-char name
 ```
 
-### `zns.listings()`
-Get all names currently listed for sale.
+## Server Verification (Optional)
+
+For security-sensitive applications, verify the server identity:
 
 ```ts
-const listings = await zns.listings();
+const zns = new ZNS({ url: "https://your-indexer.com/zns" });
+
+// Verify this is a legitimate ZNS instance
+await zns.verify();
+console.log("Verified:", zns.verified); // true
+
+// Now proceed with operations
+const status = await zns.status();
 ```
 
-### `zns.events(filter?)`
-Query blockchain events (claims, buys, lists, delists, updates, releases).
+## Validation & Utilities
 
 ```ts
-const { events } = await zns.events({ action: "CLAIM", limit: 50 });
+// Validate a Zcash Unified Address
+const valid = zns.isValidUnifiedAddress("u1qqlzrf9..."); // true/false
+
+// Validate a ZNS name
+const validName = zns.isValidName("alice"); // true
+const invalid = zns.isValidName("Alice");   // false (uppercase)
+
+// Parse ZIP-321 URI
+const parts = zns.parseZip321Uri("zcash:u1...?amount=1&memo=...");
+// { address: "u1...", amount: "1", memoRaw: "...", memoDecoded: "..." }
 ```
 
-### Action Helpers
+## Signature Verification
 
-The SDK provides prepare/complete pairs for all ZNS actions:
+```ts
+// Get admin pubkey from status
+const status = await zns.status();
 
-- `zns.prepareClaim(name, address)` / `zns.completeClaim(...)` — claim a name
-- `zns.prepareList(name, price, nonce)` / `zns.completeList(...)` — list a name for sale
-- `zns.prepareDelist(name, nonce)` / `zns.completeDelist(...)` — delist a name
-- `zns.prepareUpdate(name, newAddress, nonce)` / `zns.completeUpdate(...)` — update a name's address
-- `zns.prepareBuy(name, buyerAddress)` / `zns.completeBuy(...)` — buy a name
-- `zns.prepareRelease(name, nonce)` / `zns.completeRelease(...)` — release a name
+// Verify a listing signature
+const listing = await zns.listings().then(l => l[0]);
+const valid = await zns.verifyListing(listing, status.admin_pubkey);
 
-Each `complete*` method returns a `{ memo, uri }` object suitable for constructing a ZIP 321 URI.
+// Verify a registration
+const reg = await zns.resolveName("alice");
+const validReg = await zns.verifyRegistration(reg, status.admin_pubkey);
+```
 
-### `zns.parseZip321Uri(uri)`
-Parse a ZIP 321 URI into its components.
+## Configuration
 
 ```ts
-const parsed = zns.parseZip321Uri("zcash:addr?amount=0.1&memo=...");
+// Custom endpoint
+const zns = new ZNS({ url: "https://your-indexer.com/zns" });
+
+// Optional: verify server identity
+await zns.verify(); // throws if not a known ZNS instance
+
+// Access current status
+const status = await zns.status();
+console.log(status.admin_pubkey);  // Registry admin pubkey
+console.log(status.pricing);       // Current pricing tiers
+console.log(status.address);       // Registry payment address
 ```
 
 ## Constants
 
-- `DEFAULT_URL` — default testnet endpoint
-- `TESTNET_UIVK` — expected testnet UIVK for verification
-- `MAINNET_UIVK` — expected mainnet UIVK for verification
+```ts
+import { DEFAULT_URL, TESTNET_UIVK, MAINNET_UIVK } from "zcashname-sdk";
+
+console.log(DEFAULT_URL);  // "https://light.zcash.me/zns-testnet"
+```
+
+## CLI Example
+
+See `examples/cli/` for a working command-line interface:
+
+```bash
+# Resolve a name
+npx tsx src/index.ts resolve alice
+
+# Check availability
+npx tsx src/index.ts available bob
+
+# List all names for sale
+npx tsx src/index.ts listings
+
+# Prepare a claim (outputs payload to sign)
+npx tsx src/index.ts prepare-claim myname u1qqlzrf9...
+
+# Sign and complete with a private key
+npx tsx src/index.ts sign-claim myname u1qqlzrf9... --key-file ./key.txt
+```
+
+## Types
+
+```ts
+type Zats = number; // 1 ZEC = 100,000,000 zats
+
+interface Registration {
+  name: string;
+  address: string;
+  txid: string;
+  height: number;
+  nonce: number;
+  signature: string | null;
+  last_action: "CLAIM" | "BUY" | "UPDATE" | "DELIST" | "RELEASE";
+  pubkey: string | null;    // null = admin-registered
+  listing: Listing | null;
+}
+
+interface Listing {
+  name: string;
+  price: Zats;
+  nonce: number;
+  txid: string;
+  height: number;
+  signature: string;
+  pubkey: string | null;
+}
+
+interface Status {
+  synced_height: number;
+  admin_pubkey: string;
+  uivk: string;
+  address: string;
+  registered: number;
+  listed: number;
+  pricing: Pricing;
+}
+
+interface Pricing {
+  nonce: number;
+  height: number;
+  tiers: Zats[]; // cost for names of length 1, 2, 3...
+}
+
+interface PreparedClaim {
+  readonly name: string;
+  readonly address: string;
+  readonly cost: Zats;
+  readonly payload: string;  // sign this
+  complete(signature: string, userPubkey?: string): CompletedAction;
+}
+
+interface CompletedAction {
+  memo: string;  // ZNS:CLAIM:name:address:sig:pubkey
+  uri: string;   // zcash:addr?amount=...&memo=...
+}
+```
 
 ## License
 
-MIT
+MIT