README

Modern PHP 8.3+ BOLT 11 Lightning Network invoice encoder/decoder. Full spec compliance, production-ready.

Features

• ⚡ Full BOLT 11 spec compliance — All 12 spec test vectors pass
• 🔐 Encode, sign & decode — Complete lifecycle support
• 🏗️ Modern PHP 8.3+ — Enums, readonly classes, named arguments, match expressions
• 🔍 PHPStan level 9 + Psalm errorLevel 1 — Maximum static analysis strictness from two analyzers
• 🌐 All networks — Bitcoin, Testnet, Signet, Regtest
• 🏷️ All tag types — payment_hash, description, route hints, feature bits, metadata, and more
• 🔄 Round-trip safe — Encode → sign → decode preserves all data
• 📏 PSR-12 code style — Enforced with PHP-CS-Fixer
• 🔒 Audited crypto dependency — Uses paragonie/ecc for ECDSA operations

Installation

composer require nova-carnivore/bolt11-php

Requirements

• PHP 8.3 or higher
• ext-gmp (required by paragonie/ecc)

Quick Start

Decode an Invoice

use Nova\Bitcoin\Bolt11\Decoder;

$invoice = Decoder::decode('lnbc2500u1pvjluez...');

$invoice->satoshis;          // 250000
$invoice->millisatoshis;     // '250000000'
$invoice->network;           // Network::Bitcoin
$invoice->timestamp;         // 1496314658
$invoice->payeeNodeKey;      // '03e7156ae33b...'

// Access tags
$invoice->getPaymentHash();   // hex string
$invoice->getDescription();   // 'string'
$invoice->getPaymentSecret(); // hex string
$invoice->isExpired();        // bool
$invoice->getTag('payment_hash'); // Tag object

Encode an Invoice

use Nova\Bitcoin\Bolt11\Encoder;
use Nova\Bitcoin\Bolt11\Network;
use Nova\Bitcoin\Bolt11\Tag;

$unsigned = Encoder::encode(
    network: Network::Bitcoin,
    satoshis: 1000,
    tags: [
        Tag::paymentHash('0001020304050607...'),
        Tag::paymentSecret('1111111111111111...'),
        Tag::description('test payment'),
        Tag::expiry(3600),
    ],
);

Sign an Invoice

use Nova\Bitcoin\Bolt11\Signer;

$signed = Signer::sign($unsigned, $privateKeyHex);

$signed->paymentRequest; // 'lnbc10u1...'
$signed->complete;       // true
$signed->payeeNodeKey;   // compressed public key

Amount Helpers

use Nova\Bitcoin\Bolt11\Helpers;

Helpers::satToHrp(250000);       // '2500u'
Helpers::hrpToSat('2500u');      // '250000'
Helpers::millisatToHrp('1000');  // '10n'
Helpers::hrpToMillisat('10n');   // '1000'

API Reference

Decoder::decode(string $paymentRequest): Invoice

Decodes a BOLT 11 payment request string into an Invoice object. Handles both lowercase and UPPERCASE invoices.

Encoder::encode(...): Invoice

Creates an unsigned invoice. Parameters:

Signer::sign(Invoice $invoice, string $privateKeyHex): Invoice

Signs an unsigned invoice with a secp256k1 private key.

Invoice (Value Object)

Tag Factory Methods

Tag::paymentHash(string $hex): Tag
Tag::paymentSecret(string $hex): Tag
Tag::description(string $text): Tag
Tag::descriptionHash(string $hex): Tag
Tag::payeeNodeKey(string $hex): Tag
Tag::expiry(int $seconds): Tag
Tag::minFinalCltvExpiry(int $blocks): Tag
Tag::fallbackAddress(int $code, string $addressHash): Tag
Tag::routeHint(array $hops): Tag
Tag::featureBits(FeatureBits $bits): Tag
Tag::metadata(string $hex): Tag

Enums

enum Network: string {
    case Bitcoin = 'bc';
    case Testnet = 'tb';
    case Signet  = 'tbs';
    case Regtest = 'bcrt';
}

enum TagType: int {
    case PaymentHash = 1;
    case PaymentSecret = 16;
    case Description = 13;
    // ... and more
}

enum Multiplier: string {
    case Milli = 'm';
    case Micro = 'u';
    case Nano  = 'n';
    case Pico  = 'p';
}

BOLT 11 Spec Compliance

All 12 official test vectors pass:

Supported Tagged Fields

Exception Handling

use Nova\Bitcoin\Bolt11\Exception\{
    Bolt11Exception,           // Base exception
    InvalidInvoiceException,   // Malformed invoice
    InvalidChecksumException,  // Bad bech32 checksum
    InvalidSignatureException, // Signature issues
    InvalidAmountException,    // Bad amount format
    UnsupportedNetworkException, // Unknown network
};

try {
    $invoice = Decoder::decode($paymentRequest);
} catch (InvalidChecksumException $e) {
    // Bad checksum
} catch (InvalidInvoiceException $e) {
    // Malformed invoice
} catch (Bolt11Exception $e) {
    // Any BOLT 11 error
}

Development

# Install dependencies
composer install

# Run tests
vendor/bin/phpunit

# Static analysis
vendor/bin/phpstan analyse
vendor/bin/psalm

# Code style check
vendor/bin/php-cs-fixer fix --dry-run --diff

# Fix code style
vendor/bin/php-cs-fixer fix

Architecture

src/
├── Decoder.php            # Main decoder
├── Encoder.php            # Main encoder
├── Signer.php             # Invoice signing (secp256k1)
├── Secp256k1Recovery.php  # ECDSA public key recovery
├── Invoice.php            # Immutable value object
├── Tag.php                # Tag value object with factory methods
├── TagType.php            # Tag type enum
├── Network.php            # Network enum (Bitcoin, Testnet, Signet, Regtest)
├── Multiplier.php         # Amount multiplier enum (m, u, n, p)
├── Amount.php             # Amount value object
├── RouteHint.php          # Route hint value object
├── FallbackAddress.php    # Fallback address value object
├── FeatureBits.php        # Feature bits handler
├── Bech32.php             # Bech32 encoder/decoder
├── Helpers.php            # Static helper methods
└── Exception/
    ├── Bolt11Exception.php
    ├── InvalidInvoiceException.php
    ├── InvalidChecksumException.php
    ├── InvalidSignatureException.php
    ├── InvalidAmountException.php
    └── UnsupportedNetworkException.php

License

MIT — see LICENSE.