@wopr-network/platform-core 1.57.0 → 1.58.1

package/dist/billing/crypto/__tests__/address-gen.test.js

@@ -0,0 +1,118 @@
+import { HDKey } from "@scure/bip32";
+import { describe, expect, it } from "vitest";
+import { deriveAddress, deriveTreasury, isValidXpub } from "../address-gen.js";
+function makeTestXpub(path) {
+    const seed = new Uint8Array(32);
+    seed[0] = 1;
+    const master = HDKey.fromMasterSeed(seed);
+    return master.derive(path).publicExtendedKey;
+}
+const BTC_XPUB = makeTestXpub("m/44'/0'/0'");
+const ETH_XPUB = makeTestXpub("m/44'/60'/0'");
+describe("deriveAddress — bech32 (BTC)", () => {
+    it("derives a valid bc1q address", () => {
+        const addr = deriveAddress(BTC_XPUB, 0, "bech32", { hrp: "bc" });
+        expect(addr).toMatch(/^bc1q[a-z0-9]+$/);
+    });
+    it("derives different addresses for different indices", () => {
+        const a = deriveAddress(BTC_XPUB, 0, "bech32", { hrp: "bc" });
+        const b = deriveAddress(BTC_XPUB, 1, "bech32", { hrp: "bc" });
+        expect(a).not.toBe(b);
+    });
+    it("is deterministic", () => {
+        const a = deriveAddress(BTC_XPUB, 42, "bech32", { hrp: "bc" });
+        const b = deriveAddress(BTC_XPUB, 42, "bech32", { hrp: "bc" });
+        expect(a).toBe(b);
+    });
+    it("uses tb prefix for testnet", () => {
+        const addr = deriveAddress(BTC_XPUB, 0, "bech32", { hrp: "tb" });
+        expect(addr).toMatch(/^tb1q[a-z0-9]+$/);
+    });
+    it("rejects negative index", () => {
+        expect(() => deriveAddress(BTC_XPUB, -1, "bech32", { hrp: "bc" })).toThrow("Invalid");
+    });
+    it("throws without hrp param", () => {
+        expect(() => deriveAddress(BTC_XPUB, 0, "bech32", {})).toThrow("hrp");
+    });
+});
+describe("deriveAddress — bech32 (LTC)", () => {
+    const LTC_XPUB = makeTestXpub("m/44'/2'/0'");
+    it("derives a valid ltc1q address", () => {
+        const addr = deriveAddress(LTC_XPUB, 0, "bech32", { hrp: "ltc" });
+        expect(addr).toMatch(/^ltc1q[a-z0-9]+$/);
+    });
+});
+describe("deriveAddress — p2pkh (DOGE)", () => {
+    const DOGE_XPUB = makeTestXpub("m/44'/3'/0'");
+    it("derives a valid D... address", () => {
+        const addr = deriveAddress(DOGE_XPUB, 0, "p2pkh", { version: "0x1e" });
+        expect(addr).toMatch(/^D[a-km-zA-HJ-NP-Z1-9]+$/);
+    });
+    it("derives different addresses for different indices", () => {
+        const a = deriveAddress(DOGE_XPUB, 0, "p2pkh", { version: "0x1e" });
+        const b = deriveAddress(DOGE_XPUB, 1, "p2pkh", { version: "0x1e" });
+        expect(a).not.toBe(b);
+    });
+    it("throws without version param", () => {
+        expect(() => deriveAddress(DOGE_XPUB, 0, "p2pkh", {})).toThrow("version");
+    });
+});
+describe("deriveAddress — p2pkh (TRON)", () => {
+    const TRON_XPUB = makeTestXpub("m/44'/195'/0'");
+    it("derives a valid T... address", () => {
+        const addr = deriveAddress(TRON_XPUB, 0, "p2pkh", { version: "0x41" });
+        expect(addr).toMatch(/^T[a-km-zA-HJ-NP-Z1-9]+$/);
+    });
+    it("is deterministic", () => {
+        const a = deriveAddress(TRON_XPUB, 5, "p2pkh", { version: "0x41" });
+        const b = deriveAddress(TRON_XPUB, 5, "p2pkh", { version: "0x41" });
+        expect(a).toBe(b);
+    });
+});
+describe("deriveAddress — evm (ETH)", () => {
+    it("derives a valid Ethereum address", () => {
+        const addr = deriveAddress(ETH_XPUB, 0, "evm");
+        expect(addr).toMatch(/^0x[0-9a-fA-F]{40}$/);
+    });
+    it("derives different addresses for different indices", () => {
+        const a = deriveAddress(ETH_XPUB, 0, "evm");
+        const b = deriveAddress(ETH_XPUB, 1, "evm");
+        expect(a).not.toBe(b);
+    });
+    it("is deterministic", () => {
+        const a = deriveAddress(ETH_XPUB, 42, "evm");
+        const b = deriveAddress(ETH_XPUB, 42, "evm");
+        expect(a).toBe(b);
+    });
+    it("returns checksummed address", () => {
+        const addr = deriveAddress(ETH_XPUB, 0, "evm");
+        expect(addr).toMatch(/^0x[0-9a-fA-F]{40}$/);
+    });
+});
+describe("deriveAddress — unknown type", () => {
+    it("throws for unknown address type", () => {
+        expect(() => deriveAddress(BTC_XPUB, 0, "foo")).toThrow("Unknown address type");
+    });
+});
+describe("deriveTreasury", () => {
+    it("derives a valid bech32 treasury address", () => {
+        const addr = deriveTreasury(BTC_XPUB, "bech32", { hrp: "bc" });
+        expect(addr).toMatch(/^bc1q[a-z0-9]+$/);
+    });
+    it("differs from deposit address at index 0", () => {
+        const deposit = deriveAddress(BTC_XPUB, 0, "bech32", { hrp: "bc" });
+        const treasury = deriveTreasury(BTC_XPUB, "bech32", { hrp: "bc" });
+        expect(deposit).not.toBe(treasury);
+    });
+});
+describe("isValidXpub", () => {
+    it("accepts valid xpub", () => {
+        expect(isValidXpub(BTC_XPUB)).toBe(true);
+    });
+    it("rejects garbage", () => {
+        expect(isValidXpub("not-an-xpub")).toBe(false);
+    });
+    it("rejects empty string", () => {
+        expect(isValidXpub("")).toBe(false);
+    });
+});

package/dist/billing/crypto/__tests__/key-server.test.js

@@ -11,6 +11,7 @@ function createMockDb() {
         nextIndex: 1,
         decimals: 8,
         addressType: "bech32",
+        encodingParams: '{"hrp":"bc"}',
         confirmations: 6,
     };
     const db = {
@@ -178,6 +179,7 @@ describe("key-server routes", () => {
             nextIndex: 0,
             decimals: 18,
             addressType: "evm",
+            encodingParams: "{}",
             confirmations: 1,
         };
         const db = {
@@ -236,6 +238,7 @@ describe("key-server routes", () => {
             nextIndex: 0,
             decimals: 18,
             addressType: "evm",
+            encodingParams: "{}",
             confirmations: 1,
         };
         const db = {

package/dist/billing/crypto/address-gen.d.ts

@@ -0,0 +1,24 @@
+export interface EncodingParams {
+    /** Bech32 human-readable prefix (e.g. "bc", "ltc", "tb"). */
+    hrp?: string;
+    /** Base58Check version byte as hex string (e.g. "0x1e" for DOGE, "0x41" for TRON). */
+    version?: string;
+}
+/**
+ * Derive a deposit address from an xpub at a given BIP-44 index.
+ * Path: xpub / 0 / index (external chain).
+ * No private keys involved.
+ *
+ * @param xpub - Extended public key
+ * @param index - Derivation index (0, 1, 2, ...)
+ * @param addressType - Encoding type: "bech32", "p2pkh", "evm"
+ * @param params - Chain-specific encoding params from DB (parsed JSON)
+ */
+export declare function deriveAddress(xpub: string, index: number, addressType: string, params?: EncodingParams): string;
+/**
+ * Derive the treasury address (internal chain, index 0).
+ * Used for sweep destinations.
+ */
+export declare function deriveTreasury(xpub: string, addressType: string, params?: EncodingParams): string;
+/** Validate that a string is an xpub (not xprv). */
+export declare function isValidXpub(key: string): boolean;

package/dist/billing/crypto/address-gen.js

@@ -0,0 +1,137 @@
+/**
+ * Universal address derivation — one function for all secp256k1 chains.
+ *
+ * Encoding type and chain-specific params (HRP, version byte) are read from
+ * the paymentMethods DB row, not hardcoded per chain. Adding a new chain
+ * is a DB INSERT, not a code change.
+ *
+ * Supported encodings:
+ *   - bech32:  BTC (bc1q...), LTC (ltc1q...) — params: { hrp }
+ *   - p2pkh:   DOGE (D...), TRON (T...) — params: { version }
+ *   - evm:     ETH, ERC-20 (0x...) — params: {}
+ */
+import { ripemd160 } from "@noble/hashes/legacy.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { bech32 } from "@scure/base";
+import { HDKey } from "@scure/bip32";
+import { publicKeyToAddress } from "viem/accounts";
+// ---------- encoding helpers ----------
+const BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+function base58encode(data) {
+    let num = 0n;
+    for (const byte of data)
+        num = num * 256n + BigInt(byte);
+    let encoded = "";
+    while (num > 0n) {
+        encoded = BASE58_ALPHABET[Number(num % 58n)] + encoded;
+        num = num / 58n;
+    }
+    for (const byte of data) {
+        if (byte !== 0)
+            break;
+        encoded = `1${encoded}`;
+    }
+    return encoded;
+}
+function hash160(pubkey) {
+    return ripemd160(sha256(pubkey));
+}
+function encodeBech32(pubkey, hrp) {
+    const h = hash160(pubkey);
+    const words = bech32.toWords(h);
+    return bech32.encode(hrp, [0, ...words]);
+}
+function encodeP2pkh(pubkey, versionByte) {
+    const h = hash160(pubkey);
+    const payload = new Uint8Array(21);
+    payload[0] = versionByte;
+    payload.set(h, 1);
+    const checksum = sha256(sha256(payload));
+    const full = new Uint8Array(25);
+    full.set(payload);
+    full.set(checksum.slice(0, 4), 21);
+    return base58encode(full);
+}
+function encodeEvm(pubkey) {
+    const hexPubKey = `0x${Array.from(pubkey, (b) => b.toString(16).padStart(2, "0")).join("")}`;
+    return publicKeyToAddress(hexPubKey);
+}
+// ---------- public API ----------
+/**
+ * Derive a deposit address from an xpub at a given BIP-44 index.
+ * Path: xpub / 0 / index (external chain).
+ * No private keys involved.
+ *
+ * @param xpub - Extended public key
+ * @param index - Derivation index (0, 1, 2, ...)
+ * @param addressType - Encoding type: "bech32", "p2pkh", "evm"
+ * @param params - Chain-specific encoding params from DB (parsed JSON)
+ */
+export function deriveAddress(xpub, index, addressType, params = {}) {
+    if (!Number.isInteger(index) || index < 0)
+        throw new Error(`Invalid derivation index: ${index}`);
+    const master = HDKey.fromExtendedKey(xpub);
+    const child = master.deriveChild(0).deriveChild(index);
+    if (!child.publicKey)
+        throw new Error("Failed to derive public key");
+    switch (addressType) {
+        case "bech32": {
+            if (!params.hrp)
+                throw new Error("bech32 encoding requires 'hrp' param");
+            return encodeBech32(child.publicKey, params.hrp);
+        }
+        case "p2pkh": {
+            if (!params.version)
+                throw new Error("p2pkh encoding requires 'version' param");
+            const versionByte = Number(params.version);
+            if (!Number.isInteger(versionByte) || versionByte < 0 || versionByte > 255)
+                throw new Error(`Invalid p2pkh version byte: ${params.version}`);
+            return encodeP2pkh(child.publicKey, versionByte);
+        }
+        case "evm":
+            return encodeEvm(child.publicKey);
+        default:
+            throw new Error(`Unknown address type: ${addressType}`);
+    }
+}
+/**
+ * Derive the treasury address (internal chain, index 0).
+ * Used for sweep destinations.
+ */
+export function deriveTreasury(xpub, addressType, params = {}) {
+    const master = HDKey.fromExtendedKey(xpub);
+    const child = master.deriveChild(1).deriveChild(0); // internal chain
+    if (!child.publicKey)
+        throw new Error("Failed to derive public key");
+    switch (addressType) {
+        case "bech32": {
+            if (!params.hrp)
+                throw new Error("bech32 encoding requires 'hrp' param");
+            return encodeBech32(child.publicKey, params.hrp);
+        }
+        case "p2pkh": {
+            if (!params.version)
+                throw new Error("p2pkh encoding requires 'version' param");
+            const versionByte = Number(params.version);
+            if (!Number.isInteger(versionByte) || versionByte < 0 || versionByte > 255)
+                throw new Error(`Invalid p2pkh version byte: ${params.version}`);
+            return encodeP2pkh(child.publicKey, versionByte);
+        }
+        case "evm":
+            return encodeEvm(child.publicKey);
+        default:
+            throw new Error(`Unknown address type: ${addressType}`);
+    }
+}
+/** Validate that a string is an xpub (not xprv). */
+export function isValidXpub(key) {
+    if (!key.startsWith("xpub"))
+        return false;
+    try {
+        HDKey.fromExtendedKey(key);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/billing/crypto/btc/checkout.js

@@ -1,5 +1,5 @@
 import { Credit } from "../../../credits/credit.js";
-import { deriveBtcAddress } from "./address-gen.js";
+import { deriveAddress } from "../address-gen.js";
 export const MIN_BTC_USD = 10;
 /**
  * Create a BTC checkout — derive a unique deposit address, store the charge.
@@ -17,7 +17,10 @@ export async function createBtcCheckout(deps, opts) {
     const maxRetries = 3;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
         const derivationIndex = await deps.chargeStore.getNextDerivationIndex();
-        const depositAddress = deriveBtcAddress(deps.xpub, derivationIndex, network);
+        const hrpMap = { mainnet: "bc", testnet: "tb", regtest: "bcrt" };
+        const depositAddress = deriveAddress(deps.xpub, derivationIndex, "bech32", {
+            hrp: hrpMap[network],
+        });
         const referenceId = `btc:${depositAddress}`;
         try {
             await deps.chargeStore.createStablecoinCharge({

package/dist/billing/crypto/btc/index.d.ts

@@ -1,5 +1,5 @@
-export type { UtxoChain, UtxoNetwork } from "./address-gen.js";
-export { deriveAddress, deriveBtcAddress, deriveBtcTreasury, deriveTreasury } from "./address-gen.js";
+export type { EncodingParams } from "../address-gen.js";
+export { deriveAddress, deriveTreasury, isValidXpub } from "../address-gen.js";
 export type { BtcCheckoutDeps, BtcCheckoutResult } from "./checkout.js";
 export { createBtcCheckout, MIN_BTC_USD } from "./checkout.js";
 export { centsToSats, loadBitcoindConfig, satsToCents } from "./config.js";

package/dist/billing/crypto/btc/index.js

@@ -1,4 +1,4 @@
-export { deriveAddress, deriveBtcAddress, deriveBtcTreasury, deriveTreasury } from "./address-gen.js";
+export { deriveAddress, deriveTreasury, isValidXpub } from "../address-gen.js";
 export { createBtcCheckout, MIN_BTC_USD } from "./checkout.js";
 export { centsToSats, loadBitcoindConfig, satsToCents } from "./config.js";
 export { settleBtcPayment } from "./settler.js";

package/dist/billing/crypto/evm/checkout.js

@@ -1,5 +1,5 @@
 import { Credit } from "../../../credits/credit.js";
-import { deriveDepositAddress } from "./address-gen.js";
+import { deriveAddress } from "../address-gen.js";
 import { getTokenConfig, tokenAmountFromCents } from "./config.js";
 export const MIN_STABLECOIN_USD = 10;
 /**
@@ -23,7 +23,7 @@ export async function createStablecoinCheckout(deps, opts) {
     const maxRetries = 3;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
         const derivationIndex = await deps.chargeStore.getNextDerivationIndex();
-        const depositAddress = deriveDepositAddress(deps.xpub, derivationIndex);
+        const depositAddress = deriveAddress(deps.xpub, derivationIndex, "evm");
         const referenceId = `sc:${opts.chain}:${opts.token.toLowerCase()}:${depositAddress.toLowerCase()}`;
         try {
             await deps.chargeStore.createStablecoinCharge({

package/dist/billing/crypto/evm/eth-checkout.js

@@ -1,6 +1,6 @@
 import { Credit } from "../../../credits/credit.js";
+import { deriveAddress } from "../address-gen.js";
 import { centsToNative } from "../oracle/convert.js";
-import { deriveDepositAddress } from "./address-gen.js";
 export const MIN_ETH_USD = 10;
 /**
  * Create an ETH checkout — derive deposit address, lock price, store charge.
@@ -21,7 +21,7 @@ export async function createEthCheckout(deps, opts) {
     const maxRetries = 3;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
         const derivationIndex = await deps.chargeStore.getNextDerivationIndex();
-        const depositAddress = deriveDepositAddress(deps.xpub, derivationIndex);
+        const depositAddress = deriveAddress(deps.xpub, derivationIndex, "evm");
         const referenceId = `eth:${opts.chain}:${depositAddress}`;
         try {
             await deps.chargeStore.createStablecoinCharge({

package/dist/billing/crypto/evm/index.d.ts

@@ -1,4 +1,5 @@
-export { deriveDepositAddress, isValidXpub } from "./address-gen.js";
+export type { EncodingParams } from "../address-gen.js";
+export { deriveAddress, isValidXpub } from "../address-gen.js";
 export type { StablecoinCheckoutDeps, StablecoinCheckoutResult } from "./checkout.js";
 export { createStablecoinCheckout, MIN_STABLECOIN_USD } from "./checkout.js";
 export { centsFromTokenAmount, getChainConfig, getTokenConfig, tokenAmountFromCents } from "./config.js";

package/dist/billing/crypto/evm/index.js

@@ -1,4 +1,4 @@
-export { deriveDepositAddress, isValidXpub } from "./address-gen.js";
+export { deriveAddress, isValidXpub } from "../address-gen.js";
 export { createStablecoinCheckout, MIN_STABLECOIN_USD } from "./checkout.js";
 export { centsFromTokenAmount, getChainConfig, getTokenConfig, tokenAmountFromCents } from "./config.js";
 export { createEthCheckout, MIN_ETH_USD } from "./eth-checkout.js";

package/dist/billing/crypto/key-server-entry.js

@@ -68,6 +68,7 @@ async function main() {
         oracle,
         bitcoindUser: BITCOIND_USER,
         bitcoindPassword: BITCOIND_PASSWORD,
+        serviceKey: SERVICE_KEY,
         log: (msg, meta) => console.log(`[watcher] ${msg}`, meta ?? ""),
     });
     const server = serve({ fetch: app.fetch, port: PORT });

package/dist/billing/crypto/key-server.js

@@ -10,8 +10,7 @@
 import { eq, sql } from "drizzle-orm";
 import { Hono } from "hono";
 import { derivedAddresses, pathAllocations, paymentMethods } from "../../db/schema/crypto.js";
-import { deriveAddress, deriveP2pkhAddress } from "./btc/address-gen.js";
-import { deriveDepositAddress } from "./evm/address-gen.js";
+import { deriveAddress } from "./address-gen.js";
 import { centsToNative } from "./oracle/convert.js";
 import { AssetNotSupportedError } from "./oracle/types.js";
 /**
@@ -38,21 +37,16 @@ async function deriveNextAddress(db, chainId, tenantId) {
         if (!method.xpub)
             throw new Error(`No xpub configured for chain: ${chainId}`);
         const index = method.nextIndex - 1;
-        // Route to the right derivation function via address_type (DB-driven, no hardcoded chains)
-        let address;
-        switch (method.addressType) {
-            case "bech32":
-                address = deriveAddress(method.xpub, index, (method.network ?? "mainnet"), method.chain);
-                break;
-            case "p2pkh":
-                address = deriveP2pkhAddress(method.xpub, index, method.chain);
-                break;
-            case "evm":
-                address = deriveDepositAddress(method.xpub, index);
-                break;
-            default:
-                throw new Error(`Unknown address type: ${method.addressType}`);
+        // Universal address derivation — encoding type + params are DB-driven.
+        // Adding a new chain is a DB INSERT, not a code change.
+        let encodingParams = {};
+        try {
+            encodingParams = JSON.parse(method.encodingParams ?? "{}");
+        }
+        catch {
+            throw new Error(`Invalid encoding_params JSON for chain ${chainId}: ${method.encodingParams}`);
         }
+        const address = deriveAddress(method.xpub, index, method.addressType, encodingParams);
         // Step 2: Record in immutable log. If this address was already derived by a
         // sibling chain (shared xpub), the unique constraint fires and we retry
         // with the next index (which is already incremented above).
@@ -177,9 +171,12 @@ export function createKeyServerApp(deps) {
             callbackUrl: body.callbackUrl,
             expectedAmount: expectedAmount.toString(),
         });
-        // Format display amount for the client
-        const divisor = 10 ** method.decimals;
-        const displayAmount = `${(Number(expectedAmount) / divisor).toFixed(Math.min(method.decimals, 8))} ${token}`;
+        // Format display amount for the client (BigInt-safe, no Number overflow)
+        const divisor = 10n ** BigInt(method.decimals);
+        const whole = expectedAmount / divisor;
+        const frac = expectedAmount % divisor;
+        const fracStr = frac.toString().padStart(method.decimals, "0").slice(0, 8).replace(/0+$/, "");
+        const displayAmount = `${whole}${fracStr ? `.${fracStr}` : ""} ${token}`;
         return c.json({
             chargeId: referenceId,
             address,
@@ -273,6 +270,15 @@ export function createKeyServerApp(deps) {
         if (inserted.rowCount === 0) {
             return c.json({ error: "Path allocation already exists", path: `m/44'/${body.coin_type}'/${body.account_index}'` }, 409);
         }
+        // Validate encoding_params match address_type requirements
+        const addrType = body.address_type ?? "evm";
+        const encParams = body.encoding_params ?? {};
+        if (addrType === "bech32" && !encParams.hrp) {
+            return c.json({ error: "bech32 address_type requires encoding_params.hrp" }, 400);
+        }
+        if (addrType === "p2pkh" && !encParams.version) {
+            return c.json({ error: "p2pkh address_type requires encoding_params.version" }, 400);
+        }
         // Upsert the payment method
         await deps.methodStore.upsert({
             id: body.id,
@@ -289,6 +295,7 @@ export function createKeyServerApp(deps) {
             oracleAddress: body.oracle_address ?? null,
             xpub: body.xpub,
             addressType: body.address_type ?? "evm",
+            encodingParams: JSON.stringify(body.encoding_params ?? {}),
             confirmations: body.confirmations ?? 6,
         });
         return c.json({ id: body.id, path: `m/44'/${body.coin_type}'/${body.account_index}'` }, 201);

package/dist/billing/crypto/payment-method-store.d.ts

@@ -14,6 +14,7 @@ export interface PaymentMethodRecord {
     oracleAddress: string | null;
     xpub: string | null;
     addressType: string;
+    encodingParams: string;
     confirmations: number;
 }
 export interface IPaymentMethodStore {

package/dist/billing/crypto/payment-method-store.js

@@ -47,6 +47,7 @@ export class DrizzlePaymentMethodStore {
             oracleAddress: method.oracleAddress,
             xpub: method.xpub,
             addressType: method.addressType,
+            encodingParams: method.encodingParams,
             confirmations: method.confirmations,
         })
             .onConflictDoUpdate({
@@ -65,6 +66,7 @@ export class DrizzlePaymentMethodStore {
                 oracleAddress: method.oracleAddress,
                 xpub: method.xpub,
                 addressType: method.addressType,
+                encodingParams: method.encodingParams,
                 confirmations: method.confirmations,
             },
         });
@@ -102,6 +104,7 @@ function toRecord(row) {
         oracleAddress: row.oracleAddress,
         xpub: row.xpub,
         addressType: row.addressType,
+        encodingParams: row.encodingParams,
         confirmations: row.confirmations,
     };
 }

package/dist/billing/crypto/watcher-service.d.ts

@@ -29,6 +29,8 @@ export interface WatcherServiceOpts {
     log?: (msg: string, meta?: Record<string, unknown>) => void;
     /** Allowed callback URL prefixes. Default: ["https://"] — enforces HTTPS. */
     allowedCallbackPrefixes?: string[];
+    /** Service key sent as Bearer token in webhook deliveries. */
+    serviceKey?: string;
 }
 export interface PaymentPayload {
     txHash: string;

package/dist/billing/crypto/watcher-service.js

@@ -43,7 +43,7 @@ async function enqueueWebhook(db, chargeId, callbackUrl, payload) {
         payload: JSON.stringify(payload),
     });
 }
-async function processDeliveries(db, allowedPrefixes, log) {
+async function processDeliveries(db, allowedPrefixes, log, serviceKey) {
     const now = new Date().toISOString();
     const pending = await db
         .select()
@@ -60,9 +60,12 @@ async function processDeliveries(db, allowedPrefixes, log) {
             continue;
         }
         try {
+            const headers = { "Content-Type": "application/json" };
+            if (serviceKey)
+                headers.Authorization = `Bearer ${serviceKey}`;
             const res = await fetch(row.callbackUrl, {
                 method: "POST",
-                headers: { "Content-Type": "application/json" },
+                headers,
                 body: row.payload,
             });
             if (!res.ok)
@@ -175,6 +178,7 @@ export async function startWatchers(opts) {
     const deliveryMs = opts.deliveryIntervalMs ?? 10_000;
     const log = opts.log ?? (() => { });
     const allowedPrefixes = opts.allowedCallbackPrefixes ?? ["https://"];
+    const serviceKey = opts.serviceKey;
     const timers = [];
     const methods = await methodStore.listEnabled();
     const utxoMethods = methods.filter((m) => m.type === "native" && (m.chain === "bitcoin" || m.chain === "litecoin" || m.chain === "dogecoin"));
@@ -388,7 +392,7 @@ export async function startWatchers(opts) {
     // --- Webhook delivery outbox processor ---
     timers.push(setInterval(async () => {
         try {
-            const count = await processDeliveries(db, allowedPrefixes, log);
+            const count = await processDeliveries(db, allowedPrefixes, log, serviceKey);
             if (count > 0)
                 log("Webhooks delivered", { count });
         }

package/dist/db/schema/crypto.d.ts

@@ -682,6 +682,23 @@ export declare const paymentMethods: import("drizzle-orm/pg-core").PgTableWithCo
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        encodingParams: import("drizzle-orm/pg-core").PgColumn<{
+            name: "encoding_params";
+            tableName: "payment_methods";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         confirmations: import("drizzle-orm/pg-core").PgColumn<{
             name: "confirmations";
             tableName: "payment_methods";

package/dist/db/schema/crypto.js

@@ -76,6 +76,7 @@ export const paymentMethods = pgTable("payment_methods", {
     oracleAddress: text("oracle_address"), // Chainlink feed address for price (null = 1:1 stablecoin)
     xpub: text("xpub"), // HD wallet extended public key for deposit address derivation
     addressType: text("address_type").notNull().default("evm"), // "bech32" (BTC/LTC), "p2pkh" (DOGE), "evm" (ETH/ERC20)
+    encodingParams: text("encoding_params").notNull().default("{}"), // JSON: {"hrp":"bc"}, {"version":"0x1e"}, etc.
     confirmations: integer("confirmations").notNull().default(1),
     nextIndex: integer("next_index").notNull().default(0), // atomic derivation counter, never reuses
     createdAt: text("created_at").notNull().default(sql `(now())`),

package/drizzle/migrations/0020_encoding_params_column.sql

@@ -0,0 +1,7 @@
+ALTER TABLE "payment_methods" ADD COLUMN "encoding_params" text DEFAULT '{}' NOT NULL;
+--> statement-breakpoint
+UPDATE "payment_methods" SET "encoding_params" = '{"hrp":"bc"}' WHERE "address_type" = 'bech32' AND "chain" = 'bitcoin';
+--> statement-breakpoint
+UPDATE "payment_methods" SET "encoding_params" = '{"hrp":"ltc"}' WHERE "address_type" = 'bech32' AND "chain" = 'litecoin';
+--> statement-breakpoint
+UPDATE "payment_methods" SET "encoding_params" = '{"version":"0x1e"}' WHERE "address_type" = 'p2pkh' AND "chain" = 'dogecoin';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.57.0",
+  "version": "1.58.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",