/ 
Business-Bitcoin-1.051
River stage zero No dependents
/ Business::Bitcoin

NAME

Business::Bitcoin - Easy and secure way to accept Bitcoin payments online

VERSION

$Revision: 1.051 $
$Date: Tue Oct 16 22:26:58 PDT 2018 $

SYNOPSIS

An easy and secure way to accept Bitcoin payments online using an HD wallet, generating new receiving addresses on demand and keeping the wallet private key offline.

use Business::Bitcoin;

my $bizbtc = new Business::Bitcoin (DB => '/tmp/bizbtc.db',
                                    XPUB => 'xpub...',
                                    Create => 1);

my $req = $bizbtc->request(Amount => 4200);

print 'Please pay '           . $req->amount . ' Satoshi ' .
      'to Bitcoin address '   . $req->address . ".\n" .
      'Once the payment has ' . $req->confirmations , ' confirmations, ' .
      "press <enter> to continue.\n";
readline(*STDIN);

print ($req->verify ? "Verified\n" : "Verification failed\n");

print "Enter a request address to verify a payment.\n";
my $address = <STDIN>; chomp $address;

my $req2 = $bizbtc->findreq(Address => $address);
print ($req2->verify ? "Verified\n" : "Verification failed\n");

HOW TO USE

To start receiving Bitcoin payments online, create an HD wallet using a BIP-32 HD wallet app such as Electrum, get the Extended Public Key for the wallet (a string beginning with "xpub") and plug it into the constructor's XPUB argument.

Now you can receive online payments as outlined above, while keeping your private key secure offline or in a hardware wallet. You should take all precautions to ensure that your XPUB key on the server is also safe, as its compromise can weaken your security, though it can't in itself lead to the loss of any Bitcoin.

To make this work right you need to find the correct key to plug into the XPUB parameter, so that the addresses generated by Business::Bitcoin match those your wallet uses to receive payments.

If you're using the Electrum wallet, you can just use its Master Public Key (from the menubar select Wallet -> Master Public Keys). To use this key you must also set the 'Path' parameter to 'electrum' when creating a new Business::Bitcoin object (or via the path() accessor).

By default, however, the addresses Business::Bitcoin generates will be for the key derivation path k/i, where k is the path of the extended public key provided in the XPUB parameter, and i is the index of the address being generated.

This provides the flexibility to use Business::Bitcoin in conjunction with any wallet, because different wallets use different key derivation paths to generate addresses. e.g. Electrum uses the path "m/0/i", MultiBit HD uses "m/a'/0/i", Mycellium uses "m/44'/0'/a'/0/i", etc. (m is the "Master Public Key" and a is the "account" index).

To have Business::Bitcoin generate addresses matching those generated by your wallet, ensure that the XPUB parameter contains the public key for the penultimate element of your wallet's key derivation path. So for Electrum that would be m/0, for MultiBit HD m/a'/0, and for Mycellium m/44'/0'/a'/0

Some wallets may not readily provide the key for this element of the path. In that case you can find it using a tool such as "ku" from Pycoin https://github.com/richardkiss/pycoin or a JavaScript tool such as the one at http://bip32.org/. It's probably best never to paste private keys in web forms however, so if your key derivation path requires the private key, best to use something like the "ku" tool on an offline machine.

METHODS

new

Create a new Business::Bitcoin object and open (or create) the requests database. The following named arguments are required:

    DB - The filename of the requests database

    XPUB - The extended public key for the wallet receiving payments

The following optional named arguments can be provided:

    Create - Create the requests table if it doesn't exist. If the table doesn't exist and Create is not true, the constructor will return undef. Unset by default.

    Clobber - Wipe out any existing database file first. Unset by default.

    StartIndex - Start generating receiving keys from the specified index rather than from 0. Useful if you've already used some receiving addresses before starting to receive payments using this module. Only relevant when Create is true and a new requests table is being created. Ignored when an existing requests table is being used; in that case the index is generated by the database. By default, receiving addresses will be generated starting from the first one, at index 0.

    Path - Set the path option for the key provided in the XPUB parameter. By default this is set to 'penultimate' which means the XPUB parameter should hold the key of the penultimate path element as described above. You can also set this to 'electrum', in which case you can directly provide ELectrum's "Master Public Key" in the XPUB parameter. (The master public key is at path "m", whereas the penultimate one to generate Electrum compatible addresses is at "m/0").

request

Create a new payment request and generate a new receiving address. Returns a Business::Bitcoin::Request object if successful, or undef on error. The following named argument is required:

    Amount - The amount of the payment requested, in Satoshi.

The following optional named arguments can be provided:

    Confirmations - The number of confirmations needed to verify payment of this request. The default is 5.

    Reference - Optional reference ID to be associated with the request, to facilitate integration with existing ordering systems. If a reference ID is provided it should be unique for each request.

findreq

Find a previously created payment request, by either Address or Reference. Returns a Business::Bitcoin::Request object if successful, or undef on error. Exactly one of the following named arguments is required:

    Address - The receiving address associated with the payment request

    Reference - The reference ID associated with the payment request

The following optional named argument can be provided:

    Confirmations - The number of confirmations needed to verify payment of this request. The default is 5.

ACCESSORS

Accessors can be called with no arguments to query the value of an object property, or with a single argument, to set the property to a specific value (unless the property is read only).

db

The filename of the requests DB file.

xpub

The extended public key from which all receiving keys are generated.

path

The path option for the XPUB key. This can either be 'penultimate' (the default) in which case addresses are generated using the path "k/i", or 'electrum' in which case addresses are generated using the path "k/0/i", where "k" is the path of the XPUB key provided.

version

The version number of this module. Read only.

PREREQUISITES

DBD::SQLite

Used to keep track of payment requests.

LWP and an Internet connection

Required to verify payments. Currently this is done via the blockchain.info API.

AUTHOR

Ashish Gulhati, <biz-btc at hash.neo.tc>

BUGS

Please report any bugs or feature requests to bug-business-bitcoin at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Business-Bitcoin. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Business::Bitcoin

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright (c) Ashish Gulhati.

This software package is Open Software; you can use, redistribute, and/or modify it under the terms of the Open Artistic License 2.0.

Please see http://www.opensoftwr.org/oal20.txt for the full license terms, and ensure that the license grant applies to you before using or modifying this software. By using or modifying this software, you indicate your agreement with the license terms.