bip-321 0.0.7 → 0.0.9

package/README.md

@@ -27,6 +27,18 @@ result.paymentMethods.forEach((method: PaymentMethod) => {
 });
 ```
 
+```typescript
+import { encodeBIP321 } from "bip-321";
+
+try {
+  const { uri } = encodeBIP321({ address: "bitcoin_address", label: "Label", message: "Message", amount: 0.5 });
+
+  // uri = bitcoin:bitcoin_address?label=Label&message=Message&amount=0.5
+} catch (error) {
+  console.error(error)
+}
+```
+
 ## Installation
 
 ```bash
@@ -42,7 +54,7 @@ npm install bip-321
 ## Quick Start
 
 ```typescript
-import { parseBIP321 } from "bip-321";
+import { parseBIP321, encodeBIP321 } from "bip-321";
 
 // Parse a simple Bitcoin address
 const result = parseBIP321("bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa");
@@ -51,6 +63,15 @@ console.log(result.valid); // true
 console.log(result.network); // "mainnet"
 console.log(result.address); // "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
 console.log(result.paymentMethods); // Array of payment methods
+
+// Encode a simple Bitcoin address
+try {
+  const { uri } = encodeBIP321({ address: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa" });
+
+  console.log(uri); // bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
+} catch (error) {
+  console.error(error)
+}
 ```
 
 ## Validation Functions
@@ -140,9 +161,11 @@ result.paymentMethods.forEach((method) => {
 ### Lightning-Only Payment
 
 ```typescript
-const result = parseBIP321(
-  "bitcoin:?lightning=lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3s..."
-);
+// Encode lightning-only payment (no on-chain address)
+const { uri } = encodeBIP321({ lightning: "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3s..." });
+
+// Parse lightning-only payment
+const result = parseBIP321(uri);
 
 console.log(result.paymentMethods[0].type); // "lightning"
 console.log(result.paymentMethods[0].network); // "mainnet"
@@ -151,18 +174,18 @@ console.log(result.paymentMethods[0].network); // "mainnet"
 ### Ark Payment
 
 ```typescript
-// Mainnet Ark address
-const result = parseBIP321(
-  "bitcoin:?ark=ark1pwh9vsmezqqpjy9akejayl2vvcse6he97rn40g84xrlvrlnhayuuyefrp9nse2yspqqjl5wpy"
-);
+// Encode Ark-only payment (no on-chain address)
+const { uri } = encodeBIP321({ ark: "ark1pwh9vsmezqqpjy9akejayl2vvcse6he97rn40g84xrlvrlnhayuuyefrp9nse2yspqqjl5wpy" });
+
+// Parse Ark payment
+const result = parseBIP321(uri);
 
 console.log(result.paymentMethods[0].type); // "ark"
 console.log(result.paymentMethods[0].network); // "mainnet"
 
 // Testnet Ark address
-const testnetResult = parseBIP321(
-  "bitcoin:?ark=tark1pm6sr0fpzqqpnzzwxf209kju4qavs4gtumxk30yv2u5ncrvtp72z34axcvrydtdqpqq5838km"
-);
+const { uri: testnetUri } = encodeBIP321({ ark: "tark1pm6sr0fpzqqpnzzwxf209kju4qavs4gtumxk30yv2u5ncrvtp72z34axcvrydtdqpqq5838km" });
+const testnetResult = parseBIP321(testnetUri);
 
 console.log(testnetResult.paymentMethods[0].network); // "testnet"
 ```
@@ -238,6 +261,51 @@ Parses a BIP-321 URI and returns detailed information about the payment request.
 
 **Returns:** `BIP321ParseResult` object
 
+### `encodeBIP321(params: BIP321EncodeParams): BIP321EncodeResult`
+
+Encodes payment parameters into a BIP-321 URI string. Validates the generated URI before returning.
+
+**Parameters:**
+- `params` - The `BIP321EncodeParams` object containing payment details
+
+**Returns:** `BIP321EncodeResult` object
+
+**Throws:** `Error` if the generated URI is invalid or contains no valid payment methods
+
+### `BIP321EncodeParams` Interface
+
+```typescript
+interface BIP321EncodeParams {
+  address?: string;                              // Main Bitcoin address
+  amount?: number;                               // Amount in BTC
+  label?: string;                                // Label for the recipient
+  message?: string;                              // Message describing the transaction
+  lightning?: string | string[];                 // BOLT11 Lightning invoice(s)
+  lno?: string | string[];                       // BOLT12 offer(s)
+  sp?: string | string[];                        // Silent Payment address(es)
+  ark?: string | string[];                       // Ark address(es)
+  bc?: string | string[];                        // Mainnet address(es)
+  tb?: string | string[];                        // Testnet address(es)
+  bcrt?: string | string[];                      // Regtest address(es)
+  tbs?: string | string[];                       // Signet address(es)
+  pop?: string;                                  // Proof of payment callback URI
+  reqPop?: string;                               // Required proof of payment callback URI
+  optionalParams?: Record<string, string | string[]>; // Additional optional parameters
+}
+```
+
+**Note:** `pop` and `reqPop` are mutually exclusive - only one can be provided.
+
+### `BIP321EncodeResult` Interface
+
+```typescript
+interface BIP321EncodeResult extends BIP321ParseResult {
+  uri: string; // The encoded BIP-321 URI string
+}
+```
+
+The result includes all fields from `BIP321ParseResult` plus the generated `uri` string.
+
 ### Validation Functions
 
 The library exports individual validation functions for each payment method type:

package/bun.lock

@@ -1,5 +1,6 @@
 {
   "lockfileVersion": 1,
+  "configVersion": 0,
   "workspaces": {
     "": {
       "name": "bip-321",

package/index.test.ts

@@ -4,6 +4,7 @@ import {
   getPaymentMethodsByNetwork,
   getValidPaymentMethods,
   formatPaymentMethodsSummary,
+  encodeBIP321,
 } from "./index";
 
 const TEST_DATA = {
@@ -599,3 +600,367 @@ describe("BIP-321 Parser", () => {
     });
   });
 });
+
+describe("BIP-321 Encoder", () => {
+  describe("Basic Encoding", () => {
+    test("encodes simple address", () => {
+      const result = encodeBIP321({ address: TEST_DATA.addresses.mainnet.p2pkh });
+      expect(result.valid).toBe(true);
+      expect(result.uri).toBe(`bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}`);
+    });
+
+    test("encodes bech32 address", () => {
+      const result = encodeBIP321({ address: TEST_DATA.addresses.mainnet.bech32 });
+      expect(result.valid).toBe(true);
+      expect(result.uri).toBe(`bitcoin:${TEST_DATA.addresses.mainnet.bech32}`);
+    });
+
+    test("encodes taproot address", () => {
+      const result = encodeBIP321({ address: TEST_DATA.addresses.mainnet.taproot });
+      expect(result.valid).toBe(true);
+      expect(result.uri).toBe(`bitcoin:${TEST_DATA.addresses.mainnet.taproot}`);
+    });
+
+    test("encodes testnet address", () => {
+      const result = encodeBIP321({ address: TEST_DATA.addresses.testnet.bech32 });
+      expect(result.valid).toBe(true);
+      expect(result.network).toBe("testnet");
+      expect(result.uri).toBe(`bitcoin:${TEST_DATA.addresses.testnet.bech32}`);
+    });
+
+    test("encodes empty address with query params", () => {
+      const result = encodeBIP321({ lightning: TEST_DATA.lightning.mainnet });
+      expect(result.valid).toBe(true);
+      expect(result.uri).toBe(`bitcoin:?lightning=${TEST_DATA.lightning.mainnet}`);
+    });
+  });
+
+  describe("Query Parameters", () => {
+    test("encodes label parameter", () => {
+      const result = encodeBIP321({ address: TEST_DATA.addresses.mainnet.p2pkh, label: "bip321" });
+      expect(result.uri).toBe(`bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?label=bip321`);
+    });
+
+    test("encodes message parameter", () => {
+      const result = encodeBIP321({ address: TEST_DATA.addresses.mainnet.p2pkh, message: "bip321" });
+      expect(result.uri).toBe(`bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?message=bip321`);
+    });
+
+    test("encodes amount parameter", () => {
+      const result = encodeBIP321({ address: TEST_DATA.addresses.mainnet.p2pkh, amount: 20.3 });
+      expect(result.valid).toBe(true);
+      expect(result.amount).toBe(20.3);
+      expect(result.uri).toBe(`bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?amount=20.3`);
+    });
+
+    test("encodes zero amount", () => {
+      const result = encodeBIP321({ address: TEST_DATA.addresses.mainnet.p2pkh, amount: 0 });
+      expect(result.valid).toBe(true);
+      expect(result.amount).toBe(0);
+      expect(result.uri).toBe(`bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?amount=0`)
+    });
+
+    test("encodes multiple parameters", () => {
+      const result = encodeBIP321({
+        address: TEST_DATA.addresses.mainnet.p2pkh,
+        amount: 50,
+        label: "Luke-Jr",
+        message: "Donation for project xyz",
+      });
+      expect(result.valid).toBe(true);
+      expect(result.amount).toBe(50);
+      expect(result.label).toBe("Luke-Jr");
+      expect(result.message).toBe("Donation for project xyz");
+      expect(result.uri).toBe(`bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?amount=50&label=Luke-Jr&message=Donation%20for%20project%20xyz`);
+    });
+
+    test("encodes special characters in label", () => {
+      const result = encodeBIP321({ address: TEST_DATA.addresses.mainnet.p2pkh, label: "Test & Label" });
+      expect(result.valid).toBe(true);
+      expect(result.label).toBe("Test & Label");
+      expect(result.uri).toBe(`bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?label=Test%20%26%20Label`);
+    });
+
+    test("encodes special characters in message", () => {
+      const result = encodeBIP321({ address: TEST_DATA.addresses.mainnet.p2pkh, message: "Donation for project xyz" });
+      expect(result.valid).toBe(true);
+      expect(result.message).toBe("Donation for project xyz");
+      expect(result.uri).toBe(`bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?message=Donation%20for%20project%20xyz`);
+    });
+  });
+
+  describe("Lightning Invoice", () => {
+    test("encodes with single lightning invoice", () => {
+      const result = encodeBIP321({
+        address: TEST_DATA.addresses.mainnet.p2pkh,
+        lightning: TEST_DATA.lightning.mainnet,
+      });
+      expect(result.valid).toBe(true);
+      expect(result.paymentMethods.some((pm) => pm.type === "lightning")).toBe(true);
+      expect(result.uri).toBe(`bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?lightning=${TEST_DATA.lightning.mainnet}`);
+    });
+
+    test("encodes with multiple lightning invoices", () => {
+      const result = encodeBIP321({
+        lightning: [TEST_DATA.lightning.mainnet, TEST_DATA.lightning.mainnet],
+      });
+      expect(result.valid).toBe(true);
+      expect(result.paymentMethods.filter((pm) => pm.type === "lightning").length).toBe(2);
+      expect(result.uri).toBe(`bitcoin:?lightning=${TEST_DATA.lightning.mainnet}&lightning=${TEST_DATA.lightning.mainnet}`);
+    });
+
+    test("encodes lightning without address", () => {
+      const result = encodeBIP321({ lightning: TEST_DATA.lightning.mainnet });
+      expect(result.valid).toBe(true);
+      expect(result.uri).toBe(`bitcoin:?lightning=${TEST_DATA.lightning.mainnet}`);
+    });
+
+    test("encodes testnet lightning invoice", () => {
+      const result = encodeBIP321({ lightning: TEST_DATA.lightning.testnet });
+      expect(result.valid).toBe(true);
+      expect(result.paymentMethods[0]!.network).toBe("testnet");
+      expect(result.uri).toBe(`bitcoin:?lightning=${TEST_DATA.lightning.testnet}`);
+    });
+  });
+
+  describe("Alternative Payment Methods", () => {
+    test("encodes silent payment address", () => {
+      const result = encodeBIP321({ sp: TEST_DATA.silentPayment.mainnet });
+      expect(result.valid).toBe(true);
+      expect(result.paymentMethods[0]!.type).toBe("silent-payment");
+      expect(result.paymentMethods[0]!.network).toBe("mainnet");
+      expect(result.uri).toBe(`bitcoin:?sp=${TEST_DATA.silentPayment.mainnet}`);
+    });
+
+    test("encodes testnet silent payment address", () => {
+      const result = encodeBIP321({ sp: TEST_DATA.silentPayment.testnet });
+      expect(result.valid).toBe(true);
+      expect(result.paymentMethods[0]!.network).toBe("testnet");
+      expect(result.uri).toBe(`bitcoin:?sp=${TEST_DATA.silentPayment.testnet}`);
+    });
+
+    test("encodes multiple silent payment addresses", () => {
+      const result = encodeBIP321({
+        sp: [TEST_DATA.silentPayment.mainnet, TEST_DATA.silentPayment.mainnet],
+      });
+      expect(result.valid).toBe(true);
+      expect(result.paymentMethods.filter((pm) => pm.type === "silent-payment").length).toBe(2);
+      expect(result.uri).toBe(`bitcoin:?sp=${TEST_DATA.silentPayment.mainnet}&sp=${TEST_DATA.silentPayment.mainnet}`);
+    });
+
+    test("encodes Ark address", () => {
+      const result = encodeBIP321({ ark: TEST_DATA.ark.mainnet });
+      expect(result.valid).toBe(true);
+      expect(result.paymentMethods[0]!.type).toBe("ark");
+      expect(result.paymentMethods[0]!.network).toBe("mainnet");
+      expect(result.uri).toBe(`bitcoin:?ark=${TEST_DATA.ark.mainnet}`);
+    });
+
+    test("encodes testnet Ark address", () => {
+      const result = encodeBIP321({ ark: TEST_DATA.ark.testnet });
+      expect(result.valid).toBe(true);
+      expect(result.paymentMethods[0]!.network).toBe("testnet");
+      expect(result.uri).toBe(`bitcoin:?ark=${TEST_DATA.ark.testnet}`);
+    });
+
+    test("encodes BOLT12 offer", () => {
+      const result = encodeBIP321({ lno: "lno1qqqq02k20d" });
+      expect(result.valid).toBe(true);
+      expect(result.paymentMethods[0]!.type).toBe("offer");
+      expect(result.uri).toBe("bitcoin:?lno=lno1qqqq02k20d");
+    });
+  });
+
+  describe("Network-specific Addresses", () => {
+    test("encodes bc parameter", () => {
+      const result = encodeBIP321({ bc: TEST_DATA.addresses.mainnet.bech32 });
+      expect(result.valid).toBe(true);
+      expect(result.paymentMethods[0]!.network).toBe("mainnet");
+      expect(result.uri).toBe(`bitcoin:?bc=${TEST_DATA.addresses.mainnet.bech32}`);
+    });
+
+    test("encodes tb parameter", () => {
+      const result = encodeBIP321({ tb: TEST_DATA.addresses.testnet.bech32 });
+      expect(result.valid).toBe(true);
+      expect(result.paymentMethods[0]!.network).toBe("testnet");
+      expect(result.uri).toBe(`bitcoin:?tb=${TEST_DATA.addresses.testnet.bech32}`);
+    });
+
+    test("encodes bcrt parameter", () => {
+      const result = encodeBIP321({ bcrt: TEST_DATA.addresses.regtest.bech32 });
+      expect(result.valid).toBe(true);
+      expect(result.paymentMethods[0]!.network).toBe("regtest");
+      expect(result.uri).toBe(`bitcoin:?bcrt=${TEST_DATA.addresses.regtest.bech32}`);
+    });
+
+    test("encodes multiple bc addresses", () => {
+      const result = encodeBIP321({
+        bc: [TEST_DATA.addresses.mainnet.bech32, TEST_DATA.addresses.mainnet.taproot],
+      });
+      expect(result.valid).toBe(true);
+      expect(result.paymentMethods.length).toBe(2);
+      expect(result.uri).toBe(`bitcoin:?bc=${TEST_DATA.addresses.mainnet.bech32}&bc=${TEST_DATA.addresses.mainnet.taproot}`);
+    });
+  });
+
+  describe("Proof of Payment", () => {
+    test("encodes pop parameter", () => {
+      const result = encodeBIP321({
+        address: TEST_DATA.addresses.mainnet.p2pkh,
+        pop: "customapp:",
+      });
+      expect(result.valid).toBe(true);
+      expect(result.pop).toBeDefined();
+      expect(result.popRequired).toBe(false);
+      expect(result.uri).toBe(`bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?pop=customapp%3A`);
+    });
+
+    test("encodes req-pop parameter", () => {
+      const result = encodeBIP321({
+        address: TEST_DATA.addresses.mainnet.p2pkh,
+        reqPop: "customapp:",
+      });
+      expect(result.valid).toBe(true);
+      expect(result.pop).toBeDefined();
+      expect(result.popRequired).toBe(true);
+      expect(result.uri).toBe(`bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?req-pop=customapp%3A`);
+    });
+  });
+
+  describe("Optional Parameters", () => {
+    test("encodes custom optional parameters", () => {
+      const result = encodeBIP321({
+        address: TEST_DATA.addresses.mainnet.p2pkh,
+        optionalParams: { custom: "value" },
+      });
+      expect(result.valid).toBe(true);
+      expect(result.optionalParams.custom).toEqual(["value"]);
+      expect(result.uri).toBe(`bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?custom=value`);
+    });
+
+    test("encodes multiple custom optional parameters", () => {
+      const result = encodeBIP321({
+        address: TEST_DATA.addresses.mainnet.p2pkh,
+        optionalParams: { foo: "bar", baz: ["one", "two"] },
+      });
+      expect(result.valid).toBe(true);
+      expect(result.optionalParams.foo).toEqual(["bar"]);
+      expect(result.optionalParams.baz).toEqual(["one", "two"]);
+      expect(result.uri).toBe(`bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?foo=bar&baz=one&baz=two`);
+    });
+  });
+
+  describe("Combined Payment Methods", () => {
+    test("encodes address with lightning and silent payment", () => {
+      const result = encodeBIP321({
+        address: TEST_DATA.addresses.mainnet.p2pkh,
+        lightning: TEST_DATA.lightning.mainnet,
+        sp: TEST_DATA.silentPayment.mainnet,
+      });
+      expect(result.valid).toBe(true);
+      expect(result.paymentMethods.length).toBe(3);
+      expect(result.paymentMethods.some((pm) => pm.type === "onchain")).toBe(true);
+      expect(result.paymentMethods.some((pm) => pm.type === "lightning")).toBe(true);
+      expect(result.paymentMethods.some((pm) => pm.type === "silent-payment")).toBe(true);
+      expect(result.uri).toBe(`bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?lightning=${TEST_DATA.lightning.mainnet}&sp=${TEST_DATA.silentPayment.mainnet}`);
+    });
+
+    test("encodes all parameters together", () => {
+      const result = encodeBIP321({
+        address: TEST_DATA.addresses.mainnet.p2pkh,
+        amount: 0.5,
+        label: "Test",
+        message: "Payment",
+        lightning: TEST_DATA.lightning.mainnet,
+        sp: TEST_DATA.silentPayment.mainnet,
+        ark: TEST_DATA.ark.mainnet,
+      });
+      expect(result.valid).toBe(true);
+      expect(result.amount).toBe(0.5);
+      expect(result.label).toBe("Test");
+      expect(result.message).toBe("Payment");
+      expect(result.paymentMethods.length).toBe(4);
+      expect(result.uri).toBe(`bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?amount=0.5&label=Test&message=Payment&lightning=${TEST_DATA.lightning.mainnet}&sp=${TEST_DATA.silentPayment.mainnet}&ark=${TEST_DATA.ark.mainnet}`);
+    });
+  });
+
+  describe("Invalid Data", () => {
+    test("throws on invalid address", () => {
+      expect(() => encodeBIP321({ address: "invalid_bitcoin_address" })).toThrow();
+    });
+
+    test("throws on negative amount", () => {
+      expect(() => encodeBIP321({
+        address: TEST_DATA.addresses.mainnet.p2pkh,
+        amount: -1,
+      })).toThrow("Invalid amount format");
+    });
+
+    test("throws on NaN amount", () => {
+      expect(() => encodeBIP321({
+        address: TEST_DATA.addresses.mainnet.p2pkh,
+        amount: NaN,
+      })).toThrow("Invalid amount format");
+    });
+
+    test("throws on Infinity amount", () => {
+      expect(() => encodeBIP321({
+        address: TEST_DATA.addresses.mainnet.p2pkh,
+        amount: Infinity,
+      })).toThrow("Invalid amount format");
+    });
+
+    test("throws on invalid lightning invoice", () => {
+      expect(() => encodeBIP321({ lightning: "invalid_invoice" })).toThrow(/lightning/i);
+    });
+
+    test("throws on invalid silent payment address", () => {
+      expect(() => encodeBIP321({ sp: "sp1invalid" })).toThrow(/silent payment/i);
+    });
+
+    test("throws on invalid Ark address", () => {
+      expect(() => encodeBIP321({ ark: "ark1invalid" })).toThrow(/Ark/i);
+    });
+
+    test("throws on forbidden pop scheme", () => {
+      expect(() => encodeBIP321({
+        address: TEST_DATA.addresses.mainnet.p2pkh,
+        reqPop: "https://example.com",
+      })).toThrow(/Forbidden pop scheme/i);
+    });
+
+    test("throws on network mismatch in bc parameter", () => {
+      expect(() => encodeBIP321({ bc: TEST_DATA.addresses.testnet.bech32 })).toThrow(/network mismatch/i);
+    });
+
+    test("throws on empty params with no payment method", () => {
+      expect(() => encodeBIP321({ label: "test" })).toThrow("No valid payment methods found");
+    });
+  });
+
+  describe("Round-trip Encoding", () => {
+    test("encoded URI can be parsed back", () => {
+      const params = {
+        address: TEST_DATA.addresses.mainnet.p2pkh,
+        amount: 1.5,
+        label: "Test Label",
+        message: "Test Message",
+      };
+      const encoded = encodeBIP321(params);
+      expect(encoded.valid).toBe(true);
+      expect(encoded.address).toBe(params.address);
+      expect(encoded.amount).toBe(params.amount);
+      expect(encoded.label).toBe(params.label);
+      expect(encoded.message).toBe(params.message);
+      expect(encoded.uri).toBe(`bitcoin:${TEST_DATA.addresses.mainnet.p2pkh}?amount=1.5&label=Test%20Label&message=Test%20Message`);
+    });
+
+    test("encoded lightning URI can be parsed back", () => {
+      const encoded = encodeBIP321({ lightning: TEST_DATA.lightning.mainnet });
+      expect(encoded.valid).toBe(true);
+      expect(encoded.paymentMethods[0]!.type).toBe("lightning");
+      expect(encoded.paymentMethods[0]!.value).toBe(TEST_DATA.lightning.mainnet);
+      expect(encoded.uri).toBe(`bitcoin:?lightning=${TEST_DATA.lightning.mainnet}`);
+    });
+  });
+});

package/index.ts

@@ -17,17 +17,19 @@ export {
   validatePopUri,
 };
 
+export type Network = "mainnet" | "testnet" | "regtest" | "signet";
+
 export interface PaymentMethod {
   type: "onchain" | "lightning" | "offer" | "silent-payment" | "ark";
   value: string;
-  network?: "mainnet" | "testnet" | "regtest" | "signet";
+  network?: Network;
   valid: boolean;
   error?: string;
 }
 
 export interface BIP321ParseResult {
   address?: string;
-  network?: "mainnet" | "testnet" | "regtest" | "signet";
+  network?: Network;
   amount?: number;
   label?: string;
   message?: string;
@@ -42,7 +44,7 @@ export interface BIP321ParseResult {
 
 export function parseBIP321(
   uri: string,
-  expectedNetwork?: "mainnet" | "testnet" | "regtest" | "signet",
+  expectedNetwork?: Network,
 ): BIP321ParseResult {
   const result: BIP321ParseResult = {
     paymentMethods: [],
@@ -232,7 +234,12 @@ export function parseBIP321(
         const decodedValue = decodeURIComponent(value);
         const validation = validateBitcoinAddress(decodedValue);
         const networkMatches =
-          validation.valid && validation.network === expectedNetwork;
+          validation.valid &&
+          (validation.network === expectedNetwork ||
+            // Testnet and signet are interchangeable for onchain
+            (validation.network === "testnet" &&
+              expectedNetwork === "signet") ||
+            (validation.network === "signet" && expectedNetwork === "testnet"));
 
         result.paymentMethods.push({
           type: "onchain",
@@ -274,12 +281,16 @@ export function parseBIP321(
     for (const method of result.paymentMethods) {
       if (method.network && method.network !== expectedNetwork) {
         // For Ark and Silent Payments, testnet covers testnet/signet/regtest
+        // For onchain, testnet and signet are interchangeable
         const isTestnetCompatible =
-          (method.type === "ark" || method.type === "silent-payment") &&
-          method.network === "testnet" &&
-          (expectedNetwork === "testnet" ||
-            expectedNetwork === "signet" ||
-            expectedNetwork === "regtest");
+          ((method.type === "ark" || method.type === "silent-payment") &&
+            method.network === "testnet" &&
+            (expectedNetwork === "testnet" ||
+              expectedNetwork === "signet" ||
+              expectedNetwork === "regtest")) ||
+          (method.type === "onchain" &&
+            ((method.network === "testnet" && expectedNetwork === "signet") ||
+              (method.network === "signet" && expectedNetwork === "testnet")));
 
         if (!isTestnetCompatible) {
           result.errors.push(
@@ -305,6 +316,90 @@ export function parseBIP321(
   return result;
 }
 
+interface BIP321EncodeParamsBase {
+  address?: string;
+  amount?: number;
+  label?: string;
+  message?: string;
+  lightning?: string | string[];
+  lno?: string | string[];
+  sp?: string | string[];
+  ark?: string | string[];
+  bc?: string | string[];
+  tb?: string | string[];
+  bcrt?: string | string[];
+  tbs?: string | string[];
+  optionalParams?: Record<string, string | string[]>;
+}
+
+// Make pop and reqPop mutually exclusive using discriminated union
+export type BIP321EncodeParams = BIP321EncodeParamsBase &
+  (
+    | { pop?: string; reqPop?: never }
+    | { pop?: never; reqPop?: string }
+    | { pop?: never; reqPop?: never }
+  );
+
+export type BIP321EncodeResult = BIP321ParseResult & { uri: string }
+
+export function encodeBIP321(params: BIP321EncodeParams): BIP321EncodeResult {
+  const searchParams = new URLSearchParams();
+
+  const append = (key: string, value: string | string[] | undefined) => {
+    if (value === undefined) return;
+    const values = Array.isArray(value) ? value : [value];
+    for (const v of values) {
+      searchParams.append(key, v);
+    }
+  };
+
+  if (params.amount !== undefined) {
+    if (Number.isNaN(params.amount) || !Number.isFinite(params.amount) || params.amount < 0) {
+      throw new Error("Invalid amount format");
+    }
+    searchParams.append("amount", params.amount.toString());
+  }
+
+  append("label", params.label);
+  append("message", params.message);
+
+  if (params.pop !== undefined) {
+    searchParams.append("pop", params.pop);
+  } else if (params.reqPop !== undefined) {
+    searchParams.append("req-pop", params.reqPop);
+  }
+
+  append("lightning", params.lightning);
+  append("lno", params.lno);
+  append("sp", params.sp);
+  append("ark", params.ark);
+
+  append("bc", params.bc);
+  append("tb", params.tb);
+  append("bcrt", params.bcrt);
+  append("tbs", params.tbs);
+
+  if (params.optionalParams) {
+    for (const [key, value] of Object.entries(params.optionalParams)) {
+      append(key, value);
+    }
+  }
+
+  const address = params.address ?? "";
+
+  // URLSearchParams encodes spaces as '+', but BIP-321 expects percent encoding
+  const query = searchParams.toString().replace(/\+/g, "%20");
+  const uri = `bitcoin:${address}${query ? `?${query}` : ""}`;
+  const parsed = parseBIP321(uri);
+
+  const hasValidPaymentMethod = parsed.paymentMethods.some((pm) => pm.valid);
+  if (!parsed.valid || !hasValidPaymentMethod) {
+    throw new Error(parsed.errors.join("; ") || "No valid payment methods");
+  }
+
+  return { ...parsed, uri };
+}
+
 export function getPaymentMethodsByNetwork(
   result: BIP321ParseResult,
 ): Record<string, PaymentMethod[]> {

package/package.json

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