zcashname-sdk 0.5.0 → 0.5.1

package/README.md

@@ -0,0 +1,93 @@
+# Zcash Name System (ZNS) SDK
+
+TypeScript SDK for interacting with the Zcash Name System — a decentralized naming system built on Zcash.
+
+## Install
+
+```bash
+npm install zcashname-sdk
+```
+
+## Quick Start
+
+```ts
+import { ZNS } from "zcashname-sdk";
+
+const zns = await ZNS.create();
+
+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}`);
+}
+```
+
+## API
+
+### `ZNS.create(options?)`
+Create a new ZNS instance connected to the default testnet endpoint.
+
+```ts
+const zns = await ZNS.create();
+const znsMainnet = await ZNS.create({ url: "https://light.zcash.me/zns-mainnet" });
+```
+
+### `zns.resolve(query)`
+Resolve a name to its registered address. Returns `null` if the name is available.
+
+```ts
+const result = await zns.resolve("alice");
+```
+
+### `zns.isAvailable(name)`
+Check if a name is available for registration.
+
+```ts
+const available = await zns.isAvailable("bob");
+```
+
+### `zns.listings()`
+Get all names currently listed for sale.
+
+```ts
+const listings = await zns.listings();
+```
+
+### `zns.events(filter?)`
+Query blockchain events (claims, buys, lists, delists, updates, releases).
+
+```ts
+const { events } = await zns.events({ action: "CLAIM", limit: 50 });
+```
+
+### Action Helpers
+
+The SDK provides prepare/complete pairs for all ZNS actions:
+
+- `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
+
+Each `complete*` method returns a `{ memo, uri }` object suitable for constructing a ZIP 321 URI.
+
+### `zns.parseZip321Uri(uri)`
+Parse a ZIP 321 URI into its components.
+
+```ts
+const parsed = zns.parseZip321Uri("zcash:addr?amount=0.1&memo=...");
+```
+
+## Constants
+
+- `DEFAULT_URL` — default testnet endpoint
+- `TESTNET_UIVK` — expected testnet UIVK for verification
+- `MAINNET_UIVK` — expected mainnet UIVK for verification
+
+## License
+
+MIT

package/dist/zns.cjs

@@ -185,17 +185,23 @@ var ZNS = class _ZNS {
     const memoDecoded = memoRaw ? this.decodeBase64Url(memoRaw) : "";
     return { address, amount, memoRaw, memoDecoded };
   }
-  async enrichRegistration(reg) {
+  async enrichRegistration(raw) {
+    const { listing: rawListing, ...reg } = raw;
     const sovereign = reg.pubkey != null && reg.pubkey !== this._adminPubkey;
-    let verified = false;
-    if (reg.signature && this._adminPubkey) {
-      const payload = this.registrationPayload(reg);
-      if (payload) {
-        const pubkey = sovereign ? reg.pubkey : this._adminPubkey;
-        verified = await this.verifyEd25519(payload, reg.signature, pubkey);
-      }
-    }
-    return { ...reg, listing: null, verified, sovereign };
+    const verified = await this.verifyRegistration(reg, sovereign);
+    const listing = rawListing ? await this.verifyListing(rawListing) : null;
+    return { ...reg, listing, verified, sovereign };
+  }
+  async verifyRegistration(reg, sovereign) {
+    if (!reg.signature || !this._adminPubkey) return false;
+    const payload = this.registrationPayload(reg);
+    if (!payload) return false;
+    const pubkey = sovereign ? reg.pubkey : this._adminPubkey;
+    return this.verifyEd25519(payload, reg.signature, pubkey);
+  }
+  async verifyListing(listing) {
+    const verified = this._adminPubkey ? await this.verifyEd25519(this.listingPayload(listing), listing.signature, this._adminPubkey) : false;
+    return { ...listing, verified };
   }
   async enrichListing(listing) {
     let verified = false;

package/dist/zns.d.cts

@@ -18,7 +18,7 @@ interface Listing {
     signature: string;
 }
 interface ResolveResult extends Registration {
-    listing: Listing | null;
+    listing: VerifiedListing | null;
     verified: boolean;
     sovereign: boolean;
 }
@@ -122,6 +122,8 @@ declare class ZNS {
         memoDecoded: string;
     };
     private enrichRegistration;
+    private verifyRegistration;
+    private verifyListing;
     private enrichListing;
     private enrichEvent;
     private registrationPayload;

package/dist/zns.d.ts

@@ -18,7 +18,7 @@ interface Listing {
     signature: string;
 }
 interface ResolveResult extends Registration {
-    listing: Listing | null;
+    listing: VerifiedListing | null;
     verified: boolean;
     sovereign: boolean;
 }
@@ -122,6 +122,8 @@ declare class ZNS {
         memoDecoded: string;
     };
     private enrichRegistration;
+    private verifyRegistration;
+    private verifyListing;
     private enrichListing;
     private enrichEvent;
     private registrationPayload;

package/dist/zns.js

@@ -158,17 +158,23 @@ var ZNS = class _ZNS {
     const memoDecoded = memoRaw ? this.decodeBase64Url(memoRaw) : "";
     return { address, amount, memoRaw, memoDecoded };
   }
-  async enrichRegistration(reg) {
+  async enrichRegistration(raw) {
+    const { listing: rawListing, ...reg } = raw;
     const sovereign = reg.pubkey != null && reg.pubkey !== this._adminPubkey;
-    let verified = false;
-    if (reg.signature && this._adminPubkey) {
-      const payload = this.registrationPayload(reg);
-      if (payload) {
-        const pubkey = sovereign ? reg.pubkey : this._adminPubkey;
-        verified = await this.verifyEd25519(payload, reg.signature, pubkey);
-      }
-    }
-    return { ...reg, listing: null, verified, sovereign };
+    const verified = await this.verifyRegistration(reg, sovereign);
+    const listing = rawListing ? await this.verifyListing(rawListing) : null;
+    return { ...reg, listing, verified, sovereign };
+  }
+  async verifyRegistration(reg, sovereign) {
+    if (!reg.signature || !this._adminPubkey) return false;
+    const payload = this.registrationPayload(reg);
+    if (!payload) return false;
+    const pubkey = sovereign ? reg.pubkey : this._adminPubkey;
+    return this.verifyEd25519(payload, reg.signature, pubkey);
+  }
+  async verifyListing(listing) {
+    const verified = this._adminPubkey ? await this.verifyEd25519(this.listingPayload(listing), listing.signature, this._adminPubkey) : false;
+    return { ...listing, verified };
   }
   async enrichListing(listing) {
     let verified = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zcashname-sdk",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "type": "module",
   "description": "TypeScript SDK for the Zcash Name System (ZNS)",
   "main": "dist/zns.cjs",
@@ -14,7 +14,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "scripts": {
     "build": "tsup src/zns.ts --format cjs,esm --dts",