afp-sdk 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

{afp_sdk-0.3.0.dist-info → afp_sdk-0.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: afp-sdk
-Version: 0.3.0
+Version: 0.5.0
 Summary: Autonomous Futures Protocol Python SDK
 Keywords: autonity,web3,trading,crypto,prediction,forecast,markets
 License-Expression: MIT
@@ -25,6 +25,10 @@ Description-Content-Type: text/markdown
 
 # Autonomous Futures Protocol Python SDK
 
+Decentralized clearing and creation of Forecast Futures on any timeseries.
+
+![CI](https://github.com/autonity/afp-sdk/actions/workflows/ci.yml/badge.svg)
+
 ## Installation
 
 This library is published on PyPI as the [afp-sdk](https://pypi.org/project/afp-sdk/)
@@ -34,6 +38,11 @@ package. It can be installed in a virtualenv with:
 pip install afp-sdk
 ```
 
+## Documentation
+
+See [afp.autonity.org](https://afp.autonity.org/) for the Autonomous Futures Protocol
+documentation, including the Python SDK reference.
+
 ## Overview
 
 The `afp` package consists of the following:
@@ -43,6 +52,13 @@ The `afp` package consists of the following:
 - `afp.bindings` submodule: Low-level API that provides typed Python bindings
   for the Clearing System smart contracts.
 
+## Configuration
+
+By default the SDK communicates with the AFP Clearing System contracts on
+Autonity Mainnet, and the AutEx Exchange. Connection parameters can be
+overridden via the `afp.AFP` constructor and environment variables; see the
+documentation of the `afp.AFP` class for the available parameters.
+
 ## Usage
 
 ### Preparation
@@ -53,7 +69,8 @@ In order to trade in the AFP system, traders need to prepare the following:
 - The address of the product's collateral token.
 - An Autonity account for managing the margin account. It needs to hold a
   balance in ATN (for paying gas fee) and in the product's collateral token.
-- An Autonity account for signing intents. The two accounts can be the same.
+- An Autonity account for signing intents and submitting trades to the
+  exchange. The two accounts can be the same.
 - The address of an Autonity RPC provider. They can be found on
   [Chainlist](https://chainlist.org/?search=autonity).
 
@@ -64,57 +81,60 @@ import os
 
 PRODUCT_ID = "0x38d502bb683f53ec7c3d7a14b4aa47ac717659e121426131c0189c15bf4b9460"
 COLLATERAL_ASSET = "0xD1A1e4035a164cF42228A8aAaBC2c0Ac9e49687B"
-MARGIN_ACCOUNT_PRIVATE_KEY = os.environ["MARGIN_ACCOUNT_PRIVATE_KEY"]
-INTENT_ACCOUNT_PRIVATE_KEY = os.environ["INTENT_ACCOUNT_PRIVATE_KEY"]
+PRIVATE_KEY = os.environ["PRIVATE_KEY"]
 AUTONITY_RPC_URL = "https://bakerloo.autonity-apis.com"
 ```
 
-Account IDs (addresses) may be retrieved from the private keys with `eth_account`:
+### Configuration
 
-```py
-from eth_account import Account
-
-MARGIN_ACCOUNT_ID = Account.from_key(MARGIN_ACCOUNT_PRIVATE_KEY).address
-INTENT_ACCOUNT_ID = Account.from_key(INTENT_ACCOUNT_PRIVATE_KEY).address
-```
+An application instance can be created with the `afp.AFP()` constructor. An instance
+is associated with a trading venue and a margin account.
 
-### Clearing API
+The required constructor arguments are the RPC provider URL and the authenticator of
+the blockchain account that manages the margin account.
 
-Functions of the Clearing API can be accessed via the `afp.Clearing`
-session object. It connects to the specified Autonity RPC provider and
-communicates with the Clearing System smart contracts.
+An "authenticator" is a service that implements the `afp.Authenticator` protocol.
+Available options are `afp.PrivateKeyAuthenticator` that reads the private key
+from a constructor argument, and `afp.KeyfileAuthenticator` that reads the private
+key from an encrypted keyfile.
 
 ```py
 import afp
 
-clearing = afp.Clearing(MARGIN_ACCOUNT_PRIVATE_KEY, AUTONITY_RPC_URL)
+app = afp.AFP(
+    rpc_url=AUTONITY_RPC_URL,
+    authenticator=afp.PrivateKeyAuthenticator(PRIVATE_KEY),
+)
 ```
 
-Collateral can be deposited into the margin account with
-`clearing.deposit_into_margin_account()`.
+### Margin Account API
 
-```py
-from decimal import Decimal
+Margin accounts can be managed via the `MarginAccount` session object. It
+connects to the specified Autonity RPC provider and communicates with the
+Clearing System smart contracts.
 
-clearing.deposit_into_margin_account(COLLATERAL_ASSET, Decimal("100.00"))
-print(clearing.capital(COLLATERAL_ASSET))
+```py
+margin_account = app.MarginAccount()
 ```
 
-The intent account should be authorized to submit orders. This is only required
-if the intent account and the margin account are different.
+Collateral can be deposited into the margin account with `margin_account.deposit()`.
 
 ```py
-clearing.authorize(COLLATERAL_ASSET, INTENT_ACCOUNT_ID)
+from decimal import Decimal
+
+margin_account.deposit(COLLATERAL_ASSET, Decimal("100.00"))
+print(margin_account.capital(COLLATERAL_ASSET))
 ```
 
 ### Trading API
 
-The functions of the trading API can be accessed via the `afp.Trading` session
-object. It communicates with the AutEx exchange and authenticates on creation with
-the intent account's private key.
+Functions of the trading API can be accessed via the `Trading` session object.
+It communicates with the AutEx exchange and authenticates on creation with the
+intent account's private key. The intent account authenticator is optional, it
+defaults to the authenticator set in the `AFP` constructor.
 
 ```py
-trading = afp.Trading(INTENT_ACCOUNT_PRIVATE_KEY)
+trading = app.Trading()
 ```
 
 To start trading a product, its parameters shall be retrieved from the server.
@@ -169,28 +189,12 @@ print(fills)
 
 See further code examples in the [examples](./examples/) directory.
 
-## Configuration
-
-By default the SDK communicates with the AFP Clearing System contracts on
-Autonity Mainnet, and the AutEx Exchange. Connection parameters can be
-overridden with the following environment variables:
-
-```sh
-AFP_EXCHANGE_URL=
-AFP_CHAIN_ID=
-AFP_CLEARING_DIAMOND_ADDRESS=
-AFP_MARGIN_ACCOUNT_REGISTRY_ADDRESS=
-AFP_ORACLE_PROVIDER_ADDRESS=
-AFP_PRODUCT_REGISTRY_ADDRESS=
-AFP_SYSTEM_VIEWER_ADDRESS=
-```
-
 ## Development
 
 The package uses [`uv`](https://docs.astral.sh/uv/) as project manager.
 
-- Dependecies can be installed with the `uv sync` command.
-- Linters can be executed with the `uv run poe lint` command.
-- Tests can be executed with the `uv run poe test` command.
-- Distributions can be checked before release with the `uv run poe check-dist` command.
-- Markdown API documentation can be generated with the `uv run poe doc-gen` command.
+- Install dependencies with the `uv sync` command.
+- Execute linters with the `uv run poe lint` command.
+- Run tests with the `uv run poe test` command.
+- Check distributions before release with the `uv run poe check-dist` command.
+- Generate markdown API documentation with the `uv run poe doc-gen` command.

afp_sdk-0.5.0.dist-info/RECORD

@@ -0,0 +1,37 @@
+afp/__init__.py,sha256=tvvXz4miC3QI8wy4vjAAf_LtL-19eEgBRA6dnrh3LA8,349
+afp/afp.py,sha256=1xpocnWjALP6QlA-Hn7G2znttJ-ikcb2WA9sLueY3zc,9107
+afp/api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+afp/api/admin.py,sha256=5Q2V6Lde8ERwa0OvNhgez50WW6RcQH0eBA6aHPGwVtY,1243
+afp/api/base.py,sha256=5X1joEwFX4gxYUDCSTvp_hSFCfLZCktnW-UtZFxDquk,4471
+afp/api/margin_account.py,sha256=sC1DF7J3QTHR7cXcRjTG33oZswVy6qr9xnevQbrQ-ew,15256
+afp/api/product.py,sha256=9EGQ5_UZ0m_uIkBIukp99fYVtTIQrqupXxQQ1ATev_E,9100
+afp/api/trading.py,sha256=exQQ3LJA6XCbRAUBuYVjSJ5PHFi4COyqDORxC37LLfQ,10379
+afp/auth.py,sha256=791uNaXrmcRuLbzSzgBsro1k4EOP9N1Ez3VCChX-giw,2054
+afp/bindings/__init__.py,sha256=_n9xoogYi8AAlSx_PE-wjnwP1ujVyDUwoRM0BSm243U,1271
+afp/bindings/auctioneer_facet.py,sha256=4p906zdU2lUsqpWlsiLE3dlxTPrlNpqk8DtjiQUWJ8M,23919
+afp/bindings/bankruptcy_facet.py,sha256=-Kp4Ap5PLAmo_tFrp-1s_yAh0mtHS20z3BC5YIrVjrU,12548
+afp/bindings/clearing_facet.py,sha256=cfyDo-s9_DesbK1Oe-8rfbTCS3HBX9X-L6HbzSydEFk,34898
+afp/bindings/erc20.py,sha256=-jw7ohcEbUL7g3PpK3-a5_7ClUDCDHt1bezm-w7exzo,10822
+afp/bindings/facade.py,sha256=8IehHRqmt9xVe4OJLVAfedprv1fc6mLj7COOjpI_AwA,2588
+afp/bindings/final_settlement_facet.py,sha256=1U5F3WFvf4GUml3gb90YF9RZK_xCwBsX2zRQ8sWSkR0,9470
+afp/bindings/margin_account.py,sha256=hqvHpfM62SAEXSt__NZzAQGu9z7DnIa9LbSgHHkhsKE,45872
+afp/bindings/margin_account_registry.py,sha256=mx9sAU6HuC09d-LAf9bzP57HPLa3M6qXpN7Lj-uiXSc,18800
+afp/bindings/mark_price_tracker_facet.py,sha256=vnVsAmpts_2Sv9Jmx3JlON8X8FJd9D2jOFhqSwXIA7A,2830
+afp/bindings/oracle_provider.py,sha256=CMpVAXdUuTP_W9ZE297B-m9MjuW90yCOhNLMVl3kCf0,15863
+afp/bindings/product_registry.py,sha256=-_h786jzMCsaTqqnoxpmVgBkGf45eCUMthp_PkqrET0,42137
+afp/bindings/system_viewer.py,sha256=0FivdhpfXMrBesXcHkfO9uELyr7GiRmGe36xS5sURGE,41094
+afp/bindings/trading_protocol.py,sha256=ZloF3REbjFq9v0UGVsM0_Lk0EhfWJKdeJ0PzVEnyZo0,39573
+afp/config.py,sha256=_WKywiuty8poE1A0v46uBe1JGpfCzRlxCPamKennfpE,699
+afp/constants.py,sha256=XIph4R0Tx-BPw_NZJgWUtb7NdS9sYzEciFRSStm3VMs,1840
+afp/decorators.py,sha256=SEUQtbgPGc4iVPtBQV2eiCejcDAVImmXcI0uPXFhtJA,2774
+afp/enums.py,sha256=4dglBx4Amcu0GrlJn0cIj-rp9uDHZGfDEP_vMAO02xo,485
+afp/exceptions.py,sha256=frdS-EH84K0fOf92RgRgNkTe3VII2m36XNCS8eyXLLM,390
+afp/exchange.py,sha256=ZhpZzq33jBGAderS9Pl_WZjnYLlECG7nyjYdX24KnRo,5760
+afp/hashing.py,sha256=gBCWN93-ydRPlgnnorSvDQlylcnglrAypRDb-1K-20I,1949
+afp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+afp/schemas.py,sha256=bby8MKc6ALv-v8UaUrhiaKwpkXuQexA6CD8hw6urLUM,5083
+afp/validators.py,sha256=zQvPu3HDu6ADnEE72EJlS5hc1-xfru78Mzd74s1u_EM,1841
+afp_sdk-0.5.0.dist-info/licenses/LICENSE,sha256=ZdaKItgc2ppfqta2OJV0oHpSJiK87PUxmUkUo-_0SB8,1065
+afp_sdk-0.5.0.dist-info/WHEEL,sha256=5h_Q-_6zWQhhADpsAD_Xpw7gFbCRK5WjOOEq0nB806Q,79
+afp_sdk-0.5.0.dist-info/METADATA,sha256=zO6jbifQf9v8abl1bgpTNyuWLxpn1Oz-ch6PH0yms_0,6354
+afp_sdk-0.5.0.dist-info/RECORD,,

{afp_sdk-0.3.0.dist-info → afp_sdk-0.5.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.8.15
+Generator: uv 0.8.18
 Root-Is-Purelib: true
 Tag: py3-none-any

afp/api/liquidation.py

@@ -1,167 +0,0 @@
-from decimal import Decimal
-from functools import cache
-from typing import Iterable
-
-from hexbytes import HexBytes
-from web3 import Web3
-
-from .. import validators
-from ..bindings import (
-    BidData,
-    ClearingDiamond,
-    ProductRegistry,
-    Side as OnChainOrderSide,
-)
-from ..bindings.facade import CLEARING_DIAMOND_ABI
-from ..bindings.product_registry import ABI as PRODUCT_REGISTRY_ABI
-from ..decorators import convert_web3_error
-from ..enums import OrderSide
-from ..schemas import AuctionData, Bid
-from .base import ClearingSystemAPI
-
-
-class Liquidation(ClearingSystemAPI):
-    """API for participating in liquidation auctions.
-
-    Parameters
-    ----------
-    private_key : str
-        The private key of the blockchain account that participates in a liquidation
-        auction.
-    autonity_rpc_url : str
-        The URL of a JSON-RPC provider for Autonity. (HTTPS only.)
-    """
-
-    @staticmethod
-    def create_bid(product_id: str, price: Decimal, quantity: int, side: str) -> Bid:
-        """Create a bid to be submitted to a liquidation auction.
-
-        Parameters
-        ----------
-        product_id : str
-        price: Decimal
-        quantity: int
-        side: str
-
-        Returns
-        -------
-        afp.schemas.Bid
-        """
-        return Bid(
-            product_id=product_id,
-            price=price,
-            quantity=quantity,
-            side=getattr(OrderSide, side.upper()),
-        )
-
-    ### Transactions ###
-
-    @convert_web3_error(CLEARING_DIAMOND_ABI)
-    def request_liquidation(self, margin_account_id: str, collateral_asset: str) -> str:
-        """Request a liquidation auction to be started.
-
-        Parameters
-        ----------
-        margin_account_id : str
-            The ID of the margin account to be liquidated.
-        collateral_asset : str
-            The address of the collateral token that the margin account is trading with.
-
-        Returns
-        -------
-        str
-            The hash of the transaction.
-        """
-        margin_account_id = validators.validate_address(margin_account_id)
-        collateral_asset = validators.validate_address(collateral_asset)
-
-        clearing_contract = ClearingDiamond(self._w3)
-        tx_hash = clearing_contract.request_liquidation(
-            margin_account_id, collateral_asset
-        ).transact()
-        self._w3.eth.wait_for_transaction_receipt(tx_hash)
-        return Web3.to_hex(tx_hash)
-
-    @convert_web3_error(CLEARING_DIAMOND_ABI, PRODUCT_REGISTRY_ABI)
-    def submit_bids(
-        self, margin_account_id: str, collateral_asset: str, bids: Iterable[Bid]
-    ) -> str:
-        """Submit bids to a liquidation auction.
-
-        Parameters
-        ----------
-        margin_account_id : str
-            The ID of the margin account that is being liquidated.
-        collateral_asset : str
-            The address of the collateral token that the margin account is trading with.
-        bids: list of afp.schemas.Bid
-
-        Returns
-        -------
-        str
-            The hash of the transaction.
-        """
-        margin_account_id = validators.validate_address(margin_account_id)
-        collateral_asset = validators.validate_address(collateral_asset)
-
-        converted_bids = [
-            BidData(
-                product_id=HexBytes(bid.product_id),
-                price=int(bid.price * 10 ** self._tick_size(bid.product_id)),
-                quantity=bid.quantity,
-                side=getattr(OnChainOrderSide, bid.side.name),
-            )
-            for bid in bids
-        ]
-
-        clearing_contract = ClearingDiamond(self._w3)
-        tx_hash = clearing_contract.bid_auction(
-            margin_account_id, collateral_asset, converted_bids
-        ).transact()
-        self._w3.eth.wait_for_transaction_receipt(tx_hash)
-        return Web3.to_hex(tx_hash)
-
-    ### Views ###
-
-    @convert_web3_error(CLEARING_DIAMOND_ABI)
-    def auction_data(
-        self, margin_account_id: str, collateral_asset: str
-    ) -> AuctionData:
-        """Returns information on a liquidation auction.
-
-        Parameters
-        ----------
-        margin_account_id : str
-            The ID of the margin account to be liquidated.
-        collateral_asset : str
-            The address of the collateral token that the margin account is trading with.
-
-        Returns
-        -------
-        str
-            The hash of the transaction.
-        """
-        margin_account_id = validators.validate_address(margin_account_id)
-        collateral_asset = validators.validate_address(collateral_asset)
-
-        clearing_contract = ClearingDiamond(self._w3)
-        data = clearing_contract.auction_data(margin_account_id, collateral_asset)
-        divisor = 10 ** self._decimals(collateral_asset)
-        return AuctionData(
-            start_block=data.start_block,
-            margin_account_equity_at_initiation=(
-                Decimal(data.mae_at_initiation) / divisor
-            ),
-            maintenance_margin_used_at_initiation=(
-                Decimal(data.mmu_at_initiation) / divisor
-            ),
-            margin_account_equity_now=(Decimal(data.mae_now) / divisor),
-            maintenance_margin_used_now=(Decimal(data.mmu_now) / divisor),
-        )
-
-    ### Internal getters ###
-
-    @cache
-    def _tick_size(self, product_id: str) -> int:
-        product_registry_contract = ProductRegistry(self._w3)
-        return product_registry_contract.tick_size(HexBytes(product_id))

afp_sdk-0.3.0.dist-info/RECORD

@@ -1,35 +0,0 @@
-afp/__init__.py,sha256=LTxZrvSFI5blSuBEsGlyZhFfmrNVV3LpPrdi7aYwiTs,325
-afp/api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-afp/api/admin.py,sha256=7ymtCloff4UhyS-MAqA8_cndWlfZanjuGgPgkiV5Jhc,1526
-afp/api/base.py,sha256=iS-sjAc9mME2qOMEvnB6T6x9L_8oeJnHY6h79xrbAOE,2632
-afp/api/builder.py,sha256=mde8XemEMKL76KgEd5rxg7RLBS6lyIfNOEGmE1_iK0M,7114
-afp/api/clearing.py,sha256=nMVjayFkf0XYYP3aKAdgR6NaFSG4Cl_QsEuADRuIO7M,12922
-afp/api/liquidation.py,sha256=CtME5524VVW9mXMMpORyUP205sTVqpLnHIPoTy2MGa8,5439
-afp/api/trading.py,sha256=HjskW4c13CwAB-AwyIsSBcvyXKKEJk7a9768tqcTzUE,10648
-afp/bindings/__init__.py,sha256=_n9xoogYi8AAlSx_PE-wjnwP1ujVyDUwoRM0BSm243U,1271
-afp/bindings/auctioneer_facet.py,sha256=4p906zdU2lUsqpWlsiLE3dlxTPrlNpqk8DtjiQUWJ8M,23919
-afp/bindings/bankruptcy_facet.py,sha256=Yg8sLhDU0crsL1ISSy4eoeQEP5jrAuiWBBlco5MtgPc,11370
-afp/bindings/clearing_facet.py,sha256=DzRzzP9qXQ7kJMcMRwoLwLJ7S-w-2mid_CbF1fOVHaE,34081
-afp/bindings/erc20.py,sha256=-jw7ohcEbUL7g3PpK3-a5_7ClUDCDHt1bezm-w7exzo,10822
-afp/bindings/facade.py,sha256=nZmAp7r26iszxtNyE5imdl_PKbG6vii_3oYJ3Q69iow,2278
-afp/bindings/final_settlement_facet.py,sha256=1U5F3WFvf4GUml3gb90YF9RZK_xCwBsX2zRQ8sWSkR0,9470
-afp/bindings/margin_account.py,sha256=ffkpf5HEXQCxiWuLpgDcHVAiaUVvbKU1Kt0K8tvgZcA,42461
-afp/bindings/margin_account_registry.py,sha256=mx9sAU6HuC09d-LAf9bzP57HPLa3M6qXpN7Lj-uiXSc,18800
-afp/bindings/mark_price_tracker_facet.py,sha256=vnVsAmpts_2Sv9Jmx3JlON8X8FJd9D2jOFhqSwXIA7A,2830
-afp/bindings/oracle_provider.py,sha256=CMpVAXdUuTP_W9ZE297B-m9MjuW90yCOhNLMVl3kCf0,15863
-afp/bindings/product_registry.py,sha256=HFWwbFKvXk0A2dZB6KBa0Ul8-vX9uvvtGj0dhRL9UUw,43701
-afp/bindings/system_viewer.py,sha256=Kwi-Kz2oKh5qWy17N0D2LyrAbkKz_sW9OxeWh6VX_j8,41347
-afp/bindings/trading_protocol.py,sha256=ZloF3REbjFq9v0UGVsM0_Lk0EhfWJKdeJ0PzVEnyZo0,39573
-afp/config.py,sha256=GbfvtsRkRDas4L-s1E-9AB7RitrN9JRQ79R5zfv6Ha0,1190
-afp/decorators.py,sha256=Ustc15RbXGYIEqDb9lXnd-bdhZJ8ZrztN4h_vjkLsG0,2692
-afp/enums.py,sha256=4dglBx4Amcu0GrlJn0cIj-rp9uDHZGfDEP_vMAO02xo,485
-afp/exceptions.py,sha256=RE8IE6akDgbar2PobdpOiBdGZZCYkb4jWf1ozJmdLaI,342
-afp/exchange.py,sha256=K_SkVyRvs7ebW82BGbxND1r5UHzb4_TNRfkOOIG-Dvs,5444
-afp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-afp/schemas.py,sha256=8nlNPq6t_jmYEpa_WWhOIr_yvpQv5tj86uvpGTNHWZY,4996
-afp/signing.py,sha256=7fohnAvoiDA4ems_3OcVnr16OmYLSg9NnnCSzDplg6s,2235
-afp/validators.py,sha256=m61ZpP385CxsdDGJavPkXKTXnJAHKLCzedoZ8mL6daI,1818
-afp_sdk-0.3.0.dist-info/licenses/LICENSE,sha256=ZdaKItgc2ppfqta2OJV0oHpSJiK87PUxmUkUo-_0SB8,1065
-afp_sdk-0.3.0.dist-info/WHEEL,sha256=Jb20R3Ili4n9P1fcwuLup21eQ5r9WXhs4_qy7VTrgPI,79
-afp_sdk-0.3.0.dist-info/METADATA,sha256=YJmCZfdcfYbJxL2DTDKNuoiPZW0SEb13aOVgxtRgzoc,6026
-afp_sdk-0.3.0.dist-info/RECORD,,