bitcoin-decoder 0.1.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Psycarlo
+
+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

@@ -0,0 +1,19 @@
+![bitcoin-decoder](https://github.com/Psycarlo/bitcoin-decoder/blob/main/hero.png)
+
+## Installation
+
+```bash
+npm install bitcoin-decoder
+```
+
+## Quick Start
+
+```typescript
+import { decode } from 'bitcoin-decoder'
+
+const result = decode('1111111111111111111114oLvT2')
+```
+
+## License
+
+Released under the **MIT** license.

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import type { DecodedData, Input } from './types';
+declare function decode(input: Input): DecodedData;
+export { decode };
+export type { DecodedData, Destination, Metadata, Network, ParsedLNAddress, WellKnown } from './types';
+export { wellKnown } from './utils/lightning-address';
+declare const _default: {
+    decode: typeof decode;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,162 @@
+import { DecodeError } from './types';
+import { ARK_PREFIXES, ark } from './utils/ark';
+import { bip321 } from './utils/bip-321';
+import { BITCOIN_ADDRESS_PREFIXES, bitcoin } from './utils/bitcoin';
+import { bolt11 } from './utils/bolt11';
+import { bolt12 } from './utils/bolt12';
+import { lightningAddress } from './utils/lightning-address';
+import { LNURL_PREFIX, lnurl } from './utils/lnurl';
+import { getNetwork } from './utils/network';
+const BIP321_PREFIX = 'bitcoin:';
+const LIGHTNING_PREFIX = 'lightning:';
+const BOLT11_PREFIXES = ['lnbcrt', 'lntbs', 'lnbc', 'lntb'];
+const BOLT12_PREFIXES = ['lnbcrto1', 'lnto1', 'lno1'];
+function toDestination(pd) {
+    if (pd.type === 'bitcoin-address') {
+        return {
+            destination: pd.value,
+            type: pd.type,
+            protocol: pd.protocol,
+            addressType: pd.addressType
+        };
+    }
+    return {
+        destination: pd.value,
+        type: pd.type,
+        protocol: pd.protocol
+    };
+}
+function decodeBolt11(input, invoice) {
+    const parsedDestination = bolt11(invoice);
+    const destination = toDestination(parsedDestination.destination);
+    return {
+        input,
+        destination,
+        destinations: [destination],
+        network: getNetwork(invoice) || 'unknown',
+        metadata: parsedDestination.metadata
+    };
+}
+function decodeBolt12(input, offer) {
+    const parsedDestination = bolt12(offer);
+    const destination = toDestination(parsedDestination.destination);
+    return {
+        input,
+        destination,
+        destinations: [destination],
+        network: getNetwork(offer) || 'unknown',
+        metadata: parsedDestination.metadata
+    };
+}
+function decodeLightningAddress(input) {
+    const parsedDestination = lightningAddress(input);
+    const destination = toDestination(parsedDestination.destination);
+    return {
+        input,
+        destination,
+        destinations: [destination],
+        network: 'unknown'
+    };
+}
+function decodeLnurl(input) {
+    const parsedDestination = lnurl(input);
+    const destination = toDestination(parsedDestination.destination);
+    return {
+        input,
+        destination,
+        destinations: [destination],
+        network: 'unknown'
+    };
+}
+function decodeArk(input) {
+    const parsedDestination = ark(input);
+    const destination = toDestination(parsedDestination.destination);
+    return {
+        input,
+        destination,
+        destinations: [destination],
+        network: getNetwork(input) || 'unknown'
+    };
+}
+function decodeBip321(input) {
+    const parsedDestinations = bip321(input);
+    const first = parsedDestinations[0];
+    if (!first) {
+        throw new DecodeError(`No supported payment methods in BIP-321 URI: ${input}`, 'NO_PAYMENT_METHODS');
+    }
+    const destination = toDestination(first.destination);
+    const destinations = parsedDestinations.map((pd) => toDestination(pd.destination));
+    return {
+        input,
+        destination,
+        destinations,
+        network: getNetwork(destination.destination) || 'unknown',
+        metadata: first.metadata
+    };
+}
+function decodeBitcoin(input) {
+    const parsedDestination = bitcoin(input);
+    const destination = toDestination(parsedDestination.destination);
+    return {
+        input,
+        destination,
+        destinations: [destination],
+        network: getNetwork(input) || 'unknown'
+    };
+}
+function decodeInput(input) {
+    const lowerInput = input.toLowerCase();
+    if (lowerInput.startsWith(BIP321_PREFIX)) {
+        return decodeBip321(input);
+    }
+    if (lowerInput.startsWith(LIGHTNING_PREFIX)) {
+        return decodeBolt11(input, input.slice(LIGHTNING_PREFIX.length));
+    }
+    if (BOLT11_PREFIXES.some((prefix) => lowerInput.startsWith(prefix))) {
+        return decodeBolt11(input, input);
+    }
+    if (BOLT12_PREFIXES.some((prefix) => lowerInput.startsWith(prefix))) {
+        return decodeBolt12(input, input);
+    }
+    if (lowerInput.startsWith(LNURL_PREFIX)) {
+        return decodeLnurl(input);
+    }
+    if (ARK_PREFIXES.some((prefix) => lowerInput.startsWith(prefix))) {
+        return decodeArk(input);
+    }
+    if (input.includes('@')) {
+        return decodeLightningAddress(input);
+    }
+    if (BITCOIN_ADDRESS_PREFIXES.some((prefix) => lowerInput.startsWith(prefix))) {
+        return decodeBitcoin(input);
+    }
+    throw new DecodeError(`Unknown input format: ${input}`, 'UNKNOWN_FORMAT');
+}
+function getErrorCode(error) {
+    if (error instanceof DecodeError) {
+        return {
+            valid: false,
+            input: '',
+            errorMessage: error.message,
+            errorCode: error.code
+        };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        valid: false,
+        input: '',
+        errorMessage: message,
+        errorCode: 'UNKNOWN_FORMAT'
+    };
+}
+function decode(input) {
+    try {
+        return { valid: true, ...decodeInput(input) };
+    }
+    catch (error) {
+        return { ...getErrorCode(error), input };
+    }
+}
+export { decode };
+export { wellKnown } from './utils/lightning-address';
+export default { decode };

package/dist/types/index.d.ts

@@ -0,0 +1,69 @@
+export type Input = string;
+/** Bitcoin network
+ *
+ *  `testnet` here includes bitcoin testnet, signet, and regtest.
+ */
+export type Network = 'mainnet' | 'testnet' | 'unknown';
+export type Protocol = 'on-chain' | 'lightning' | 'ark';
+export type Metadata = {
+    /** Amount in sats */
+    amount?: number;
+    description?: string;
+};
+export type DestinationType = 'bitcoin-address' | 'bolt11' | 'bolt12' | 'lnurl' | 'lnaddress' | 'ark-address';
+export type BitcoinAddressType = 'p2pkh' | 'p2sh' | 'p2wpkh' | 'p2wsh' | 'p2tr';
+export type Destination = {
+    destination: string;
+    type: 'bitcoin-address';
+    protocol: Protocol;
+    addressType: BitcoinAddressType;
+} | {
+    destination: string;
+    type: Exclude<DestinationType, 'bitcoin-address'>;
+    protocol: Protocol;
+};
+export type ErrorCode = 'UNKNOWN_FORMAT' | 'INVALID_HRP' | 'INVALID_VERSION' | 'EMPTY_ADDRESS' | 'PAYLOAD_TOO_SHORT' | 'INVALID_CHECKSUM' | 'INVALID_BOLT12' | 'INVALID_BIP321' | 'INVALID_LNADDRESS' | 'INVALID_LNURL' | 'NO_PAYMENT_METHODS';
+export type ParsedLNAddress = {
+    username: string;
+    domain: string;
+};
+export type WellKnown = {
+    callback: string;
+    minSendable: number;
+    maxSendable: number;
+    commentAllowed?: number;
+    metadata?: string;
+};
+type DecodedSuccess = {
+    valid: true;
+    /** Raw text passed by the user */
+    input: Input;
+    /** All parsed destinations */
+    destinations: Destination[];
+    /** Shortcut primary destination for convenience. Lightning > Ark > On-chain */
+    readonly destination: Destination;
+    /** Bitcoin network associated with the destination(s) */
+    network: Network;
+    /** Most relevant metadata */
+    metadata?: Metadata;
+};
+type DecodedError = {
+    valid: false;
+    /** Raw text passed by the user */
+    input: Input;
+    errorMessage: string;
+    errorCode: ErrorCode;
+};
+export type DecodedData = DecodedSuccess | DecodedError;
+export declare class DecodeError extends Error {
+    code: ErrorCode;
+    constructor(message: string, code: ErrorCode);
+}
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+export type ParsedDestination = {
+    destination: DistributiveOmit<Destination, 'destination'> & {
+        value: string;
+    };
+    metadata?: Metadata;
+};
+export {};

package/dist/types/index.js

@@ -0,0 +1,7 @@
+export class DecodeError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+    }
+}

package/dist/utils/ark.d.ts

@@ -0,0 +1,4 @@
+import type { Input, ParsedDestination } from '../types';
+declare const ARK_PREFIXES: string[];
+declare function ark(input: Input): ParsedDestination;
+export { ark, ARK_PREFIXES };

package/dist/utils/ark.js

@@ -0,0 +1,43 @@
+import { bech32m } from '@scure/base';
+import { DecodeError } from '../types';
+const ARK_PREFIXES = ['ark', 'tark'];
+const VALID_VERSIONS = [0, 1];
+const MIN_PAYLOAD_LENGTH = 4;
+function validate(input) {
+    let prefix;
+    let words;
+    try {
+        const decoded = bech32m.decode(input, 1023);
+        prefix = decoded.prefix;
+        words = decoded.words;
+    }
+    catch {
+        throw new DecodeError('Invalid bech32m checksum', 'INVALID_CHECKSUM');
+    }
+    if (!ARK_PREFIXES.includes(prefix)) {
+        throw new DecodeError(`Invalid HRP: ${prefix}`, 'INVALID_HRP');
+    }
+    const [version] = words;
+    if (version === undefined) {
+        throw new DecodeError('Empty address', 'EMPTY_ADDRESS');
+    }
+    if (!VALID_VERSIONS.includes(version)) {
+        throw new DecodeError(`Unknown version: ${version}`, 'INVALID_VERSION');
+    }
+    const payloadBits = (words.length - 1) * 5;
+    const payloadBytes = Math.floor(payloadBits / 8);
+    if (payloadBytes < MIN_PAYLOAD_LENGTH) {
+        throw new DecodeError('Payload too short', 'PAYLOAD_TOO_SHORT');
+    }
+}
+function ark(input) {
+    validate(input);
+    return {
+        destination: {
+            value: input,
+            protocol: 'ark',
+            type: 'ark-address'
+        }
+    };
+}
+export { ark, ARK_PREFIXES };

package/dist/utils/bip-321.d.ts

@@ -0,0 +1,3 @@
+import type { Input, ParsedDestination } from '../types';
+declare function bip321(input: Input): ParsedDestination[];
+export { bip321 };

package/dist/utils/bip-321.js

@@ -0,0 +1,56 @@
+import { parseBIP321 } from 'bip-321';
+import { ark } from './ark';
+import { bitcoin } from './bitcoin';
+import { bolt11 } from './bolt11';
+import { bolt12 } from './bolt12';
+const SATS_PER_BTC = 100_000_000;
+/** Priority order: Lightning (0) > Ark (1) > On-chain (2) */
+const PROTOCOL_PRIORITY = {
+    lightning: 0,
+    offer: 0,
+    ark: 1,
+    onchain: 2
+};
+const SUPPORTED_TYPES = new Set(Object.keys(PROTOCOL_PRIORITY));
+function isSupportedType(type) {
+    return SUPPORTED_TYPES.has(type);
+}
+function getMetadata(result) {
+    const amount = result.amount
+        ? Math.round(result.amount * SATS_PER_BTC)
+        : undefined;
+    const description = result.message ?? result.label;
+    if (amount === undefined && description === undefined) {
+        return undefined;
+    }
+    return { amount, description };
+}
+function mapPaymentMethod(paymentMethod, metadata) {
+    if (paymentMethod.type === 'lightning') {
+        return bolt11(paymentMethod.value);
+    }
+    if (paymentMethod.type === 'offer') {
+        return bolt12(paymentMethod.value);
+    }
+    if (paymentMethod.type === 'ark') {
+        return ark(paymentMethod.value);
+    }
+    const parsed = bitcoin(paymentMethod.value);
+    return { ...parsed, metadata };
+}
+function parse(result) {
+    const metadata = getMetadata(result);
+    return result.paymentMethods
+        .filter((method) => (method.valid || method.type === 'offer') &&
+        isSupportedType(method.type))
+        .sort((a, b) => PROTOCOL_PRIORITY[a.type] - PROTOCOL_PRIORITY[b.type])
+        .map((method) => mapPaymentMethod(method, metadata));
+}
+function bip321(input) {
+    const result = parseBIP321(input);
+    if (!result.valid) {
+        throw new Error(`Invalid BIP-321 URI: ${result.errors.join(', ')}`);
+    }
+    return parse(result);
+}
+export { bip321 };

package/dist/utils/bitcoin.d.ts

@@ -0,0 +1,4 @@
+import type { Input, ParsedDestination } from '../types';
+declare const BITCOIN_ADDRESS_PREFIXES: string[];
+declare function bitcoin(input: Input): ParsedDestination;
+export { bitcoin, BITCOIN_ADDRESS_PREFIXES };

package/dist/utils/bitcoin.js

@@ -0,0 +1,124 @@
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bech32, bech32m, createBase58check } from '@scure/base';
+import { DecodeError } from '../types';
+const b58c = createBase58check(sha256);
+const SEGWIT_HRPS = ['bc', 'tb', 'bcrt'];
+const BITCOIN_ADDRESS_PREFIXES = [
+    'bc1',
+    'tb1',
+    'bcrt1',
+    '1',
+    '3',
+    'm',
+    'n',
+    '2'
+];
+const P2PKH_VERSIONS = new Set([0x00, 0x6f]);
+const P2SH_VERSIONS = new Set([0x05, 0xc4]);
+function getAddressType(version) {
+    if (P2PKH_VERSIONS.has(version)) {
+        return 'p2pkh';
+    }
+    if (P2SH_VERSIONS.has(version)) {
+        return 'p2sh';
+    }
+    throw new DecodeError(`Unknown version byte: ${version}`, 'INVALID_VERSION');
+}
+function validateLegacy(input) {
+    let decoded;
+    try {
+        decoded = b58c.decode(input);
+    }
+    catch {
+        throw new DecodeError('Invalid base58check checksum', 'INVALID_CHECKSUM');
+    }
+    if (decoded.length !== 21) {
+        throw new DecodeError('Invalid address length', 'PAYLOAD_TOO_SHORT');
+    }
+    const version = decoded[0];
+    if (version === undefined) {
+        throw new DecodeError('Empty address', 'EMPTY_ADDRESS');
+    }
+    return getAddressType(version);
+}
+function isValidHrp(prefix) {
+    return SEGWIT_HRPS.includes(prefix);
+}
+function getSegwitAddressType(version, programLength) {
+    if (version === 0) {
+        return programLength === 20 ? 'p2wpkh' : 'p2wsh';
+    }
+    return 'p2tr';
+}
+function validateSegwit(input) {
+    const lowerInput = input.toLowerCase();
+    // Try bech32 (witness version 0)
+    try {
+        const decoded = bech32.decode(lowerInput, 90);
+        if (!isValidHrp(decoded.prefix)) {
+            throw new DecodeError(`Invalid HRP: ${decoded.prefix}`, 'INVALID_HRP');
+        }
+        const [version] = decoded.words;
+        if (version !== 0) {
+            throw new DecodeError('Witness v0 must use bech32 encoding', 'INVALID_VERSION');
+        }
+        const data = bech32.fromWords(decoded.words.slice(1));
+        if (data.length !== 20 && data.length !== 32) {
+            throw new DecodeError(`Invalid witness program length: ${data.length}`, 'PAYLOAD_TOO_SHORT');
+        }
+        return getSegwitAddressType(version, data.length);
+    }
+    catch (error) {
+        if (error instanceof DecodeError) {
+            throw error;
+        }
+    }
+    // Try bech32m (witness version 1+)
+    try {
+        const decoded = bech32m.decode(lowerInput, 90);
+        if (!isValidHrp(decoded.prefix)) {
+            throw new DecodeError(`Invalid HRP: ${decoded.prefix}`, 'INVALID_HRP');
+        }
+        const [version] = decoded.words;
+        if (version === undefined || version < 1 || version > 16) {
+            throw new DecodeError(`Invalid witness version: ${version}`, 'INVALID_VERSION');
+        }
+        const data = bech32m.fromWords(decoded.words.slice(1));
+        if (version === 1) {
+            if (data.length !== 32) {
+                throw new DecodeError(`Invalid witness program length: ${data.length}`, 'PAYLOAD_TOO_SHORT');
+            }
+            return getSegwitAddressType(version, data.length);
+        }
+        // Future witness versions (2-16): program must be 2-40 bytes
+        if (data.length < 2 || data.length > 40) {
+            throw new DecodeError(`Invalid witness program length: ${data.length}`, 'PAYLOAD_TOO_SHORT');
+        }
+        return getSegwitAddressType(version, data.length);
+    }
+    catch (error) {
+        if (error instanceof DecodeError) {
+            throw error;
+        }
+        throw new DecodeError('Invalid bech32/bech32m checksum', 'INVALID_CHECKSUM');
+    }
+}
+function validate(input) {
+    const lowerInput = input.toLowerCase();
+    if (SEGWIT_HRPS.some((hrp) => lowerInput.startsWith(`${hrp}1`))) {
+        return validateSegwit(input);
+    }
+    return validateLegacy(input);
+}
+function bitcoin(input) {
+    const addressType = validate(input);
+    return {
+        destination: {
+            value: input,
+            protocol: 'on-chain',
+            type: 'bitcoin-address',
+            addressType
+        }
+    };
+}
+export { bitcoin, BITCOIN_ADDRESS_PREFIXES };

package/dist/utils/bolt11.d.ts

@@ -0,0 +1,3 @@
+import type { Input, ParsedDestination } from '../types';
+declare function bolt11(input: Input): ParsedDestination;
+export { bolt11 };

package/dist/utils/bolt11.js

@@ -0,0 +1,23 @@
+import { decode } from 'light-bolt11-decoder';
+function getSection(decodedInvoice, name) {
+    return decodedInvoice.sections.find((section) => section.name === name);
+}
+function parse(decodedInvoice) {
+    const amount = getSection(decodedInvoice, 'amount');
+    const description = getSection(decodedInvoice, 'description');
+    return {
+        destination: {
+            value: decodedInvoice.paymentRequest,
+            protocol: 'lightning',
+            type: 'bolt11'
+        },
+        metadata: {
+            amount: amount ? Number(amount.value) / 1000 : undefined,
+            description: description?.value
+        }
+    };
+}
+function bolt11(input) {
+    return parse(decode(input));
+}
+export { bolt11 };

package/dist/utils/bolt12.d.ts

@@ -0,0 +1,3 @@
+import type { Input, ParsedDestination } from '../types';
+declare function bolt12(input: Input): ParsedDestination;
+export { bolt12 };

package/dist/utils/bolt12.js

@@ -0,0 +1,170 @@
+import { bech32, hex, utf8 } from '@scure/base';
+const BECH32_ALPHABET = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l';
+// BOLT12 TLV types from the spec
+const TLV_TYPES = {
+    2: 'offer_chains',
+    4: 'offer_metadata',
+    6: 'offer_currency',
+    8: 'offer_amount',
+    10: 'description',
+    12: 'offer_features',
+    14: 'offer_absolute_expiry',
+    16: 'offer_paths',
+    18: 'issuer',
+    20: 'offer_quantity_max',
+    22: 'node_id',
+    80: 'invreq_metadata',
+    82: 'invreq_payer_id',
+    160: 'invoice_paths',
+    162: 'invoice_blindedpay',
+    164: 'invoice_created_at',
+    166: 'invoice_relative_expiry',
+    168: 'invoice_payment_hash',
+    170: 'invoice_amount',
+    172: 'invoice_fallbacks',
+    174: 'invoice_features',
+    176: 'invoice_node_id',
+    240: 'signature'
+};
+/** Read a BigSize integer (variable-length encoding from the Lightning spec). */
+function readBigSize(data, offset) {
+    const first = data[offset];
+    if (first === undefined) {
+        throw new Error('Unexpected end of data');
+    }
+    if (first < 0xfd) {
+        return [first, offset + 1];
+    }
+    if (first === 0xfd) {
+        return [(data[offset + 1] ?? 0) * 256 + (data[offset + 2] ?? 0), offset + 3];
+    }
+    if (first === 0xfe) {
+        return [
+            (data[offset + 1] ?? 0) * 16_777_216 +
+                (data[offset + 2] ?? 0) * 65_536 +
+                (data[offset + 3] ?? 0) * 256 +
+                (data[offset + 4] ?? 0),
+            offset + 5
+        ];
+    }
+    throw new Error('BigSize value too large');
+}
+function parseValue(type, value) {
+    const name = TLV_TYPES[type];
+    switch (name) {
+        case 'description':
+        case 'issuer':
+        case 'offer_currency':
+            return utf8.encode(value);
+        case 'node_id':
+        case 'offer_metadata':
+        case 'invreq_metadata':
+        case 'invreq_payer_id':
+        case 'invoice_payment_hash':
+        case 'invoice_node_id':
+        case 'signature':
+            return hex.encode(value);
+        case 'offer_amount':
+        case 'offer_quantity_max':
+        case 'offer_absolute_expiry':
+        case 'invoice_created_at':
+        case 'invoice_relative_expiry':
+        case 'invoice_amount': {
+            let n = 0;
+            for (const byte of value) {
+                n = n * 256 + byte;
+            }
+            return n;
+        }
+        case 'offer_chains': {
+            const chains = [];
+            for (let i = 0; i < value.length; i += 32) {
+                chains.push(hex.encode(value.slice(i, i + 32)));
+            }
+            return chains;
+        }
+        default:
+            return hex.encode(value);
+    }
+}
+/**
+ * Decode bech32 data without checksum verification.
+ * BOLT12 offers use bech32 encoding but omit the checksum per spec,
+ * which causes standard bech32 decoders to reject them.
+ */
+function decodeBech32NoChecksum(str) {
+    const lower = str.toLowerCase();
+    const sepIndex = lower.lastIndexOf('1');
+    if (sepIndex < 1) {
+        throw new Error('Invalid bech32 string');
+    }
+    const dataStr = lower.slice(sepIndex + 1);
+    const words = [];
+    for (const char of dataStr) {
+        const idx = BECH32_ALPHABET.indexOf(char);
+        if (idx === -1) {
+            throw new Error(`Invalid bech32 character: ${char}`);
+        }
+        words.push(idx);
+    }
+    return words;
+}
+function decode(offerRequest) {
+    if (typeof offerRequest !== 'string') {
+        throw new Error('Offer request must be a string');
+    }
+    const lower = offerRequest.toLowerCase();
+    if (!lower.startsWith('ln')) {
+        throw new Error('Invalid BOLT12 offer request');
+    }
+    // Try standard bech32 decode first (handles offers with valid checksum),
+    // then fall back to no-checksum decode (e.g. Phoenix wallet offers)
+    let words;
+    const decoded = bech32.decodeUnsafe(offerRequest, Number.MAX_SAFE_INTEGER);
+    if (decoded) {
+        words = Array.from(decoded.words);
+    }
+    else {
+        words = decodeBech32NoChecksum(offerRequest);
+    }
+    // Convert 5-bit words to bytes
+    const data = bech32.fromWordsUnsafe(words);
+    if (!data) {
+        throw new Error('Failed to convert bech32 words to bytes');
+    }
+    // Parse byte-level TLV records (BigSize type + BigSize length + value)
+    const sections = [];
+    let offset = 0;
+    while (offset < data.length) {
+        const [type, afterType] = readBigSize(data, offset);
+        const [length, afterLength] = readBigSize(data, afterType);
+        const value = data.slice(afterLength, afterLength + length);
+        offset = afterLength + length;
+        const name = TLV_TYPES[type] ?? `unknown_${type}`;
+        sections.push({
+            name,
+            value: parseValue(type, value)
+        });
+    }
+    return { offerRequest, sections };
+}
+function getSection(decodedOffer, name) {
+    return decodedOffer.sections.find((section) => section.name === name);
+}
+function parse(decodedOffer) {
+    const description = getSection(decodedOffer, 'description');
+    return {
+        destination: {
+            value: decodedOffer.offerRequest,
+            protocol: 'lightning',
+            type: 'bolt12'
+        },
+        metadata: {
+            description: typeof description?.value === 'string' ? description.value : undefined
+        }
+    };
+}
+function bolt12(input) {
+    return parse(decode(input));
+}
+export { bolt12 };

package/dist/utils/lightning-address.d.ts

@@ -0,0 +1,5 @@
+import type { Input, ParsedDestination, ParsedLNAddress, WellKnown } from '../types';
+declare function parse(input: Input): ParsedLNAddress;
+declare function lightningAddress(input: Input): ParsedDestination;
+declare function wellKnown(lnaddress: string, needsParse?: boolean): Promise<WellKnown | false>;
+export { lightningAddress, parse, wellKnown };

package/dist/utils/lightning-address.js

@@ -0,0 +1,65 @@
+import { DecodeError } from '../types';
+const BASE_URL = 'https://';
+const headers = { 'Content-Type': 'application/json' };
+function parse(input) {
+    const atIndex = input.indexOf('@');
+    if (atIndex < 1) {
+        throw new DecodeError('Invalid lightning address format', 'INVALID_LNADDRESS');
+    }
+    const username = input.slice(0, atIndex);
+    const domain = input.slice(atIndex + 1);
+    if (!domain.includes('.')) {
+        throw new DecodeError('Invalid lightning address format', 'INVALID_LNADDRESS');
+    }
+    return { username, domain };
+}
+function lightningAddress(input) {
+    parse(input);
+    return {
+        destination: {
+            value: input,
+            protocol: 'lightning',
+            type: 'lnaddress'
+        }
+    };
+}
+async function wellKnown(lnaddress, needsParse = true) {
+    let url = lnaddress;
+    if (needsParse) {
+        try {
+            const parsed = parse(lnaddress);
+            url = `${BASE_URL}${parsed.domain}/.well-known/lnurlp/${parsed.username}`;
+        }
+        catch {
+            return false;
+        }
+    }
+    try {
+        const response = await fetch(url, {
+            headers,
+            method: 'GET'
+        });
+        const json = (await response.json());
+        const { callback, minSendable, maxSendable, commentAllowed, metadata } = json;
+        if (!callback) {
+            return false;
+        }
+        if (!minSendable) {
+            return false;
+        }
+        if (!maxSendable) {
+            return false;
+        }
+        return {
+            callback,
+            minSendable,
+            maxSendable,
+            commentAllowed,
+            metadata
+        };
+    }
+    catch {
+        return false;
+    }
+}
+export { lightningAddress, parse, wellKnown };

package/dist/utils/lnurl.d.ts

@@ -0,0 +1,4 @@
+import type { Input, ParsedDestination } from '../types';
+declare const LNURL_PREFIX = "lnurl";
+declare function lnurl(input: Input): ParsedDestination;
+export { lnurl, LNURL_PREFIX };

package/dist/utils/lnurl.js

@@ -0,0 +1,32 @@
+import { bech32 } from '@scure/base';
+import { DecodeError } from '../types';
+const LNURL_PREFIX = 'lnurl';
+function lnurl(input) {
+    let words;
+    try {
+        const decoded = bech32.decode(input, 2000);
+        if (decoded.prefix !== LNURL_PREFIX) {
+            throw new DecodeError(`Invalid HRP: expected "${LNURL_PREFIX}", got "${decoded.prefix}"`, 'INVALID_LNURL');
+        }
+        words = decoded.words;
+    }
+    catch (error) {
+        if (error instanceof DecodeError) {
+            throw error;
+        }
+        throw new DecodeError('Invalid LNURL encoding', 'INVALID_LNURL');
+    }
+    const bytes = bech32.fromWords(words);
+    const url = new TextDecoder().decode(new Uint8Array(bytes));
+    if (!url.startsWith('https://')) {
+        throw new DecodeError('LNURL does not contain a valid URL', 'INVALID_LNURL');
+    }
+    return {
+        destination: {
+            value: input,
+            protocol: 'lightning',
+            type: 'lnurl'
+        }
+    };
+}
+export { lnurl, LNURL_PREFIX };

package/dist/utils/network.d.ts

@@ -0,0 +1,3 @@
+import type { Input, Network } from '../types';
+declare function getNetwork(input: Input): Network | undefined;
+export { getNetwork };

package/dist/utils/network.js

@@ -0,0 +1,48 @@
+const MAINNET_ADDRESS_PREFIXES = ['bc1p', 'bc1q', 'bc1', '1', '3'];
+const TESTNET_ADDRESS_PREFIXES = [
+    'bcrt1q',
+    'bcrt1p',
+    'tb1q',
+    'tb1p',
+    'm',
+    'n',
+    '2'
+];
+const MAINNET_BOLT11_PREFIXES = ['lnbc'];
+const TESTNET_BOLT11_PREFIXES = ['lnbcrt', 'lntbs', 'lntb'];
+const MAINNET_BOLT12_PREFIXES = ['lno1'];
+const TESTNET_BOLT12_PREFIXES = ['lnbcrto1', 'lnto1'];
+const MAINNET_ARK_PREFIXES = ['ark'];
+const TESTNET_ARK_PREFIXES = ['tark'];
+function startsWithAny(input, prefixes) {
+    return prefixes.some((prefix) => input.startsWith(prefix));
+}
+function getNetwork(input) {
+    const lowerInput = input.toLowerCase();
+    if (startsWithAny(lowerInput, TESTNET_ADDRESS_PREFIXES)) {
+        return 'testnet';
+    }
+    if (startsWithAny(lowerInput, MAINNET_ADDRESS_PREFIXES)) {
+        return 'mainnet';
+    }
+    if (startsWithAny(lowerInput, TESTNET_BOLT11_PREFIXES)) {
+        return 'testnet';
+    }
+    if (startsWithAny(lowerInput, MAINNET_BOLT11_PREFIXES)) {
+        return 'mainnet';
+    }
+    if (startsWithAny(lowerInput, TESTNET_BOLT12_PREFIXES)) {
+        return 'testnet';
+    }
+    if (startsWithAny(lowerInput, MAINNET_BOLT12_PREFIXES)) {
+        return 'mainnet';
+    }
+    if (startsWithAny(lowerInput, TESTNET_ARK_PREFIXES)) {
+        return 'testnet';
+    }
+    if (startsWithAny(lowerInput, MAINNET_ARK_PREFIXES)) {
+        return 'mainnet';
+    }
+    return undefined;
+}
+export { getNetwork };

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "bitcoin-decoder",
+  "version": "0.1.0",
+  "description": "Decode bitcoin QR codes, URIs, and raw strings",
+  "type": "module",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "author": {
+    "name": "psycarlo",
+    "email": "psycarlo1@gmail.com",
+    "url": "https://psycarlo.com"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "bun test",
+    "type-check": "tsc --noEmit",
+    "check": "ultracite check",
+    "fix": "ultracite fix",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@noble/hashes": "^2.0.1",
+    "@scure/base": "^2.0.0",
+    "bip-321": "^0.0.10",
+    "light-bolt11-decoder": "^3.2.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.0",
+    "@types/bun": "^1.3.9",
+    "typescript": "^5.9.3",
+    "ultracite": "7.2.3"
+  },
+  "keywords": [
+    "bitcoin",
+    "decode",
+    "on-chain",
+    "lightning",
+    "ark",
+    "bip-21",
+    "bip-321",
+    "uri"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Psycarlo/bitcoin-decode"
+  },
+  "bugs": {
+    "email": "psycarlo1@gmail.com",
+    "url": "https://github.com/Psycarlo/bitcoin-decode/issues"
+  },
+  "homepage": "https://github.com/Psycarlo/bitcoin-decode#readme",
+  "workspaces": [
+    "website"
+  ]
+}