did-beta-bch 0.0.0-stage → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to `cashlet-did` will be documented here.
+
+## [Unreleased]
+
+### Added
+- `buildAnchorTx(bindingId, utxo)` — build an OP_RETURN BCH transaction anchoring a binding to the chain
+- `issueCredential(subjectNpub, type, issuerPrivkey)` — issue a third-party Nostr attestation (kind 30079)
+- `resolveCredentials(npub)` — fetch all credentials issued to an npub from relays
+- `buildDisclosure(attrs)` — commit to a set of attributes with individual SHA-256 hashes
+- `verifyDisclosure(revealed, commitments)` — verify selectively revealed attributes against commitments
+- `resolveAddress(npub)` — one-call pay-by-handle helper; returns BCH address string or null
+- `resolveIdentityChain(npub)` — returns full binding history for an npub, newest first
+- Key rotation support: `previousBindingId` field in `CanonicalBinding`; `["supersedes", id]` tag in published Nostr events
+- `anchor` field in `CanonicalBinding`; `["bch-anchor", txid]` tag in Nostr events
+
+## [0.1.0] — initial extraction
+
+### Added
+- `buildBinding()` — construct a canonical BCH–Nostr identity binding
+- `bchSigningPayload()` — deterministic payload for BCH key to sign
+- `nostrEventTemplate()` — unsigned Nostr event template (kind 30078)
+- `resolveIdentity(npub)` — resolve BCH address from npub via Nostr relays
+- `verifyIdentity(resolved)` — verify BCH + Nostr signatures on a resolved identity
+- `verifyChallengeProof(proof, nonce)` — verify challenge-response authentication proof
+- `publishToRelays()` / `queryRelays()` — minimal NIP-01 relay client
+- `DEFAULT_RELAYS` — nos.lol, relay.damus.io, relay.nostr.band
+- `canonicalize()` / `sha256hex()` — deterministic JSON serialisation utilities

package/README.md

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# cashlet-did
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A standalone, framework-agnostic library implementing the **Cashlet DID protocol** — a decentralised identity layer that binds Bitcoin Cash (BCH) addresses to Nostr public keys.
+
+Any BCH wallet or Nostr client can use this library to publish, resolve, and verify BCH–Nostr identity bindings without depending on the Cashlet extension.
+
+## Install
+
+```sh
+npm install cashlet-did
+```
+
+## Usage
+
+### Pay by handle — one call
+
+```ts
+import { resolveAddress } from 'cashlet-did'
+
+const address = await resolveAddress('npub1...')
+// Returns a token-aware bitcoincash:z... address
+// Works for BCH, CashTokens (FT), and NFTs — no conversion needed
+if (address) wallet.sendTo(address, amount)
+```
+
+### Resolve + verify
+
+const identity = await resolveIdentity('npub1...')
+if (identity) {
+  console.log(identity.bchAddress) // bitcoincash:z...
+  const result = await verifyIdentity(identity)
+  console.log(result.status) // "verified"
+}
+```
+
+### Build and publish a binding (wallet integration)
+
+```ts
+import { buildBinding, bchSigningPayload, nostrEventTemplate, publishToRelays, DEFAULT_RELAYS } from 'cashlet-did'
+import { finalizeEvent } from 'nostr-tools'
+
+const binding = await buildBinding(bchAddress, 'mainnet', nostrPubkeyHex)
+const message = bchSigningPayload(binding)
+
+// Sign message with BCH private key (recoverable compact sig)
+const bchSig = signWithBchKey(message) // your wallet's signing function
+
+const template = nostrEventTemplate(binding, { message, signature: bchSig })
+const event = finalizeEvent(template, nostrPrivkey)
+await publishToRelays(DEFAULT_RELAYS, event)
+```
+
+### Verify a challenge-response proof
+
+```ts
+import { verifyChallengeProof } from 'cashlet-did'
+
+const valid = verifyChallengeProof(
+  { signature, payload, address },
+  nonce
+)
+```
+
+## Protocol
+
+Bindings are published as Nostr events of kind `30078` with the following tags:
+
+| Tag | Value |
+|---|---|
+| `d` | binding ID (SHA-256 of canonical binding JSON) |
+| `bch` | BCH address, network |
+| `bch-proof` | signing payload, recoverable compact signature |
+| `protocol` | `cashlet-did`, version |
+| `t` | `cashlet-did` |
+
+The BCH signature uses Bitcoin signed message format (`\x18Bitcoin Signed Message:\n`) with a 65-byte recoverable compact signature (recovery ID byte + 64-byte compact sig).
+
+## Relays
+
+Default relays: `wss://nos.lol`, `wss://relay.damus.io`, `wss://relay.nostr.band`
+
+Pass a custom relay list to any function that accepts `relays?: string[]`.
+
+## License
+
+MIT

package/dist/anchor.d.ts

@@ -0,0 +1,18 @@
+/**
+ * BCH on-chain identity commitment via OP_RETURN.
+ * Anchors a bindingId to a BCH block, providing a tamper-evident timestamp.
+ */
+export declare const ANCHOR_PREFIX = "cashlet-did:";
+export interface AnchorUtxo {
+    txid: string;
+    vout: number;
+    valueSats: number;
+    lockingBytecode: Uint8Array;
+    privateKey: Uint8Array;
+}
+export interface AnchorResult {
+    txHex: string;
+    opReturnData: string;
+}
+/** Build an OP_RETURN tx anchoring a bindingId to the BCH chain */
+export declare function buildAnchorTx(bindingId: string, utxo: AnchorUtxo): Promise<AnchorResult>;

package/dist/anchor.js

@@ -0,0 +1,47 @@
+/**
+ * BCH on-chain identity commitment via OP_RETURN.
+ * Anchors a bindingId to a BCH block, providing a tamper-evident timestamp.
+ */
+export const ANCHOR_PREFIX = "cashlet-did:";
+const OP_RETURN = 0x6a;
+const DUST_SATS = 1000; // anchor output value (burned)
+const FEE_SATS = 500;
+/** Build an OP_RETURN tx anchoring a bindingId to the BCH chain */
+export async function buildAnchorTx(bindingId, utxo) {
+    const { encodeTransaction, generateTransaction, hexToBin, binToHex, walletTemplateP2pkhNonHd, importWalletTemplate, walletTemplateToCompilerBch } = await import("@bitauth/libauth");
+    const data = ANCHOR_PREFIX + bindingId;
+    const dataBytes = new TextEncoder().encode(data);
+    // OP_RETURN <push> <data>
+    const opReturnScript = new Uint8Array([OP_RETURN, dataBytes.length, ...dataBytes]);
+    const template = importWalletTemplate(walletTemplateP2pkhNonHd);
+    if (typeof template === "string")
+        throw new Error(template);
+    const compiler = walletTemplateToCompilerBch(template);
+    const result = generateTransaction({
+        inputs: [{
+                outpointTransactionHash: hexToBin(utxo.txid).reverse(),
+                outpointIndex: utxo.vout,
+                sequenceNumber: 0xffffffff,
+                unlockingBytecode: {
+                    compiler,
+                    data: { keys: { privateKeys: { key: utxo.privateKey } } },
+                    valueSatoshis: BigInt(utxo.valueSats),
+                    script: "unlock",
+                    token: undefined,
+                },
+            }],
+        locktime: 0,
+        outputs: [
+            { lockingBytecode: opReturnScript, valueSatoshis: 0n },
+            // change back to sender minus fee
+            {
+                lockingBytecode: utxo.lockingBytecode,
+                valueSatoshis: BigInt(utxo.valueSats - FEE_SATS),
+            },
+        ],
+        version: 2,
+    });
+    if (!result.success)
+        throw new Error("Failed to build anchor tx: " + JSON.stringify(result.errors));
+    return { txHex: binToHex(encodeTransaction(result.transaction)), opReturnData: data };
+}

package/dist/binding.d.ts

@@ -0,0 +1,59 @@
+export declare const PROTOCOL_ID = "cashlet-did";
+export declare const PROTOCOL_VERSION = "1.0.0";
+export declare const BINDING_KIND = 30078;
+export type Network = "mainnet" | "testnet" | "chipnet";
+export interface CanonicalBinding {
+    protocol: typeof PROTOCOL_ID;
+    version: typeof PROTOCOL_VERSION;
+    bindingId: string;
+    bch: {
+        address: string;
+        network: Network;
+        paymentCode?: string;
+    };
+    nostr: {
+        pubkey: string;
+    };
+    createdAt: number;
+    nonce: string;
+    purpose: "identity-binding-v1";
+    previousBindingId?: string;
+    anchor?: {
+        txid: string;
+        blockHeight?: number;
+    };
+}
+export interface IdentityBinding {
+    binding: CanonicalBinding;
+    bchProof: {
+        message: string;
+        signature: string;
+        pubkeyHex?: string;
+    };
+    nostrProof: {
+        event: NostrEvent;
+    };
+    publishedAt?: number;
+}
+export interface NostrEvent {
+    id: string;
+    pubkey: string;
+    created_at: number;
+    kind: number;
+    tags: string[][];
+    content: string;
+    sig: string;
+}
+export declare function canonicalize(v: unknown): string;
+export declare function sha256hex(s: string): Promise<string>;
+export declare function buildBinding(bchAddress: string, network: Network, nostrPubkey: string, paymentCode?: string, previousBindingId?: string): Promise<CanonicalBinding>;
+export declare function bchSigningPayload(binding: CanonicalBinding): string;
+export declare function nostrEventTemplate(binding: CanonicalBinding, bchProof?: {
+    message: string;
+    signature: string;
+}): {
+    kind: number;
+    created_at: number;
+    tags: string[][];
+    content: string;
+};

package/dist/binding.js

@@ -0,0 +1,71 @@
+export const PROTOCOL_ID = "cashlet-did";
+export const PROTOCOL_VERSION = "1.0.0";
+export const BINDING_KIND = 30078;
+export function canonicalize(v) {
+    if (v === null || typeof v !== "object")
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return "[" + v.map(canonicalize).join(",") + "]";
+    const obj = v;
+    const keys = Object.keys(obj).sort();
+    return "{" + keys.filter(k => obj[k] !== undefined)
+        .map(k => JSON.stringify(k) + ":" + canonicalize(obj[k])).join(",") + "}";
+}
+export async function sha256hex(s) {
+    const buf = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(s));
+    return Array.from(new Uint8Array(buf)).map(b => b.toString(16).padStart(2, "0")).join("");
+}
+function randomHex(bytes) {
+    const arr = new Uint8Array(bytes);
+    crypto.getRandomValues(arr);
+    return Array.from(arr).map(b => b.toString(16).padStart(2, "0")).join("");
+}
+export async function buildBinding(bchAddress, network, nostrPubkey, paymentCode, previousBindingId) {
+    const partial = {
+        protocol: PROTOCOL_ID,
+        version: PROTOCOL_VERSION,
+        bch: { address: bchAddress, network, ...(paymentCode ? { paymentCode } : {}) },
+        nostr: { pubkey: nostrPubkey },
+        createdAt: Math.floor(Date.now() / 1000),
+        nonce: randomHex(32),
+        purpose: "identity-binding-v1",
+        ...(previousBindingId ? { previousBindingId } : {}),
+    };
+    const bindingId = await sha256hex(canonicalize(partial));
+    return { ...partial, bindingId };
+}
+export function bchSigningPayload(binding) {
+    return `${PROTOCOL_ID}/bch-proof/v${PROTOCOL_VERSION}\n` + canonicalize({
+        bindingId: binding.bindingId,
+        bchAddress: binding.bch.address,
+        bchNetwork: binding.bch.network,
+        nostrPubkey: binding.nostr.pubkey,
+        nonce: binding.nonce,
+        purpose: binding.purpose,
+        createdAt: binding.createdAt,
+    });
+}
+export function nostrEventTemplate(binding, bchProof) {
+    return {
+        kind: BINDING_KIND,
+        created_at: Math.floor(Date.now() / 1000),
+        tags: [
+            ["d", binding.bindingId],
+            ["bch", binding.bch.address, binding.bch.network],
+            ["protocol", PROTOCOL_ID, PROTOCOL_VERSION],
+            ["t", PROTOCOL_ID],
+            ...(binding.previousBindingId ? [["supersedes", binding.previousBindingId]] : []),
+            ...(binding.anchor ? [["bch-anchor", binding.anchor.txid, ...(binding.anchor.blockHeight ? [String(binding.anchor.blockHeight)] : [])]] : []),
+            ...(bchProof ? [["bch-proof", bchProof.message, bchProof.signature]] : []),
+        ],
+        content: canonicalize({
+            protocol: PROTOCOL_ID,
+            version: PROTOCOL_VERSION,
+            bindingId: binding.bindingId,
+            bch: binding.bch,
+            nonce: binding.nonce,
+            createdAt: binding.createdAt,
+            ...(binding.previousBindingId ? { previousBindingId: binding.previousBindingId } : {}),
+        }),
+    };
+}

package/dist/credentials.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Verifiable Credentials — third-party attestations anchored to a Nostr identity.
+ * Issuer signs a Nostr event (kind 30079) attesting a claim about a subject npub.
+ * Subject's binding event links to received credentials via ["credential", eventId, issuerPubkey, type] tag.
+ */
+import type { RelayResult } from "./relay.js";
+export declare const CREDENTIAL_KIND = 30079;
+export interface CredentialPayload {
+    subject: string;
+    type: string;
+    issuedAt: number;
+    expiry?: number;
+    claims?: Record<string, string>;
+}
+export interface IssuedCredential {
+    id: string;
+    issuer: string;
+    payload: CredentialPayload;
+    rawEvent: object;
+}
+/** Issue a credential — issuer signs a Nostr event attesting a claim about subjectNpub */
+export declare function issueCredential(subjectNpub: string, type: string, issuerPrivkey: Uint8Array, claims?: Record<string, string>, relays?: string[]): Promise<{
+    credential: IssuedCredential;
+    results: RelayResult[];
+}>;
+/** Resolve all credentials issued to an npub */
+export declare function resolveCredentials(npub: string, relays?: string[]): Promise<IssuedCredential[]>;

package/dist/credentials.js

@@ -0,0 +1,61 @@
+/**
+ * Verifiable Credentials — third-party attestations anchored to a Nostr identity.
+ * Issuer signs a Nostr event (kind 30079) attesting a claim about a subject npub.
+ * Subject's binding event links to received credentials via ["credential", eventId, issuerPubkey, type] tag.
+ */
+import { finalizeEvent, nip19 } from "nostr-tools";
+import { queryRelays, publishToRelays, DEFAULT_RELAYS } from "./relay.js";
+export const CREDENTIAL_KIND = 30079;
+/** Issue a credential — issuer signs a Nostr event attesting a claim about subjectNpub */
+export async function issueCredential(subjectNpub, type, issuerPrivkey, claims, relays = DEFAULT_RELAYS) {
+    const decoded = nip19.decode(subjectNpub);
+    if (decoded.type !== "npub")
+        throw new Error("Invalid npub");
+    const subjectPubkey = decoded.data;
+    const payload = {
+        subject: subjectPubkey,
+        type,
+        issuedAt: Math.floor(Date.now() / 1000),
+        ...(claims ? { claims } : {}),
+    };
+    const template = {
+        kind: CREDENTIAL_KIND,
+        created_at: payload.issuedAt,
+        tags: [
+            ["p", subjectPubkey],
+            ["credential-type", type],
+            ["t", "cashlet-did-credential"],
+        ],
+        content: JSON.stringify(payload),
+    };
+    const signed = finalizeEvent(template, issuerPrivkey);
+    const results = await publishToRelays(relays, signed);
+    const { getPublicKey } = await import("nostr-tools");
+    const issuerPubkey = getPublicKey(issuerPrivkey);
+    return {
+        credential: { id: signed.id, issuer: issuerPubkey, payload, rawEvent: signed },
+        results,
+    };
+}
+/** Resolve all credentials issued to an npub */
+export async function resolveCredentials(npub, relays = DEFAULT_RELAYS) {
+    const decoded = nip19.decode(npub);
+    if (decoded.type !== "npub")
+        return [];
+    const pubkey = decoded.data;
+    const events = await queryRelays(relays, {
+        kinds: [CREDENTIAL_KIND],
+        "#p": [pubkey],
+        "#t": ["cashlet-did-credential"],
+        limit: 50,
+    });
+    return events.map(e => {
+        try {
+            const payload = JSON.parse(e.content);
+            return { id: e.id, issuer: e.pubkey, payload, rawEvent: e };
+        }
+        catch {
+            return null;
+        }
+    }).filter(Boolean);
+}

package/dist/disclosure.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Selective disclosure of identity attributes.
+ * Each attribute is individually hashed — the holder commits to all attributes
+ * in the binding event, then reveals only chosen ones to a verifier.
+ *
+ * Usage:
+ *   const d = await buildDisclosure({ merchant: "true", country: "AU" })
+ *   // store d.commitments in binding event tags
+ *   const revealed = d.reveal(["merchant"])
+ *   // verifier calls verifyDisclosure(revealed, commitments)
+ */
+export interface Disclosure {
+    /** SHA-256 hashes of each attribute — publish these in the binding event */
+    commitments: Record<string, string>;
+    /** Reveal selected attribute values — share with verifier */
+    reveal: (keys: string[]) => Record<string, string>;
+}
+/** Build a disclosure object from a set of attributes */
+export declare function buildDisclosure(attrs: Record<string, string>): Promise<Disclosure>;
+/**
+ * Verify that revealed attributes match their published commitments.
+ * Returns the set of verified attribute keys.
+ */
+export declare function verifyDisclosure(revealed: Record<string, string>, commitments: Record<string, string>): Promise<{
+    verified: string[];
+    failed: string[];
+}>;

package/dist/disclosure.js

@@ -0,0 +1,45 @@
+/**
+ * Selective disclosure of identity attributes.
+ * Each attribute is individually hashed — the holder commits to all attributes
+ * in the binding event, then reveals only chosen ones to a verifier.
+ *
+ * Usage:
+ *   const d = await buildDisclosure({ merchant: "true", country: "AU" })
+ *   // store d.commitments in binding event tags
+ *   const revealed = d.reveal(["merchant"])
+ *   // verifier calls verifyDisclosure(revealed, commitments)
+ */
+async function hashAttr(key, value) {
+    const data = new TextEncoder().encode(`cashlet-did/attr/${key}:${value}`);
+    const buf = await crypto.subtle.digest("SHA-256", data);
+    return Array.from(new Uint8Array(buf)).map(b => b.toString(16).padStart(2, "0")).join("");
+}
+/** Build a disclosure object from a set of attributes */
+export async function buildDisclosure(attrs) {
+    const commitments = {};
+    for (const [k, v] of Object.entries(attrs)) {
+        commitments[k] = await hashAttr(k, v);
+    }
+    return {
+        commitments,
+        reveal: (keys) => Object.fromEntries(keys.filter(k => k in attrs).map(k => [k, attrs[k]])),
+    };
+}
+/**
+ * Verify that revealed attributes match their published commitments.
+ * Returns the set of verified attribute keys.
+ */
+export async function verifyDisclosure(revealed, commitments) {
+    const verified = [];
+    const failed = [];
+    for (const [k, v] of Object.entries(revealed)) {
+        const expected = commitments[k];
+        if (!expected) {
+            failed.push(k);
+            continue;
+        }
+        const actual = await hashAttr(k, v);
+        (actual === expected ? verified : failed).push(k);
+    }
+    return { verified, failed };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { buildDisclosure, verifyDisclosure, type Disclosure, } from "./disclosure.js";
+export { buildAnchorTx, ANCHOR_PREFIX, type AnchorUtxo, type AnchorResult, } from "./anchor.js";
+export { issueCredential, resolveCredentials, CREDENTIAL_KIND, type CredentialPayload, type IssuedCredential, } from "./credentials.js";
+export { PROTOCOL_ID, PROTOCOL_VERSION, BINDING_KIND, type Network, type CanonicalBinding, type IdentityBinding, type NostrEvent, buildBinding, bchSigningPayload, nostrEventTemplate, canonicalize, sha256hex, } from "./binding.js";
+export { publishToRelay, publishToRelays, queryRelay, queryRelays, DEFAULT_RELAYS, type RelayResult, } from "./relay.js";
+export { resolveIdentity, resolveAddress, verifyIdentity, verifyChallengeProof, resolveIdentityChain, type VerifyResult, type VerifyStatus, type ResolvedIdentity, } from "./verify.js";

package/dist/index.js

@@ -0,0 +1,14 @@
+export { buildDisclosure, verifyDisclosure, } from "./disclosure.js";
+export { buildAnchorTx, ANCHOR_PREFIX, } from "./anchor.js";
+export { issueCredential, resolveCredentials, CREDENTIAL_KIND, } from "./credentials.js";
+export { 
+// Protocol constants
+PROTOCOL_ID, PROTOCOL_VERSION, BINDING_KIND, 
+// Binding construction
+buildBinding, bchSigningPayload, nostrEventTemplate, canonicalize, sha256hex, } from "./binding.js";
+export { 
+// Relay communication
+publishToRelay, publishToRelays, queryRelay, queryRelays, DEFAULT_RELAYS, } from "./relay.js";
+export { 
+// Verification
+resolveIdentity, resolveAddress, verifyIdentity, verifyChallengeProof, resolveIdentityChain, } from "./verify.js";

package/dist/relay.d.ts

@@ -0,0 +1,11 @@
+import type { NostrEvent } from "./binding.js";
+export interface RelayResult {
+    relay: string;
+    ok: boolean;
+    error?: string;
+}
+export declare function publishToRelay(url: string, event: NostrEvent): Promise<RelayResult>;
+export declare function publishToRelays(relays: string[], event: NostrEvent): Promise<RelayResult[]>;
+export declare function queryRelay(url: string, filter: Record<string, unknown>): Promise<NostrEvent[]>;
+export declare function queryRelays(relays: string[], filter: Record<string, unknown>): Promise<NostrEvent[]>;
+export declare const DEFAULT_RELAYS: string[];

package/dist/relay.js

@@ -0,0 +1,76 @@
+const TIMEOUT_MS = 8000;
+function openRelay(url) {
+    return new Promise((resolve, reject) => {
+        const ws = new WebSocket(url);
+        const t = setTimeout(() => { ws.close(); reject(new Error("connect timeout")); }, TIMEOUT_MS);
+        ws.onopen = () => { clearTimeout(t); resolve(ws); };
+        ws.onerror = () => { clearTimeout(t); reject(new Error("connect error")); };
+    });
+}
+export async function publishToRelay(url, event) {
+    try {
+        const ws = await openRelay(url);
+        return await new Promise((resolve) => {
+            const t = setTimeout(() => { ws.close(); resolve({ relay: url, ok: false, error: "publish timeout" }); }, TIMEOUT_MS);
+            ws.onmessage = (e) => {
+                clearTimeout(t);
+                ws.close();
+                try {
+                    const msg = JSON.parse(e.data);
+                    if (msg[0] === "OK" && msg[1] === event.id)
+                        resolve({ relay: url, ok: msg[2] === true, error: msg[3] || undefined });
+                    else
+                        resolve({ relay: url, ok: false, error: "unexpected response" });
+                }
+                catch {
+                    resolve({ relay: url, ok: false, error: "parse error" });
+                }
+            };
+            ws.send(JSON.stringify(["EVENT", event]));
+        });
+    }
+    catch (e) {
+        return { relay: url, ok: false, error: String(e) };
+    }
+}
+export async function publishToRelays(relays, event) {
+    return Promise.all(relays.map(r => publishToRelay(r, event)));
+}
+export async function queryRelay(url, filter) {
+    try {
+        const ws = await openRelay(url);
+        return await new Promise((resolve) => {
+            const events = [];
+            const subId = Math.random().toString(36).slice(2);
+            const t = setTimeout(() => { ws.close(); resolve(events); }, TIMEOUT_MS);
+            ws.onmessage = (e) => {
+                try {
+                    const msg = JSON.parse(e.data);
+                    if (msg[0] === "EVENT" && msg[1] === subId)
+                        events.push(msg[2]);
+                    if (msg[0] === "EOSE" && msg[1] === subId) {
+                        clearTimeout(t);
+                        ws.close();
+                        resolve(events);
+                    }
+                }
+                catch { /* ignore */ }
+            };
+            ws.send(JSON.stringify(["REQ", subId, filter]));
+        });
+    }
+    catch {
+        return [];
+    }
+}
+export async function queryRelays(relays, filter) {
+    const results = await Promise.all(relays.map(r => queryRelay(r, filter)));
+    const seen = new Set();
+    return results.flat().filter(e => { if (seen.has(e.id))
+        return false; seen.add(e.id); return true; });
+}
+export const DEFAULT_RELAYS = [
+    "wss://nos.lol",
+    "wss://relay.damus.io",
+    "wss://relay.nostr.band",
+];

package/dist/verify.d.ts

@@ -0,0 +1,40 @@
+import { canonicalize, sha256hex, bchSigningPayload, type CanonicalBinding, type IdentityBinding, type NostrEvent } from "./binding.js";
+export type VerifyStatus = "verified" | "invalid_bch_sig" | "invalid_nostr_sig" | "id_mismatch" | "malformed";
+export interface VerifyResult {
+    status: VerifyStatus;
+    bchValid: boolean;
+    nostrValid: boolean;
+    details: string;
+}
+export interface ResolvedIdentity {
+    npub: string;
+    pubkey: string;
+    bchAddress: string;
+    network: string;
+    bindingId: string;
+    createdAt: number;
+    bchProofTag: string[];
+    rawEvent: NostrEvent;
+}
+/** Resolve a BCH address from an npub via Nostr relays */
+export declare function resolveIdentity(npub: string, relays?: string[]): Promise<ResolvedIdentity | null>;
+/** Verify the BCH + Nostr signatures on a resolved identity */
+export declare function verifyIdentity(resolved: ResolvedIdentity): Promise<VerifyResult>;
+/** Verify a challenge-response proof */
+export declare function verifyChallengeProof(proof: {
+    signature: string;
+    payload: string;
+    address: string;
+}, nonce: string): boolean;
+/**
+ * Resolve a BCH address from an npub — the primary pay-by-handle entry point.
+ * Returns the verified BCH address string, or null if not found.
+ *
+ * @example
+ * const address = await resolveAddress('npub1...')
+ * if (address) wallet.sendTo(address, amount)
+ */
+export declare function resolveAddress(npub: string, relays?: string[]): Promise<string | null>;
+/** Returns full binding history for an npub, newest first */
+export declare function resolveIdentityChain(npub: string, relays?: string[]): Promise<ResolvedIdentity[]>;
+export { bchSigningPayload, canonicalize, sha256hex, type CanonicalBinding, type IdentityBinding };

package/dist/verify.js

@@ -0,0 +1,164 @@
+import { verifyEvent } from "nostr-tools";
+import { secp256k1, hash256, encodeCashAddress, hash160 } from "@bitauth/libauth";
+import { canonicalize, sha256hex, bchSigningPayload, BINDING_KIND, PROTOCOL_ID, } from "./binding.js";
+import { queryRelays, DEFAULT_RELAYS } from "./relay.js";
+import { nip19 } from "nostr-tools";
+function bitcoinMsgHash(message) {
+    const enc = new TextEncoder();
+    const msgBytes = enc.encode(message);
+    const prefix = enc.encode("\x18Bitcoin Signed Message:\n");
+    const lenByte = new Uint8Array([msgBytes.length]);
+    return hash256(new Uint8Array([...prefix, ...lenByte, ...msgBytes]));
+}
+function recoverBchAddress(sigHex, msgHash, expectedAddress) {
+    const sig = Uint8Array.from(sigHex.match(/.{2}/g).map(b => parseInt(b, 16)));
+    const tryRecover = (compact, id) => {
+        try {
+            const pub = secp256k1.recoverPublicKeyCompressed(compact, id, msgHash);
+            if (!(pub instanceof Uint8Array))
+                return null;
+            const addrPrefix = (expectedAddress?.split(":")[0] ?? "bitcoincash");
+            for (const type of ["p2pkhWithTokens", "p2pkh"]) {
+                const r = encodeCashAddress({ prefix: addrPrefix, type, payload: hash160(pub) });
+                if (r?.address)
+                    return r.address;
+                if (typeof r === "string")
+                    return r;
+            }
+        }
+        catch { /* try next */ }
+        return null;
+    };
+    if (sig.length === 65) {
+        const recoveryId = (sig[0] & 0x03);
+        const addr = tryRecover(sig.slice(1), recoveryId);
+        if (addr)
+            return addr;
+    }
+    for (const id of [0, 1, 2, 3]) {
+        const addr = tryRecover(sig, id);
+        if (addr)
+            return addr;
+    }
+    return null;
+}
+/** Resolve a BCH address from an npub via Nostr relays */
+export async function resolveIdentity(npub, relays = DEFAULT_RELAYS) {
+    const decoded = nip19.decode(npub);
+    if (decoded.type !== "npub")
+        return null;
+    const pubkey = decoded.data;
+    const events = await queryRelays(relays, {
+        kinds: [BINDING_KIND],
+        authors: [pubkey],
+        "#t": [PROTOCOL_ID],
+        limit: 10,
+    });
+    if (!events.length)
+        return null;
+    // Pick latest
+    const event = events.sort((a, b) => b.created_at - a.created_at)[0];
+    const bchTag = event.tags.find(t => t[0] === "bch");
+    const dTag = event.tags.find(t => t[0] === "d");
+    const bchProofTag = event.tags.find(t => t[0] === "bch-proof");
+    if (!bchTag || !dTag || !bchProofTag)
+        return null;
+    let createdAt = event.created_at;
+    try {
+        createdAt = JSON.parse(event.content).createdAt ?? createdAt;
+    }
+    catch { /* use event ts */ }
+    return {
+        npub,
+        pubkey,
+        bchAddress: bchTag[1],
+        network: bchTag[2] ?? "mainnet",
+        bindingId: dTag[1],
+        createdAt,
+        bchProofTag,
+        rawEvent: event,
+    };
+}
+/** Verify the BCH + Nostr signatures on a resolved identity */
+export async function verifyIdentity(resolved) {
+    const { bchProofTag, rawEvent, bchAddress, bindingId, pubkey } = resolved;
+    const [, message, sigHex] = bchProofTag;
+    // 1. Nostr event signature
+    let nostrValid = false;
+    try {
+        nostrValid = verifyEvent(rawEvent);
+        const dTag = rawEvent.tags.find(t => t[0] === "d");
+        const bchTag = rawEvent.tags.find(t => t[0] === "bch");
+        if (dTag?.[1] !== bindingId || bchTag?.[1] !== bchAddress)
+            nostrValid = false;
+        if (rawEvent.pubkey !== pubkey)
+            nostrValid = false;
+    }
+    catch {
+        nostrValid = false;
+    }
+    // 2. BCH signature recovery
+    const msgHash = bitcoinMsgHash(message);
+    const recovered = recoverBchAddress(sigHex, msgHash, bchAddress);
+    const bchValid = recovered === bchAddress;
+    // 3. Payload integrity
+    if (!message.startsWith(`${PROTOCOL_ID}/bch-proof/`)) {
+        return { status: "malformed", bchValid: false, nostrValid, details: "Unexpected proof payload format" };
+    }
+    if (bchValid && nostrValid)
+        return { status: "verified", bchValid, nostrValid, details: "Both proofs valid" };
+    if (!bchValid)
+        return { status: "invalid_bch_sig", bchValid, nostrValid, details: "BCH signature invalid" };
+    return { status: "invalid_nostr_sig", bchValid, nostrValid, details: "Nostr signature invalid" };
+}
+/** Verify a challenge-response proof */
+export function verifyChallengeProof(proof, nonce) {
+    if (!proof.payload.includes(nonce))
+        return false;
+    if (!proof.payload.startsWith(`${PROTOCOL_ID}/challenge`))
+        return false;
+    const msgHash = bitcoinMsgHash(proof.payload);
+    const recovered = recoverBchAddress(proof.signature, msgHash, proof.address);
+    return recovered === proof.address;
+}
+/**
+ * Resolve a BCH address from an npub — the primary pay-by-handle entry point.
+ * Returns the verified BCH address string, or null if not found.
+ *
+ * @example
+ * const address = await resolveAddress('npub1...')
+ * if (address) wallet.sendTo(address, amount)
+ */
+export async function resolveAddress(npub, relays = DEFAULT_RELAYS) {
+    const identity = await resolveIdentity(npub, relays);
+    return identity?.bchAddress ?? null;
+}
+/** Returns full binding history for an npub, newest first */
+export async function resolveIdentityChain(npub, relays = DEFAULT_RELAYS) {
+    const decoded = nip19.decode(npub);
+    if (decoded.type !== "npub")
+        return [];
+    const pubkey = decoded.data;
+    const events = await queryRelays(relays, {
+        kinds: [BINDING_KIND],
+        authors: [pubkey],
+        "#t": [PROTOCOL_ID],
+        limit: 50,
+    });
+    const results = [];
+    for (const event of events.sort((a, b) => b.created_at - a.created_at)) {
+        const bchTag = event.tags.find(t => t[0] === "bch");
+        const dTag = event.tags.find(t => t[0] === "d");
+        const bchProofTag = event.tags.find(t => t[0] === "bch-proof");
+        if (!bchTag || !dTag || !bchProofTag)
+            continue;
+        let createdAt = event.created_at;
+        try {
+            createdAt = JSON.parse(event.content).createdAt ?? createdAt;
+        }
+        catch { /* use event ts */ }
+        results.push({ npub, pubkey, bchAddress: bchTag[1], network: bchTag[2] ?? "mainnet", bindingId: dTag[1], createdAt, bchProofTag, rawEvent: event });
+    }
+    return results;
+}
+export { bchSigningPayload, canonicalize, sha256hex };

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "did-beta-bch",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Decentralised identity protocol binding BCH addresses to Nostr public keys",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist", "README.md", "CHANGELOG.md"],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["bch", "bitcoin-cash", "nostr", "did", "decentralised-identity", "cashaddr", "nip-06", "nip-07"],
+  "author": "",
+  "license": "MIT",
+  "engines": { "node": ">=18" },
+  "dependencies": {
+    "@bitauth/libauth": "^3.1.0-next.8",
+    "nostr-tools": "^2.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  }
+}