bip-321 0.0.3 → 0.0.5

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,7 +5,7 @@ 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, and silent payments
+- ✅ **Multiple payment methods** - Supports on-chain, Lightning (BOLT11), BOLT12 offers, silent payments, and Ark
 - ✅ **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
@@ -21,7 +21,7 @@ result.paymentMethods;  // PaymentMethod[]
 result.errors;          // string[]
 
 result.paymentMethods.forEach((method: PaymentMethod) => {
-  method.type;    // "onchain" | "lightning" | "lno" | "silent-payment" | "other"
+  method.type;    // "onchain" | "lightning" | "offer" | "silent-payment" | "ark"
   method.network; // "mainnet" | "testnet" | "regtest" | "signet" | undefined
   method.valid;   // boolean
 });
@@ -105,6 +105,49 @@ console.log(result.paymentMethods[0].type); // "lightning"
 console.log(result.paymentMethods[0].network); // "mainnet"
 ```
 
+### Ark Payment
+
+```typescript
+// Mainnet Ark address
+const result = parseBIP321(
+  "bitcoin:?ark=ark1pwh9vsmezqqpjy9akejayl2vvcse6he97rn40g84xrlvrlnhayuuyefrp9nse2yspqqjl5wpy"
+);
+
+console.log(result.paymentMethods[0].type); // "ark"
+console.log(result.paymentMethods[0].network); // "mainnet"
+
+// Testnet Ark address
+const testnetResult = parseBIP321(
+  "bitcoin:?ark=tark1pm6sr0fpzqqpnzzwxf209kju4qavs4gtumxk30yv2u5ncrvtp72z34axcvrydtdqpqq5838km"
+);
+
+console.log(testnetResult.paymentMethods[0].network); // "testnet"
+```
+
+### 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
@@ -112,7 +155,7 @@ const result = parseBIP321(
   "bitcoin:?lightning=lnbc...&lno=lno1bogusoffer&sp=sp1qsilentpayment"
 );
 
-// Returns 3 payment methods: lightning, lno (BOLT12), and silent-payment
+// Returns 3 payment methods: lightning, offer (BOLT12), and silent-payment
 console.log(`Total payment methods: ${result.paymentMethods.length}`);
 ```
 
@@ -142,12 +185,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:
 
@@ -181,7 +240,7 @@ interface BIP321ParseResult {
 
 ```typescript
 interface PaymentMethod {
-  type: "onchain" | "lightning" | "lno" | "silent-payment" | "other";
+  type: "onchain" | "lightning" | "offer" | "silent-payment" | "ark";
   value: string; // The actual address/invoice value
   network?: "mainnet" | "testnet" | "regtest" | "signet";
   valid: boolean; // Whether this payment method is valid
@@ -231,8 +290,9 @@ console.log(summary);
 |--------|--------------|-------------|
 | On-chain | `address` or `bc`/`tb`/`bcrt`/`tbs` | Bitcoin addresses (P2PKH, P2SH, Segwit, Taproot) |
 | Lightning | `lightning` | BOLT11 Lightning invoices |
-| BOLT12 | `lno` | Lightning BOLT12 offers |
+| BOLT12 Offer | `lno` | Lightning BOLT12 offers |
 | Silent Payments | `sp` | BIP352 Silent Payment addresses |
+| Ark | `ark` | Ark addresses (mainnet: `ark1...`, testnet: `tark1...`) |
 
 ## Network Detection
 
@@ -249,6 +309,10 @@ The library automatically detects the network from:
 - **Regtest**: `lnbcrt...`
 - **Signet**: `lntbs...`
 
+### Ark Addresses
+- **Mainnet**: `ark1...`
+- **Testnet**: `tark1...`
+
 ## Validation Rules
 
 The parser enforces BIP-321 validation rules:
@@ -261,6 +325,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
 
@@ -307,15 +372,15 @@ 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)
+- [BIP-352 Silent Payments](https://github.com/bitcoin/bips/blob/master/bip-0352.mediawiki)
+- [BOAT-0001 Ark Address Format](https://github.com/ark-protocol/boats/blob/master/boat-0001.md)
+- [BOLT11 Lightning Invoices](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md)
+- [BOLT12 Lightning Offers](https://github.com/lightning/bolts/blob/master/12-offer-encoding.md)