Bitcoind Coin Handler¶

Module contents¶

Bitcoind-based Coin Handler

This python module is a Coin Handler for Privex’s CryptoToken Converter, designed to handle all required functionality for both receiving and sending any cryptocurrency which has a coin daemon that has a JSONRPC API backwards compatible with bitcoind.

It will automatically handle any payments.models.Coin which has it’s type set to bitcoind

Coin object settings:

For each coin you intend to use with this handler, you should configure it as such:

Coin Key Description

coin_type This should be set to Bitcoind RPC compatible crypto (db value: bitcoind)

setting_host The IP or hostname for the daemon. If not specified, defaults to 127.0.0.1 / localhost

setting_port The RPC port for the daemon. If not specified, defaults to 8332

setting_user The rpcuser for the daemon. Generally MUST be specified.

setting_pass The rpcpassword for the daemon. Generally MUST be specified

setting_json A JSON string for optional extra config (see below)

Extra JSON (Handler Custom) config options:

confirms_needed Default 0; Amount of confirmations needed before loading a TX

use_trusted Default: True; If enabled, TXs returned from the daemon with ‘trusted’:true will always be accepted at 0 confs regardless of confirms_needed

string_amt Default: True; If true, when sending coins, a Decimal will be used (as a string). This can cause problems with older coins such as Dogecoin, so for older coins that need floats, set this to False.

Django Settings:

If you’d rather not store the RPC details in the database, you may specify them in Django’s settings.py.

If a coin symbol is specified in settings.COIND_RPC they will be used exclusively, and any handler settings on the Coin object will be ignored.

If a settings key isn’t specified, the default is the same as shown for coin object settings.

Example COIND_RPC Setting:
COIND_RPC = {
  "BTC": {
      'user': 'bitcoinrpc',
      'password': 'SuperSecurePass',
      'host':     '127.0.0.1',
      'port':     8332,
      'confirms_needed': 0,
      'string_amt': True,
      'use_trusted': True
  }
}

Copyright:

+===================================================+
|                 © 2019 Privex Inc.                |
|               https://www.privex.io               |
+===================================================+
|                                                   |
|        CryptoToken Converter                      |
|                                                   |
|        Core Developer(s):                         |
|                                                   |
|          (+)  Chris (@someguy123) [Privex]        |
|                                                   |
+===================================================+

payments.coin_handlers.Bitcoin.reload()[source]¶

Reload’s the provides property for the loader and manager from the DB.

By default, as there are many coins that use a direct fork of bitcoind, our classes can provide for any models.Coin by scanning for coins with the type bitcoind. This saves us from hard coding specific coin symbols.

Submodules¶

BitcoinLoader module¶

Copyright:

+===================================================+
|                 © 2019 Privex Inc.                |
|               https://www.privex.io               |
+===================================================+
|                                                   |
|        CryptoToken Converter                      |
|                                                   |
|        Core Developer(s):                         |
|                                                   |
|          (+)  Chris (@someguy123) [Privex]        |
|                                                   |
+===================================================+

class payments.coin_handlers.Bitcoin.BitcoinLoader.BitcoinLoader(symbols)[source]¶

Bases: payments.coin_handlers.base.BatchLoader.BatchLoader, payments.coin_handlers.Bitcoin.BitcoinMixin.BitcoinMixin

BitcoinLoader - Despite the name, loads TXs from any coin that has a bitcoind-compatible JsonRPC API

Known to work with: bitcoind, litecoind, dogecoind

Copyright:

+===================================================+
|                 © 2019 Privex Inc.                |
|               https://www.privex.io               |
+===================================================+
|                                                   |
|        CryptoToken Converter                      |
|                                                   |
|        Core Developer(s):                         |
|                                                   |
|          (+)  Chris (@someguy123) [Privex]        |
|                                                   |
+===================================================+

For the required Django settings, please see the module docstring in coin_handlers.Bitcoin

clean_txs(symbol: str, transactions: Iterable[dict], account: str = None) → Generator[dict, None, None][source]¶

Filters a list of transactions transactions as required, yields dict’s conforming with models.Deposit

Filters out transactions that are not marked as ‘receive’
Filters out mining transactions
Filters by address if account is specified
Filters out transactions that don’t have enough confirms, and are not reported as ‘trusted’

Return Generator<dict>:
Parameters:	symbol – Symbol of coin being cleaned transactions – A `list<dict>` or generator producing dict’s account – If not None, only return TXs sent to this address.
	A generator outputting dictionaries formatted as below

Output Format:

{
  txid:str, coin:str (symbol), vout:int,
  tx_timestamp:datetime, address:str, amount:Decimal
}

load_batch(symbol, limit=100, offset=0, account=None)[source]¶

Loads a batch of transactions for symbol in their original format into self.transactions

Parameters:	symbol (str) – The coin symbol to load TXs for limit (int) – The amount of transactions to load offset (int) – The amount of most recent TXs to skip (for pagination) account (str) – NOT USED BY THIS LOADER

provides¶: Dynamically populated by Bitcoin.__init__

rpcs = {}¶: For each coin connection specified in settings.COIND_RPC, we map it’s symbol to an instantiated instance of BitcoinRPC - stored as a static property, ensuring we don’t have to constantly re-create them.

settings¶: To ensure we always get fresh settings from the DB after a reload, self.settings gets _prep_settings()

BitcoinManager module¶

Copyright:

+===================================================+
|                 © 2019 Privex Inc.                |
|               https://www.privex.io               |
+===================================================+
|                                                   |
|        CryptoToken Converter                      |
|                                                   |
|        Core Developer(s):                         |
|                                                   |
|          (+)  Chris (@someguy123) [Privex]        |
|                                                   |
+===================================================+

class payments.coin_handlers.Bitcoin.BitcoinManager.BitcoinManager(symbol: str)[source]¶

Bases: payments.coin_handlers.base.BaseManager.BaseManager, payments.coin_handlers.Bitcoin.BitcoinMixin.BitcoinMixin

BitcoinManager - Despite the name, handles sending, balance, and deposit addresses for any coin that has a bitcoind-compatible JsonRPC API

Known to work with: bitcoind, litecoind, dogecoind

Copyright:

+===================================================+
|                 © 2019 Privex Inc.                |
|               https://www.privex.io               |
+===================================================+
|                                                   |
|        CryptoToken Converter                      |
|                                                   |
|        Core Developer(s):                         |
|                                                   |
|          (+)  Chris (@someguy123) [Privex]        |
|                                                   |
+===================================================+

For the required Django settings, please see the module docstring in coin_handlers.Bitcoin

address_valid(address) → bool[source]¶: If address is determined to be valid by the coind RPC, will return True. Otherwise False.

balance(address: str = None, memo: str = None, memo_case: bool = False) → decimal.Decimal[source]¶

Get the total amount received by an address, or the balance of the wallet if address not specified.

Parameters:	address – Crypto address to get balance for, if None, returns whole wallet balance memo – NOT USED BY THIS MANAGER memo_case – NOT USED BY THIS MANAGER
Returns:	Decimal(balance)

get_deposit() → tuple[source]¶: Returns a deposit address for this symbol :return tuple: A tuple containing (‘address’, crypto_address)

health() → Tuple[str, tuple, tuple][source]¶

Return health data for the passed symbol.

Health data will include: Symbol, Status, Current Block, Node Version, Wallet Balance, and number of p2p connections (all as strings)

Return tuple health_data:
	(manager_name:str, headings:list/tuple, health_data:list/tuple,)

health_test() → bool[source]¶

Check if the coin daemon is up or not, by requesting basic information such as current block and version.

Return bool:	True if the coin daemon appears to be working, False if it’s not

provides¶: Dynamically populated by Bitcoin.__init__

rpcs = {}¶: For each coin connection specified in settings.COIND_RPC, we map it’s symbol to an instantiated instance of BitcoinRPC - stored as a static property, ensuring we don’t have to constantly re-create them.

send(amount, address, memo=None, from_address=None, trigger_data=None) → dict[source]¶

Send the amount amount of self.symbol to a given address.

Example - send 0.1 LTC to LVXXmgcVYBZAuiJM3V99uG48o3yG89h2Ph

>>> s = BitcoinManager('LTC')
>>> s.send(address='LVXXmgcVYBZAuiJM3V99uG48o3yG89h2Ph', amount=Decimal('0.1'))

Parameters:	amount (Decimal) – Amount of coins to send, as a Decimal() address – Address to send the coins to from_address – NOT USED BY THIS MANAGER memo – NOT USED BY THIS MANAGER
Raises:	AccountNotFound – The destination address isn’t valid NotEnoughBalance – The wallet does not have enough balance to send this amount.
Return dict:	Result Information

Format:

{
    txid:str - Transaction ID - None if not known,
    coin:str - Symbol that was sent,
    amount:Decimal - The amount that was sent (after fees),
    fee:Decimal    - TX Fee that was taken from the amount,
    from:str       - The account/address the coins were sent from,
    send_type:str       - Should be statically set to "send"
}

setting¶: Retrieve only our symbol from self.settings for convenience

settings¶: To ensure we always get fresh settings from the DB after a reload, self.settings gets _prep_settings()

BitcoinMixin module¶

Copyright:

+===================================================+
|                 © 2019 Privex Inc.                |
|               https://www.privex.io               |
+===================================================+
|                                                   |
|        CryptoToken Converter                      |
|                                                   |
|        Core Developer(s):                         |
|                                                   |
|          (+)  Chris (@someguy123) [Privex]        |
|                                                   |
+===================================================+

class payments.coin_handlers.Bitcoin.BitcoinMixin.BitcoinMixin[source]¶

Bases: object

BitcoinMixin - shared code used by both Bitcoin.BitcoinLoader and Bitcoin.BitcoinManager

Copyright:

+===================================================+
|                 © 2019 Privex Inc.                |
|               https://www.privex.io               |
+===================================================+
|                                                   |
|        CryptoToken Converter                      |
|                                                   |
|        Core Developer(s):                         |
|                                                   |
|          (+)  Chris (@someguy123) [Privex]        |
|                                                   |
+===================================================+

all_coins¶

Since this is a Mixin, it may be self.coin: Coin, or self.coins: List[Coin]. This property detects whether we have a single coin, or multiple, and returns them as a dict.

Return dict coins:
	A dict<str,Coin> of supported coins, mapped by symbol