vqrcoinrpc


Namevqrcoinrpc JSON
Version 0.6.4 PyPI version JSON
download
home_pagehttps://github.com/surugh/vqr-python-async-rpc
SummaryLightweight VQR JSON-RPC Python asynchronous client
upload_time2024-01-16 04:12:48
maintainer
docs_urlNone
authorLibor Martinek, Peerchemist, Surugh
requires_python>=3.7
licenseMIT
keywords vqr async json-rpc
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # vqr-python-async-rpc
Lightweight VQR async JSON-RPC Python client.

Serves as a tiny layer between an application and a VQRcoin daemon, its primary usage
is querying the current state of VQRcoin blockchain, network stats, transactions...

If you want complete Bitcoin experience in Python, consult
[python-bitcoinlib](https://github.com/petertodd/python-bitcoinlib).

## Installation
```bash
$ pip install vqrcoinrpc
```

## Supported methods
Here is a list of supported methods, divided by their categories. Should you need
method not implemented, wrap the call in `VqrcoinRPC.acall(<your_method>, ...)` coroutine.

### Blockchain

| Method              | Supported? |
|---------------------|:----------:|
| `getbestblockhash`  |     ✔      |
| `getblock`          |     ✔      |
| `getblockchaininfo` |     ✔      |
| `getblockcount`     |     ✔      |
| `getblockhash`      |     ✔      |
| `getblockheader`    |     ✔      |
| `getblockstats`     |     ✔      |
| `getchaintips`      |     ✔      |
| `getdifficulty`     |     ✔      |
| `getmempoolinfo`    |     ✔      |
| `getnetworkhashps`  |     ✔      |

### Mining

| Method          | Supported? |
|-----------------|:----------:|
| `getmininginfo` |     ✔      |

### Network

| Method               | Supported? |
|----------------------|:----------:|
| `getconnectioncount` |     ✔      |
| `getnetworkinfo`     |     ✔      |

### Raw transactions

| Method              | Supported? |
|---------------------|:----------:|
| `analyzepsbt`       |     ✔      |
| `combinepsbt`       |     ✔      |
| `decodepsbt`        |     ✔      |
| `finalizepsbt`      |     ✔      |
| `getrawtransaction` |     ✔      |
| `joinpsbts`         |     ✔      |
| `utxoupdatepsbt`    |     ✔      |

### Wallet

| Method                         | Supported? |
|--------------------------------|:----------:|
| `getbalance`                   |     ✔      |
| `getwalletinfo`                |     ✔      |
| `listaddressgroupings`         |     ✔      |
| `sendtoaddress`                |     ✔      |
| `importpubkey`                 |     ✔      |
| `getnewaddress`                |     ✔      |
| `listreceivedbyaddress`        |     ✔      |
| `listunspent`                  |     ✔      |
| `signrawtransactionwithwallet` |     ✔      |
| `createwallet`                 |     ✔      |
| `walletpassphrase`             |     ✔      |
| `walletprocesspsbt`            |     ✔      |

## Usage
Minimal illustration (assuming Python 3.8+, where you can run `async` code in console)
listreceivedbyaddress
```
$ python -m asyncio
>>> import asyncio
>>>
>>> from vqrcoinrpc import VqrcoinRPC
>>> rpc = VqrcoinRPC.from_config("http://localhost:7332", ("rpc_user", "rpc_passwd"))
>>> await rpc.getconnectioncount()
10
>>> await rpc.aclose()  # Clean-up resource
```

You can also use the `VqrcoinRPC` as an asynchronous context manager, which does
all the resource clean-up automatically, as the following example shows:

$ cat
vqr_rpc_minimal.py

```python

import asyncio

from vqrcoinrpc import VqrcoinRPC


async def main():
  async with VqrcoinRPC.from_config("http://localhost:7332",
                                    ("rpc_user", "rpc_password")) as rpc:
    print(await rpc.getconnectioncount())


if __name__ == "__main__":
  asyncio.run(main())
```

Running this script yields:
```
$ python vqr_rpc_minimal.py
10
```

If you want customize the underlying `httpx.AsyncClient`, you can instantiate the `VqrcoinRPC` with one.
Consider the following script, where the client is configured to log every HTTP request before it is sent
out over the wire:

$ cat
vqr_custom_client.py

```python

import asyncio

import httpx

from vqrcoinrpc import VqrcoinRPC


async def log_request(request: httpx.Request) -> None:
  print(request.content)


async def main() -> None:
  client = httpx.AsyncClient(auth=("rpc_user", "rpc_password"),
                             event_hooks={"request": [log_request]})
  async with VqrcoinRPC(url="http://localhost:7332", client=client) as rpc:
    print(await rpc.getconnectioncount())


if __name__ == "__main__":
  asyncio.run(main())
```

Running this script yields:

```
$ python vqr_custom_client.py 
b'{"jsonrpc":"2.0","id":1,"method":"getconnectioncount","params":[]}'
0
```

## Testing

A `Containerfile` is provided as a means to build an OCI image of a Bitcoin `regtest` node.
Build the image (`podman` is used, but `docker` should be fine too):

```
$ podman build \
  -f Containerfile \
  --build-arg BTC_VERSION=v24.1 \
  -t bitcoin-regtest:v24.1 \
  -t bitcoin-regtest:latest \
  .
```

and run it afterwards:

```
$ podman run \
  --rm \
  -it \
  --mount=type=bind,src=./tests/bitcoin-regtest.conf,target=/home/rpc/.bitcoin/bitcoin.conf \
  -p 127.0.0.1:18443:18443 \
  --name bitcoin-regtest \
  localhost/bitcoin-regtest:v24.1
```

which will expose the Bitcoin `regtest` node on port 18443, accesible from localhost only, with RPC user/password `rpc_user/rpc_password`.

After you are done testing, stop the container via:

```
$ podman stop bitcoin-regtest
```

---

If you want to test against a different version of Bitcoin node, pass a different [tag](https://github.com/bitcoin/bitcoin/tags) in the build stage:

```
$ podman build \
  -f Containerfile \
  --build-arg BTC_VERSION=v25.0 \
  -t bitcoin-regtest:v25.0 \
  -t bitcoin-regtest:latest \
  .
```

---

Different settings of the Bitcoin node may be passed via mounting your custom configuration file, or optionally as "arguments" to `podman run`:


```
$ podman run \
  --rm \
  -it \
  --mount=type=bind,src=<path/to/your/config_file>,target=/home/rpc/.bitcoin/bitcoin.conf \
  -p 127.0.0.1:18443:18443 \
  --name bitcoin-regtest \
  localhost/bitcoin-regtest:v24.1 <your> <args> ...
```

---

Please, keep in mind that Bitcoin node compiled in the image is intended for testing & debugging purposes only! It may serve you as an inspiration for building
your own, production-ready Bitcoin node, but its intended usage is testing!

---

For testing this library, install `tox` (preferably, in a fresh virtual environment).

Afterwards, coding-style is enforced by running:

```
(your-venv-with-tox) $ tox run -e linters
```

and tests corresponding are run (this example uses Python3.11)

```
(your-venv-with-tox) $ tox run -e py311
```

If you do not want to run tests marked as `"integration"`, which denote those requiring the bitcoin regtest node to run, you can filter them out by:

```
(your-venv-with-tox) $ tox run -e py311 -- -m 'not integration'
```


## Changelog

- **2024/01/13 - 0.6.3**: Fix wallet RPC methods
- **2024/01/13 - 0.6.3**: Add wallet RPC methods
- **2024/01/13 - 0.6.2**: Add wallet RPC methods, from *coin fork
- **2023/06/04 - 0.6.1**: Add RPC methods, mainly concerned with PSBTs
- **2023/06/01 - 0.6.0**:
  * `VqrcoinRPC` is now instantiated with a `httpx.AsyncClient` directly and an optional `counter` argument, which is a callable that may be used for distinguishing
    the JSON-RPC requests. Old-style instantiation, with `url` and optional user/password tuple, is kept within `VqrcoinRPC.from_config` method.

- **2021/12/28 - 0.5.0** change the signature of `VqrcoinRPC` from `host, port, ...` to `url, ...`, delegating the creation of the node url to the caller.

## License
MIT

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/surugh/vqr-python-async-rpc",
    "name": "vqrcoinrpc",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.7",
    "maintainer_email": "",
    "keywords": "vqr async json-rpc",
    "author": "Libor Martinek, Peerchemist, Surugh",
    "author_email": "surugh@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/ab/18/1cb8f12eefecc70a60ef32a85ad267a84b8c8af94299e61599b1f58aba2e/vqrcoinrpc-0.6.4.tar.gz",
    "platform": null,
    "description": "# vqr-python-async-rpc\nLightweight VQR async JSON-RPC Python client.\n\nServes as a tiny layer between an application and a VQRcoin daemon, its primary usage\nis querying the current state of VQRcoin blockchain, network stats, transactions...\n\nIf you want complete Bitcoin experience in Python, consult\n[python-bitcoinlib](https://github.com/petertodd/python-bitcoinlib).\n\n## Installation\n```bash\n$ pip install vqrcoinrpc\n```\n\n## Supported methods\nHere is a list of supported methods, divided by their categories. Should you need\nmethod not implemented, wrap the call in `VqrcoinRPC.acall(<your_method>, ...)` coroutine.\n\n### Blockchain\n\n| Method              | Supported? |\n|---------------------|:----------:|\n| `getbestblockhash`  |     \u2714      |\n| `getblock`          |     \u2714      |\n| `getblockchaininfo` |     \u2714      |\n| `getblockcount`     |     \u2714      |\n| `getblockhash`      |     \u2714      |\n| `getblockheader`    |     \u2714      |\n| `getblockstats`     |     \u2714      |\n| `getchaintips`      |     \u2714      |\n| `getdifficulty`     |     \u2714      |\n| `getmempoolinfo`    |     \u2714      |\n| `getnetworkhashps`  |     \u2714      |\n\n### Mining\n\n| Method          | Supported? |\n|-----------------|:----------:|\n| `getmininginfo` |     \u2714      |\n\n### Network\n\n| Method               | Supported? |\n|----------------------|:----------:|\n| `getconnectioncount` |     \u2714      |\n| `getnetworkinfo`     |     \u2714      |\n\n### Raw transactions\n\n| Method              | Supported? |\n|---------------------|:----------:|\n| `analyzepsbt`       |     \u2714      |\n| `combinepsbt`       |     \u2714      |\n| `decodepsbt`        |     \u2714      |\n| `finalizepsbt`      |     \u2714      |\n| `getrawtransaction` |     \u2714      |\n| `joinpsbts`         |     \u2714      |\n| `utxoupdatepsbt`    |     \u2714      |\n\n### Wallet\n\n| Method                         | Supported? |\n|--------------------------------|:----------:|\n| `getbalance`                   |     \u2714      |\n| `getwalletinfo`                |     \u2714      |\n| `listaddressgroupings`         |     \u2714      |\n| `sendtoaddress`                |     \u2714      |\n| `importpubkey`                 |     \u2714      |\n| `getnewaddress`                |     \u2714      |\n| `listreceivedbyaddress`        |     \u2714      |\n| `listunspent`                  |     \u2714      |\n| `signrawtransactionwithwallet` |     \u2714      |\n| `createwallet`                 |     \u2714      |\n| `walletpassphrase`             |     \u2714      |\n| `walletprocesspsbt`            |     \u2714      |\n\n## Usage\nMinimal illustration (assuming Python 3.8+, where you can run `async` code in console)\nlistreceivedbyaddress\n```\n$ python -m asyncio\n>>> import asyncio\n>>>\n>>> from vqrcoinrpc import VqrcoinRPC\n>>> rpc = VqrcoinRPC.from_config(\"http://localhost:7332\", (\"rpc_user\", \"rpc_passwd\"))\n>>> await rpc.getconnectioncount()\n10\n>>> await rpc.aclose()  # Clean-up resource\n```\n\nYou can also use the `VqrcoinRPC` as an asynchronous context manager, which does\nall the resource clean-up automatically, as the following example shows:\n\n$ cat\nvqr_rpc_minimal.py\n\n```python\n\nimport asyncio\n\nfrom vqrcoinrpc import VqrcoinRPC\n\n\nasync def main():\n  async with VqrcoinRPC.from_config(\"http://localhost:7332\",\n                                    (\"rpc_user\", \"rpc_password\")) as rpc:\n    print(await rpc.getconnectioncount())\n\n\nif __name__ == \"__main__\":\n  asyncio.run(main())\n```\n\nRunning this script yields:\n```\n$ python vqr_rpc_minimal.py\n10\n```\n\nIf you want customize the underlying `httpx.AsyncClient`, you can instantiate the `VqrcoinRPC` with one.\nConsider the following script, where the client is configured to log every HTTP request before it is sent\nout over the wire:\n\n$ cat\nvqr_custom_client.py\n\n```python\n\nimport asyncio\n\nimport httpx\n\nfrom vqrcoinrpc import VqrcoinRPC\n\n\nasync def log_request(request: httpx.Request) -> None:\n  print(request.content)\n\n\nasync def main() -> None:\n  client = httpx.AsyncClient(auth=(\"rpc_user\", \"rpc_password\"),\n                             event_hooks={\"request\": [log_request]})\n  async with VqrcoinRPC(url=\"http://localhost:7332\", client=client) as rpc:\n    print(await rpc.getconnectioncount())\n\n\nif __name__ == \"__main__\":\n  asyncio.run(main())\n```\n\nRunning this script yields:\n\n```\n$ python vqr_custom_client.py \nb'{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"getconnectioncount\",\"params\":[]}'\n0\n```\n\n## Testing\n\nA `Containerfile` is provided as a means to build an OCI image of a Bitcoin `regtest` node.\nBuild the image (`podman` is used, but `docker` should be fine too):\n\n```\n$ podman build \\\n  -f Containerfile \\\n  --build-arg BTC_VERSION=v24.1 \\\n  -t bitcoin-regtest:v24.1 \\\n  -t bitcoin-regtest:latest \\\n  .\n```\n\nand run it afterwards:\n\n```\n$ podman run \\\n  --rm \\\n  -it \\\n  --mount=type=bind,src=./tests/bitcoin-regtest.conf,target=/home/rpc/.bitcoin/bitcoin.conf \\\n  -p 127.0.0.1:18443:18443 \\\n  --name bitcoin-regtest \\\n  localhost/bitcoin-regtest:v24.1\n```\n\nwhich will expose the Bitcoin `regtest` node on port 18443, accesible from localhost only, with RPC user/password `rpc_user/rpc_password`.\n\nAfter you are done testing, stop the container via:\n\n```\n$ podman stop bitcoin-regtest\n```\n\n---\n\nIf you want to test against a different version of Bitcoin node, pass a different [tag](https://github.com/bitcoin/bitcoin/tags) in the build stage:\n\n```\n$ podman build \\\n  -f Containerfile \\\n  --build-arg BTC_VERSION=v25.0 \\\n  -t bitcoin-regtest:v25.0 \\\n  -t bitcoin-regtest:latest \\\n  .\n```\n\n---\n\nDifferent settings of the Bitcoin node may be passed via mounting your custom configuration file, or optionally as \"arguments\" to `podman run`:\n\n\n```\n$ podman run \\\n  --rm \\\n  -it \\\n  --mount=type=bind,src=<path/to/your/config_file>,target=/home/rpc/.bitcoin/bitcoin.conf \\\n  -p 127.0.0.1:18443:18443 \\\n  --name bitcoin-regtest \\\n  localhost/bitcoin-regtest:v24.1 <your> <args> ...\n```\n\n---\n\nPlease, keep in mind that Bitcoin node compiled in the image is intended for testing & debugging purposes only! It may serve you as an inspiration for building\nyour own, production-ready Bitcoin node, but its intended usage is testing!\n\n---\n\nFor testing this library, install `tox` (preferably, in a fresh virtual environment).\n\nAfterwards, coding-style is enforced by running:\n\n```\n(your-venv-with-tox) $ tox run -e linters\n```\n\nand tests corresponding are run (this example uses Python3.11)\n\n```\n(your-venv-with-tox) $ tox run -e py311\n```\n\nIf you do not want to run tests marked as `\"integration\"`, which denote those requiring the bitcoin regtest node to run, you can filter them out by:\n\n```\n(your-venv-with-tox) $ tox run -e py311 -- -m 'not integration'\n```\n\n\n## Changelog\n\n- **2024/01/13 - 0.6.3**: Fix wallet RPC methods\n- **2024/01/13 - 0.6.3**: Add wallet RPC methods\n- **2024/01/13 - 0.6.2**: Add wallet RPC methods, from *coin fork\n- **2023/06/04 - 0.6.1**: Add RPC methods, mainly concerned with PSBTs\n- **2023/06/01 - 0.6.0**:\n  * `VqrcoinRPC` is now instantiated with a `httpx.AsyncClient` directly and an optional `counter` argument, which is a callable that may be used for distinguishing\n    the JSON-RPC requests. Old-style instantiation, with `url` and optional user/password tuple, is kept within `VqrcoinRPC.from_config` method.\n\n- **2021/12/28 - 0.5.0** change the signature of `VqrcoinRPC` from `host, port, ...` to `url, ...`, delegating the creation of the node url to the caller.\n\n## License\nMIT\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Lightweight VQR JSON-RPC Python asynchronous client",
    "version": "0.6.4",
    "project_urls": {
        "Homepage": "https://github.com/surugh/vqr-python-async-rpc"
    },
    "split_keywords": [
        "vqr",
        "async",
        "json-rpc"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "1bd196844314e641381e9c4ffc3cd96267db87bd934ce26c23cfd55852b5274c",
                "md5": "02ae9a96de0a68b089ea7760d7c09500",
                "sha256": "e1d904f7cd459e9768cc88acde8f39bb557a09785871c3c0f8a9935d25b454d9"
            },
            "downloads": -1,
            "filename": "vqrcoinrpc-0.6.4-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "02ae9a96de0a68b089ea7760d7c09500",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 12695,
            "upload_time": "2024-01-16T04:12:46",
            "upload_time_iso_8601": "2024-01-16T04:12:46.643706Z",
            "url": "https://files.pythonhosted.org/packages/1b/d1/96844314e641381e9c4ffc3cd96267db87bd934ce26c23cfd55852b5274c/vqrcoinrpc-0.6.4-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "ab181cb8f12eefecc70a60ef32a85ad267a84b8c8af94299e61599b1f58aba2e",
                "md5": "e4db1fb21882c2d6c42b3c65a7a37362",
                "sha256": "88cd43ab26944ee21cbcce4a16bcf369f246fa81047b6fb6e53c1fd40aaed27c"
            },
            "downloads": -1,
            "filename": "vqrcoinrpc-0.6.4.tar.gz",
            "has_sig": false,
            "md5_digest": "e4db1fb21882c2d6c42b3c65a7a37362",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 15551,
            "upload_time": "2024-01-16T04:12:48",
            "upload_time_iso_8601": "2024-01-16T04:12:48.768254Z",
            "url": "https://files.pythonhosted.org/packages/ab/18/1cb8f12eefecc70a60ef32a85ad267a84b8c8af94299e61599b1f58aba2e/vqrcoinrpc-0.6.4.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-01-16 04:12:48",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "surugh",
    "github_project": "vqr-python-async-rpc",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "requirements": [],
    "tox": true,
    "lcname": "vqrcoinrpc"
}
        
Elapsed time: 1.89603s