Configuration¶

Introduction ¶

cryptoassets.core must know about cryptocurrencies, databases and backends you use in your application.

Creating application object and configuring it ¶

Most of interaction with cryptoassets.core is done through cryptoassets.core.app.CryptoAssetsApp application object. Create one singleton instance within your application:

from cryptoassets.core.app import CryptoAssetsApp

assets_app = CryptoAssetsApp()

Configuring using YAML configuration file ¶

Use cryptoassets.configuration.Configuraror.load_yaml_file() to load YAML syntax config file:

from cryptoassets.core.app import CryptoAssetsApp
from cryptoassets.core.configuration import Configurator

assets_app = CryptoAssetsApp()

# This will load the configuration file for the cryptoassets framework
configurer = Configurator(assets_app)
configurer.load_yaml_file("my-cryptoassets-settings.yaml")

Example YAML configuration file:

---

# Cryptoassets.core configuration for example application

database:
    url: sqlite:////tmp/cryptoassets.example.sqlite

# What services we use to run talk to the cryptocurrency networks.
# This will configure us to use pre-defined block.io API service
# testnet accounts for BTC and Doge (coins are worthless)
coins:
    btc:
        backend:
            class: cryptoassets.core.backend.blockio.BlockIo
            api_key: b2db-c8ad-29d2-c611
            pin: ThisIsNotVerySecret1
            network: btctest
            # walletnotify section tells how we receive
            # transaction updates from the  the backend
            # (new deposits to the backend wallet)
            walletnotify:
                class: cryptoassets.core.backend.blockiowebsocket.BlockIoWebsocketNotifyHandler

# This section tells how cryptoassets helper process will
# notify your app from events like new incoming transactions
# and outgoing transaction confirmation updates
events:
    # For each event, we send a HTTP webhook notification
    # to your app. Your app should be listening HTTP at localhost:10000
    example_app:
        class: cryptoassets.core.event.http.HTTPEventHandler
        url: http://localhost:10000

Configuring using Python dict ¶

You can give your settings as Python dictionary:

CRYPTOASSETS_SETTINGS = {

    # You can use a separate database for cryptoassets,
    # or share the Django database. In any case, cryptoassets
    # will use a separate db connection.
    "database": {
        "url": "postgresql://localhost/cryptoassets",
        "echo": True,
    },

    # Locally running bitcoind in testnet
    "coins": {
        "btc": {
            "backend": {
                "class": "cryptoassets.core.backend.bitcoind.Bitcoind",
                "url": "http://x:y@127.0.0.1:9999/",

                # bitcoind has 60 seconds to get back to us
                "timeout": 60,

                # Cryptoassets helper process will use this UNIX named pipe to communicate
                # with bitcoind
                "walletnotify": {
                    "class": "cryptoassets.core.backend.httpwalletnotify.HTTPWalletNotifyHandler",
                    "ip": "127.0.0.1",
                    "port": 28882
               },
            },

            # We run in testnet mode
            "testnet": True
        },
    },
}

configurator.load_from_dict(CRYPTOASSETS_SETTINGS)

Configuration sections ¶

database ¶

Configure usd SQLAlchemy database connection.

Example:

"database": {
    "url": "postgresql://localhost/cryptoassets",
    "echo": true,
}

Note

The database connection will always use Serializable transaction isolation level.

For more information see

echo ¶

Set to true (or in Python to True) and executed SQL statements will be logged via Python logging.

coins ¶

Configure database models and used backends for cryptocurrencies and assets enabled in your application.

This dictonary contains a list of subentries.

Name of each entry is acronym of the cryptoasset in lowercase (btc, doge)

Example:

"coins": {
    # AppleByte using applebyted (bitcoind-like) as the backend
    "aby": {
        "backend": {
            "class": "cryptoassets.core.backend.bitcoind.Bitcoind",
            "url": "http://x:y@127.0.0.1:8607/",
            "walletnotify": {
                "class": "cryptoassets.core.backend.httpwalletnotify.HTTPWalletNotifyHandler",
                "ip": "127.0.0.1",
                "port": 28882
            },
        },
    },

    "bitcoin": {
        "backend": {
            "class": "cryptoassets.core.backend.bitcoind.Bitcoind",
            "url": "http://foo:bar@127.0.0.1:8332/"
            "max_tracked_incoming_confirmations": 20,
            "walletnotify":
                "class": "cryptoassets.core.backend.pipewalletnotify.PipedWalletNotifyHandler",
                "fname": "/tmp/cryptoassets-unittest-walletnotify"
        }
    }
},

models ¶

Optional.

You can set up your own altcoin or override default SQLAlchemy model configuration for an existing cryptoasset.

The value of this variable is the Python module containing coin_description variable. For more information how to describe your cryptoasset models, see cryptoassets.core.coin.registry.

Example:

"jesuscoin": {
    "backend": {
        "class": "cryptoassets.core.backend.bitcoind.Bitcoind",
        "url": "http://x:y@127.0.0.1:8607/",
        "walletnotify": {
            "class": "cryptoassets.core.backend.httpwalletnotify.HTTPWalletNotifyHandler",
            "ip": "127.0.0.1",
            "port": 28882
        },
    },
    "models": "mycoin.models"
},

testnet ¶

Set to true (Python True) if the coin backend is connected to a testnet.

This may affect address validation in the future. Currently this information is not utilized.

Example:

"jesuscoin": {
    "backend": {
        "class": "cryptoassets.core.backend.bitcoind.Bitcoind",
        "url": "http://x:y@127.0.0.1:8607/",
    },
    "testnet": True
},

This is how many confirmations tools.confirmationupdate tracks for each network transactions, both incoming and outgoing, until we consider it “closed” and stop polling backend for updates. The default value is 15.

For more information see cryptoassets.core.tools.confirmationupdate.

backend ¶

Installed backends for one cryptoasset in coins section.

For the available backends see backends list.

Each backend contains the following options

param walletnofiy:
param class:	tells which backend we are going to use
	tells what kind of incoming transaction notifications we have from the backend
param max_tracked_incoming_confirmations:
	This applications for mined coins and backends which do not actively post confirmations updates. It tells up to how many confirmations we poll the backend for confirmation updates. For details see `cryptoassets.core.tools.opentransactions`.

Other options: All backends take connection details (url, IPs) and credentials (passwords, API keys, etc.) These options are backend specific, so see the details from the backend documentation.

Example:

"coins" : {
    "btc": {
        "backend": {
            "class": "cryptoassets.core.backend.bitcoind.Bitcoind",
            "url": "http://x:y@127.0.0.1:8607/",
            "walletnotify": {
                "class": "cryptoassets.core.backend.httpwalletnotify.HTTPWalletNotifyHandler",
                "ip": "127.0.0.1",
                "port": 28882
            },
        },
    },
}

walletnotify ¶

Wallet notify configuration tells how cryptoassets helper service receives cryptoasset transaction updates from the cryptoassets backend (bitcoind, API service). Unless this is configured, cryptoassets service or your application won’t know about incoming transactions.

walletnotify section must be given in under backend configuration. It’s content depends on the chosen wallet notification method. For more information see qallet notification documentation.

Example:

"jesuscoin": {
    "backend": {
        "class": "cryptoassets.core.backend.bitcoind.Bitcoind",
        "url": "http://x:y@127.0.0.1:8607/",
        "walletnotify": {
            "class": "cryptoassets.core.backend.httpwalletnotify.HTTPWalletNotifyHandler",
            "ip": "127.0.0.1",
            "port": 28882
        },
    },
},

events ¶

Event handling is configured in the events section of the configuration file.

Event handling configuration tells how cryptoassets helper service notifies your application about occured events (transaction updates, etc.). There exist various means to communicate between your application and cryptoassets helper service.

For more information and examples read event API documentation.

Event section consists name and configuration data pairs. Currently event handler name is only used for logging purposes. You can configure multiple event handlers

Each handler gets class parameters and event handler specific setup parameters.

Example configuration

# List of cryptoassets notification handlers.
# Use this special handler to convert cryptoassets notifications to Django signals.
"events": {
    "django": {
        "class": "cryptoassets.core.event.python.InProcessNotifier",
        "callback": "cryptoassets.django.incoming.handle_tx_update"
    }
},

status_server ¶

Configure mini status server which you can use to check cryptoassets helper service status.

Example:

"database": {
    "url": "sqlite:////tmp/payments.sqlite",
},

...

"status-server": {
    "ip": "127.0.0.1",
    "port": 9000
}

ip ¶

IP address the status server will be listening to. Default 127.0.0.1.

port ¶

Port the status server is listening to.s

service ¶

Cryptoassets helper service process specific configuration. These sections only concern cryptoassets helper service process itself, not any framework calls you make inside your own Python application.

Example:

service:
    broadcast_period: 60
    logging:
        formatters:
            verbose:
                format: '%(levelname)s %(asctime)s %(module)s %(process)d %(thread)d %(message)s'

        handlers:
            file:
                level: DEBUG
                class: logging.FileHandler
                filename: /tmp/cryptoassets-startstop-test.log
                formatter: verbose
            console:
                level: DEBUG
                class: logging.StreamHandler
                formatter: verbose
                stream: ext://sys.stdout

        root:
            handlers:
                - file
                - console
            level: DEBUG

broadcast_period ¶

How often (seconds) the helper service will check for outgoing transactions to broadcast.

Default is 30 seconds.

logging ¶

Configure logging for cryptoassets helper service. Loggers are not configured if you import and call cryptoassets.core framework from your application.

cryptoassets.core uses standard Python logging mechanism.

For logging within your application when calling model methods configure logging with Python logging configuration.

Configuration¶

Introduction ¶

Creating application object and configuring it ¶

Configuring using YAML configuration file ¶

Configuring using Python dict ¶

Configuration sections ¶

database ¶

url ¶

echo ¶

coins ¶

models ¶

testnet ¶

max_confirmation_count ¶

backend ¶

walletnotify ¶

events ¶

status_server ¶

ip ¶

port ¶

service ¶

broadcast_period ¶

logging ¶