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
},
max_confirmation_count¶
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 class: | tells which backend we are going to use |
---|---|
param walletnofiy: | |
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
}
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.