bip-321 0.0.3 → 0.0.5

package/index.ts

@@ -3,8 +3,17 @@ import { decode as decodeLightning } from "light-bolt11-decoder";
 import { sha256 } from "@noble/hashes/sha2.js";
 import { base58, bech32, bech32m } from "@scure/base";
 
+// Type declaration for missing export in light-bolt12-decoder
+declare module "light-bolt12-decoder" {
+  export function decode(offer: string): {
+    offerRequest: string;
+    sections: Array<{ name: string; value: unknown }>;
+  };
+}
+import { decode as decodeBolt12 } from "light-bolt12-decoder";
+
 export interface PaymentMethod {
-  type: "onchain" | "lightning" | "lno" | "silent-payment" | "other";
+  type: "onchain" | "lightning" | "offer" | "silent-payment" | "ark";
   value: string;
   network?: "mainnet" | "testnet" | "regtest" | "signet";
   valid: boolean;
@@ -115,7 +124,7 @@ function detectAddressNetwork(
       else if (version === 0x6f || version === 0xc4) {
         return "testnet";
       }
-    } catch (e) {
+    } catch {
       return undefined;
     }
   } catch {
@@ -174,12 +183,129 @@ function validateLightningInvoice(invoice: string): {
   }
 }
 
+function validateBolt12Offer(offer: string): {
+  valid: boolean;
+  error?: string;
+} {
+  try {
+    if (!offer || typeof offer !== "string") {
+      return { valid: false, error: "Empty or invalid offer" };
+    }
+
+    const lowerOffer = offer.toLowerCase();
+    if (!lowerOffer.startsWith("ln")) {
+      return { valid: false, error: "Invalid BOLT12 offer format" };
+    }
+
+    decodeBolt12(offer);
+    return { valid: true };
+  } catch (e) {
+    return {
+      valid: false,
+      error: `Invalid BOLT12 offer: ${e instanceof Error ? e.message : String(e)}`,
+    };
+  }
+}
+
+function validateSilentPaymentAddress(address: string): {
+  valid: boolean;
+  network?: "mainnet" | "testnet" | "regtest" | "signet";
+  error?: string;
+} {
+  try {
+    const lowerAddress = address.toLowerCase();
+
+    let network: "mainnet" | "testnet" | undefined;
+    if (lowerAddress.startsWith("sp1q")) {
+      network = "mainnet";
+    } else if (lowerAddress.startsWith("tsp1q")) {
+      network = "testnet";
+    } else {
+      return { valid: false, error: "Invalid silent payment address prefix" };
+    }
+
+    const decoded = bech32m.decode(address as `${string}1${string}`, 1023);
+
+    const expectedPrefix = network === "mainnet" ? "sp" : "tsp";
+    if (decoded.prefix !== expectedPrefix) {
+      return { valid: false, error: "Invalid silent payment address prefix" };
+    }
+
+    // Check version (first word should be 0 for v0, which encodes as 'q')
+    if (decoded.words.length === 0 || decoded.words[0] !== 0) {
+      return { valid: false, error: "Unsupported silent payment version" };
+    }
+
+    // Convert from 5-bit words to bytes
+    const dataWords = decoded.words.slice(1);
+    const data = bech32m.fromWordsUnsafe(dataWords);
+
+    if (!data) {
+      return { valid: false, error: "Invalid silent payment address data" };
+    }
+
+    // BIP-352: v0 addresses must be exactly 66 bytes (33-byte scan key + 33-byte spend key)
+    if (data.length !== 66) {
+      return { valid: false, error: "Invalid silent payment address length" };
+    }
+
+    // Validate both public keys are valid compressed keys (0x02 or 0x03 prefix)
+    const scanKey = data[0];
+    const spendKey = data[33];
+    if (
+      (scanKey !== 0x02 && scanKey !== 0x03) ||
+      (spendKey !== 0x02 && spendKey !== 0x03)
+    ) {
+      return {
+        valid: false,
+        error: "Invalid public key format in silent payment address",
+      };
+    }
+
+    return { valid: true, network };
+  } catch (e) {
+    return {
+      valid: false,
+      error: `Invalid silent payment address: ${e instanceof Error ? e.message : String(e)}`,
+    };
+  }
+}
+
+function validateArkAddress(address: string): {
+  valid: boolean;
+  network?: "mainnet" | "testnet" | "regtest" | "signet";
+  error?: string;
+} {
+  try {
+    const lowerAddress = address.toLowerCase();
+
+    if (lowerAddress.startsWith("ark1")) {
+      const decoded = bech32m.decode(address as `${string}1${string}`, 1023);
+      if (decoded.prefix === "ark") {
+        return { valid: true, network: "mainnet" };
+      }
+    } else if (lowerAddress.startsWith("tark1")) {
+      const decoded = bech32m.decode(address as `${string}1${string}`, 1023);
+      if (decoded.prefix === "tark") {
+        return { valid: true, network: "testnet" };
+      }
+    }
+
+    return { valid: false, error: "Invalid Ark address format" };
+  } catch (e) {
+    return {
+      valid: false,
+      error: `Invalid Ark address: ${e instanceof Error ? e.message : String(e)}`,
+    };
+  }
+}
+
 function validatePopUri(popUri: string): { valid: boolean; error?: string } {
   try {
     const decoded = decodeURIComponent(popUri);
     const schemeMatch = decoded.match(/^([a-zA-Z][a-zA-Z0-9+.-]*):?/);
 
-    if (schemeMatch && schemeMatch[1]) {
+    if (schemeMatch?.[1]) {
       const scheme = schemeMatch[1].toLowerCase();
       if (FORBIDDEN_POP_SCHEMES.includes(scheme)) {
         return { valid: false, error: `Forbidden pop scheme: ${scheme}` };
@@ -192,7 +318,10 @@ function validatePopUri(popUri: string): { valid: boolean; error?: string } {
   }
 }
 
-export function parseBIP321(uri: string): BIP321ParseResult {
+export function parseBIP321(
+  uri: string,
+  expectedNetwork?: "mainnet" | "testnet" | "regtest" | "signet",
+): BIP321ParseResult {
   const result: BIP321ParseResult = {
     paymentMethods: [],
     requiredParams: [],
@@ -265,7 +394,7 @@ export function parseBIP321(uri: string): BIP321ParseResult {
       }
 
       const lowerKey = key.toLowerCase();
-      const count = (seenKeys.get(lowerKey) || 0) + 1;
+      const count = (seenKeys.get(lowerKey) ?? 0) + 1;
       seenKeys.set(lowerKey, count);
 
       if (lowerKey === "label") {
@@ -305,7 +434,7 @@ export function parseBIP321(uri: string): BIP321ParseResult {
           // Keep pop value encoded as per spec
           const validation = validatePopUri(value);
           if (!validation.valid) {
-            result.errors.push(validation.error || "Invalid pop URI");
+            result.errors.push(validation.error ?? "Invalid pop URI");
             if (lowerKey === "req-pop") {
               result.valid = false;
             }
@@ -324,28 +453,47 @@ export function parseBIP321(uri: string): BIP321ParseResult {
           error: validation.error,
         });
         if (!validation.valid) {
-          result.errors.push(validation.error || "Invalid lightning invoice");
+          result.errors.push(validation.error ?? "Invalid lightning invoice");
         }
       } else if (lowerKey === "lno") {
         const decodedValue = decodeURIComponent(value);
+        const validation = validateBolt12Offer(decodedValue);
         result.paymentMethods.push({
-          type: "lno",
+          type: "offer",
           value: decodedValue,
-          valid: true,
+          valid: validation.valid,
+          error: validation.error,
         });
+        if (!validation.valid) {
+          result.errors.push(validation.error ?? "Invalid BOLT12 offer");
+        }
       } else if (lowerKey === "sp") {
         const decodedValue = decodeURIComponent(value);
-        const isSilentPayment = decodedValue.toLowerCase().startsWith("sp1");
+        const validation = validateSilentPaymentAddress(decodedValue);
         result.paymentMethods.push({
           type: "silent-payment",
           value: decodedValue,
-          valid: isSilentPayment,
-          error: isSilentPayment
-            ? undefined
-            : "Invalid silent payment address format",
+          network: validation.network,
+          valid: validation.valid,
+          error: validation.error,
+        });
+        if (!validation.valid) {
+          result.errors.push(
+            validation.error ?? "Invalid silent payment address",
+          );
+        }
+      } else if (lowerKey === "ark") {
+        const decodedValue = decodeURIComponent(value);
+        const validation = validateArkAddress(decodedValue);
+        result.paymentMethods.push({
+          type: "ark",
+          value: decodedValue,
+          network: validation.network,
+          valid: validation.valid,
+          error: validation.error,
         });
-        if (!isSilentPayment) {
-          result.errors.push("Invalid silent payment address format");
+        if (!validation.valid) {
+          result.errors.push(validation.error ?? "Invalid Ark address");
         }
       } else if (
         lowerKey === "bc" ||
@@ -379,7 +527,7 @@ export function parseBIP321(uri: string): BIP321ParseResult {
         if (!validation.valid || !networkMatches) {
           result.errors.push(
             !validation.valid
-              ? validation.error!
+              ? (validation.error ?? "Invalid address")
               : `Address network mismatch for ${lowerKey} parameter`,
           );
           result.valid = false;
@@ -389,9 +537,7 @@ export function parseBIP321(uri: string): BIP321ParseResult {
         result.errors.push(`Unknown required parameter: ${key}`);
         result.valid = false;
       } else {
-        if (!result.optionalParams[lowerKey]) {
-          result.optionalParams[lowerKey] = [];
-        }
+        result.optionalParams[lowerKey] ??= [];
         result.optionalParams[lowerKey].push(decodeURIComponent(value));
       }
     }
@@ -402,6 +548,19 @@ export function parseBIP321(uri: string): BIP321ParseResult {
     result.valid = false;
   }
 
+  if (expectedNetwork) {
+    for (const method of result.paymentMethods) {
+      if (method.network && method.network !== expectedNetwork) {
+        result.errors.push(
+          `Payment method network mismatch: expected ${expectedNetwork}, got ${method.network}`,
+        );
+        result.valid = false;
+        method.valid = false;
+        method.error = `Network mismatch: expected ${expectedNetwork}`;
+      }
+    }
+  }
+
   if (result.popRequired && result.pop) {
     const hasValidPaymentMethod = result.paymentMethods.some((pm) => pm.valid);
     if (!hasValidPaymentMethod) {
@@ -426,10 +585,17 @@ export function getPaymentMethodsByNetwork(
   };
 
   for (const method of result.paymentMethods) {
-    if (method.network && byNetwork[method.network]) {
-      byNetwork[method.network]!.push(method);
+    const { network } = method;
+    if (network && network in byNetwork) {
+      const networkArray = byNetwork[network];
+      if (networkArray) {
+        networkArray.push(method);
+      }
     } else {
-      byNetwork.unknown!.push(method);
+      const unknownArray = byNetwork.unknown;
+      if (unknownArray) {
+        unknownArray.push(method);
+      }
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bip-321",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "A TypeScript/JavaScript library for parsing BIP-321 Bitcoin URI scheme with support for multiple payment methods",
   "type": "module",
   "main": "./index.ts",
@@ -16,7 +16,7 @@
     "test": "bun test",
     "example": "bun example.ts",
     "check": "tsc --noEmit",
-    "lint": "oxlint"
+    "lint": "eslint ."
   },
   "keywords": [
     "bitcoin",
@@ -45,11 +45,15 @@
     "@noble/hashes": "^2.0.1",
     "@scure/base": "^2.0.0",
     "bitcoinjs-lib": "^7.0.0",
-    "light-bolt11-decoder": "^3.2.0"
+    "light-bolt11-decoder": "^3.2.0",
+    "light-bolt12-decoder": "^1.0.3"
   },
   "devDependencies": {
     "@types/bun": "latest",
-    "oxlint": "^1.26.0"
+    "@typescript-eslint/eslint-plugin": "^8.46.3",
+    "@typescript-eslint/parser": "^8.46.3",
+    "eslint": "^9.39.1",
+    "eslint-plugin-import": "^2.32.0"
   },
   "peerDependencies": {
     "typescript": "^5"

package/oxlintrc.json

@@ -1,23 +0,0 @@
-{
-  "categories": {
-    "correctness": "warn",
-    "suspicious": "warn",
-    "pedantic": "warn",
-    "perf": "warn",
-    "style": "warn",
-    "restriction": "warn"
-  },
-  "rules": {
-    "typescript/no-explicit-any": "error",
-    "typescript/no-non-null-assertion": "error",
-    "no-console": "warn",
-    "no-debugger": "error",
-    "eqeqeq": "error"
-  },
-  "ignorePatterns": [
-    "**/node_modules/**",
-    "**/dist/**",
-    "**/build/**",
-    "**/*.min.js"
-  ]
-}