# autonity.py

[Autonity](https://autonity.org) is a public, EVM based, proof-of-stake
blockchain for decentralized clearing of smart derivatives contracts. See the
[Autonity Documentation](https://docs.autonity.org) site to learn more.

This package provides typed Python bindings (a.k.a. wrappers) for Autonity
protocol contracts using the [Web3.py](https://github.com/ethereum/web3.py)
framework to provide users with convenient and statically-checked Python
interactions with Autonity.

## Installation

This package is published on PyPI as the
[`autonity`](https://pypi.org/project/autonity/) package. It can be installed in
a virtualenv using pip or a compatible package manager:

```console
pip install autonity
```

## Overview

The `autonity` package consists of the following:

- [`autonity.contracts.*`](./autonity/contracts/): Subpackage containing modules
  for protocol contracts. Each module consists of the contract binding class,
  the contract ABI, and ports of Solidity structures and enumerations.
- [`autonity.constants`](./autonity/constants.py): Essential protocol parameters exposed as Python variables for convenience.
- [`autonity.factory`](./autonity/factory.py): Factory functions that return
  instances of contract binding classes. They retrieve the contract address and
  ensure that there is no version mismatch between the contract and the
  bindings.

For convenience, the functions of the `factory` module are also available as
top-level `autonity` module variables.

## Usage

Example usage:

```python
from web3 import Web3, HTTPProvider
from autonity import Autonity, LiquidLogic

# Connect to an Autonity RPC provider; select one from Chainlist
w3 = Web3(HTTPProvider("<RPC-URL>"))

# Create the typed binding around the Autonity contract
autonity = Autonity(w3)

# Get the total supply of Newton
ntn_supply = autonity.total_supply()
print(f"Total NTN supply: {ntn_supply}")

# Get the current validator list
validator_addresses = autonity.get_validators()

# Get the description of the 0-th validator and print its LiquidState contract address
validator = autonity.get_validator(validator_addresses[0])
print(f"LNTN contract address: {validator.liquid_state_contract}")

# Query unclaimed fees for <ADDRESS> from the validator's LiquidLogic contract
liquid = LiquidLogic(w3, validator.liquid_state_contract)
unclaimed_atn = liquid.unclaimed_rewards("<ADDRESS>")
print(f"Unclaimed rewards: {unclaimed_atn} ATN")
```

## Development

The package uses the [Hatch](https://hatch.pypa.io) Python project manager. It
is recommended to [install Hatch](https://hatch.pypa.io/latest/install/#pipx)
using [pipx](https://pipx.pypa.io/):

```sh
pipx install hatch
```

### Installing Python interpreters (optional)

This project aims to be compatible with all the officially-supported versions of
Python. Check python.org
[Status of Python versions](https://devguide.python.org/versions/) for more
info.

To run the tests against all supported Python versions, it is necessary to
install the relevant distributions of Python. Hatch is able to download these
Python binaries into the user home directory:

```console
$ hatch python install all
Installed 3.7 @ /home/develop/.local/share/hatch/pythons/3.7
Installed 3.8 @ /home/develop/.local/share/hatch/pythons/3.8
Installed 3.9 @ /home/develop/.local/share/hatch/pythons/3.9
Installed 3.10 @ /home/develop/.local/share/hatch/pythons/3.10
Installed 3.11 @ /home/develop/.local/share/hatch/pythons/3.11
Installed 3.12 @ /home/develop/.local/share/hatch/pythons/3.12
Installed pypy2.7 @ /home/develop/.local/share/hatch/pythons/pypy2.7
Installed pypy3.9 @ /home/develop/.local/share/hatch/pythons/pypy3.9
Installed pypy3.10 @ /home/develop/.local/share/hatch/pythons/pypy3.10
```

⚠️ Hatch will modify your shell configuration to add these directories to your
`$PATH`.

### Building and testing

To launch the tests across all supported Python versions, run:

```sh
hatch run test:all
```

To limit the tests to a specific Python version, add a
[`hatch run`](https://hatch.pypa.io/latest/cli/reference/#hatch-run) `+`
argument:

```sh
hatch run +py=3.12 test:all
```

To lint the code base, use the command:

```sh
hatch run lint:check
```

### Updating the contract bindings

To update contract bindings for a new version of the Autonity protocol, add the
new [AGC](https://github.com/autonity/autonity) version (Git tag or commit ID)
to `AUTONITY_VERSION`, then generate the contract bindings with `make`:

```console
echo v0.14.0 > AUTONITY_VERSION
make
```

Contract functions are ordered alphabetically in order to produce deterministic
output. After executing the script against a new version of the code, the diffs
can be reviewed to determine which methods have been modified, removed or added.
The generated Python bindings include the contract ABIs as Python dictionaries.

If there is a new contract to include, add a new target to `Makefile` and a new
factory function to `autonity/factory.py` and `autonity/__init__.py`.

## Contributing

To contribute a non-critical bug fix, please open a pull request against the
`master` branch as per
[Github Flow](https://docs.github.com/en/get-started/quickstart/github-flow). If
the bug is critical, then it may qualify as a _hotfix_, see the next section for
details.

To work on a new feature described in an open issue, check the corresponding
issue isn't already assigned to someone. If it's available, post a comment in
the issue to request a maintainer assign it to you.

To contribute a feature that isn't tracked in an existing issue, please first
open a new issue describing the feature before commencing development.

### Contributing a hotfix

To qualify as a _hotfix_:

- _relevance_: the bug affects the most recent release of the software
- _severity_: the bug has an adverse impact on users of the software
- _compatibility_: the fix for the bug is fully backwards-compatible

Contributing a _hotfix_:

- _Develop the fix on top of `stable`_. Create a new branch starting from the
  `stable` branch to develop and test the fix.
- _Open a pull request against `stable`_. Create a new pull request with the
  changes and set `stable` as the target branch.

## Reporting a vulnerability

**Please do not file a public ticket** mentioning the vulnerability.

Instead, please send an email to <security@autonity.org> to report a security
issue.

The following PGP key may be used to communicate sensitive information to
developers:

Fingerprint: `6006 CCC3 DD11 7885 1A23 4290 7486 F832 6320 219E`

```
-----BEGIN PGP PUBLIC KEY BLOCK-----


VtiVUMzKBEpmz4LdeSy73Qfr
=12PL
-----END PGP PUBLIC KEY BLOCK-----
```
