Quickstart

Note

This guide assume that you have installed and configured bitcoin-core node. See Install cryptocurrency nodes for instructions.

This guide will walk you through the basics of creating simple bitcoin payment system that can receive and send transactions, create addresses, and estimate fees.

Creating currency and node objects

django-obm store configuration for specific node in database. There are two ways to create them.

1. Managemant command

Open settings.py and define BLOCKCHAIN_NODES_INITIAL_CONFIG setting. It maps on fields of django_obm.models.Node and related to it django_obm.models.Currency models.

BLOCKCHAIN_NODES_INITIAL_CONFIG = [
    {
        'currency': {
            'name': 'BTC',
            'min_confirmations': 2,
        },
        'name': 'bitcoin-core',
        'is_default': True,
        'rpc_username': 'rpcuser',
        'rpc_password': '************',
        'rpc_host': 'localhost',
        'rpc_port': 18332,
    },
]

To apply the config on database execute command bellow in your Django root:

$ python manage.py init_nodes
<Currency: BTC> created successfully.
<Node: bitcoin-core> created successfully.

It’s worth clarifying, that you can’t create Node or Currency object if framework doesn’t support corresponded cryptocurrency or node. To discover supported things you can use special connectors registry property.

>>> from django_obm import connectors
>>> connectors.registry.available_currencies
{'BTC'}
>>> connectors.registry.available_nodes
{'bitcoin-core'}

2. Manual creation

Also it can be created in any place of your project then when you need it.

>>> from django_obm import models
>>> currency = models.Currency.objects.create(
...     name='BTC',
...     min_confirmations=2,
... )
>>> models.Node.objects.create(
...     name='bitcoin-core',
...     currency=currency,
...     is_default=True,
...     rpc_username='username',
...     rpc_password='password',
...     rpc_host='127.0.0.1',
...     rpc_port=18332,
... )
<Node: bitcoin-core>

Receive payments

There are method and daemon to fetch received transactions from nodes and write them into database. Each transaction will get status tx.is_confirmed == True if the conformations number greater than tx.node.currency.min_conformations, in our case it’s 2.

Method

Now you are ready to receive payments. For fetch new received transaction call models.Node manager process_receipts method:

>>> models.Node.objects.process_receipts()

Daemon

Also you can use built-in daemon, that will do it by timer. Just execute run_receipts_processing django command.

python manage.py run_receipts_processing --frequency=120

It runs process_receipts models.Node manager method with specified frequency (defaults to 60 sec.). For defineing your own default frequency set RECEIPTS_PROCESSING_DEFAULT_FREQUENCY to needed value in settings.py.

The daemon has the --once option that allow to execute process_receipts only once, like regular command. It might be helpful if you wish to use some system-level (like systemd, crontab etc.) tool to accept payments.

Example

You can find the example in example project.