bip-321 0.0.2 → 0.0.4

package/AGENTS.md

@@ -0,0 +1,261 @@
+# BIP-321 Parser - Agent Development Guide
+
+This document provides guidance for AI agents and developers working on the BIP-321 Bitcoin URI parser library.
+
+## Project Overview
+
+A TypeScript/JavaScript library for parsing BIP-321 Bitcoin URIs with support for multiple payment methods (on-chain, Lightning, BOLT12, Silent Payments). Works natively in Node.js, browsers, and React Native without build tools.
+
+## Tech Stack
+
+### Runtime
+- **Bun** - Primary development runtime
+- Use `bun test` instead of `jest` or `vitest`
+- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
+- Use `bun install` for package management
+
+### Key Dependencies
+
+**Why These Specific Dependencies:**
+
+1. **`@scure/base`** (^2.0.0)
+   - Pure JavaScript base58, bech32, and bech32m encoding
+   - Works natively in all environments (Node.js, browser, React Native)
+   - No browserify or build tools needed
+   - Used for Base58 address decoding and bech32/bech32m validation
+
+2. **`@noble/hashes`** (^2.0.1)
+   - Pure JavaScript cryptographic hashing (SHA-256)
+   - Properly exports all modules (no import warnings)
+   - Used for Base58Check checksum validation
+   - Import path: `@noble/hashes/sha2.js` (with .js extension)
+
+3. **`bitcoinjs-lib`** (^7.0.0)
+   - Standard Bitcoin library for address validation
+   - Note: Taproot addresses require manual bech32m validation (ECC lib not initialized)
+   - Fallback to `@scure/base` for taproot validation
+
+4. **`light-bolt11-decoder`** (^3.2.0)
+   - Lightweight Lightning BOLT11 invoice parser
+   - No heavy dependencies
+
+### What We AVOID
+
+- ❌ `bs58` - Requires browserify for browsers
+- ❌ `bs58check` - Has module export warnings with `@noble/hashes`
+- ❌ `express` or heavy server frameworks
+- ❌ Build tools (webpack, browserify, rollup)
+
+## Development Commands
+
+```bash
+# Run tests
+bun test
+
+# Run TypeScript type check
+bun run check
+# or
+bunx tsc --noEmit
+
+# Run examples
+bun example.ts
+
+# Run linter
+bun run lint
+```
+
+## Project Structure
+
+```
+bip-321/
+├── index.ts           # Main parser implementation
+├── index.test.ts      # Comprehensive test suite (39 tests)
+├── example.ts         # Usage examples
+├── README.md          # User documentation
+├── CLAUDE.md          # Bun-specific development rules
+├── AGENTS.md          # This file
+├── package.json       # Dependencies and scripts
+└── tsconfig.json      # TypeScript configuration
+```
+
+## Key Design Decisions
+
+### 1. Network Detection Strategy
+
+```typescript
+// Order matters for Lightning invoices!
+// Check "lnbcrt" before "lnbc" to avoid false positives
+if (lowerInvoice.startsWith("lnbcrt")) return "regtest";
+else if (lowerInvoice.startsWith("lnbc")) return "mainnet";
+else if (lowerInvoice.startsWith("lntbs")) return "signet";
+else if (lowerInvoice.startsWith("lntb")) return "testnet";
+```
+
+### 2. Taproot Address Validation
+
+bitcoinjs-lib requires ECC library initialization for taproot validation, so we use manual bech32m validation:
+
+```typescript
+// Fallback to manual bech32/bech32m validation for taproot
+const decoded = lowerAddress.startsWith("bc1p")
+  ? bech32m.decode(address as `${string}1${string}`, 90)
+  : bech32.decode(address as `${string}1${string}`, 90);
+```
+
+### 3. Base58Check Validation
+
+Manual implementation using `@scure/base` + `@noble/hashes` to avoid dependencies with browser compatibility issues:
+
+```typescript
+const decoded = base58.decode(address);
+const payload = decoded.slice(0, -4);
+const checksum = decoded.slice(-4);
+const hash = sha256(sha256(payload)); // Double SHA-256
+// Verify checksum matches
+```
+
+### 4. Query Parameter Parsing
+
+Manual parsing instead of `URLSearchParams` to preserve encoded values for `pop` parameter:
+
+```typescript
+// Parse manually to preserve encoded values for pop parameter
+const paramPairs = queryString.split("&");
+// Keep pop value encoded as per BIP-321 spec
+```
+
+## Supported Payment Methods
+
+| Type | Parameter | Validation | Notes |
+|------|-----------|------------|-------|
+| On-chain | `address`, `bc`, `tb`, `bcrt` | Full validation with network check | P2PKH, P2SH, Segwit, Taproot |
+| Lightning | `lightning` | BOLT11 decode + network detection | Mainnet, testnet, regtest, signet |
+| BOLT12 | `lno` | Accept any value | Offers (minimal validation) |
+| Silent Payments | `sp` | Prefix check (`sp1`) | BIP-352 addresses |
+
+**Removed:** BIP-351 Private Payments (`pay` parameter) - Unused spec, nobody knows what it is
+
+## Testing Guidelines
+
+### Test Structure
+- 39 tests covering all functionality
+- Use `test()` and `expect()` from `bun:test`
+- Group related tests with `describe()`
+- Use non-null assertions (`!`) where values are guaranteed to exist
+
+### Example Test Pattern
+```typescript
+test("parses mainnet address", () => {
+  const result = parseBIP321("bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa");
+  expect(result.valid).toBe(true);
+  expect(result.network).toBe("mainnet");
+  expect(result.paymentMethods[0]!.type).toBe("onchain");
+});
+```
+
+## TypeScript Type Safety
+
+All code must pass strict TypeScript checking with zero errors:
+
+```bash
+bunx tsc --noEmit  # Must pass with 0 errors
+```
+
+### Common Type Patterns
+
+```typescript
+// Use non-null assertions for array access where guaranteed
+result.paymentMethods[0]!.type
+
+// Use optional chaining for potentially undefined values
+result.paymentMethods[0]?.network
+
+// Use nullish coalescing for fallbacks
+byNetwork.mainnet?.length || 0
+```
+
+## BIP-321 Compliance Rules
+
+1. ✅ URI must start with `bitcoin:` (case-insensitive)
+2. ✅ `label`, `message`, `amount`, `pop` cannot appear multiple times
+3. ✅ `pop` and `req-pop` cannot both be present
+4. ✅ Required parameters (`req-*`) must be understood or URI is invalid
+5. ✅ Network-specific parameters must match address network
+6. ✅ `pop` scheme must not be forbidden (http, https, file, javascript, mailto)
+7. ✅ `amount` must be decimal BTC (no commas)
+8. ✅ At least one valid payment method required
+
+## Common Pitfalls
+
+### ❌ Don't Do This
+```typescript
+// Wrong: Using .js imports breaks TypeScript
+import { sha256 } from "@noble/hashes/sha2";
+
+// Wrong: bs58 requires browserify
+import bs58 from "bs58";
+
+// Wrong: Checking lnbc before lnbcrt
+if (invoice.startsWith("lnbc")) return "mainnet";
+```
+
+### ✅ Do This
+```typescript
+// Correct: Use .js extension for @noble/hashes
+import { sha256 } from "@noble/hashes/sha2.js";
+
+// Correct: Use @scure/base (works everywhere)
+import { base58 } from "@scure/base";
+
+// Correct: Check longer prefix first
+if (invoice.startsWith("lnbcrt")) return "regtest";
+else if (invoice.startsWith("lnbc")) return "mainnet";
+```
+
+## Adding New Payment Methods
+
+1. Add to `PaymentMethod` type union
+2. Add parameter parsing in `parseBIP321()`
+3. Implement validation function if needed
+4. Add network detection if applicable
+5. Write tests for new method
+6. Update README documentation
+7. Add example usage
+
+## Browser Compatibility
+
+All dependencies work natively in browsers via ES modules:
+
+```html
+<script type="module">
+  import { parseBIP321 } from './index.js';
+  // No build tools needed!
+</script>
+```
+
+**No browserify, webpack, rollup, or any build tools required.**
+
+## Performance Considerations
+
+- Address validation is synchronous and fast
+- Lightning invoice decoding is the slowest operation
+- No async operations in the entire codebase
+- Manual Base58 validation is faster than external libraries
+
+## Contributing Guidelines
+
+1. All changes must pass TypeScript type check (`bun run check`)
+2. All tests must pass (`bun test`)
+3. Add tests for new functionality
+4. Update README for API changes
+5. Keep dependencies minimal and browser-compatible
+6. No build tools or polyfills
+7. Maintain cross-platform compatibility (Node.js, browser, React Native)
+
+## Resources
+
+- [BIP-321 Specification](https://bips.dev/321/)
+- [BIP-21 (Original)](https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki)
+- [BIP-352 Silent Payments](https://github.com/bitcoin/bips/blob/master/bip-0352.mediawiki)
+- [@scure/base Documentation](https://github.com/paulmillr/scure-base)
+- [@noble/hashes Documentation](https://github.com/paulmillr/noble-hashes)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nitesh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -5,30 +5,23 @@ A TypeScript/JavaScript library for parsing BIP-321 Bitcoin URI scheme. This lib
 ## Features
 
 - ✅ **Complete BIP-321 compliance** - Implements the full BIP-321 specification
-- ✅ **Multiple payment methods** - Supports on-chain, Lightning (BOLT11), BOLT12 offers, silent payments, and private payments
+- ✅ **Multiple payment methods** - Supports on-chain, Lightning (BOLT11), BOLT12 offers, and silent payments
 - ✅ **Network detection** - Automatically detects mainnet, testnet, regtest, and signet networks
 - ✅ **Address validation** - Validates Bitcoin addresses (P2PKH, P2SH, Segwit v0, Taproot)
 - ✅ **Lightning invoice validation** - Validates BOLT11 Lightning invoices
-- ✅ **Cross-platform** - Works in Node.js, browsers, and React Native
-- ✅ **TypeScript support** - Fully typed with TypeScript definitions
-- ✅ **Proof of payment** - Supports pop/req-pop parameters for payment callbacks
-- ✅ **Comprehensive error handling** - Clear error messages for invalid URIs
 
 ```typescript
 import { parseBIP321, type BIP321ParseResult, type PaymentMethod } from "bip-321";
 
-// Fully typed result with autocomplete support
 const result: BIP321ParseResult = parseBIP321("bitcoin:...");
 
-// TypeScript knows all available properties
 result.valid;           // boolean
 result.network;         // "mainnet" | "testnet" | "regtest" | "signet" | undefined
 result.paymentMethods;  // PaymentMethod[]
 result.errors;          // string[]
 
-// Payment methods are also fully typed
 result.paymentMethods.forEach((method: PaymentMethod) => {
-  method.type;    // "onchain" | "lightning" | "lno" | "silent-payment" | "private-payment" | "other"
+  method.type;    // "onchain" | "lightning" | "lno" | "silent-payment" | "other"
   method.network; // "mainnet" | "testnet" | "regtest" | "signet" | undefined
   method.valid;   // boolean
 });
@@ -46,16 +39,6 @@ Or with npm:
 npm install bip-321
 ```
 
-### Note on Dependencies
-
-This library uses modern, browser-native dependencies:
-- **`@scure/base`** - Pure JavaScript base58, bech32, and bech32m encoding (no browserify needed)
-- **`@noble/hashes`** - Pure JavaScript cryptographic hashing
-- **`bitcoinjs-lib`** - Bitcoin address validation
-- **`light-bolt11-decoder`** - Lightning invoice parsing
-
-All dependencies work natively in Node.js, browsers, and React Native without any build tools or polyfills required.
-
 ## Quick Start
 
 ```typescript
@@ -122,6 +105,30 @@ console.log(result.paymentMethods[0].type); // "lightning"
 console.log(result.paymentMethods[0].network); // "mainnet"
 ```
 
+### Network Validation
+
+```typescript
+// Ensure all payment methods are mainnet
+const result = parseBIP321(
+  "bitcoin:bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq?lightning=lnbc...",
+  "mainnet"
+);
+
+if (result.valid) {
+  // All payment methods are guaranteed to be mainnet
+  console.log("All payment methods are mainnet");
+}
+
+// Reject testnet addresses when expecting mainnet
+const invalid = parseBIP321(
+  "bitcoin:tb1qghfhmd4zh7ncpmxl3qzhmq566jk8ckq4gafnmg",
+  "mainnet"
+);
+
+console.log(invalid.valid); // false
+console.log(invalid.errors); // ["Payment method network mismatch..."]
+```
+
 ### Multiple Payment Methods
 
 ```typescript
@@ -159,12 +166,28 @@ if (!result.valid) {
 
 ## API Reference
 
-### `parseBIP321(uri: string): BIP321ParseResult`
+### `parseBIP321(uri: string, expectedNetwork?: "mainnet" | "testnet" | "regtest" | "signet"): BIP321ParseResult`
 
 Parses a BIP-321 URI and returns detailed information about the payment request.
 
 **Parameters:**
 - `uri` - The Bitcoin URI string to parse
+- `expectedNetwork` (optional) - Expected network for all payment methods. If specified, all payment methods must match this network or the URI will be marked invalid.
+</text>
+
+<old_text line=240>
+## Validation Rules
+
+The parser enforces BIP-321 validation rules:
+
+1. ✅ URI must start with `bitcoin:` (case-insensitive)
+2. ✅ Address in URI path must be valid or empty
+3. ✅ `amount` must be decimal BTC (no commas)
+4. ✅ `label`, `message`, and `amount` cannot appear multiple times
+5. ✅ `pop` and `req-pop` cannot both be present
+6. ✅ Required parameters (`req-*`) must be understood or URI is invalid
+7. ✅ Network-specific parameters (`bc`, `tb`, etc.) must match address network
+8. ✅ `pop` URI scheme must not be forbidden (http, https, file, javascript, mailto)
 
 **Returns:** `BIP321ParseResult` object containing:
 
@@ -198,7 +221,7 @@ interface BIP321ParseResult {
 
 ```typescript
 interface PaymentMethod {
-  type: "onchain" | "lightning" | "lno" | "silent-payment" | "private-payment" | "other";
+  type: "onchain" | "lightning" | "lno" | "silent-payment" | "other";
   value: string; // The actual address/invoice value
   network?: "mainnet" | "testnet" | "regtest" | "signet";
   valid: boolean; // Whether this payment method is valid
@@ -250,7 +273,6 @@ console.log(summary);
 | Lightning | `lightning` | BOLT11 Lightning invoices |
 | BOLT12 | `lno` | Lightning BOLT12 offers |
 | Silent Payments | `sp` | BIP352 Silent Payment addresses |
-| Private Payments | `pay` | BIP351 Private Payment addresses |
 
 ## Network Detection
 
@@ -279,6 +301,7 @@ The parser enforces BIP-321 validation rules:
 6. ✅ Required parameters (`req-*`) must be understood or URI is invalid
 7. ✅ Network-specific parameters (`bc`, `tb`, etc.) must match address network
 8. ✅ `pop` URI scheme must not be forbidden (http, https, file, javascript, mailto)
+9. ✅ If `expectedNetwork` is specified, all payment methods must match that network
 
 ## Browser Usage
 
@@ -325,15 +348,11 @@ function parseQRCode(data: string) {
 }
 ```
 
-## Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.
-
 ## License
 
-BSD-2-Clause (same as BIP-321)
+MIT
 
 ## Related
 
-- [BIP-321 Specification](https://bips.dev/321/)
+- [BIP-321 Specification](https://github.com/bitcoin/bips/blob/master/bip-0321.mediawiki)
 - [BIP-21 (Original)](https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki)

package/index.test.ts

@@ -6,12 +6,40 @@ import {
   formatPaymentMethodsSummary,
 } from "./index";
 
+const TEST_DATA = {
+  addresses: {
+    mainnet: {
+      p2pkh: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
+      bech32: "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
+      taproot: "bc1pdyp8m5mhurxa9mf822jegnhu49g2zcchgcq8jzrjxg58u2lvudyqftt43a",
+    },
+    testnet: {
+      bech32: "tb1qghfhmd4zh7ncpmxl3qzhmq566jk8ckq4gafnmg",
+    },
+    regtest: {
+      bech32: "bcrt1qw508d6qejxtdg4y5r3zarvary0c5xw7kygt080",
+    },
+  },
+  lightning: {
+    mainnet:
+      "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs",
+    testnet:
+      "lntb2500n1pwxlkl5pp5g8hz28tlf950ps942lu3dknfete8yax2ctywpwjs872x9kngvvuqdqage5hyum5yp6x2um5yp5kuan0d93k2cqzyskdc5s2ltgm9kklz42x3e4tggdd9lcep2s9t2yk54gnfxg48wxushayrt52zjmua43gdnxmuc5s0c8g29ja9vnxs6x3kxgsha07htcacpmdyl64",
+    regtest:
+      "lnbcrt50u1p5s6w2zpp5juf0r9zutj4zv00kpuuqmgn246azqaq0u5kksx93p46ue94gpmrsdqqcqzzsxqyz5vqsp57u7clsm57nas7c0r2p4ujxr8whla6gxmwf44yqt9f862evjzd3ds9qxpqysgqrwvspjd8g3cfrkg2mrmxfdjcwk5nenw2qnmrys0rvkdmxes6jf5xfykunl5g9hnnahsnz0c90u7k42hmr7w90c0qkw3lllwy40mmqgsqjtyzpd",
+    signet:
+      "lntbs10u1p5s6wgtsp5d8a763exauvdk6s5gwvl8zmuapmgjq05fdv6trasjd4slvgkvzzqpp56vxdyl24hmkpz0tvqq84xdpqqeql3x7kh8tey4uum2cu8jny6djqdq4g9exkgznw3hhyefqyvenyxqzjccqp2rzjqdwy5et9ygczjl2jqmr9e5xm28u3gksjfrf0pht04uwz2lt9d59cypqelcqqq8gqqqqqqqqpqqqqqzsqqc9qxpqysgq0x0pg2s65rnp2cr35td5tq0vwgmnrghkpzt93eypqvvfu5m40pcjl9k2x2m4kqgvz2ez8tzxqgw0nyeg2w60nfky579uakd4mhr3ncgp0xwars",
+  },
+} as const;
+
 describe("BIP-321 Parser", () => {
   describe("Basic Address Parsing", () => {
     test("parses simple mainnet address", () => {
-      const result = parseBIP321("bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa");
+      const result = parseBIP321(
+        `bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}`,
+      );
       expect(result.valid).toBe(true);
-      expect(result.address).toBe("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa");
+      expect(result.address).toBe(TEST_DATA.addresses.mainnet.p2pkh);
       expect(result.network).toBe("mainnet");
       expect(result.paymentMethods.length).toBe(1);
       expect(result.paymentMethods[0]!.type).toBe("onchain");
@@ -20,7 +48,7 @@ describe("BIP-321 Parser", () => {
 
     test("parses bech32 mainnet address", () => {
       const result = parseBIP321(
-        "bitcoin:bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
+        `bitcoin:${TEST_DATA.addresses.mainnet.bech32}`,
       );
       expect(result.valid).toBe(true);
       expect(result.network).toBe("mainnet");
@@ -29,7 +57,7 @@ describe("BIP-321 Parser", () => {
 
     test("parses testnet address", () => {
       const result = parseBIP321(
-        "bitcoin:tb1qghfhmd4zh7ncpmxl3qzhmq566jk8ckq4gafnmg",
+        `bitcoin:${TEST_DATA.addresses.testnet.bech32}`,
       );
       expect(result.valid).toBe(true);
       expect(result.network).toBe("testnet");
@@ -37,7 +65,7 @@ describe("BIP-321 Parser", () => {
 
     test("parses uppercase URI", () => {
       const result = parseBIP321(
-        "BITCOIN:BC1QAR0SRRR7XFKVY5L643LYDNW9RE59GTZZWF5MDQ",
+        `BITCOIN:${TEST_DATA.addresses.mainnet.bech32.toUpperCase()}`,
       );
       expect(result.valid).toBe(true);
       expect(result.network).toBe("mainnet");
@@ -47,7 +75,7 @@ describe("BIP-321 Parser", () => {
   describe("Query Parameters", () => {
     test("parses label parameter", () => {
       const result = parseBIP321(
-        "bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa?label=Luke-Jr",
+        `bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?label=Luke-Jr`,
       );
       expect(result.valid).toBe(true);
       expect(result.label).toBe("Luke-Jr");
@@ -55,7 +83,7 @@ describe("BIP-321 Parser", () => {
 
     test("parses amount parameter", () => {
       const result = parseBIP321(
-        "bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa?amount=20.3",
+        `bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?amount=20.3`,
       );
       expect(result.valid).toBe(true);
       expect(result.amount).toBe(20.3);
@@ -63,7 +91,7 @@ describe("BIP-321 Parser", () => {
 
     test("parses message parameter", () => {
       const result = parseBIP321(
-        "bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa?message=Donation%20for%20project%20xyz",
+        `bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?message=Donation%20for%20project%20xyz`,
       );
       expect(result.valid).toBe(true);
       expect(result.message).toBe("Donation for project xyz");
@@ -71,7 +99,7 @@ describe("BIP-321 Parser", () => {
 
     test("parses multiple parameters", () => {
       const result = parseBIP321(
-        "bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa?amount=50&label=Luke-Jr&message=Donation%20for%20project%20xyz",
+        `bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?amount=50&label=Luke-Jr&message=Donation%20for%20project%20xyz`,
       );
       expect(result.valid).toBe(true);
       expect(result.amount).toBe(50);
@@ -81,7 +109,7 @@ describe("BIP-321 Parser", () => {
 
     test("rejects invalid amount with comma", () => {
       const result = parseBIP321(
-        "bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa?amount=50,000.00",
+        `bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?amount=50,000.00`,
       );
       expect(result.valid).toBe(false);
       expect(result.errors).toContain("Invalid amount format");
@@ -89,7 +117,7 @@ describe("BIP-321 Parser", () => {
 
     test("rejects multiple label parameters", () => {
       const result = parseBIP321(
-        "bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa?label=Luke-Jr&label=Matt",
+        `bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?label=Luke-Jr&label=Matt`,
       );
       expect(result.valid).toBe(false);
       expect(result.errors).toContain("Multiple label parameters not allowed");
@@ -97,7 +125,7 @@ describe("BIP-321 Parser", () => {
 
     test("rejects multiple amount parameters", () => {
       const result = parseBIP321(
-        "bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa?amount=42&amount=10",
+        `bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?amount=42&amount=10`,
       );
       expect(result.valid).toBe(false);
       expect(result.errors).toContain("Multiple amount parameters not allowed");
@@ -107,7 +135,7 @@ describe("BIP-321 Parser", () => {
   describe("Lightning Invoice", () => {
     test("parses lightning invoice with fallback", () => {
       const result = parseBIP321(
-        "bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa?lightning=lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs",
+        `bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?lightning=${TEST_DATA.lightning.mainnet}`,
       );
       expect(result.valid).toBe(true);
       expect(result.paymentMethods.length).toBe(2);
@@ -121,7 +149,7 @@ describe("BIP-321 Parser", () => {
 
     test("parses lightning invoice without fallback", () => {
       const result = parseBIP321(
-        "bitcoin:?lightning=lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs",
+        `bitcoin:?lightning=${TEST_DATA.lightning.mainnet}`,
       );
       expect(result.valid).toBe(true);
       expect(result.address).toBeUndefined();
@@ -131,7 +159,7 @@ describe("BIP-321 Parser", () => {
 
     test("detects signet lightning invoice", () => {
       const result = parseBIP321(
-        "bitcoin:?lightning=lntbs10u1p5s6wgtsp5d8a763exauvdk6s5gwvl8zmuapmgjq05fdv6trasjd4slvgkvzzqpp56vxdyl24hmkpz0tvqq84xdpqqeql3x7kh8tey4uum2cu8jny6djqdq4g9exkgznw3hhyefqyvenyxqzjccqp2rzjqdwy5et9ygczjl2jqmr9e5xm28u3gksjfrf0pht04uwz2lt9d59cypqelcqqq8gqqqqqqqqpqqqqqzsqqc9qxpqysgq0x0pg2s65rnp2cr35td5tq0vwgmnrghkpzt93eypqvvfu5m40pcjl9k2x2m4kqgvz2ez8tzxqgw0nyeg2w60nfky579uakd4mhr3ncgp0xwars",
+        `bitcoin:?lightning=${TEST_DATA.lightning.signet}`,
       );
       expect(result.valid).toBe(true);
       expect(result.paymentMethods[0]!.network).toBe("signet");
@@ -139,7 +167,7 @@ describe("BIP-321 Parser", () => {
 
     test("detects regtest lightning invoice", () => {
       const result = parseBIP321(
-        "bitcoin:?lightning=lnbcrt50u1p5s6w2zpp5juf0r9zutj4zv00kpuuqmgn246azqaq0u5kksx93p46ue94gpmrsdqqcqzzsxqyz5vqsp57u7clsm57nas7c0r2p4ujxr8whla6gxmwf44yqt9f862evjzd3ds9qxpqysgqrwvspjd8g3cfrkg2mrmxfdjcwk5nenw2qnmrys0rvkdmxes6jf5xfykunl5g9hnnahsnz0c90u7k42hmr7w90c0qkw3lllwy40mmqgsqjtyzpd",
+        `bitcoin:?lightning=${TEST_DATA.lightning.regtest}`,
       );
       expect(result.valid).toBe(true);
       expect(result.paymentMethods[0]!.network).toBe("regtest");
@@ -147,7 +175,7 @@ describe("BIP-321 Parser", () => {
 
     test("detects testnet lightning invoice", () => {
       const result = parseBIP321(
-        "bitcoin:?lightning=lntb2500n1pwxlkl5pp5g8hz28tlf950ps942lu3dknfete8yax2ctywpwjs872x9kngvvuqdqage5hyum5yp6x2um5yp5kuan0d93k2cqzyskdc5s2ltgm9kklz42x3e4tggdd9lcep2s9t2yk54gnfxg48wxushayrt52zjmua43gdnxmuc5s0c8g29ja9vnxs6x3kxgsha07htcacpmdyl64",
+        `bitcoin:?lightning=${TEST_DATA.lightning.testnet}`,
       );
       expect(result.valid).toBe(true);
       expect(result.paymentMethods[0]!.network).toBe("testnet");
@@ -155,7 +183,7 @@ describe("BIP-321 Parser", () => {
 
     test("rejects testnet address in bc parameter", () => {
       const result = parseBIP321(
-        "bitcoin:?bc=tb1qghfhmd4zh7ncpmxl3qzhmq566jk8ckq4gafnmg",
+        `bitcoin:?bc=${TEST_DATA.addresses.testnet.bech32}`,
       );
       expect(result.valid).toBe(false);
       expect(result.errors.some((e) => e.includes("network mismatch"))).toBe(
@@ -186,18 +214,12 @@ describe("BIP-321 Parser", () => {
       expect(result.valid).toBe(true);
       expect(result.paymentMethods.length).toBe(2);
     });
-
-    test("parses private payment address", () => {
-      const result = parseBIP321("bitcoin:?pay=bip351address");
-      expect(result.valid).toBe(true);
-      expect(result.paymentMethods[0]!.type).toBe("private-payment");
-    });
   });
 
   describe("Network-specific Parameters", () => {
     test("parses bc parameter for mainnet", () => {
       const result = parseBIP321(
-        "bitcoin:?bc=bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
+        `bitcoin:?bc=${TEST_DATA.addresses.mainnet.bech32}`,
       );
       expect(result.valid).toBe(true);
       expect(result.paymentMethods[0]!.network).toBe("mainnet");
@@ -205,7 +227,7 @@ describe("BIP-321 Parser", () => {
 
     test("parses tb parameter for testnet", () => {
       const result = parseBIP321(
-        "bitcoin:?tb=tb1qghfhmd4zh7ncpmxl3qzhmq566jk8ckq4gafnmg",
+        `bitcoin:?tb=${TEST_DATA.addresses.testnet.bech32}`,
       );
       expect(result.valid).toBe(true);
       expect(result.paymentMethods[0]!.network).toBe("testnet");
@@ -213,7 +235,7 @@ describe("BIP-321 Parser", () => {
 
     test("rejects testnet address in bc parameter", () => {
       const result = parseBIP321(
-        "bitcoin:?bc=tb1qghfhmd4zh7ncpmxl3qzhmq566jk8ckq4gafnmg",
+        `bitcoin:?bc=${TEST_DATA.addresses.testnet.bech32}`,
       );
       expect(result.valid).toBe(false);
       expect(result.errors.some((e) => e.includes("network mismatch"))).toBe(
@@ -223,7 +245,7 @@ describe("BIP-321 Parser", () => {
 
     test("parses multiple segwit versions", () => {
       const result = parseBIP321(
-        "bitcoin:?bc=bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq&bc=bc1pdyp8m5mhurxa9mf822jegnhu49g2zcchgcq8jzrjxg58u2lvudyqftt43a",
+        `bitcoin:?bc=${TEST_DATA.addresses.mainnet.bech32}&bc=${TEST_DATA.addresses.mainnet.taproot}`,
       );
       expect(result.valid).toBe(true);
       expect(result.paymentMethods.length).toBe(2);
@@ -235,7 +257,7 @@ describe("BIP-321 Parser", () => {
   describe("Proof of Payment", () => {
     test("parses pop parameter", () => {
       const result = parseBIP321(
-        "bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa?pop=initiatingapp%3a",
+        `bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?pop=initiatingapp%3a`,
       );
       expect(result.valid).toBe(true);
       expect(result.pop).toBe("initiatingapp%3a");
@@ -244,7 +266,7 @@ describe("BIP-321 Parser", () => {
 
     test("parses req-pop parameter", () => {
       const result = parseBIP321(
-        "bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa?req-pop=callbackuri%3a",
+        `bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?req-pop=callbackuri%3a`,
       );
       expect(result.valid).toBe(true);
       expect(result.pop).toBe("callbackuri%3a");
@@ -253,7 +275,7 @@ describe("BIP-321 Parser", () => {
 
     test("rejects forbidden http scheme in pop", () => {
       const result = parseBIP321(
-        "bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa?pop=https%3aiwantyouripaddress.com",
+        `bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?pop=https%3aiwantyouripaddress.com`,
       );
       expect(
         result.errors.some((e) => e.includes("Forbidden pop scheme")),
@@ -262,14 +284,14 @@ describe("BIP-321 Parser", () => {
 
     test("rejects payment when req-pop uses forbidden scheme", () => {
       const result = parseBIP321(
-        "bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa?req-pop=https%3aevilwebsite.com",
+        `bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?req-pop=https%3aevilwebsite.com`,
       );
       expect(result.valid).toBe(false);
     });
 
     test("rejects multiple pop parameters", () => {
       const result = parseBIP321(
-        "bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa?pop=callback%3a&req-pop=callback%3a",
+        `bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?pop=callback%3a&req-pop=callback%3a`,
       );
       expect(result.valid).toBe(false);
       expect(result.errors.some((e) => e.includes("Multiple pop"))).toBe(true);
@@ -279,7 +301,7 @@ describe("BIP-321 Parser", () => {
   describe("Required Parameters", () => {
     test("rejects unknown required parameters", () => {
       const result = parseBIP321(
-        "bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa?req-somethingyoudontunderstand=50",
+        `bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?req-somethingyoudontunderstand=50`,
       );
       expect(result.valid).toBe(false);
       expect(result.requiredParams.length).toBeGreaterThan(0);
@@ -287,7 +309,7 @@ describe("BIP-321 Parser", () => {
 
     test("accepts unknown optional parameters", () => {
       const result = parseBIP321(
-        "bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa?somethingyoudontunderstand=50",
+        `bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?somethingyoudontunderstand=50`,
       );
       expect(result.valid).toBe(true);
       expect(result.optionalParams.somethingyoudontunderstand).toEqual(["50"]);
@@ -321,7 +343,7 @@ describe("BIP-321 Parser", () => {
   describe("Helper Functions", () => {
     test("getPaymentMethodsByNetwork groups correctly", () => {
       const result = parseBIP321(
-        "bitcoin:bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq?tb=tb1qghfhmd4zh7ncpmxl3qzhmq566jk8ckq4gafnmg",
+        `bitcoin:${TEST_DATA.addresses.mainnet.bech32}?tb=${TEST_DATA.addresses.testnet.bech32}`,
       );
       const byNetwork = getPaymentMethodsByNetwork(result);
       expect(byNetwork.mainnet!.length).toBe(1);
@@ -330,7 +352,7 @@ describe("BIP-321 Parser", () => {
 
     test("getValidPaymentMethods filters correctly", () => {
       const result = parseBIP321(
-        "bitcoin:bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq?lightning=invalidinvoice",
+        `bitcoin:${TEST_DATA.addresses.mainnet.bech32}?lightning=invalidinvoice`,
       );
       const valid = getValidPaymentMethods(result);
       expect(valid.length).toBe(1);
@@ -339,7 +361,7 @@ describe("BIP-321 Parser", () => {
 
     test("formatPaymentMethodsSummary produces output", () => {
       const result = parseBIP321(
-        "bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa?amount=1.5&label=Test",
+        `bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?amount=1.5&label=Test`,
       );
       const summary = formatPaymentMethodsSummary(result);
       expect(summary).toContain("Valid: true");
@@ -351,11 +373,93 @@ describe("BIP-321 Parser", () => {
   describe("Case Insensitivity", () => {
     test("handles mixed case in parameters", () => {
       const result = parseBIP321(
-        "bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa?AMOUNT=1.5&Label=Test",
+        `bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?AMOUNT=1.5&Label=Test`,
       );
       expect(result.valid).toBe(true);
       expect(result.amount).toBe(1.5);
       expect(result.label).toBe("Test");
     });
   });
+
+  describe("Network Validation", () => {
+    test("accepts mainnet address when expecting mainnet", () => {
+      const result = parseBIP321(
+        `bitcoin:${TEST_DATA.addresses.mainnet.bech32}`,
+        "mainnet",
+      );
+      expect(result.valid).toBe(true);
+      expect(result.paymentMethods[0]!.network).toBe("mainnet");
+      expect(result.paymentMethods[0]!.valid).toBe(true);
+    });
+
+    test("rejects testnet address when expecting mainnet", () => {
+      const result = parseBIP321(
+        `bitcoin:${TEST_DATA.addresses.testnet.bech32}`,
+        "mainnet",
+      );
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.includes("network mismatch"))).toBe(
+        true,
+      );
+      expect(result.paymentMethods[0]!.valid).toBe(false);
+    });
+
+    test("accepts testnet lightning invoice when expecting testnet", () => {
+      const result = parseBIP321(
+        `bitcoin:?lightning=${TEST_DATA.lightning.testnet}`,
+        "testnet",
+      );
+      expect(result.valid).toBe(true);
+      expect(result.paymentMethods[0]!.network).toBe("testnet");
+    });
+
+    test("rejects mainnet lightning invoice when expecting testnet", () => {
+      const result = parseBIP321(
+        `bitcoin:?lightning=${TEST_DATA.lightning.mainnet}`,
+        "testnet",
+      );
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.includes("expected testnet"))).toBe(
+        true,
+      );
+    });
+
+    test("rejects mixed networks when expecting specific network", () => {
+      const result = parseBIP321(
+        `bitcoin:${TEST_DATA.addresses.mainnet.bech32}?tb=${TEST_DATA.addresses.testnet.bech32}`,
+        "mainnet",
+      );
+      expect(result.valid).toBe(false);
+      expect(result.paymentMethods[0]!.valid).toBe(true);
+      expect(result.paymentMethods[1]!.valid).toBe(false);
+    });
+
+    test("accepts regtest address when expecting regtest", () => {
+      const result = parseBIP321(
+        `bitcoin:${TEST_DATA.addresses.regtest.bech32}`,
+        "regtest",
+      );
+      expect(result.valid).toBe(true);
+      expect(result.paymentMethods[0]!.network).toBe("regtest");
+    });
+
+    test("works without network parameter (no validation)", () => {
+      const result = parseBIP321(
+        `bitcoin:${TEST_DATA.addresses.mainnet.bech32}?tb=${TEST_DATA.addresses.testnet.bech32}`,
+      );
+      expect(result.valid).toBe(true);
+      expect(result.paymentMethods[0]!.network).toBe("mainnet");
+      expect(result.paymentMethods[1]!.network).toBe("testnet");
+    });
+
+    test("validates all payment methods against expected network", () => {
+      const result = parseBIP321(
+        `bitcoin:${TEST_DATA.addresses.mainnet.bech32}?lightning=${TEST_DATA.lightning.mainnet}`,
+        "mainnet",
+      );
+      expect(result.valid).toBe(true);
+      expect(result.paymentMethods.length).toBe(2);
+      expect(result.paymentMethods.every((pm) => pm.valid)).toBe(true);
+    });
+  });
 });

package/index.ts

@@ -4,13 +4,7 @@ import { sha256 } from "@noble/hashes/sha2.js";
 import { base58, bech32, bech32m } from "@scure/base";
 
 export interface PaymentMethod {
-  type:
-    | "onchain"
-    | "lightning"
-    | "lno"
-    | "silent-payment"
-    | "private-payment"
-    | "other";
+  type: "onchain" | "lightning" | "lno" | "silent-payment" | "other";
   value: string;
   network?: "mainnet" | "testnet" | "regtest" | "signet";
   valid: boolean;
@@ -198,7 +192,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: [],
@@ -353,13 +350,6 @@ export function parseBIP321(uri: string): BIP321ParseResult {
         if (!isSilentPayment) {
           result.errors.push("Invalid silent payment address format");
         }
-      } else if (lowerKey === "pay") {
-        const decodedValue = decodeURIComponent(value);
-        result.paymentMethods.push({
-          type: "private-payment",
-          value: decodedValue,
-          valid: true,
-        });
       } else if (
         lowerKey === "bc" ||
         lowerKey === "tb" ||
@@ -415,6 +405,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bip-321",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "A TypeScript/JavaScript library for parsing BIP-321 Bitcoin URI scheme with support for multiple payment methods",
   "type": "module",
   "main": "./index.ts",

package/CLAUDE.md

@@ -1,107 +0,0 @@
----
-
-Default to using Bun instead of Node.js.
-
-- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
-- Use `bun test` instead of `jest` or `vitest`
-- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
-- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
-- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
-- Bun automatically loads .env, so don't use dotenv.
-
-## APIs
-
-- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
-- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
-- `Bun.redis` for Redis. Don't use `ioredis`.
-- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
-- `WebSocket` is built-in. Don't use `ws`.
-- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
-- Bun.$`ls` instead of execa.
-
-## Testing
-
-Use `bun test` to run tests.
-
-```ts#index.test.ts
-import { test, expect } from "bun:test";
-
-test("hello world", () => {
-  expect(1).toBe(1);
-});
-```
-
-## Frontend
-
-Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.
-
-Server:
-
-```ts#index.ts
-import index from "./index.html"
-
-Bun.serve({
-  routes: {
-    "/": index,
-    "/api/users/:id": {
-      GET: (req) => {
-        return new Response(JSON.stringify({ id: req.params.id }));
-      },
-    },
-  },
-  // optional websocket support
-  websocket: {
-    open: (ws) => {
-      ws.send("Hello, world!");
-    },
-    message: (ws, message) => {
-      ws.send(message);
-    },
-    close: (ws) => {
-      // handle close
-    }
-  },
-  development: {
-    hmr: true,
-    console: true,
-  }
-})
-```
-
-HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle.
-
-```html#index.html
-<html>
-  <body>
-    <h1>Hello, world!</h1>
-    <script type="module" src="./frontend.tsx"></script>
-  </body>
-</html>
-```
-
-With the following `frontend.tsx`:
-
-```tsx#frontend.tsx
-import React from "react";
-
-// import .css files directly and it works
-import './index.css';
-
-import { createRoot } from "react-dom/client";
-
-const root = createRoot(document.body);
-
-export default function Frontend() {
-  return <h1>Hello, world!</h1>;
-}
-
-root.render(<Frontend />);
-```
-
-Then, run index.ts
-
-```sh
-bun --hot ./index.ts
-```
-
-For more information, read the Bun API docs in `node_modules/bun-types/docs/**.md`.