README.md

Monero Python Library

Warning

monero-python is currently under maintenance, expect bugs and breaking changes. The maintenance of this project has been generously funded by the Monero CCS.

A Python library for creating Monero applications using RPC and Python bindings to monero v0.18.4.4 'Fluorine Fermi'.

• Supports wallet and daemon RPC clients.
• Supports client-side wallets using Python bindings.
• Supports multisig, view-only, and offline wallets.
• Wallet types are interchangeable by conforming to a common interface.
• Uses a clearly defined data model and API specification intended to be intuitive and robust.
• Query wallet transactions, transfers, and outputs by their properties.
• Fetch and process binary data from the daemon (e.g. raw blocks).
• Receive notifications when blocks are added to the chain or when wallets sync, send, or receive.

Architecture

Build Python applications using RPC or Python bindings to monero-project/monero. Wallet implementations are interchangeable by conforming to a common interface, MoneroWallet.

Sample code

from monero import *

# connect to daemon
daemon: MoneroDaemon = MoneroDaemonRpc("http://localhost:38081", "superuser", "abctesting123")
height: int = daemon.get_height() # 1523651
txs_in_pool: list[MoneroTx] = daemon.get_tx_pool() # get transactions in the pool

# create wallet from mnemonic phrase using Python bindings to monero-project

wallet_config = MoneroWalletConfig()
wallet_config.path = "sample_wallet_full"
wallet_config.password = "supersecretpassword123"
wallet_config.network_type = MoneroNetworkType.STAGENET
wallet_config.server = MoneroRpcConnection()
wallet_config.server.username = "superuser"
wallet_config.server.password = "abctesting123"
wallet_config.seed = "hefty value scenic..."
wallet_config.restore_height = 573936
wallet_full: MoneroWallet = MoneroWalletFull.create_wallet(wallet_config)

# custom wallet listener implementation
listener: MoneroWalletListener = MyWalletListener()

# synchronize the wallet and receive progress notifications
wallet_full.sync(listener)

# synchronize in the background every 5 seconds
wallet_full.start_syncing(5000)

# receive notifications when funds are received, confirmed, and unlocked
wallet_full.add_listener(listener)

# connect to wallet RPC and open wallet
wallet_rpc: MoneroWallet = MoneroWalletRpc("http://localhost:38083", "rpc_user", "abc123")
wallet_rpc.open_wallet("sample_wallet_rpc", "supersecretpassword123")
primary_address: str = wallet_rpc.get_primary_address() # 555zgduFhmKd2o8rPUz...
balance: int = wallet_rpc.get_balance() # 533648366742
txs: list[MoneroTxWallet] = wallet_rpc.get_txs() # get transactions containing transfers to/from the wallet

# send funds from RPC wallet to full wallet
tx_config = MoneroTxConfig()
tx_config.account_index = 0
tx_config.address = wallet_full.get_address(1, 0)
tx_config.amount = 250000000000 # send 0.25 XMR (denominated in atomic units)
tx_config.relay = False # create transaction and relay to the network if true

created_tx: MoneroTxWallet = wallet_rpc.create_tx(tx_config)
fee: int = created_tx.get_fee() # "Are you sure you want to send... ?"
wallet_rpc.relay_tx(created_tx) # relay the transaction

# save and close wallet
wallet_full.close(True)

Building monero-python from source

Linux and macOS

1. Install build dependencies:
   

   # Ubuntu/Debian
   
   sudo apt install -y python3-all python3-pip python3-pybind11

   # Fedora/RedHat
   
   sudo dnf install -y python3-all python3-pip python3-pybind11

2. Clone the project repository:

   git clone --recurse-submodules https://github.com/everoddandeven/monero-python.git

3. Build the monero-cpp submodule (located at ./external/monero-cpp) as a native library by following instructions for your system.

4. Copy shared library ./external/monero-cpp/build/libmonero-cpp.so to /usr/lib:

   sudo cp ./external/monero-cpp/build/libmonero-cpp.so /usr/lib/
   

5. Build monero-python to ./build/:
   

   cd monero-python
   mkdir -p build
   cd build
   cmake ..
   make

6. Or build and install monero-python with pip: pip3 install . --break-system-packages

Linux Docker Build

1. Install Docker

2. Clone the repository

   git clone --recursive https://github.com/everoddandeven/monero-python.git

3. Prepare build environment

   cd monero-python
   docker build --tag monero-python:build-linux --build-arg THREADS=4 --file Dockerfile.linux .

4. (Optional) Specify build image

   cd monero-python
   docker build --tag monero-python:build-linux --build-arg BASE_IMAGE="ubuntu:22.04" --build-arg THREADS=4 --file Dockerfile.linux .

5. Build

   docker run --rm -it -v <MONERO_PYTHON_DIR_FULL_PATH>:/monero-python -w /monero-python monero-python:build-linux sh ./docker/build.sh

   • MONERO_PYTHON_DIR_FULL_PATH - full path to monero-python directory

6. Library build will be placed in monero-python/build directory

Windows

1. Download and install MSYS2.

2. Press the Windows button and launch MSYS2 MINGW64.

3. Update packages: pacman -Syu and confirm at prompts.

4. Relaunch MSYS2 (if necessary) and install dependencies:

   pacman -S mingw-w64-x86_64-toolchain make mingw-w64-x86_64-cmake mingw-w64-x86_64-openssl mingw-w64-x86_64-zeromq mingw-w64-x86_64-libsodium mingw-w64-x86_64-hidapi mingw-w64-x86_64-unbound mingw-w64-x86_64-protobuf git mingw-w64-x86_64-libusb gettext base-devel
   wget https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-icu-75.1-2-any.pkg.tar.zst
   pacman -U mingw-w64-x86_64-icu-75.1-2-any.pkg.tar.zst
   wget https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-boost-1.85.0-4-any.pkg.tar.zst
   pacman -U mingw-w64-x86_64-boost-1.85.0-4-any.pkg.tar.zst
   wget https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-pybind11-2.13.6-2-any.pkg.tar.zst
   pacman -U mingw-w64-x86_64-pybind11-2.13.6-2-any.pkg.tar.zst
   

5. Clone repo: git clone --recurse-submodules https://github.com/everoddandeven/monero-python.git

6. Build monero-cpp, located as a submodule at ./external/monero-cpp:

   ./bin/build_libmonero_cpp.sh
   

7. Build monero-python:

   mkdir -p build &&
   cd build &&
   cmake ..
   cmake --build .
   

8. Or run build script: ./bin/build_libmonero_python.sh

Use RPC servers in your project:

1. Download and install Monero CLI.
2. Start monerod, e.g.: ./monerod --stagenet (or use a remote daemon).
3. Start monero-wallet-rpc, e.g.: ./monero-wallet-rpc --daemon-address http://localhost:38081 --stagenet --rpc-bind-port 38083 --rpc-login rpc_user:abc123 --wallet-dir ./

Note

On Windows, if you want to use native wallets instead of monero-wallet-rpc, or if you want to process binary data, first install MSYS2:

1. Install MSYS2.
2. Environment variables > System variables > Path > Edit > New > C:\msys64\mingw64\bin

Memory Growth

If you see unrestricted memory growth using monero-python, consider applying jemalloc to improve memory management with malloc. In many cases, this can completely resolve the memory growth.

For example: export LD_PRELOAD=/path/to/libjemalloc.a then run your app.

Running Python tests

1. Install pytest:

   # With PIP
   
   pip3 install pytest pytest-rerunfailures --break-system-packages

   # System-wide installation Ubuntu/Debian
   
   sudo apt install -y python3-pytest python3-pytest-rerunfailures

   # System-wide installation Fedora/RedHat
   
   sudo dnf install -y python3-pytest python3-pytest-rerunfailures

2. Clone the project repository:

   git clone --recurse-submodules https://github.com/everoddandeven/monero-python.git
   
   cd monero-python

3. Setup docker test environment

   docker compose -f tests/docker-compose.yml up -d node_1 node_2 xmr_wallet_1 xmr_wallet_2

4. Or start RPC servers locally:
   1. Download and install Monero CLI.
   2. Start monerod, e.g.: ./monerod --stagenet (or use a remote daemon).
   3. Start monero-wallet-rpc, e.g.: ./monero-wallet-rpc --daemon-address http://localhost:38081 --stagenet --rpc-bind-port 38083 --rpc-login rpc_user:abc123 --wallet-dir ./
5. Configure the appropriate RPC endpoints, authentication, and other settings in config.ini.
6. Run all python tests with:

   pytest

7. Cleanup docker test environment

   docker compose -f tests/docker-compose.yml down -v

Related projects

• monero-cpp
• monero-java
• monero-ts

License

This project is licensed under MIT.

Donations

If this library has been valuable to you, please consider donating to support its continued development. 🙏

XMR

84rXAu3QhsfbQ2vbxyoEptbRLZ2gtyL8k2qCeJwM5AU4FcxVDEbLRuxMZD5pXD1TR295Nodn7y9mkjoMemHrnMqa9ZnJTza