Bips Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bitcoin/bips
   

   No additional configuration is needed—this is a pure PHP library with no Laravel-specific dependencies.

2. First Use Case: Fetching a BIP

   use Bitcoin\Bitcoin;
   use Bitcoin\Network\NetworkFactory;
   
   $network = NetworkFactory::mainnet();
   $bitcoin = new Bitcoin($network);
   
   // Fetch BIP-21 (URI Scheme)
   $bip21 = $bitcoin->getBip(21);
   echo $bip21->getTitle(); // Output: "Bitcoin URI Scheme"
   

3. Where to Look First

   • BIP List: Explore available BIPs via $bitcoin->getBips() (returns an array of BIP objects).
   • Network-Specific BIPs: Use NetworkFactory to switch between mainnet, testnet, or regtest.
   • Documentation: Check the Bitcoin Wiki for context on BIPs.

Implementation Patterns

Common Workflows

1. Validating Bitcoin Addresses (BIP-173)

   $network = NetworkFactory::mainnet();
   $bitcoin = new Bitcoin($network);
   
   $bip173 = $bitcoin->getBip(173);
   $isValid = $bip173->validateAddress('1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa'); // true
   

2. Parsing URIs (BIP-21)

   $bip21 = $bitcoin->getBip(21);
   $uri = $bip21->parseUri('bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa?amount=0.1');
   echo $uri->getAddress(); // 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
   echo $uri->getAmount();  // 0.1
   

3. Generating Bech32 Addresses (BIP-173)

   $bip173 = $bitcoin->getBip(173);
   $bech32 = $bip173->generateBech32Address('bc', '0014751e76e8199196d454941c45d1b3a323f1433bd6');
   echo $bech32; // bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq
   

4. Integration with Laravel Requests

   use Illuminate\Http\Request;
   
   public function handleBitcoinUri(Request $request) {
       $uri = $request->input('bitcoin_uri');
       $bip21 = (new Bitcoin(NetworkFactory::mainnet()))->getBip(21);
       $parsed = $bip21->parseUri($uri);
   
       return response()->json($parsed->toArray());
   }
   

5. Testing with Regtest

   $network = NetworkFactory::regtest();
   $bitcoin = new Bitcoin($network);
   $bip32 = $bitcoin->getBip(32); // Hierarchical Deterministic Wallets
   

Extension Points

• Custom BIPs: Extend the library by implementing Bitcoin\BIP\BIPInterface for unsupported BIPs.
• Network-Specific Logic: Override NetworkFactory to add custom networks (e.g., for forks like Litecoin).
• Caching: Cache BIP objects in Laravel’s cache layer to avoid repeated parsing:

  $bip = Cache::remember("bip.{$bipNumber}", now()->addHours(1), fn() =>
      (new Bitcoin($network))->getBip($bipNumber)
  );
  

Gotchas and Tips

Pitfalls

1. Network Mismatches

   • Issue: Using mainnet BIPs with testnet addresses (or vice versa) will fail validation.
   • Fix: Always initialize Bitcoin with the correct network:

     $network = NetworkFactory::testnet(); // For testnet addresses
     

2. BIP Versioning

   • Issue: Some BIPs (e.g., BIP-32) have multiple versions. The library may default to the latest, breaking legacy code.
   • Fix: Check the BIP’s getVersion() method or documentation for compatibility.

3. Deprecated BIPs

   • Issue: Older BIPs (e.g., BIP-70) may not be fully implemented or may be obsolete.
   • Fix: Verify BIP status on the Bitcoin Wiki before use.

4. Performance with Large BIPs

   • Issue: Parsing complex BIPs (e.g., BIP-158) can be slow for high-traffic Laravel routes.
   • Fix: Cache BIP objects or lazy-load them:

     $bip = $bitcoin->getBip(158)->setLazyLoading(true);
     

Debugging Tips

1. Enable Strict Mode

   $bitcoin = new Bitcoin($network, true); // Throws exceptions for invalid operations
   

2. Log BIP Parsing Errors

   try {
       $bip = $bitcoin->getBip(9999); // Non-existent BIP
   } catch (\Bitcoin\Exception\BIPNotFoundException $e) {
       Log::error("BIP not found: {$e->getBipNumber()}");
   }
   

3. Validate Inputs

   • Always sanitize user-provided inputs (e.g., Bitcoin URIs) before parsing:

     $uri = filter_var($request->input('uri'), FILTER_SANITIZE_URL);
     

Configuration Quirks

1. Default Network

   • The library defaults to mainnet. Explicitly set the network to avoid surprises:

     $bitcoin = new Bitcoin(NetworkFactory::mainnet()); // Always specify!
     

2. BIP Metadata

   • Some BIPs (e.g., BIP-44) include metadata like purpose or version. Access via:

     $bip44 = $bitcoin->getBip(44);
     echo $bip44->getMetadata()['purpose']; // "Multi-purpose"
     

3. Thread Safety

   • The library is stateless and thread-safe. Instantiate Bitcoin per request or reuse across threads.

Pro Tips

1. Batch Processing

   • Fetch multiple BIPs in one go for wallet logic (e.g., BIP-32 + BIP-44):

     $bips = [
         $bitcoin->getBip(32),
         $bitcoin->getBip(44),
         $bitcoin->getBip(49),
     ];
     

2. Laravel Service Provider

   • Bind the Bitcoin instance to the container for dependency injection:

     // config/app.php
     'bindings' => [
         Bitcoin::class => fn() => new Bitcoin(NetworkFactory::mainnet()),
     ];
     

3. Custom Exceptions

   • Extend Bitcoin\Exception\BitcoinException for domain-specific error handling:

     throw new BitcoinException("Invalid BIP-21 URI: {$uri}");
     

4. Testing

   • Use NetworkFactory::regtest() for isolated testing:

     $bitcoin = new Bitcoin(NetworkFactory::regtest());
     $bip32 = $bitcoin->getBip(32);
     $this->assertTrue($bip32->isValidMasterPrivateKey('xprv...'));