afp-sdk 0.5.4__tar.gz → 0.6.0__tar.gz

{afp_sdk-0.5.4 → afp_sdk-0.6.0}/CHANGELOG.md

@@ -1,3 +1,27 @@
+## [v0.6.0] - 2026-01-22
+
+### Added
+
+- Add Python 3.14 support ([#45](https://github.com/autonity/afp-sdk/pull/45))
+- Add Prediction Product schemas to `afp.schemas` module for product creation ([#45](https://github.com/autonity/afp-sdk/pull/45))
+- Add `Product.pin()` method for extended metadata IPFS upload an pinning ([#46](https://github.com/autonity/afp-sdk/pull/46))
+- Add `Product.validate()` and `Product.validate_json()` methods for importing and validating product specifications ([#46](https://github.com/autonity/afp-sdk/pull/46))
+- Add `Product.dump()` and `Product.dump_json()` methods for exporting product specifications ([#46](https://github.com/autonity/afp-sdk/pull/46))
+- Add `Product.get()` method for downloading product specifications from Autonity & IPFS ([#46](https://github.com/autonity/afp-sdk/pull/46))
+
+### Changed
+
+- Update `Product.register()` method signature with the `initial_builder_stake` attribute ([#45](https://github.com/autonity/afp-sdk/pull/45))
+- Update the AutEx exchange interface ([#42](https://github.com/autonity/afp-sdk/pull/42))
+- Update contract bindings for the updated Clearing System interface ([#42](https://github.com/autonity/afp-sdk/pull/42))
+- Update default contract addresses ([5948faa](https://github.com/autonity/afp-sdk/commit/5948faa1882a1ee1237936525df6534043b30f03))
+
+### Removed
+
+- Remove Python 3.11 support ([#45](https://github.com/autonity/afp-sdk/pull/45))
+- Remove the `Product.create()` method ([#45](https://github.com/autonity/afp-sdk/pull/45))
+- Remove deprecated methods `Trading.open_orders()`, `Product.create_product()`, `Product.register_product()` and `Product.product_state()` ([#41](https://github.com/autonity/afp-sdk/pull/41))
+
 ## [v0.5.4] - 2025-11-05
 
 ### Added
@@ -78,6 +102,7 @@
 
 _First public release for Forecastathon._
 
+[v0.6.0]: https://github.com/autonity/afp-sdk/releases/tag/v0.6.0
 [v0.5.4]: https://github.com/autonity/afp-sdk/releases/tag/v0.5.4
 [v0.5.3]: https://github.com/autonity/afp-sdk/releases/tag/v0.5.3
 [v0.5.2]: https://github.com/autonity/afp-sdk/releases/tag/v0.5.2

{afp_sdk-0.5.4 → afp_sdk-0.6.0}/PKG-INFO

@@ -1,22 +1,26 @@
 Metadata-Version: 2.4
 Name: afp-sdk
-Version: 0.5.4
+Version: 0.6.0
 Summary: Autonomous Futures Protocol Python SDK
 Keywords: autonity,web3,trading,crypto,prediction,forecast,markets
 License-Expression: MIT
 License-File: LICENSE
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: dag-cbor>=0.3.3
 Requires-Dist: decorator>=5.2.1
 Requires-Dist: inflection>=0.5.1
+Requires-Dist: ipld-car>=0.0.1
+Requires-Dist: multiformats>=0.3.1.post4
 Requires-Dist: pydantic>=2.10.6
 Requires-Dist: requests>=2.32.0
+Requires-Dist: rfc8785>=0.1.4
 Requires-Dist: siwe>=4.4.0
 Requires-Dist: web3>=7.6.0
-Requires-Python: >=3.11
+Requires-Python: >=3.12
 Project-URL: Changes, https://github.com/autonity/afp-sdk/blob/master/CHANGELOG.md
 Project-URL: Homepage, https://github.com/autonity/afp-sdk
 Project-URL: Issues, https://github.com/autonity/afp-sdk/issues
@@ -187,14 +191,73 @@ fills = trading.order_fills(product_id=PRODUCT_ID)
 print(fills)
 ```
 
+### Product API
+
+Use the `Product` session object to validate a product schema, pin the
+specification to IPFS, and register it on-chain.
+
+In order to use the product API for product building, connection parameters of
+an IPFS pinning service like [Filebase](https://filebase.com/) should be
+included in the `AFP` constructor parameters.
+
+```py
+IPFS_API_URL = "https://rpc.filebase.io"
+IPFS_API_KEY = os.environ["IPFS_API_KEY"]
+
+app = afp.AFP(
+    rpc_url=AUTONITY_RPC_URL,
+    authenticator=afp.PrivateKeyAuthenticator(PRIVATE_KEY),
+    ipfs_api_url=IPFS_API_URL,
+    ipfs_api_key=IPFS_API_KEY,
+)
+
+product = app.Product()
+```
+
+A JSON product specification can be parsed and validated with
+`product.validate_json()`.
+
+```py
+with open("product-spec.json") as spec_file:
+    specification = product.validate_json(spec_file.read())
+```
+
+Alternatively, it can also be validated from a Python dictionary.
+
+```py
+spec_dict = {
+    "product": {...},
+    "outcome_space": {...},
+    "outcome_point": {...},
+    "oracle_config": {...},
+    "oracle_fallback": {...},
+}
+specification = product.validate(spec_dict)
+```
+
+Product specifications are stored at two different places, the `PredictionProductV1`
+object is stored on-chain in the Product Registry contract, while the rest of the
+product specification is referred to as _extended metadata_ and it is uploaded to IPFS.
+
+The first step therefore is to upload the extended metadata of the product to
+IPFS and to pin the root node of the DAG. `product.pin()` returns a modified
+copy of the specification that incudes the extended metadata CID.
+
+```py
+pinned_specification = product.pin(specification)
+```
+
+The product can then be registered with the Product Registry contract via a
+blockchain transaction.
+
+```
+tx = product.register(
+    pinned_specification, initial_builder_stake=Decimal("10")
+)
+```
+
 See further code examples in the [examples](./examples/) directory.
 
 ## Development
 
-The package uses [`uv`](https://docs.astral.sh/uv/) as project manager.
-
-- 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.
+See [DEVELOPMENT.md](./DEVELOPMENT.md) for developer documentation.

{afp_sdk-0.5.4 → afp_sdk-0.6.0}/README.md

@@ -162,14 +162,73 @@ fills = trading.order_fills(product_id=PRODUCT_ID)
 print(fills)
 ```
 
+### Product API
+
+Use the `Product` session object to validate a product schema, pin the
+specification to IPFS, and register it on-chain.
+
+In order to use the product API for product building, connection parameters of
+an IPFS pinning service like [Filebase](https://filebase.com/) should be
+included in the `AFP` constructor parameters.
+
+```py
+IPFS_API_URL = "https://rpc.filebase.io"
+IPFS_API_KEY = os.environ["IPFS_API_KEY"]
+
+app = afp.AFP(
+    rpc_url=AUTONITY_RPC_URL,
+    authenticator=afp.PrivateKeyAuthenticator(PRIVATE_KEY),
+    ipfs_api_url=IPFS_API_URL,
+    ipfs_api_key=IPFS_API_KEY,
+)
+
+product = app.Product()
+```
+
+A JSON product specification can be parsed and validated with
+`product.validate_json()`.
+
+```py
+with open("product-spec.json") as spec_file:
+    specification = product.validate_json(spec_file.read())
+```
+
+Alternatively, it can also be validated from a Python dictionary.
+
+```py
+spec_dict = {
+    "product": {...},
+    "outcome_space": {...},
+    "outcome_point": {...},
+    "oracle_config": {...},
+    "oracle_fallback": {...},
+}
+specification = product.validate(spec_dict)
+```
+
+Product specifications are stored at two different places, the `PredictionProductV1`
+object is stored on-chain in the Product Registry contract, while the rest of the
+product specification is referred to as _extended metadata_ and it is uploaded to IPFS.
+
+The first step therefore is to upload the extended metadata of the product to
+IPFS and to pin the root node of the DAG. `product.pin()` returns a modified
+copy of the specification that incudes the extended metadata CID.
+
+```py
+pinned_specification = product.pin(specification)
+```
+
+The product can then be registered with the Product Registry contract via a
+blockchain transaction.
+
+```
+tx = product.register(
+    pinned_specification, initial_builder_stake=Decimal("10")
+)
+```
+
 See further code examples in the [examples](./examples/) directory.
 
 ## Development
 
-The package uses [`uv`](https://docs.astral.sh/uv/) as project manager.
-
-- 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.
+See [DEVELOPMENT.md](./DEVELOPMENT.md) for developer documentation.

{afp_sdk-0.5.4 → afp_sdk-0.6.0}/afp/__init__.py

@@ -1,12 +1,15 @@
 """Autonomous Futures Protocol Python SDK."""
 
-from . import bindings
+from . import bindings, enums, exceptions, schemas
 from .afp import AFP
 from .auth import Authenticator, KeyfileAuthenticator, PrivateKeyAuthenticator
 from .exceptions import AFPException
 
 __all__ = (
     "bindings",
+    "enums",
+    "exceptions",
+    "schemas",
     "AFP",
     "AFPException",
     "Authenticator",

{afp_sdk-0.5.4 → afp_sdk-0.6.0}/afp/afp.py

@@ -27,6 +27,13 @@ class AFP:
         The REST API base URL of the exchange. Defaults to the URL of the AutEx
         exchange. Its default value can be overridden with the `AFP_EXCHANGE_URL`
         environment variable.
+    ipfs_api_url : str, optional
+        The RPC API root URL of an IPFS node that supports Kubo RPC API v0, required
+        for product registration. Defaults to the URL of a local IPFS node. Its default
+        value can be overridden with the `AFP_IPFS_API_URL` environment variable.
+    ipfs_api_key : str, optional
+        The access token to include in API requests to the IPFS client. Its default
+        value can be overridden with the `AFP_IPFS_API_KEY` environment variable.
     chain_id : str, optional
         The chain ID of the Autonity network. Defauls to the chain ID of Autonity
         Mainnet. Its default value can be overridden with the `AFP_CHAIN_ID` environment
@@ -79,6 +86,8 @@ class AFP:
         authenticator: Authenticator | None = None,
         rpc_url: str | None = defaults.RPC_URL,
         exchange_url: str = defaults.EXCHANGE_URL,
+        ipfs_api_url: str = defaults.IPFS_API_URL,
+        ipfs_api_key: str | None = defaults.IPFS_API_KEY,
         chain_id: int = defaults.CHAIN_ID,
         gas_limit: int | None = defaults.GAS_LIMIT,
         max_fee_per_gas: int | None = defaults.MAX_FEE_PER_GAS,
@@ -97,6 +106,8 @@ class AFP:
             authenticator=authenticator,
             exchange_url=exchange_url,
             rpc_url=rpc_url,
+            ipfs_api_url=ipfs_api_url,
+            ipfs_api_key=ipfs_api_key,
             chain_id=chain_id,
             gas_limit=gas_limit,
             max_fee_per_gas=max_fee_per_gas,

{afp_sdk-0.5.4 → afp_sdk-0.6.0}/afp/api/admin.py

@@ -1,7 +1,7 @@
 from .. import validators
 from ..decorators import refresh_token_on_expiry
 from ..enums import ListingState
-from ..schemas import ExchangeProductListingSubmission, ExchangeProductUpdateSubmission
+from ..dtos import ExchangeProductListingSubmission, ExchangeProductUpdateSubmission
 from .base import ExchangeAPI
 
 

{afp_sdk-0.5.4 → afp_sdk-0.6.0}/afp/api/base.py

@@ -11,11 +11,13 @@ from web3.contract.contract import ContractFunction
 from web3.types import TxParams
 
 from ..auth import Authenticator
-from ..config import Config
 from ..bindings.erc20 import ERC20
+from ..config import Config
+from ..dtos import LoginSubmission
 from ..exceptions import ConfigurationError
 from ..exchange import ExchangeClient
-from ..schemas import LoginSubmission, Transaction
+from ..ipfs import IPFSClient
+from ..schemas import Transaction
 
 
 class BaseAPI(ABC):
@@ -127,3 +129,10 @@ class ExchangeAPI(BaseAPI, ABC):
             statement=None,
         )
         return message.prepare_message()
+
+
+class IPFSManager(ABC):
+    _ipfs_client: IPFSClient
+
+    def __init__(self, config: Config):
+        self._ipfs_client = IPFSClient(config.ipfs_api_url, config.ipfs_api_key)

{afp_sdk-0.5.4 → afp_sdk-0.6.0}/afp/api/margin_account.py

@@ -1,6 +1,5 @@
 from decimal import Decimal
 from functools import cache
-from typing import Iterable
 
 from eth_typing.evm import ChecksumAddress
 from hexbytes import HexBytes
@@ -9,54 +8,26 @@ from web3.exceptions import ContractCustomError
 
 from .. import validators
 from ..bindings import (
-    BidData,
-    ClearingDiamond,
     MarginAccount as MarginContract,
     MarginAccountRegistry,
     ProductRegistry,
-    Side as OnChainOrderSide,
 )
 from ..bindings.erc20 import ERC20
 from ..bindings.facade import CLEARING_DIAMOND_ABI
 from ..bindings.margin_account import ABI as MARGIN_CONTRACT_ABI
 from ..bindings.margin_account_registry import ABI as MARGIN_ACCOUNT_REGISTRY_ABI
-from ..bindings.product_registry import ABI as PRODUCT_REGISTRY_ABI
 from ..decorators import convert_web3_error
 from ..exceptions import NotFoundError
-from ..schemas import AuctionData, Bid, OrderSide, Position, Transaction
+from ..schemas import Position, Transaction
 from .base import ClearingSystemAPI
 
 
 class MarginAccount(ClearingSystemAPI):
     """API for managing margin accounts."""
 
-    ### Factories ###
-
-    @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(MARGIN_CONTRACT_ABI)
+    @convert_web3_error(MARGIN_CONTRACT_ABI, CLEARING_DIAMOND_ABI)
     def authorize(self, collateral_asset: str, intent_account_id: str) -> Transaction:
         """Authorizes a blockchain account to submit intents to the clearing system
         using the margin account associated with the collateral asset.
@@ -79,7 +50,7 @@ class MarginAccount(ClearingSystemAPI):
             self._margin_contract(collateral_asset).authorize(intent_account_id)
         )
 
-    @convert_web3_error(MARGIN_CONTRACT_ABI)
+    @convert_web3_error(MARGIN_CONTRACT_ABI, CLEARING_DIAMOND_ABI)
     def deposit(
         self, collateral_asset: str, amount: Decimal
     ) -> tuple[Transaction, Transaction]:
@@ -118,7 +89,7 @@ class MarginAccount(ClearingSystemAPI):
         )
         return (tx1, tx2)
 
-    @convert_web3_error(MARGIN_CONTRACT_ABI)
+    @convert_web3_error(MARGIN_CONTRACT_ABI, CLEARING_DIAMOND_ABI)
     def withdraw(self, collateral_asset: str, amount: Decimal) -> Transaction:
         """Withdraws the specified amount of collateral tokens from the margin account
         associated with the collateral asset.
@@ -141,78 +112,9 @@ class MarginAccount(ClearingSystemAPI):
             self._margin_contract(collateral_asset).withdraw(token_amount)
         )
 
-    @convert_web3_error(CLEARING_DIAMOND_ABI)
-    def request_liquidation(
-        self, margin_account_id: str, collateral_asset: str
-    ) -> Transaction:
-        """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
-        -------
-        afp.schemas.Transaction
-            Transaction parameters.
-        """
-        margin_account_id = validators.validate_address(margin_account_id)
-        collateral_asset = validators.validate_address(collateral_asset)
-
-        clearing_contract = ClearingDiamond(
-            self._w3, self._config.clearing_diamond_address
-        )
-        return self._transact(
-            clearing_contract.request_liquidation(margin_account_id, collateral_asset)
-        )
-
-    @convert_web3_error(CLEARING_DIAMOND_ABI, PRODUCT_REGISTRY_ABI)
-    def submit_bids(
-        self, margin_account_id: str, collateral_asset: str, bids: Iterable[Bid]
-    ) -> Transaction:
-        """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
-        -------
-        afp.schemas.Transaction
-            Transaction parameters.
-        """
-        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, self._config.clearing_diamond_address
-        )
-        return self._transact(
-            clearing_contract.bid_auction(
-                margin_account_id, collateral_asset, converted_bids
-            )
-        )
-
     ### Views ###
 
-    @convert_web3_error(MARGIN_CONTRACT_ABI)
+    @convert_web3_error(MARGIN_CONTRACT_ABI, CLEARING_DIAMOND_ABI)
     def capital(self, collateral_asset: str) -> Decimal:
         """Returns the amount of collateral tokens in the margin account associated
         with the collateral asset.
@@ -232,7 +134,7 @@ class MarginAccount(ClearingSystemAPI):
         )
         return Decimal(amount) / 10 ** self._decimals(collateral_asset)
 
-    @convert_web3_error(MARGIN_CONTRACT_ABI)
+    @convert_web3_error(MARGIN_CONTRACT_ABI, CLEARING_DIAMOND_ABI)
     def position(self, collateral_asset: str, position_id: str) -> Position:
         """Returns the parameters of a position in the margin account associated with
         the collateral asset.
@@ -261,7 +163,7 @@ class MarginAccount(ClearingSystemAPI):
             pnl=Decimal(data.pnl) / 10**decimals,
         )
 
-    @convert_web3_error(MARGIN_CONTRACT_ABI)
+    @convert_web3_error(MARGIN_CONTRACT_ABI, CLEARING_DIAMOND_ABI)
     def positions(self, collateral_asset: str) -> list[Position]:
         """Returns all positions in the margin account associated with the collateral
         asset.
@@ -281,7 +183,7 @@ class MarginAccount(ClearingSystemAPI):
         )
         return [self.position(collateral_asset, Web3.to_hex(id)) for id in position_ids]
 
-    @convert_web3_error(MARGIN_CONTRACT_ABI)
+    @convert_web3_error(MARGIN_CONTRACT_ABI, CLEARING_DIAMOND_ABI)
     def equity(self, collateral_asset: str) -> Decimal:
         """Returns the margin account equity in the margin account associated with the
         collateral asset.
@@ -301,7 +203,7 @@ class MarginAccount(ClearingSystemAPI):
         )
         return Decimal(amount) / 10 ** self._decimals(collateral_asset)
 
-    @convert_web3_error(MARGIN_CONTRACT_ABI)
+    @convert_web3_error(MARGIN_CONTRACT_ABI, CLEARING_DIAMOND_ABI)
     def maintenance_margin_available(self, collateral_asset: str) -> Decimal:
         """Returns the maintenance margin available in the margin account associated
         with the collateral asset.
@@ -321,7 +223,7 @@ class MarginAccount(ClearingSystemAPI):
         )
         return Decimal(amount) / 10 ** self._decimals(collateral_asset)
 
-    @convert_web3_error(MARGIN_CONTRACT_ABI)
+    @convert_web3_error(MARGIN_CONTRACT_ABI, CLEARING_DIAMOND_ABI)
     def maintenance_margin_used(self, collateral_asset: str) -> Decimal:
         """Returns the maintenance margin used in the margin account associated with
         the collateral asset.
@@ -341,7 +243,7 @@ class MarginAccount(ClearingSystemAPI):
         )
         return Decimal(amount) / 10 ** self._decimals(collateral_asset)
 
-    @convert_web3_error(MARGIN_CONTRACT_ABI)
+    @convert_web3_error(MARGIN_CONTRACT_ABI, CLEARING_DIAMOND_ABI)
     def profit_and_loss(self, collateral_asset: str) -> Decimal:
         """Returns the profit and loss in the margin account associated with the
         collateral asset.
@@ -361,7 +263,7 @@ class MarginAccount(ClearingSystemAPI):
         )
         return Decimal(amount) / 10 ** self._decimals(collateral_asset)
 
-    @convert_web3_error(MARGIN_CONTRACT_ABI)
+    @convert_web3_error(MARGIN_CONTRACT_ABI, CLEARING_DIAMOND_ABI)
     def withdrawable_amount(self, collateral_asset: str) -> Decimal:
         """Returns the amount of collateral tokens withdrawable from the margin account
         associated with the collateral asset.
@@ -381,44 +283,6 @@ class MarginAccount(ClearingSystemAPI):
         )
         return Decimal(amount) / 10 ** self._decimals(collateral_asset)
 
-    @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, self._config.clearing_diamond_address
-        )
-        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