diff --git a/README.rst b/README.rst index 135ecf54..5e91f9da 100644 --- a/README.rst +++ b/README.rst @@ -4,14 +4,17 @@ Python Bitcoin Library Bitcoin cryptocurrency Library writen in Python. Allows you to create a fully functional Bitcoin wallet with a single line of code. -Use this library to create and manage transactions, addresses/keys, wallets, mnemonic password phrases and blocks with -simple and straightforward Python code. +Use this library to create and manage transactions, addresses/keys, wallets, mnemonic password phrases +and blocks with simple and straightforward Python code. You can use this library at a high level and create and manage wallets from the command line or at a low level and create your own custom made transactions, scripts, keys or wallets. The BitcoinLib connects to various service providers automatically to update wallets, transaction and -blockchain information. +blockchain information. You can also connect to a local +`Bitcoin `_ or +`Bcoin node `_. + .. image:: https://github.com/1200wd/bitcoinlib/actions/workflows/unittests.yaml/badge.svg :target: https://github.com/1200wd/bitcoinlib/actions/workflows/unittests.yaml @@ -30,7 +33,7 @@ blockchain information. Install ------- -Installed required packages +Install required packages on Ubuntu or related Linux systems: .. code-block:: bash @@ -42,9 +45,11 @@ Then install using pip $ pip install bitcoinlib -For more detailed installation instructions, how to install on other systems or troubleshooting please read https://bitcoinlib.readthedocs.io/en/latest/source/_static/manuals.install.html +Check out the `more detailed installation instructions `_ to read how to install on other systems or for +troubleshooting. -If you are using docker you can check some Dockerfiles to create images in the docker directory. +If you are using docker you can check some Dockerfiles to create images in the +`docker `_ directory. Documentation ------------- @@ -65,7 +70,7 @@ Example: Create wallet and generate new address (key) to receive bitcoins >>> from bitcoinlib.wallets import Wallet >>> w = Wallet.create('Wallet1') >>> w.get_key().address - '1Fo7STj6LdRhUuD1AiEsHpH65pXzraGJ9j' + 'bc1qk25wwkvz3am9smmm3372xct5s7cwf0hmnq8szj' Now send a small transaction to your wallet and use the scan() method to update transactions and UTXO's @@ -79,7 +84,7 @@ If successful a transaction ID is returned .. code-block:: pycon - >>> t = w.send_to('1PWXhWvUH3bcDWn6Fdq3xhMRPfxRXTjAi1', '0.001 BTC', offline=False) + >>> t = w.send_to('bc1qemtr8ywkzg483g8m34ukz2l4pl3730776vzq54', '0.001 BTC', offline=False) 'b7feea5e7c79d4f6f343b5ca28fa2a1fcacfe9a2b7f44f3d2fd8d6c2d82c4078' >>> t.info # Shows transaction information and send results @@ -87,15 +92,19 @@ If successful a transaction ID is returned More examples ------------- -Checkout the documentation page https://bitcoinlib.readthedocs.io/en/latest/ or take a look at some -more examples at https://github.com/1200wd/bitcoinlib/tree/master/examples +You can find many more examples in the `documentation `_ +for instance about the `Wallet.create() `_ method. + +There are many working examples on how to create wallets, specific transactions, encrypted databases, parse the +blockchain, connect to specific service providers in the `examples directory `_ in the source code of this library. +Some more specific examples can be found on the `Coineva website `_. Contact ------- -If you have any questions, encounter a problem or want to share an idea, please use Github Discussions -https://github.com/1200wd/bitcoinlib/discussions +If you have any questions, encounter a problem or want to share an idea, please use `Github Discussions +`_ Implements the following Bitcoin Improvement Proposals @@ -115,13 +124,12 @@ Implements the following Bitcoin Improvement Proposals Future / Roadmap ---------------- -- Support advanced scripts - Fully support timelocks -- Support for lightning network +- Support Taproot and Schnorr signatures +- Support advanced scripts - Support for Trezor wallet or other hardware wallets - Allow to scan full blockchain - Integrate simple SPV client -- Support Schnorr signatures Disclaimer diff --git a/bitcoinlib/services/bitcoind.py b/bitcoinlib/services/bitcoind.py index f8196e88..e6afbf43 100644 --- a/bitcoinlib/services/bitcoind.py +++ b/bitcoinlib/services/bitcoind.py @@ -53,10 +53,13 @@ class BitcoindClient(BaseClient): """ @staticmethod + @deprecated def from_config(configfile=None, network='bitcoin', *args): """ Read settings from bitcoind config file + Obsolete: does not work anymore, passwords are not stored in bitcoin config, only hashed password. + :param configfile: Path to config file. Leave empty to look in default places :type: str :param network: Bitcoin mainnet or testnet. Default is bitcoin mainnet @@ -129,6 +132,7 @@ def __init__(self, network='bitcoin', base_url='', denominator=100000000, *args) if isinstance(network, Network): network = network.name if not base_url: + _logger.warning("Please provide rpc connection url to bitcoind node") bdc = self.from_config('', network) base_url = bdc.base_url network = bdc.network @@ -332,12 +336,9 @@ def getinfo(self): from pprint import pprint - # 1. Connect by specifying connection URL - # base_url = 'http://bitcoinrpc:passwd@host:8332' - # bdc = BitcoindClient(base_url=base_url) - - # 2. Or connect using default settings or settings from config file - bdc = BitcoindClient() + # Connect by specifying connection URL + base_url = 'http://bitcoinrpc:passwd@host:8332' + bdc = BitcoindClient(base_url=base_url) print("\n=== SERVERINFO ===") pprint(bdc.proxy.getnetworkinfo()) diff --git a/bitcoinlib/wallets.py b/bitcoinlib/wallets.py index b9943639..eed70a90 100644 --- a/bitcoinlib/wallets.py +++ b/bitcoinlib/wallets.py @@ -58,8 +58,7 @@ def wallets_list(db_uri=None, include_cosigners=False, db_password=None): :type db_uri: str :param include_cosigners: Child wallets for multisig wallets are for internal use only and are skipped by default :type include_cosigners: bool - :param db_password: Password to use for encrypted database. Requires the installation of sqlcipher (see - documentation). + :param db_password: Password to use for encrypted database. Requires the installation of sqlcipher (see documentation). :type db_password: str :return dict: Dictionary of wallets defined in database @@ -528,6 +527,20 @@ def name(self, value): self._dbkey.name = value self._commit() + @property + def keys_public(self): + if self.key_type == 'multisig': + return [k.public_byte for k in self.key()] + else: + return [self.key_public] + + @property + def keys_private(self): + if self.key_type == 'multisig': + return [k.private_byte for k in self.key() if k.private_byte] + else: + return [self.key_private] if self.key_private else [] + def key(self): """ Get HDKey object for current WalletKey @@ -1442,7 +1455,7 @@ def __del__(self): pass def __repr__(self): - db_uri = self.db_uri.split('?')[0] + db_uri = '' if not self.db_uri else self.db_uri.split('?')[0] if DEFAULT_DATABASE in db_uri: return "" % self.name return "" % \ diff --git a/docker/README.rst b/docker/README.rst index 06294040..70813d75 100644 --- a/docker/README.rst +++ b/docker/README.rst @@ -3,5 +3,11 @@ Dockerfiles You can find some basic Dockerfiles here for various system images. -These are used for testing and are not optimized for size and configuration. If you run the container is will -start all unittests. +These are used for testing and are not optimized for size and configuration. If you run the container it will +run all unittests. + +.. code-block:: bash + + $ cd + $ docker build -t bitcoinlib . + $ docker run -it bitcoinlib diff --git a/docker/mint/Dockerfile b/docker/mint/Dockerfile new file mode 100644 index 00000000..a3e208cf --- /dev/null +++ b/docker/mint/Dockerfile @@ -0,0 +1,22 @@ +FROM linuxmintd/mint22-amd64 +MAINTAINER Cryp Toon + +WORKDIR /code + +RUN apt-get update && apt-get upgrade -y +RUN apt-get install -y \ + software-properties-common git \ + build-essential python3-dev libgmp3-dev python3-pip python3.12-venv + +ENV TZ=Europe/Brussels +RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone +RUN apt-get install -y postgresql postgresql-contrib mariadb-server libpq-dev pkg-config default-libmysqlclient-dev +RUN apt-get clean + +RUN git clone https://github.com/1200wd/bitcoinlib.git + +WORKDIR /code/bitcoinlib +RUN python3 -m venv /opt/venv +RUN /opt/venv/bin/python3 -m pip install .[dev] + +CMD /opt/venv/bin/python3 -m unittest diff --git a/docs/_static/manuals.faq.rst b/docs/_static/manuals.faq.rst new file mode 100644 index 00000000..b93d4fe8 --- /dev/null +++ b/docs/_static/manuals.faq.rst @@ -0,0 +1,71 @@ +Frequently Asked Questions +========================== + +Can I use Bitcoinlib on my system? +---------------------------------- + +BitcoinLib is platform independent and should run on your system. +Bitcoinlib is mainly developed on Ubuntu linux and runs unittests on every commit on Ubuntu and Windows. +Dockerfiles are available for Alpine, Kali and Fedora. You can find all dockerfiles on https://github.com/1200wd/bitcoinlib/tree/master/docker + +I run into an error 'x' when installing Bitcoinlib +-------------------------------------------------- + +1. Check the `installation page `_ and see if you have installed all the requirements. +2. Install the required packages one-by-one using pip install, and see if you get any specific errors. +3. Check for help in `Github Discussions `_. +4. See if you find any known `issue `_. +5. If it doesn't work out, do not hesitate to ask you question in the github discussions or post an issue! + +Does Bitcoinlib support 'x'-coin +-------------------------------- + +Bitcoinlib main focus is on Bitcoin. But besides Bitcoin it supports Litecoin and Dogecoin. For testing +it supports Bitcoin testnet3, Bitcoin regtest, Litecoin testnet and Dogecoin testnet. + +Support for Dash, Bitcoin Cash and Bitcoin SV has been dropped. + +There are currently no plans to support other coins. Main problem with supporting new coins is the lack of +service provides with a working and stable API. + +My wallet transactions are not (correctly) updating! +---------------------------------------------------- + +Most likely cause is a problem with a specific service provider. + +Please set log level to 'debug' and check the logs in bitcoinlib.log to see if you can pin down the specific error. +You could then disable the provider and post the `issue `_. + +To avoid these kind of errors it is adviced to run your local `Bcoin node `_. +With a local Bcoin node you do not depend on external Service providers which increases reliability, security, speed +and privacy. + +Can I use Bitcoinlib with another database besides SQLite? +---------------------------------------------------------- + +Yes, the library can also work with PostgreSQL or MySQL / MariaDB databases. +For more information see: `Databases `_. + +I found a bug! +-------------- + +Please help out project and post your `issue `_ on Github. +Try to include all code and data so we can reproduce and solve the issue. + +I have another question +----------------------- + +Maybe your question already has an answer om `Github Discussions `_. +Or search for an answer is this `documentation `_. + +If that does not answer your question, please post your question on on the +`Github Discussions Q&A `_. + + + +.. + My transaction is not confirming + I have imported a private key but address from other wallet does not match Bitcoinlib's address + Is Bitcoinlib secure? + Donations? + diff --git a/docs/_static/manuals.install.rst b/docs/_static/manuals.install.rst index b82adb87..b0d1b605 100644 --- a/docs/_static/manuals.install.rst +++ b/docs/_static/manuals.install.rst @@ -169,15 +169,19 @@ location for a config file in the BCL_CONFIG_FILE: os.environ['BCL_CONFIG_FILE'] = '/var/www/blocksmurfer/bitcoinlib.ini' -Tweak BitcoinLib ----------------- +Service providers and local nodes +--------------------------------- You can `Add another service Provider `_ to this library by updating settings and write a new service provider class. -If you use this library in a production environment it is advised to run your own Bcoin, Bitcoin, Litecoin or Dash node, -both for privacy and reliability reasons. More setup information: -`Setup connection to bitcoin node `_ +To increase reliability, speed and privacy or if you use this library in a production environment it +is advised to run your own Bcoin or Bitcoin node. + +More setup information: + +* `Setup connection to Bcoin node `_ +* `Setup connection to Bitcoin node `_ Some service providers require an API key to function or allow additional requests. You can add this key to the provider settings file in .bitcoinlib/providers.json diff --git a/docs/_static/manuals.security.rst b/docs/_static/manuals.security.rst index 9cde36d2..4b5a02b1 100644 --- a/docs/_static/manuals.security.rst +++ b/docs/_static/manuals.security.rst @@ -1,10 +1,10 @@ -10 Security and Privacy Tips -============================ +Frequently Asked Questions +========================== Ten tips for more privacy and security when using Bitcoin and Bitcoinlib: 1. Run your own `Bitcoin `_ - or Bcoin node, so you are not depending on external Blockchain API service providers anymore. + or `Bcoin `_ node, so you are not depending on external Blockchain API service providers anymore. This not only increases your privacy, but also makes your application much faster and more reliable. And as extra bonus you support the Bitcoin network. 2. Use multi-signature wallets. So you are able to store your private keys in separate (offline) locations. diff --git a/docs/_static/manuals.setup-bcoin.rst b/docs/_static/manuals.setup-bcoin.rst new file mode 100644 index 00000000..498841cd --- /dev/null +++ b/docs/_static/manuals.setup-bcoin.rst @@ -0,0 +1,42 @@ +How to connect Bitcoinlib to a Bcoin node +========================================= + +Bcoin is a full bitcoin node implementation, which can be used to parse the blockchain, send transactions and run a +wallet. With a Bcoin node you can retrieve transaction and utxo information for specific addresses, this is not easily +possible with a `Bitcoind `_ node. So if you want to use Bitcoinlib with a +wallet and not be dependant on external providers the best option is to run a local Bcoin node. + + +Install Bcoin node +------------------ + +You can find some instructions on how to install a bcoin node on https://coineva.com/install-bcoin-node-ubuntu.html. + +There are also some Docker images available. We have created a Docker image with the most optimal settings for +bitcoinlib. You can install them with the following command. + +.. code-block:: bash + + docker pull blocksmurfer/bcoin + + +Use Bcoin node with Bitcoinlib +------------------------------ + +To use Bcoin with bitcoinlib add the credentials to the providers.json configuration file in the .bitcoinlib directory. + +.. code-block:: text + + "bcoin": { + "provider": "bcoin", + "network": "bitcoin", + "client_class": "BcoinClient", + "provider_coin_id": "", + "url": "https://user:pass@localhost:8332/", + "api_key": "", + "priority": 20, + "denominator": 100000000, + "network_overrides": null + }, + +You can increase the priority so the Service object always connects to the Bcoin node first. diff --git a/docs/_static/manuals.setup-bitcoind-connection.rst b/docs/_static/manuals.setup-bitcoind-connection.rst index 2c38b555..d3193f86 100644 --- a/docs/_static/manuals.setup-bitcoind-connection.rst +++ b/docs/_static/manuals.setup-bitcoind-connection.rst @@ -1,4 +1,4 @@ -How to connect bitcoinlib to a bitcoin node +How to connect bitcoinlib to a Bitcoin node =========================================== This manual explains how to connect to a bitcoind server on your localhost or an a remote server. @@ -7,6 +7,12 @@ Running your own bitcoin node allows you to create a large number of requests, f and more control, privacy and independence. However you need to install and maintain it and it used a lot of resources. +.. warning:: + With a standard Bitcoin node you can only retrieve block and transaction information. You can not + query the node for information about specific addresses. So it not suitable to run in combination with a Bitcoinlib + wallet. If you would like to use Bitcoinlib wallets and not be dependent on external providers you should use a + `Bcoin node `_ instead. + Bitcoin node settings --------------------- @@ -16,47 +22,39 @@ For more information on how to install a full node read https://bitcoin.org/en/f Please make sure you have server and txindex option set to 1. +Generate a RPC authorization configuration string online: https://jlopp.github.io/bitcoin-core-rpc-auth-generator/ +or with the Python tool you can find in the Bitcoin repository: https://github.com/bitcoin/bitcoin/blob/master/share/rpcauth/rpcauth.py + So your bitcoin.conf file for testnet should look something like this. For mainnet use port 8332, and remove the 'testnet=1' line. .. code-block:: text - [rpc] - rpcuser=bitcoinrpc - rpcpassword=some_long_secure_password server=1 port=18332 txindex=1 testnet=1 + rpcauth=bitcoinlib:01cf8eb434e3c9434e244daf3fc1cc71$9cdfb346b76935569683c12858e13147eb5322399580ba51d2d878148a880d1d + rpcbind=0.0.0.0 + rpcallowip=192.168.0.0/24 +To increase your privacy and security, and for instance if you run a Bitcoin node on your home network, you can +use TOR. Bitcoind has TOR support build in, and it is ease to setup. +See https://en.bitcoin.it/wiki/Setting_up_a_Tor_hidden_service -Connect using config files --------------------------- - -Bitcoinlib looks for bitcoind config files on localhost. So if you running a full bitcoin node from -your local PC as the same user everything should work out of the box. +If you have a TOR service running you can add these lines to your bitcoin.conf settings to only use TOR. -Config files are read from the following files in this order: -* [USER_HOME_DIR]/.bitcoinlib/bitcoin.conf -* [USER_HOME_DIR]/.bitcoin/bitcoin.conf - -If your config files are at another location, you can specify this when you create a BitcoindClient -instance. - -.. code-block:: python +.. code-block:: text - from bitcoinlib.services.bitcoind import BitcoindClient - - bdc = BitcoindClient.from_config('/usr/local/src/.bitcoinlib/bitcoin.conf') - txid = 'e0cee8955f516d5ed333d081a4e2f55b999debfff91a49e8123d20f7ed647ac5' - rt = bdc.getrawtransaction(txid) - print("Raw: %s" % rt) + proxy=127.0.0.1:9050 + bind=127.0.0.1 + onlynet=onion Connect using provider settings ------------------------------- -Connection settings can also be added to the service provider settings file in +Connection settings can be added to the service provider settings file in .bitcoinlib/config/providers.json Example: @@ -79,7 +77,7 @@ Example: Connect using base_url argument ------------------------------- -Another options is to pass the 'base_url' argument to the BitcoindClient object directly. +You can also directly pass connection string wit the 'base_url' argument in the BitcoindClient object. This provides more flexibility but also the responsibility to store user and password information in a secure way. @@ -94,11 +92,27 @@ This provides more flexibility but also the responsibility to store user and pas print("Raw: %s" % rt) +You can directly r + +.. code-block:: python + + from bitcoinlib.services.bitcoind import BitcoindClient + + # Retrieve some blockchain information and statistics + bdc.proxy.getblockchaininfo() + bdc.proxy.getchaintxstats() + bdc.proxy.getmempoolinfo() + + # Add a node to the node list + bdc.proxy.addnode('blocksmurfer.io', 'add') + + + Please note: Using a remote bitcoind server ------------------------------------------- Using RPC over a public network is unsafe, so since bitcoind version 0.18 remote RPC for all network interfaces -is disabled. The rpcallowip option cannot be used to listen on all network interfaces and rpcbind has to be used to +are disabled. The rpcallowip option cannot be used to listen on all network interfaces and rpcbind has to be used to define specific IP addresses to listen on. See https://bitcoin.org/en/release/v0.18.0#configuration-option-changes You could setup a openvpn or ssh tunnel to connect to a remote server to avoid this issues. diff --git a/docs/index.rst b/docs/index.rst index a8ba2359..7b644038 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -226,12 +226,14 @@ For more examples see https://github.com/1200wd/bitcoinlib/tree/master/examples Installation and Settings source/_static/manuals.command-line-wallet - Add Service Provider Bitcoind Node + Bcoin Node + Add Service Provider Databases Encrypted Database Security & Privacy source/_static/manuals.caching + FAQ .. toctree::