did-beta-bch 2.0.1 → 3.1.0

package/dist/anchor-client.js

@@ -0,0 +1,107 @@
+/**
+ * Electrum client helpers for broadcasting anchor transactions and fetching
+ * SPV proofs. Works in Node.js (TCP) and browsers (WebSocket) via a pluggable
+ * transport. Default transports are provided for each environment.
+ */
+export const ELECTRUM_MAINNET_TCP = "electroncash.dk:50001";
+export const ELECTRUM_MAINNET_WS = "wss://electroncash.dk:50004";
+export const ELECTRUM_CHIPNET_TCP = "chipnet.imaginary.cash:50001";
+export const ELECTRUM_CHIPNET_WS = "wss://chipnet.imaginary.cash:50004";
+async function electrumCall(transport, requests, timeoutMs = 15000) {
+    const results = new Map();
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { transport.close(); reject(new Error("Electrum request timed out")); }, timeoutMs);
+        transport.onError(e => { clearTimeout(timer); reject(e); });
+        transport.onLine(line => {
+            if (!line.trim())
+                return;
+            const msg = JSON.parse(line);
+            if (msg.error) {
+                clearTimeout(timer);
+                transport.close();
+                reject(new Error(msg.error.message));
+                return;
+            }
+            results.set(msg.id, msg.result);
+            if (results.size === requests.length) {
+                clearTimeout(timer);
+                transport.close();
+                resolve(results);
+            }
+        });
+        for (const req of requests)
+            transport.send(JSON.stringify(req) + "\n");
+    });
+}
+/** WebSocket transport — works in both browser and Node.js (Node 22+ has native WebSocket). */
+export function wsTransport(url) {
+    const ws = new WebSocket(url, "binary");
+    let lineHandler = null;
+    let errHandler = null;
+    let buf = "";
+    ws.onmessage = (ev) => {
+        buf += typeof ev.data === "string" ? ev.data : new TextDecoder().decode(ev.data);
+        const lines = buf.split("\n");
+        buf = lines.pop() ?? "";
+        for (const l of lines)
+            lineHandler?.(l);
+    };
+    ws.onerror = () => errHandler?.(new Error("WebSocket error"));
+    return {
+        send: (line) => ws.readyState === WebSocket.OPEN ? ws.send(line) : ws.addEventListener("open", () => ws.send(line)),
+        onLine: (h) => { lineHandler = h; },
+        onError: (h) => { errHandler = h; },
+        close: () => ws.close(),
+    };
+}
+/**
+ * Broadcast a signed anchor transaction hex to an Electrum server.
+ * Returns the txid on success.
+ */
+export async function broadcastAnchorTx(txHex, transport) {
+    const results = await electrumCall(transport, [
+        { id: 1, method: "blockchain.transaction.broadcast", params: [txHex] },
+    ]);
+    const txid = results.get(1);
+    if (typeof txid !== "string" || !/^[0-9a-f]{64}$/.test(txid))
+        throw new Error(`Unexpected broadcast response: ${JSON.stringify(txid)}`);
+    return txid;
+}
+/**
+ * Fetch a BchAnchorProof for a confirmed transaction.
+ * checkpointHeight must match the checkpoint you intend to verify against —
+ * headers are fetched from checkpointHeight+1 through the confirmation window.
+ */
+export async function fetchAnchorProof(txid, checkpointHeight, transport, minConfirmations = 6) {
+    if (!/^[0-9a-f]{64}$/.test(txid))
+        throw new Error("Invalid txid");
+    // Step 1: get Merkle proof to learn blockHeight and tx position
+    const merkleResults = await electrumCall(transport, [
+        { id: 1, method: "blockchain.transaction.get_merkle", params: [txid, 0] },
+    ]);
+    const merkle = merkleResults.get(1);
+    if (!merkle?.block_height)
+        throw new Error("Transaction not yet confirmed or not found");
+    const blockHeight = merkle.block_height;
+    const tipHeight = blockHeight + minConfirmations - 1;
+    const startHeight = checkpointHeight + 1;
+    const count = tipHeight - startHeight + 1;
+    if (count <= 0)
+        throw new Error("Block is at or below the checkpoint height");
+    // Step 2: fetch raw tx hex + header range
+    const batchResults = await electrumCall(transport, [
+        { id: 2, method: "blockchain.transaction.get", params: [txid, false] },
+        { id: 3, method: "blockchain.block.headers", params: [startHeight, count] },
+    ]);
+    const transactionHex = batchResults.get(2);
+    const headersResult = batchResults.get(3);
+    if (typeof transactionHex !== "string")
+        throw new Error("Failed to fetch transaction hex");
+    if (!headersResult?.hex)
+        throw new Error("Failed to fetch header chain");
+    // Split concatenated 80-byte headers (160 hex chars each)
+    const headers = [];
+    for (let i = 0; i < headersResult.count; i++)
+        headers.push(headersResult.hex.slice(i * 160, i * 160 + 160));
+    return { transactionHex, blockHeight, transactionIndex: merkle.pos, merkleBranch: merkle.merkle, headers };
+}

package/dist/anchor-verification.d.ts

@@ -0,0 +1,46 @@
+export interface BchSpvCheckpoint {
+    height: number;
+    headerHex: string;
+    hash: string;
+    recentTimestamps: number[];
+}
+export interface BchAsertParameters {
+    anchorHeight: number;
+    anchorBits: number;
+    anchorPreviousBlockTime: number;
+    powLimitBits: number;
+    allowMinDifficultyBlocks?: boolean;
+}
+export interface BchAnchorProof {
+    transactionHex: string;
+    blockHeight: number;
+    transactionIndex: number;
+    merkleBranch: string[];
+    headers: string[];
+}
+export interface BchAnchorVerificationOptions {
+    checkpoint: BchSpvCheckpoint;
+    asert: BchAsertParameters;
+    minConfirmations?: number;
+    maxHeaders?: number;
+    now?: number;
+}
+export interface BchAnchorVerificationResult {
+    status: "confirmed" | "pending" | "invalid" | "unverifiable";
+    txid?: string;
+    blockHeight?: number;
+    tipHeight?: number;
+    confirmations?: number;
+    error?: string;
+    trustModel: "checkpointed-spv";
+}
+/**
+ * Verify a BCH transaction commitment, Merkle inclusion, and an ASERT header
+ * chain extending from an application-trusted checkpoint. The proof source is
+ * untrusted; checkpoint selection remains the caller's explicit trust root.
+ */
+export declare function verifyBchAnchorProof(proof: BchAnchorProof, bindingId: string, options: BchAnchorVerificationOptions): BchAnchorVerificationResult;
+export declare const BCH_MAINNET_ASERT_PARAMETERS: BchAsertParameters;
+export declare const BCH_MAINNET_CHECKPOINT: BchSpvCheckpoint;
+export declare const BCH_CHIPNET_ASERT_PARAMETERS: BchAsertParameters;
+export declare const BCH_CHIPNET_CHECKPOINT: BchSpvCheckpoint;

package/dist/anchor-verification.js

@@ -0,0 +1,282 @@
+import { decodeTransaction, hash256, hexToBin } from "@bitauth/libauth";
+import { ANCHOR_PREFIX } from "./anchor.js";
+const HEADER_BYTES = 80;
+const MAX_PROOF_HEADERS = 2048;
+const TARGET_SPACING_SECS = 600n;
+const ASERT_HALF_LIFE_SECS = 172800n;
+const ASERT_RADIX = 1n << 16n;
+function bytesToHex(bytes) {
+    return Array.from(bytes, byte => byte.toString(16).padStart(2, "0")).join("");
+}
+function reverse(bytes) {
+    return Uint8Array.from(bytes).reverse();
+}
+function parseHex(value, byteLength) {
+    if (!/^(?:[0-9a-f]{2})+$/i.test(value))
+        throw new Error("Expected even-length hexadecimal data");
+    const bytes = hexToBin(value);
+    if (typeof bytes === "string" || (byteLength !== undefined && bytes.length !== byteLength))
+        throw new Error("Invalid hexadecimal data length");
+    return bytes;
+}
+function parseHeader(headerHex) {
+    const raw = parseHex(headerHex, HEADER_BYTES);
+    const hash = hash256(raw);
+    const view = new DataView(raw.buffer, raw.byteOffset, raw.byteLength);
+    return {
+        raw,
+        hash,
+        hashHex: bytesToHex(reverse(hash)),
+        previousHash: raw.slice(4, 36),
+        merkleRoot: raw.slice(36, 68),
+        timestamp: view.getUint32(68, true),
+        bits: view.getUint32(72, true),
+    };
+}
+function compactToTarget(bits) {
+    const exponent = bits >>> 24;
+    const mantissa = bits & 0x007fffff;
+    const negative = (bits & 0x00800000) !== 0;
+    const overflow = mantissa !== 0 && (exponent > 34 ||
+        (mantissa > 0xff && exponent > 33) ||
+        (mantissa > 0xffff && exponent > 32));
+    if (negative || overflow || mantissa === 0)
+        throw new Error("Invalid compact difficulty target");
+    const target = exponent <= 3
+        ? BigInt(mantissa) >> (8n * BigInt(3 - exponent))
+        : BigInt(mantissa) << (8n * BigInt(exponent - 3));
+    if (target <= 0n || target >= (1n << 256n))
+        throw new Error("Difficulty target is out of range");
+    if (targetToCompact(target) !== bits)
+        throw new Error("Non-canonical compact difficulty target");
+    return target;
+}
+function targetToCompact(target) {
+    let size = Math.ceil(target.toString(16).length / 2);
+    let compact = size <= 3
+        ? Number(target << (8n * BigInt(3 - size)))
+        : Number(target >> (8n * BigInt(size - 3)));
+    if (compact & 0x00800000) {
+        compact >>>= 8;
+        size++;
+    }
+    return ((size << 24) | compact) >>> 0;
+}
+function asertTarget(parameters, previousHeight, previousTime) {
+    const anchorTarget = compactToTarget(parameters.anchorBits);
+    const timeDifference = BigInt(previousTime - parameters.anchorPreviousBlockTime);
+    const heightDifference = BigInt(previousHeight - parameters.anchorHeight);
+    if (heightDifference < 0n)
+        throw new Error("Checkpoint predates the ASERT anchor");
+    const exponent = ((timeDifference - TARGET_SPACING_SECS * heightDifference) * ASERT_RADIX) /
+        ASERT_HALF_LIFE_SECS;
+    const shifts = exponent >> 16n;
+    const fraction = exponent & 0xffffn;
+    const factor = ASERT_RADIX + ((195766423245049n * fraction +
+        971821376n * fraction * fraction +
+        5127n * fraction * fraction * fraction +
+        (1n << 47n)) >> 48n);
+    let target = anchorTarget * factor;
+    const shift = shifts - 16n;
+    target = shift <= 0n ? target >> -shift : target << shift;
+    const powLimit = compactToTarget(parameters.powLimitBits);
+    if (target <= 0n)
+        return 1n;
+    return target > powLimit ? powLimit : target;
+}
+function expectedBits(parameters, previousHeight, previous, candidateTime) {
+    if (parameters.allowMinDifficultyBlocks &&
+        candidateTime > previous.timestamp + Number(2n * TARGET_SPACING_SECS))
+        return parameters.powLimitBits;
+    return targetToCompact(asertTarget(parameters, previousHeight, previous.timestamp));
+}
+function assertProofOfWork(header, powLimit) {
+    const target = compactToTarget(header.bits);
+    if (target > powLimit)
+        throw new Error("Header target exceeds the network proof-of-work limit");
+    const hashValue = BigInt(`0x${header.hashHex}`);
+    if (hashValue > target)
+        throw new Error("Header does not satisfy proof of work");
+    return target;
+}
+function transactionId(transactionHex) {
+    const raw = parseHex(transactionHex);
+    const decoded = decodeTransaction(raw);
+    if (typeof decoded === "string")
+        throw new Error(`Invalid transaction: ${decoded}`);
+    return { txid: bytesToHex(reverse(hash256(raw))), outputs: decoded.outputs };
+}
+function hasBindingCommitment(outputs, bindingId) {
+    const data = new TextEncoder().encode(`${ANCHOR_PREFIX}${bindingId}`);
+    const expected = new Uint8Array([0x6a, 0x4c, data.length, ...data]);
+    return outputs.filter(output => output.valueSatoshis === 0n &&
+        output.lockingBytecode.length === expected.length &&
+        output.lockingBytecode.every((byte, index) => byte === expected[index])).length === 1;
+}
+function verifyMerkleBranch(txid, transactionIndex, branch, merkleRoot) {
+    if (!Number.isSafeInteger(transactionIndex) || transactionIndex < 0 || branch.length > 32)
+        return false;
+    let index = transactionIndex;
+    let hash = reverse(parseHex(txid, 32));
+    for (const siblingHex of branch) {
+        const sibling = reverse(parseHex(siblingHex, 32));
+        hash = index & 1
+            ? hash256(new Uint8Array([...sibling, ...hash]))
+            : hash256(new Uint8Array([...hash, ...sibling]));
+        index = Math.floor(index / 2);
+    }
+    return index === 0 && hash.every((byte, position) => byte === merkleRoot[position]);
+}
+function result(status, error, details = {}) {
+    return {
+        status,
+        trustModel: "checkpointed-spv",
+        ...(error ? { error } : {}),
+        ...details,
+    };
+}
+/**
+ * Verify a BCH transaction commitment, Merkle inclusion, and an ASERT header
+ * chain extending from an application-trusted checkpoint. The proof source is
+ * untrusted; checkpoint selection remains the caller's explicit trust root.
+ */
+export function verifyBchAnchorProof(proof, bindingId, options) {
+    try {
+        if (!/^[0-9a-f]{64}$/.test(bindingId))
+            return result("invalid", "Invalid binding ID");
+        const minConfirmations = options.minConfirmations ?? 6;
+        const maxHeaders = options.maxHeaders ?? MAX_PROOF_HEADERS;
+        if (!Number.isSafeInteger(minConfirmations) || minConfirmations < 1)
+            return result("invalid", "Minimum confirmations must be a positive integer");
+        if (!Number.isSafeInteger(maxHeaders) || maxHeaders < 1)
+            return result("invalid", "Maximum header count must be a positive integer");
+        if (!proof || !Array.isArray(proof.headers) || proof.headers.length === 0)
+            return result("unverifiable", "Header chain proof is missing");
+        if (proof.headers.length > maxHeaders)
+            return result("unverifiable", "Header chain exceeds the configured verification limit");
+        const checkpoint = options.checkpoint;
+        const checkpointHeader = parseHeader(checkpoint.headerHex);
+        if (!Number.isSafeInteger(checkpoint.height) ||
+            checkpoint.height < options.asert.anchorHeight ||
+            !Number.isSafeInteger(options.asert.anchorHeight) ||
+            !Number.isSafeInteger(options.asert.anchorPreviousBlockTime) ||
+            !Number.isSafeInteger(options.asert.powLimitBits) ||
+            checkpointHeader.hashHex !== checkpoint.hash.toLowerCase() ||
+            !Array.isArray(checkpoint.recentTimestamps) ||
+            checkpoint.recentTimestamps.length !== 11 ||
+            checkpoint.recentTimestamps[checkpoint.recentTimestamps.length - 1] !== checkpointHeader.timestamp)
+            return result("unverifiable", "Invalid or unsupported trusted checkpoint");
+        if (!Number.isSafeInteger(proof.blockHeight) || proof.blockHeight <= checkpoint.height)
+            return result("unverifiable", "Anchor predates the configured trusted checkpoint");
+        if (!Number.isSafeInteger(proof.blockHeight) ||
+            !Number.isSafeInteger(proof.transactionIndex) ||
+            !Array.isArray(proof.merkleBranch))
+            return result("invalid", "Malformed Merkle proof");
+        const transaction = transactionId(proof.transactionHex);
+        if (!hasBindingCommitment(transaction.outputs, bindingId))
+            return result("invalid", "Transaction does not contain the exact binding commitment", { txid: transaction.txid });
+        let previous = checkpointHeader;
+        let previousHeight = checkpoint.height;
+        let timestamps = checkpoint.recentTimestamps.slice(-11);
+        let inclusionHeader;
+        const powLimit = compactToTarget(options.asert.powLimitBits);
+        const now = options.now ?? Math.floor(Date.now() / 1000);
+        for (let offset = 0; offset < proof.headers.length; offset++) {
+            const height = checkpoint.height + offset + 1;
+            const header = parseHeader(proof.headers[offset]);
+            if (!header.previousHash.every((byte, index) => byte === previous.hash[index]))
+                return result("invalid", `Header chain link failed at height ${height}`);
+            if (header.timestamp <= [...timestamps].sort((a, b) => a - b)[Math.floor(timestamps.length / 2)])
+                return result("invalid", `Header timestamp violates median-time-past at height ${height}`);
+            if (header.timestamp > now + 2 * 60 * 60)
+                return result("invalid", `Header timestamp is too far in the future at height ${height}`);
+            const requiredBits = expectedBits(options.asert, previousHeight, previous, header.timestamp);
+            if (header.bits !== requiredBits)
+                return result("invalid", `Unexpected difficulty target at height ${height}`);
+            assertProofOfWork(header, powLimit);
+            if (height === proof.blockHeight)
+                inclusionHeader = header;
+            timestamps = [...timestamps, header.timestamp].slice(-11);
+            previous = header;
+            previousHeight = height;
+        }
+        const tipHeight = checkpoint.height + proof.headers.length;
+        if (!inclusionHeader)
+            return result("invalid", "Inclusion block is not present in the supplied header chain", { txid: transaction.txid, tipHeight });
+        if (!verifyMerkleBranch(transaction.txid, proof.transactionIndex, proof.merkleBranch, inclusionHeader.merkleRoot))
+            return result("invalid", "Transaction Merkle proof does not match the inclusion block", {
+                txid: transaction.txid,
+                blockHeight: proof.blockHeight,
+                tipHeight,
+            });
+        const confirmations = tipHeight - proof.blockHeight + 1;
+        return result(confirmations >= minConfirmations ? "confirmed" : "pending", undefined, {
+            txid: transaction.txid,
+            blockHeight: proof.blockHeight,
+            tipHeight,
+            confirmations,
+        });
+    }
+    catch (error) {
+        return result("invalid", error instanceof Error ? error.message : String(error));
+    }
+}
+export const BCH_MAINNET_ASERT_PARAMETERS = {
+    anchorHeight: 661647,
+    anchorBits: 0x1804dafe,
+    anchorPreviousBlockTime: 1605447844,
+    powLimitBits: 0x1d00ffff,
+};
+// Fixed trust root, cross-checked against electroncash.dk and a second independent
+// Electrum server. Refresh in a reviewed release as it ages; never fetch trust
+// roots from the same untrusted endpoint that supplies a proof.
+export const BCH_MAINNET_CHECKPOINT = {
+    height: 975752,
+    hash: "0000000000000000010a200fe779aa3c313c7fc1b355b13560ef105709d153fd",
+    headerHex: "000000248509713afafd1db2ec77ef48baf6522757a8b2cd8cb315000000000000000000d70ca4e92d1bc9485441fb6626766cc8a350e59cc44b6a15ddc36dae072f9b60eaa7e96a680f02181a62ef3c",
+    recentTimestamps: [
+        1793688001,
+        1793688081,
+        1793688330,
+        1793692665,
+        1793693308,
+        1793694029,
+        1793694650,
+        1793696313,
+        1793696954,
+        1793697100,
+        1793697770,
+    ],
+};
+// Chipnet ASERT anchor: block 16844 (November 2020 upgrade).
+// anchorPreviousBlockTime is the timestamp of block 16843.
+// Cross-checked against chipnet.imaginary.cash and chipnet.bch.ninja.
+export const BCH_CHIPNET_ASERT_PARAMETERS = {
+    anchorHeight: 16844,
+    anchorBits: 0x1d00ffff,
+    anchorPreviousBlockTime: 1605451779,
+    powLimitBits: 0x1d00ffff,
+};
+// Fixed chipnet trust root at height 330718.
+// Cross-checked against chipnet.imaginary.cash and chipnet.bch.ninja.
+// WARNING: chipnet is a test network that may be reset. This checkpoint is
+// valid for the current chipnet instance only. After a reset, callers must
+// supply a new checkpoint derived from the post-reset chain.
+export const BCH_CHIPNET_CHECKPOINT = {
+    height: 330718,
+    hash: "00000000ad6fb02510bdccdf5eb9c2d4d0f16cfaa721a0450a6c95fef549ee16",
+    headerHex: "040000004c9554d6ad2ce73070ececb406327f3f4b843146056fc64d0f010000000000003cefeb99df9976c9abc99da3a773405e8e2330603729ad0ce149071ad7868ee164cde96affff001d9f3db255",
+    recentTimestamps: [
+        1793701553,
+        1793701753,
+        1793702955,
+        1793703300,
+        1793703430,
+        1793704246,
+        1793704910,
+        1793704951,
+        1793705277,
+        1793706160,
+        1793707364,
+    ],
+};

package/dist/binding.d.ts

@@ -1,7 +1,8 @@
 import { type BchMessageProof } from "./signing.js";
 export declare const PROTOCOL_ID = "cashlet-did";
-export declare const PROTOCOL_VERSION = "2.0.0";
+export declare const PROTOCOL_VERSION = "3.0.0";
 export declare const BINDING_KIND = 30078;
+export declare const ROTATION_AUTH_KIND = 30080;
 export type Network = "mainnet" | "testnet" | "chipnet";
 export interface CanonicalBinding {
     protocol: typeof PROTOCOL_ID;
@@ -17,7 +18,7 @@ export interface CanonicalBinding {
     };
     createdAt: number;
     nonce: string;
-    purpose: "identity-binding-v2";
+    purpose: "identity-binding-v3";
     previousBindingId?: string;
     anchor?: {
         txid: string;
@@ -30,6 +31,7 @@ export interface IdentityBinding {
     nostrProof: {
         event: NostrEvent;
     };
+    rotationAuthorization?: NostrEvent;
     publishedAt?: number;
 }
 export interface NostrEvent {
@@ -45,7 +47,14 @@ 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?: BchMessageProof): {
+export declare function rotationAuthorizationTemplate(previous: CanonicalBinding, successor: CanonicalBinding): {
+    kind: number;
+    created_at: number;
+    tags: string[][];
+    content: string;
+};
+export declare function verifyRotationAuthorization(authorization: NostrEvent, previous: CanonicalBinding, successor: CanonicalBinding): boolean;
+export declare function nostrEventTemplate(binding: CanonicalBinding, bchProof?: BchMessageProof, rotationAuthorization?: NostrEvent): {
     kind: number;
     created_at: number;
     tags: string[][];

package/dist/binding.js

@@ -1,7 +1,9 @@
 import { BCH_PROOF_FORMAT, normalizeBchMessageSignature, } from "./signing.js";
+import { verifyEvent } from "nostr-tools";
 export const PROTOCOL_ID = "cashlet-did";
-export const PROTOCOL_VERSION = "2.0.0";
+export const PROTOCOL_VERSION = "3.0.0";
 export const BINDING_KIND = 30078;
+export const ROTATION_AUTH_KIND = 30080;
 export function canonicalize(v) {
     if (v === null || typeof v !== "object")
         return JSON.stringify(v);
@@ -38,7 +40,7 @@ export async function buildBinding(bchAddress, network, nostrPubkey, paymentCode
         nostr: { pubkey: nostrPubkey },
         createdAt: Math.floor(Date.now() / 1000),
         nonce: randomHex(32),
-        purpose: "identity-binding-v2",
+        purpose: "identity-binding-v3",
         ...(previousBindingId ? { previousBindingId } : {}),
     };
     const bindingId = await sha256hex(canonicalize(partial));
@@ -55,12 +57,56 @@ export function bchSigningPayload(binding) {
         createdAt: binding.createdAt,
     });
 }
-export function nostrEventTemplate(binding, bchProof) {
+export function rotationAuthorizationTemplate(previous, successor) {
+    if (successor.previousBindingId !== previous.bindingId)
+        throw new Error("Successor must reference the previous binding");
+    if (successor.nostr.pubkey === previous.nostr.pubkey)
+        throw new Error("Rotation authorization is only required when the Nostr key changes");
+    return {
+        kind: ROTATION_AUTH_KIND,
+        created_at: successor.createdAt,
+        tags: [
+            ["d", successor.bindingId],
+            ["protocol", PROTOCOL_ID, PROTOCOL_VERSION],
+            ["t", `${PROTOCOL_ID}-rotation`],
+        ],
+        content: canonicalize({
+            protocol: PROTOCOL_ID,
+            version: PROTOCOL_VERSION,
+            purpose: "key-rotation-authorization-v3",
+            previousBindingId: previous.bindingId,
+            previousPubkey: previous.nostr.pubkey,
+            successorBindingId: successor.bindingId,
+            successorPubkey: successor.nostr.pubkey,
+            successorBch: successor.bch,
+            createdAt: successor.createdAt,
+        }),
+    };
+}
+export function verifyRotationAuthorization(authorization, previous, successor) {
+    if (!authorization ||
+        authorization.kind !== ROTATION_AUTH_KIND ||
+        authorization.pubkey !== previous.nostr.pubkey ||
+        authorization.created_at !== successor.createdAt ||
+        !Array.isArray(authorization.tags) ||
+        !verifyEvent(authorization))
+        return false;
+    const expected = rotationAuthorizationTemplate(previous, successor);
+    return authorization.content === expected.content &&
+        JSON.stringify(authorization.tags) === JSON.stringify(expected.tags);
+}
+export function nostrEventTemplate(binding, bchProof, rotationAuthorization) {
     if (bchProof) {
         if (bchProof.message !== bchSigningPayload(binding))
             throw new Error("BCH proof message does not match the binding");
         normalizeBchMessageSignature(bchProof.signatureBase64);
     }
+    if (!binding.previousBindingId && rotationAuthorization)
+        throw new Error("Unexpected rotation authorization without a predecessor");
+    if (rotationAuthorization && (rotationAuthorization.kind !== ROTATION_AUTH_KIND ||
+        !Array.isArray(rotationAuthorization.tags) ||
+        rotationAuthorization.tags.find(tag => tag[0] === "d")?.[1] !== binding.bindingId))
+        throw new Error("Rotation authorization does not match the successor binding");
     return {
         kind: BINDING_KIND,
         created_at: binding.createdAt,
@@ -71,6 +117,7 @@ export function nostrEventTemplate(binding, bchProof) {
             ["protocol", PROTOCOL_ID, PROTOCOL_VERSION],
             ["t", PROTOCOL_ID],
             ...(binding.previousBindingId ? [["supersedes", binding.previousBindingId]] : []),
+            ...(rotationAuthorization ? [["rotation-proof", rotationAuthorization.id, rotationAuthorization.pubkey]] : []),
             ...(binding.anchor ? [["bch-anchor", binding.anchor.txid, ...(binding.anchor.blockHeight ? [String(binding.anchor.blockHeight)] : [])]] : []),
             ...(bchProof ? [["bch-proof", BCH_PROOF_FORMAT, bchProof.message, bchProof.signatureBase64]] : []),
         ],
@@ -82,6 +129,7 @@ export function nostrEventTemplate(binding, bchProof) {
             nonce: binding.nonce,
             createdAt: binding.createdAt,
             ...(binding.previousBindingId ? { previousBindingId: binding.previousBindingId } : {}),
+            ...(rotationAuthorization ? { rotationAuthorization } : {}),
         }),
     };
 }

package/dist/bip47.d.ts

@@ -0,0 +1,50 @@
+/**
+ * BIP47 v1 reusable payment code helpers.
+ * Notification transactions and scanning are wallet-specific and out of scope.
+ */
+import { deriveHdPrivateNodeFromBip39Mnemonic, deriveHdPath, deriveHdPublicNode, type HdPublicNodeValid, type HdPrivateNodeValid } from "@bitauth/libauth";
+export interface PaymentCode {
+    /** Compressed public key (33 bytes) */
+    publicKey: Uint8Array;
+    /** Chain code (32 bytes) */
+    chainCode: Uint8Array;
+}
+export interface EncodedPaymentCode extends PaymentCode {
+    /** Base58Check encoded payment code string ("PM8T...") */
+    encoded: string;
+}
+/**
+ * Encode a BIP47 v1 payment code from a public key and chain code.
+ */
+export declare function encodePaymentCode(publicKey: Uint8Array, chainCode: Uint8Array): Promise<string>;
+/**
+ * Decode a BIP47 v1 Base58Check payment code string.
+ */
+export declare function parsePaymentCode(paymentCode: string): PaymentCode;
+/**
+ * Derive a BIP47 payment code from a mnemonic (m/47'/0'/<account>').
+ */
+export declare function derivePaymentCode(mnemonic: string, account?: number): Promise<EncodedPaymentCode>;
+/**
+ * Derive the nth P2PKH CashAddr payment address for sending to a recipient.
+ *
+ * @param senderScanPrivkey - sender's M/47'/0'/0'/0 private key (32 bytes)
+ * @param recipientNode     - recipient's BIP47 HD public node (M/47'/0'/0')
+ * @param index             - address index (0-based)
+ * @param prefix            - CashAddr prefix, defaults to "bitcoincash"
+ */
+export declare function derivePaymentAddress(senderScanPrivkey: Uint8Array, recipientNode: HdPublicNodeValid, index: number, prefix?: "bitcoincash" | "bchtest" | "bchreg"): Promise<string>;
+/**
+ * Derive the nth payment private key for a receiver to spend funds sent via BIP47.
+ *
+ * Per BIP47 spec: s = SHA256(b[i] * A)  where A = sender's scan pubkey (M/47'/0'/0'/0)
+ *                 b' = b[i] + s
+ *
+ * @param receiverAccountNode - receiver's M/47'/0'/0' private node
+ * @param senderScanPubkey    - sender's M/47'/0'/0'/0 compressed public key (33 bytes)
+ * @param index               - address index (0-based)
+ */
+export declare function derivePaymentPrivkey(receiverAccountNode: HdPrivateNodeValid, senderScanPubkey: Uint8Array, index: number): Promise<Uint8Array>;
+export { deriveHdPublicNode, deriveHdPath, deriveHdPrivateNodeFromBip39Mnemonic };
+/** Construct a minimal HdPublicNodeValid from a BIP47 PaymentCode for use with derivePaymentAddress/derivePaymentPrivkey. */
+export declare function hdPublicNodeFromPaymentCode(pc: PaymentCode): HdPublicNodeValid;