Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
a4f7e29
Remove the old autonity module & the related tests
szemate Aug 19, 2024
18ace07
Do not run CI for every push on development branches
szemate Aug 16, 2024
96c5809
Add Makefile for generating contract bindings
szemate Aug 16, 2024
e8d1d0a
Add generated bindings to autonity/contracts
szemate Aug 16, 2024
ac9497e
Add imports to `contracts.__init__`
szemate Aug 16, 2024
696b84d
Update dependencies
szemate Aug 16, 2024
567db1c
Add `networks` module with info about Bakerloo and Piccadilly networks
szemate Aug 16, 2024
c46dd30
Update usage example in README.md
szemate Aug 16, 2024
8d40d03
Fix: mypy is a linter and not a testing tool
szemate Aug 16, 2024
d797283
Update mypy config: do not ignore rules any more
szemate Aug 16, 2024
b21098a
Document how to update contract bindings
szemate Aug 19, 2024
4aa6a0e
Add basic sanity tests
szemate Aug 19, 2024
9d6cce7
Remove hard-coded addresses from all protocol contracts except Autonity
szemate Aug 23, 2024
e49589d
Add contract binding factories
szemate Aug 23, 2024
4afcc8b
Refactor: Store Autonity constants in one place in the repository
szemate Aug 23, 2024
8e1514f
Expose contract events in the bindings
szemate Aug 29, 2024
9c729e8
Add Pyright to linters
szemate Aug 29, 2024
bfa3cc3
Add binding for IERC20 as required by aut-cli
szemate Aug 30, 2024
2e4eaa8
Add NatSpec documentation to the contract bindings
szemate Aug 30, 2024
ba28f70
Add docstrings to the rest of the API modules
szemate Sep 2, 2024
a6f5338
Extend sanity tests to call all contract functions with dummy inputs
szemate Sep 2, 2024
f1b40d4
Rename "wrapper" to "binding" throughout the repository
szemate Sep 3, 2024
3c7fbb6
Bump web3.py version to 7.2.0
szemate Sep 10, 2024
e50c950
Update bindings & Makefile to apply bugfixes from pyabigen v0.2.8
szemate Sep 4, 2024
7308b54
Update exclusions to match the API documentation generator's
szemate Sep 24, 2024
4900468
Remove NatSpec documentation comments that are under @dev tag
szemate Sep 24, 2024
e287055
Rename 'factories' to 'factory' and expose all factories at top-level
szemate Sep 25, 2024
d6c6861
Remove exclusions from Makefile because they will come from NatSpec docs
szemate Sep 11, 2024
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion .github/workflows/onpush.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,10 @@ name: onpush

on:
push:
workflow_dispatch:
branches:
- master
- stable
pull_request:

jobs:
check:
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ __pycache__/

# Root directories
/.mypy_cache/
/build/
/dist/

# Root files
Expand Down
1 change: 1 addition & 0 deletions AUTONITY_VERSION
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
v0.14.0
61 changes: 61 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
VERSION := $(shell cat AUTONITY_VERSION)
AUTONITY := build/autonity
ABIDIR := $(AUTONITY)/params/generated
SRCDIR := $(AUTONITY)/autonity/solidity/contracts
OUTDIR := autonity/contracts
BINDINGS := \
$(OUTDIR)/accountability.py \
$(OUTDIR)/acu.py \
$(OUTDIR)/autonity.py \
$(OUTDIR)/ierc20.py \
$(OUTDIR)/inflation_controller.py \
$(OUTDIR)/liquid.py \
$(OUTDIR)/non_stakable_vesting.py \
$(OUTDIR)/oracle.py \
$(OUTDIR)/stabilization.py \
$(OUTDIR)/supply_control.py \
$(OUTDIR)/upgrade_manager.py

gentargets = $(shell find $(SRCDIR) -name $(1).sol) $(addprefix $(ABIDIR)/$(1),.docdev .docuser .abi)

all: $(BINDINGS)

$(OUTDIR)/accountability.py: $(call gentargets,Accountability)
$(OUTDIR)/acu.py: $(call gentargets,ACU)
$(OUTDIR)/autonity.py: $(call gentargets,Autonity)
$(OUTDIR)/ierc20.py: $(call gentargets,IERC20)
$(OUTDIR)/inflation_controller.py: $(call gentargets,InflationController)
$(OUTDIR)/liquid.py: $(call gentargets,Liquid)
$(OUTDIR)/non_stakable_vesting.py: $(call gentargets,NonStakableVesting)
$(OUTDIR)/oracle.py: $(call gentargets,Oracle)
$(OUTDIR)/stabilization.py: $(call gentargets,Stabilization)
$(OUTDIR)/supply_control.py: $(call gentargets,SupplyControl)
$(OUTDIR)/upgrade_manager.py: $(call gentargets,UpgradeManager)

$(BINDINGS):
hatch run generate:pyabigen \
--version $(VERSION) \
--src $(word 1,$^) \
--devdoc $(word 2,$^) \
--userdoc $(word 3,$^) \
$(word 4,$^) >$@

$(ABIDIR)/%.abi: $(AUTONITY) AUTONITY_VERSION
cd $< && \
git fetch origin && \
git checkout $(VERSION) && \
make contracts

# This recipe can be removed after https://github.com/autonity/autonity/pull/1035 is released
$(ABIDIR)/%.docuser $(ABIDIR)/%.docdev: $(ABIDIR)/%.abi
$(AUTONITY)/build/bin/solc_static_linux_v0.8.21 \
--overwrite --userdoc --devdoc -o $(ABIDIR) \
$$(find $(AUTONITY)/autonity/solidity/contracts -name $(basename $(notdir $<)).sol)

$(AUTONITY):
git clone [email protected]:autonity/autonity.git $@

clean:
rm -rf $(AUTONITY)

.PHONY = clean
69 changes: 39 additions & 30 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,10 @@ settlement infrastructure specialized for developing new risk markets. It is a
fork of the [Ethereum protocol](https://ethereum.org/). See the
[Autonity documentation](https://docs.autonity.org) for further information.

This package provides typed wrappers around the Autonity-specific extensions of
Ethereum, using the [Web3.py](https://github.com/ethereum/web3.py) framework,
for convenient and statically checked interactions with the Autonity network.
This package provides typed bindings (a.k.a. wrappers) around the
Autonity-specific extensions of Ethereum, using the
[Web3.py](https://github.com/ethereum/web3.py) framework, for convenient and
statically checked interactions with the Autonity network.

## Installation

Expand All @@ -17,42 +18,41 @@ pip install autonity

## Usage

The primary utility of this library is the typed wrappers around the Autonity
protocol contract, which provides access to Autonity-specific functionality.
Example usage:

```python
from autonity.utils.web3 import create_web3_for_endpoint
from autonity import Autonity, Validator
from web3 import Web3
from autonity import Autonity, Liquid, networks

w3 = create_web3_for_endpoint("<RPC_ENDPOINT>")
# Connect to the default RPC provider on the Autonity Piccadilly Testnet
w3 = Web3(networks.piccadilly.http_provider)

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

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

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

# Get descriptor for the 0-th validator. Print LNTN contract address.
validator_desc_0 = autonity.get_validator(validator_ids[0])
print(f"LNTN contract addr: {validator_desc_0['liquid_contract']}")
# Get the description of the 0-th validator and print its Liquid contract address
validator = autonity.get_validator(validator_addresses[0])
print(f"LNTN contract address: {validator.liquid_contract}")

# Typed validator Liquid Newton contract. Query unclaimed fees for <ADDRESS>.
validator_0 = Validator(w3, validator_desc_0)
unclaimed_atn, unclaimed_ntn = validator_0.unclaimed_rewards("<ADDRESS>")
print(f"unclaimed rewards: {unclaimed_atn} ATN, {unclaimed_ntn} NTN")
# Query unclaimed fees for <ADDRESS> from the validator's Liquid contract
liquid = Liquid(w3, validator.liquid_contract)
unclaimed_atn, unclaimed_ntn = liquid.unclaimed_rewards("<ADDRESS>")
print(f"Unclaimed rewards: {unclaimed_atn} ATN, {unclaimed_ntn} NTN")
```

Where`<RPC_ENDPOINT>` is the name of the Autonity network being connected to.
See <https://docs.autonity.org/networks/> for information about specific
networks.

## Development

The project uses [hatch](https://hatch.pypa.io/latest/install/#pipx) as the
build tool. To launch the tests, run:
build tool.

To launch the tests, run:

```console
hatch run test:all
Expand All @@ -64,15 +64,24 @@ For linting use the command:
hatch run lint:check
```

### Updating the Contract ABIs
### 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
```

The script `script/update_abi.sh [AUTONITY_COMMIT]` builds the contract ABIs
using AGC at the specified Git commit ID or tag. Keys are ordered via the `jq`
tool, in order to produce deterministic output, and the results written to the
`autonity/abi` directory. Further, it normalizes the commit ID that was used.
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.

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.
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`.

## Reporting a Vulnerability

Expand Down
44 changes: 29 additions & 15 deletions autonity/__init__.py
Original file line number Diff line number Diff line change
@@ -1,19 +1,33 @@
# Copyright (C) 2015-2022 Clearmatics Technologies Ltd - All Rights Reserved.
# Copyright (C) 2015-2024 Clearmatics Technologies Ltd - All Rights Reserved.

"""
Top-level Autonity module exposing primary types.
"""
"""Package for interacting with the protocol contracts of the Autonity network."""

# pylint: disable=unused-import
# flake8: noqa

from autonity.autonity import (
from . import constants, contracts, networks
from .factory import (
Accountability,
ACU,
Autonity,
AUTONITY_CONTRACT_ADDRESS,
get_autonity_contract_version,
get_autonity_contract_abi_path,
InflationController,
Liquid,
NonStakableVesting,
Oracle,
Stabilization,
SupplyControl,
UpgradeManager,
)

__all__ = (
"constants",
"contracts",
"networks",
"Accountability",
"ACU",
"Autonity",
"InflationController",
"Liquid",
"NonStakableVesting",
"Oracle",
"Stabilization",
"SupplyControl",
"UpgradeManager",
)
from autonity.config import Config
from autonity.committee_member import CommitteeMember
from autonity.validator import ValidatorDescriptor, Validator
from autonity.tendermint import Tendermint
4 changes: 0 additions & 4 deletions autonity/__version__.py
Original file line number Diff line number Diff line change
@@ -1,5 +1 @@
"""
Release version of autonity package.
"""

__version__ = "v4.0.0"
Loading