Metadata-Version: 2.1
Name: pantos-client-library
Version: 1.1.2
Summary: Client library for engaging with the Pantos system
License: GPL-3.0-only
Author: Pantos GmbH
Author-email: contact@pantos.io
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: pantos-common (==1.4.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: cerberus (==1.3.4) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: pyyaml (==6.0.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: requests (==2.32.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: web3 (==6.5.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: pyaml-env (==1.2.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: python-dotenv (==1.0.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: aiohttp (==3.9.5) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: aiosignal (==1.3.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: amqp (==5.2.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: aniso8601 (==9.0.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: async-timeout (==4.0.3) ; python_version >= "3.10" and python_version < "3.11"
Requires-Dist: attrs (==23.2.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: billiard (==4.2.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: bitarray (==2.9.2) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: blinker (==1.8.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: celery (==5.3.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: certifi (==2024.2.2) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: charset-normalizer (==3.3.2) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: ckzg (==1.0.1) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: click (==8.1.7) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: click-didyoumean (==0.3.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: click-plugins (==1.1.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: click-repl (==0.3.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: colorama (==0.4.6) ; python_version >= "3.10" and python_version < "4.0" and platform_system == "Windows"
Requires-Dist: cytoolz (==0.12.3) ; python_version >= "3.10" and python_version < "4" and implementation_name == "cpython"
Requires-Dist: eth-abi (==5.1.0) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: eth-account (==0.11.2) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: eth-hash (==0.7.0) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: eth-keyfile (==0.8.1) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: eth-keys (==0.4.0) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: eth-rlp (==1.0.1) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: eth-typing (==3.5.2) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: eth-utils (==2.3.1) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: flask (==3.0.3) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: flask-restful (==0.3.10) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: frozenlist (==1.4.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: hexbytes (==0.3.1) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: idna (==3.7) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: itsdangerous (==2.2.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: jinja2 (==3.1.4) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: json-log-formatter (==0.5.2) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: jsonschema (==4.22.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: jsonschema-specifications (==2023.12.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: kombu (==5.3.7) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: lru-dict (==1.3.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: markupsafe (==2.1.5) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: multidict (==6.0.5) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: parsimonious (==0.10.0) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: prompt-toolkit (==3.0.43) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: protobuf (==5.26.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: pycryptodome (==3.20.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: python-dateutil (==2.9.0.post0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: pytz (==2024.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: pywin32 (==306) ; python_version >= "3.10" and python_version < "4.0" and platform_system == "Windows"
Requires-Dist: referencing (==0.35.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: regex (==2024.4.28) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: rlp (==3.0.0) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: rpds-py (==0.18.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: setuptools (==69.5.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: six (==1.16.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: toolz (==0.12.1) ; python_version >= "3.10" and python_version < "4" and (implementation_name == "pypy" or implementation_name == "cpython")
Requires-Dist: typing-extensions (==4.11.0) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: tzdata (==2024.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: urllib3 (==2.2.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: vine (==5.1.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: wcwidth (==0.2.13) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: websockets (==12.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: werkzeug (==3.0.3) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: yarl (==1.9.4) ; python_version >= "3.10" and python_version < "4.0"
Description-Content-Type: text/markdown

<img src="https://raw.githubusercontent.com/pantos-io/client-library/img/pantos-logo-full.svg" alt="Pantos logo" align="right" width="120" />

[![CI](https://github.com/pantos-io/client-library/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/pantos-io/client-library/actions/workflows/ci.yaml)
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=pantos-io_client-library2&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=pantos-io_client-library2)


# Pantos Client Library

## 1. Introduction

### 1.1 Overview

Welcome to the documentation for Pantos Client Library, a powerful tool for engaging with the Pantos system. This documentation aims to provide developers with comprehensive information on how to use the features offered by the library.

### 1.2 Features

The Pantos Client Library API exposes the following functionalities:

1. Loading the private key from a keystore file
2. Retrieve the service node bids
3. Retrieve the balance of a token
4. Transfer tokens
5. Deploy PANDAS tokens

## 2. Installation

### 2.1 Prerequisites

Please make sure that your development environment meets the following requirements:

#### Keystore File (Wallet)

The library requires a private key encrypted with a password. 

Since, for the moment, the Pantos protocol supports only EVM blockchains, only an Ethereum account keystore file is sufficient. It can be created with tools such as https://vanity-eth.tk/.

One of the most significant advantages of using Pantos is that the protocol has been designed to require minimal user friction when cross-chain operations are performed. Therefore, when using the Pantos products, you must top up your wallet only with PAN tokens.

#### Python Version

The Pantos Client Library supports **Python 3.10** or higher. Ensure that you have the correct Python version installed before the installation steps. You can download the latest version of Python from the official [Python website](https://www.python.org/downloads/).



### 2.2 Pypi package

The Pantos Client Library is available as a package from [Pypi](https://pypi.org/project/pantos-client-library/).

```bash
$ virtualenv env
$ source env/bin/activate
$ pip install pantos-client-library
```

### 2.3 Source code

The Pantos Client Library has been tested with the library versions specified in **poetry.lock**.

#### Poetry

Poetry is our tool of choice for dependency management and packaging.

Installing: 
https://python-poetry.org/docs/#installing-with-the-official-installer
or
https://python-poetry.org/docs/#installing-with-pipx

You can use the following lines to install poetry using `virtualenv`.

```bash
$ virtualenv env
$ source env/bin/activate
$ pip install poetry
```

By default poetry creates the venv directory under under ```{cache-dir}/virtualenvs```. If you opt for creating the virtualenv inside the project’s root directory, execute the following command:

```bash
poetry config virtualenvs.in-project true
```

#### Clone the repository

Clone the repository to your local machine:

```bash
$ git clone https://github.com/pantos-io/client-library.git
$ cd client-library
```

#### Libraries

Install the project dependencies:

```bash
$ poetry install --no-root
```

## 3. Usage

### 3.1 Configuration

The configuration can be found in **client-library.yml**.

The library already has a set configuration for our testnet environment, but feel free to adapt it to your needs.

### 3.2 Examples

The **api.py** exposes the public functions of the library.

The following example leverages all the functionalities of the library:

```bash
#! /usr/bin/env python
"""Example usage of the Pantos client library.

"""
import decimal
import getpass
import pathlib

import pantos.client as pc

# Example retrieval of token balance
try:
    token_balance = pc.retrieve_token_balance(
        pc.Blockchain.POLYGON,
        pc.BlockchainAddress('0xaAE34Ec313A97265635B8496468928549cdd4AB7'),
        pc.TokenSymbol('pan'))
    print('Token balance: {}'.format(token_balance))
except pc.PantosClientError:
    # Handle exception
    raise

# Example retrieval of service node bids
try:
    service_node_bids = pc.retrieve_service_node_bids(pc.Blockchain.AVALANCHE,
                                                      pc.Blockchain.CRONOS)
    print('Service node bids: {}'.format(service_node_bids))
except pc.PantosClientError:
    # Handle exception
    raise

# Read private key from file
if not pathlib.Path('my_client.keystore').exists():
    raise FileNotFoundError('Keystore file not found')
with open('my_client.keystore', 'r') as keystore_file:
    keystore = keystore_file.read()

# Example token transfer
password = getpass.getpass('Keystore password: ')
try:
    private_key = pc.decrypt_private_key(pc.Blockchain.ETHEREUM, keystore,
                                         password)
    task_id = pc.transfer_tokens(
        pc.Blockchain.ETHEREUM, pc.Blockchain.BNB_CHAIN, private_key,
        pc.BlockchainAddress('0xaAE34Ec313A97265635B8496468928549cdd4AB7'),
        pc.TokenSymbol('pan'), decimal.Decimal('3.1'))
    print('Task ID of service node: {}'.format(task_id))
except pc.PantosClientError:
    # Handle exception
    raise

# Example of deploying a token contract
password = getpass.getpass('Keystore password: ')
try:
    private_key = pc.load_private_key(pc.Blockchain.ETHEREUM,
                                      pathlib.Path('my_client.keystore'),
                                      password)
    deployment_blockchains = [pc.Blockchain.ETHEREUM]
    payment_blockchain = pc.Blockchain.ETHEREUM
    task_id = pc.deploy_pantos_compatible_token('Test_cli', 'TCLI', 7, True,
                                                False, 54321,
                                                deployment_blockchains,
                                                payment_blockchain,
                                                private_key)
    print('Task ID deployment: {}'.format(task_id))
except pc.PantosClientError:
    # Handle exception
    raise
```

## 4. Contributing

For contributions check our [code of conduct](CODE_OF_CONDUCT.md).

