afp-sdk 0.5.3__py3-none-any.whl → 0.6.0__py3-none-any.whl

afp/api/product.py

@@ -1,4 +1,3 @@
-import warnings
 from datetime import datetime
 from decimal import Decimal
 from typing import Any, cast
@@ -8,142 +7,207 @@ from hexbytes import HexBytes
 from web3 import Web3
 
 from .. import constants, hashing, validators
+from ..auth import Authenticator
+from ..config import Config
 from ..bindings import (
+    BaseProduct as OnChainBaseProduct,
     ClearingDiamond,
-    OracleSpecification,
-    Product as OnChainProduct,
-    ProductMetadata,
+    ExpirySpecification as OnChainExpirySpecification,
+    OracleSpecification as OnChainOracleSpecification,
+    PredictionProductV1 as OnChainPredictionProductV1,
+    ProductMetadata as OnChainProductMetadata,
     ProductRegistry,
 )
 from ..bindings.erc20 import ERC20
 from ..bindings.facade import CLEARING_DIAMOND_ABI
 from ..bindings.product_registry import ABI as PRODUCT_REGISTRY_ABI
 from ..decorators import convert_web3_error
-from ..exceptions import NotFoundError
-from ..schemas import ProductSpecification, Transaction
-from .base import ClearingSystemAPI
+from ..dtos import ExtendedMetadata
+from ..exceptions import NotFoundError, ValidationError
+from ..schemas import (
+    BaseProduct,
+    ExpirySpecification,
+    OracleSpecification,
+    PredictionProduct,
+    PredictionProductV1,
+    ProductMetadata,
+    Transaction,
+)
+from .base import ClearingSystemAPI, IPFSManager
 
 
-class Product(ClearingSystemAPI):
+class Product(ClearingSystemAPI, IPFSManager):
     """API for managing products."""
 
-    ### Factories ###
-
-    @convert_web3_error()
-    def create(
-        self,
-        *,
-        symbol: str,
-        description: str,
-        fsv_decimals: int,
-        fsp_alpha: Decimal,
-        fsp_beta: Decimal,
-        fsv_calldata: str,
-        start_time: datetime,
-        earliest_fsp_submission_time: datetime,
-        collateral_asset: str,
-        tick_size: int,
-        unit_value: Decimal,
-        initial_margin_requirement: Decimal,
-        maintenance_margin_requirement: Decimal,
-        auction_bounty: Decimal,
-        tradeout_interval: int,
-        extended_metadata: str,
-        oracle_address: str | None = None,
-    ) -> ProductSpecification:
-        """Creates a product specification with the given product data.
-
-        The builder account's address is derived from the private key; the price
-        quotation symbol is retrieved from the collateral asset.
+    def __init__(self, config: Config, authenticator: Authenticator | None = None):
+        ClearingSystemAPI.__init__(self, config, authenticator)
+        IPFSManager.__init__(self, config)
+
+    ### Product Specification ###
+
+    def validate(self, product_dict: dict[str, Any]) -> PredictionProduct:
+        """Creates a product specification from a dictionary.
+
+        The dictionary must follow the schema of the afp.schemas.ProductSpec model.
 
         Parameters
         ----------
-        symbol : str
-        description : str
-        fsv_decimals: int
-        fsp_alpha: Decimal
-        fsp_beta: int
-        fsv_calldata: str
-        start_time : datetime
-        earliest_fsp_submission_time : datetime
-        collateral_asset : str
-        tick_size : int
-        unit_value : Decimal
-        initial_margin_requirement : Decimal
-        maintenance_margin_requirement : Decimal
-        auction_bounty : Decimal
-        tradeout_interval : int
-        extended_metadata : str
-        oracle_address: str, optional
+        product_dict : dict
+            A dictionary that follows the PredictionProduct schema.
 
         Returns
         -------
-        afp.schemas.ProductSpecification
+        afp.schemas.PredictionProduct
+
+        Raises
+        ------
+        ValueError, afp.exceptions.ValidationError
+            If the product specification fails validation.
         """
-        if oracle_address is None:
-            oracle_address = self._config.oracle_provider_address
+        return self._verify_product_spec(PredictionProduct.model_validate(product_dict))
 
-        if len(self._w3.eth.get_code(Web3.to_checksum_address(collateral_asset))) == 0:
-            raise NotFoundError(f"No ERC20 token found at address {collateral_asset}")
-        if len(self._w3.eth.get_code(Web3.to_checksum_address(oracle_address))) == 0:
-            raise NotFoundError(f"No contract found at oracle address {oracle_address}")
+    def validate_json(self, product_json: str) -> PredictionProduct:
+        """Creates a product specification from a dictionary.
 
-        erc20_contract = ERC20(self._w3, Web3.to_checksum_address(collateral_asset))
-        price_quotation = erc20_contract.symbol()
+        The dictionary must follow the schema of the afp.schemas.ProductSpec model.
 
-        product_id = Web3.to_hex(
-            hashing.generate_product_id(self._authenticator.address, symbol)
-        )
+        Parameters
+        ----------
+        product_json : str
+            A JSON string that follows the PredictionProduct schema.
 
-        return ProductSpecification(
-            id=product_id,
-            builder_id=self._authenticator.address,
-            symbol=symbol,
-            description=description,
-            oracle_address=oracle_address,
-            fsv_decimals=fsv_decimals,
-            fsp_alpha=fsp_alpha,
-            fsp_beta=fsp_beta,
-            fsv_calldata=fsv_calldata,
-            price_quotation=price_quotation,
-            collateral_asset=collateral_asset,
-            start_time=start_time,
-            earliest_fsp_submission_time=earliest_fsp_submission_time,
-            tick_size=tick_size,
-            unit_value=unit_value,
-            initial_margin_requirement=initial_margin_requirement,
-            maintenance_margin_requirement=maintenance_margin_requirement,
-            auction_bounty=auction_bounty,
-            tradeout_interval=tradeout_interval,
-            extended_metadata=extended_metadata,
+        Returns
+        -------
+        afp.schemas.PredictionProduct
+
+        Raises
+        ------
+        ValueError, afp.exceptions.ValidationError
+            If the product specification fails validation.
+        """
+        return self._verify_product_spec(
+            PredictionProduct.model_validate_json(product_json)
         )
 
-    def create_product(self, **kwargs: Any) -> ProductSpecification:
-        """Deprecated alias of `Product.create`."""
-        warnings.warn(
-            "Product.create_product() is deprecated. Use Product.create() instead.",
-            DeprecationWarning,
-            stacklevel=2,
+    def dump(self, product_spec: PredictionProduct) -> dict[str, Any]:
+        """Creates a dictionary from a product specification.
+
+        Parameters
+        ----------
+        product_spec : afp.schemas.PredictionProduct
+            The product specification.
+
+        Returns
+        -------
+        dict
+        """
+        return product_spec.model_dump()
+
+    def dump_json(self, product_spec: PredictionProduct) -> str:
+        """Creates a JSON string from a product specification.
+
+        The producted JSON is JSON Canonicalization Scheme (RFC 8785) compliant.
+
+        Parameters
+        ----------
+        product_spec : afp.schemas.PredictionProduct
+            The product specification.
+
+        Returns
+        -------
+        str
+        """
+        return product_spec.model_dump_canonical_json()
+
+    def id(self, product_spec: PredictionProduct) -> str:
+        """Generates the product ID for a product specification.
+
+        This is the ID that the product will get after successful registration.
+
+        Parameters
+        ----------
+        product_spec : afp.schemas.PredictionProduct
+            The product specification.
+
+        Returns
+        -------
+        str
+        """
+        return Web3.to_hex(
+            hashing.generate_product_id(
+                cast(ChecksumAddress, product_spec.product.base.metadata.builder),
+                product_spec.product.base.metadata.symbol,
+            )
         )
-        return self.create(**kwargs)
 
     ### Transactions ###
 
-    @convert_web3_error(PRODUCT_REGISTRY_ABI)
-    def register(self, product_specification: ProductSpecification) -> Transaction:
+    def pin(self, product_spec: PredictionProduct) -> PredictionProduct:
+        """Uploads the product's extended metadata to IPFS and pins the CID.
+
+        Adds the CID to the product specification and returns the modified specification
+        with the extended metadata CID included.
+
+        Parameters
+        ----------
+        product_spec : afp.schemas.PredictionProduct or afp.schemas.PredictionProductV1
+            The product specification.
+
+        Returns
+        -------
+        afp.schemas.PredictionProduct
+            The product specification with extended metadata CID included.
+
+        Raises
+        ------
+        afp.exceptions.IPFSError
+            If there is an error uploading to the IPFS node.
+        """
+        extended_metadata_cid = self._ipfs_client.upload_extended_metadata(
+            ExtendedMetadata(
+                outcome_space=product_spec.outcome_space,
+                outcome_point=product_spec.outcome_point,
+                oracle_config=product_spec.oracle_config,
+                oracle_fallback=product_spec.oracle_fallback,
+            )
+        )
+        updated_base_product = product_spec.product.base.model_copy(
+            update=dict(extended_metadata=extended_metadata_cid)
+        )
+        updated_product = product_spec.product.model_copy(
+            update=dict(base=updated_base_product)
+        )
+        return product_spec.model_copy(update=dict(product=updated_product))
+
+    @convert_web3_error(PRODUCT_REGISTRY_ABI, CLEARING_DIAMOND_ABI)
+    def register(
+        self, product_spec: PredictionProduct, initial_builder_stake: Decimal
+    ) -> Transaction:
         """Submits a product specification to the clearing system.
 
+        The extended metadata should already be pinned to IPFS and the CID should be
+        specified in the afp.schemas.BaseProduct object in the product specification.
+
         Parameters
         ----------
-        product_specification : afp.schemas.ProductSpecification
+        product_spec : afp.schemas.PredictionProduct or afp.schemas.PredictionProductV1
+            The product specification.
+        initial_builder_stake : Decimal
+            Registration stake (product maintenance fee) in units of the collateral
+            asset.
 
         Returns
         -------
         afp.schemas.Transaction
             Transaction parameters.
         """
+        if product_spec.product.base.extended_metadata is None:
+            raise ValidationError(
+                "Extended metadata CID missing from product specification"
+            )
+
         erc20_contract = ERC20(
-            self._w3, cast(ChecksumAddress, product_specification.collateral_asset)
+            self._w3, cast(ChecksumAddress, product_spec.product.base.collateral_asset)
         )
         decimals = erc20_contract.decimals()
 
@@ -151,20 +215,14 @@ class Product(ClearingSystemAPI):
             self._w3, self._config.product_registry_address
         )
         return self._transact(
-            product_registry_contract.register(
-                self._convert_product_specification(product_specification, decimals)
+            product_registry_contract.register_prediction_product(
+                self._convert_prediction_product_specification(
+                    product_spec.product, decimals
+                ),
+                int(initial_builder_stake * 10**decimals),
             )
         )
 
-    def register_product(self, product: ProductSpecification) -> Transaction:
-        """Deprecated alias of `Product.register`."""
-        warnings.warn(
-            "Product.register_product() is deprecated. Use Product.register() instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self.register(product)
-
     @convert_web3_error(CLEARING_DIAMOND_ABI)
     def initiate_final_settlement(
         self, product_id: str, accounts: list[str]
@@ -199,7 +257,49 @@ class Product(ClearingSystemAPI):
 
     ### Views ###
 
-    @convert_web3_error(PRODUCT_REGISTRY_ABI)
+    @convert_web3_error(PRODUCT_REGISTRY_ABI, CLEARING_DIAMOND_ABI)
+    def get(self, product_id: str) -> PredictionProduct:
+        """Retrieves a product registered on chain.
+
+        Parameters
+        ----------
+        product_id : str
+            The ID of the product.
+
+        Returns
+        -------
+        afp.schemas.PredictionProduct
+        """
+        product_id = validators.validate_hexstr32(product_id)
+
+        product_registry_contract = ProductRegistry(
+            self._w3, self._config.product_registry_address
+        )
+        # Note: when FuturesProductV1 support is added, call type_of(product_id) first
+        # to figure out which view function should be used
+        product = product_registry_contract.prediction_product_v1(HexBytes(product_id))
+
+        erc20_contract = ERC20(self._w3, product.base.collateral_asset)
+        decimals = erc20_contract.decimals()
+
+        product = self._convert_on_chain_prediction_product(product, decimals)
+        if product.base.extended_metadata is None:
+            raise ValidationError(
+                "Extended metadata CID missing from product specification"
+            )
+
+        extended_metadata = self._ipfs_client.download_extended_metadata(
+            product.base.extended_metadata
+        )
+        return PredictionProduct(
+            product=product,
+            outcome_space=extended_metadata.outcome_space,
+            outcome_point=extended_metadata.outcome_point,
+            oracle_config=extended_metadata.oracle_config,
+            oracle_fallback=extended_metadata.oracle_fallback,
+        )
+
+    @convert_web3_error(PRODUCT_REGISTRY_ABI, CLEARING_DIAMOND_ABI)
     def state(self, product_id: str) -> str:
         """Returns the current state of a product.
 
@@ -219,16 +319,7 @@ class Product(ClearingSystemAPI):
         state = product_registry_contract.state(HexBytes(product_id))
         return state.name
 
-    def product_state(self, product_id: str) -> str:
-        """Deprecated alias of `Product.state`."""
-        warnings.warn(
-            "Product.product_state() is deprecated. Use Product.state() instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self.state(product_id)
-
-    @convert_web3_error(PRODUCT_REGISTRY_ABI)
+    @convert_web3_error(PRODUCT_REGISTRY_ABI, CLEARING_DIAMOND_ABI)
     def collateral_asset(self, product_id: str) -> str:
         """Returns the collateral asset of a product.
 
@@ -254,38 +345,101 @@ class Product(ClearingSystemAPI):
 
     ### Internal helpers ###
 
+    def _verify_product_spec(
+        self, product_spec: PredictionProduct
+    ) -> PredictionProduct:
+        validators.verify_collateral_asset(
+            self._w3, product_spec.product.base.collateral_asset
+        )
+        validators.verify_oracle(
+            self._w3, product_spec.product.base.oracle_spec.oracle_address
+        )
+        return product_spec
+
     @staticmethod
-    def _convert_product_specification(
-        product: ProductSpecification, decimals: int
-    ) -> OnChainProduct:
-        return OnChainProduct(
-            metadata=ProductMetadata(
-                builder=cast(ChecksumAddress, product.builder_id),
-                symbol=product.symbol,
-                description=product.description,
-            ),
-            oracle_spec=OracleSpecification(
-                oracle_address=cast(ChecksumAddress, product.oracle_address),
-                fsv_decimals=product.fsv_decimals,
-                fsp_alpha=int(product.fsp_alpha * constants.FULL_PRECISION_MULTIPLIER),
-                fsp_beta=int(product.fsp_beta * 10**product.fsv_decimals),
-                fsv_calldata=HexBytes(product.fsv_calldata),
+    def _convert_prediction_product_specification(
+        product: PredictionProductV1, collateral_asset_decimals: int
+    ) -> OnChainPredictionProductV1:
+        assert product.base.extended_metadata is not None
+
+        return OnChainPredictionProductV1(
+            base=OnChainBaseProduct(
+                metadata=OnChainProductMetadata(
+                    builder=cast(ChecksumAddress, product.base.metadata.builder),
+                    symbol=product.base.metadata.symbol,
+                    description=product.base.metadata.description,
+                ),
+                oracle_spec=OnChainOracleSpecification(
+                    oracle_address=cast(
+                        ChecksumAddress, product.base.oracle_spec.oracle_address
+                    ),
+                    fsv_decimals=product.base.oracle_spec.fsv_decimals,
+                    fsp_alpha=int(
+                        product.base.oracle_spec.fsp_alpha
+                        * constants.FULL_PRECISION_MULTIPLIER
+                    ),
+                    fsp_beta=int(
+                        product.base.oracle_spec.fsp_beta
+                        * 10**product.base.oracle_spec.fsv_decimals
+                    ),
+                    fsv_calldata=HexBytes(product.base.oracle_spec.fsv_calldata),
+                ),
+                collateral_asset=cast(ChecksumAddress, product.base.collateral_asset),
+                start_time=int(product.base.start_time.timestamp()),
+                point_value=int(
+                    product.base.point_value * 10**collateral_asset_decimals
+                ),
+                price_decimals=product.base.price_decimals,
+                extended_metadata=product.base.extended_metadata,
             ),
-            price_quotation=product.price_quotation,
-            collateral_asset=cast(ChecksumAddress, product.collateral_asset),
-            start_time=int(product.start_time.timestamp()),
-            earliest_fsp_submission_time=int(
-                product.earliest_fsp_submission_time.timestamp()
+            expiry_spec=OnChainExpirySpecification(
+                earliest_fsp_submission_time=int(
+                    product.expiry_spec.earliest_fsp_submission_time.timestamp()
+                ),
+                tradeout_interval=product.expiry_spec.tradeout_interval,
             ),
-            tick_size=product.tick_size,
-            unit_value=int(product.unit_value * 10**decimals),
-            initial_margin_requirement=int(
-                product.initial_margin_requirement * constants.RATE_MULTIPLIER
+            max_price=int(product.max_price * 10**product.base.price_decimals),
+            min_price=int(product.min_price * 10**product.base.price_decimals),
+        )
+
+    @staticmethod
+    def _convert_on_chain_prediction_product(
+        product: OnChainPredictionProductV1, collateral_asset_decimals: int
+    ) -> PredictionProductV1:
+        return PredictionProductV1(
+            base=BaseProduct(
+                metadata=ProductMetadata(
+                    builder=product.base.metadata.builder,
+                    symbol=product.base.metadata.symbol,
+                    description=product.base.metadata.description,
+                ),
+                oracle_spec=OracleSpecification(
+                    oracle_address=product.base.oracle_spec.oracle_address,
+                    fsv_decimals=product.base.oracle_spec.fsv_decimals,
+                    fsp_alpha=(
+                        Decimal(product.base.oracle_spec.fsp_alpha)
+                        / constants.FULL_PRECISION_MULTIPLIER
+                    ),
+                    fsp_beta=(
+                        Decimal(product.base.oracle_spec.fsp_beta)
+                        / 10**product.base.oracle_spec.fsv_decimals
+                    ),
+                    fsv_calldata=product.base.oracle_spec.fsv_calldata.to_0x_hex(),
+                ),
+                collateral_asset=product.base.collateral_asset,
+                start_time=datetime.fromtimestamp(product.base.start_time),
+                point_value=(
+                    Decimal(product.base.point_value) / 10**collateral_asset_decimals
+                ),
+                price_decimals=product.base.price_decimals,
+                extended_metadata=product.base.extended_metadata,
             ),
-            maintenance_margin_requirement=int(
-                product.maintenance_margin_requirement * constants.RATE_MULTIPLIER
+            expiry_spec=ExpirySpecification(
+                earliest_fsp_submission_time=datetime.fromtimestamp(
+                    product.expiry_spec.earliest_fsp_submission_time
+                ),
+                tradeout_interval=product.expiry_spec.tradeout_interval,
             ),
-            auction_bounty=int(product.auction_bounty * constants.RATE_MULTIPLIER),
-            tradeout_interval=product.tradeout_interval,
-            extended_metadata=product.extended_metadata,
+            max_price=Decimal(product.max_price) / 10**product.base.price_decimals,
+            min_price=Decimal(product.min_price) / 10**product.base.price_decimals,
         )

afp/api/trading.py

@@ -1,28 +1,25 @@
 import secrets
-import warnings
 from datetime import datetime, timedelta
 from decimal import Decimal
 from typing import Generator, Iterable
 
 from web3 import Web3
+from web3.constants import CHECKSUM_ADDRESSS_ZERO
 
 from .. import hashing, validators
 from ..constants import DEFAULT_BATCH_SIZE
 from ..decorators import refresh_token_on_expiry
+from ..dtos import ExchangeProductFilter, OrderFilter, OrderFillFilter, OrderSubmission
 from ..enums import OrderSide, OrderState, OrderType, TradeState
 from ..schemas import (
     ExchangeProduct,
-    ExchangeProductFilter,
     Intent,
     IntentData,
     MarketDepthData,
     OHLCVItem,
     Order,
-    OrderFilter,
     OrderCancellationData,
     OrderFill,
-    OrderFillFilter,
-    OrderSubmission,
 )
 from .base import ExchangeAPI
 
@@ -44,6 +41,7 @@ class Trading(ExchangeAPI):
         max_trading_fee_rate: Decimal,
         good_until_time: datetime,
         margin_account_id: str | None = None,
+        referral: str | None = None,
         rounding: str | None = None,
     ) -> Intent:
         """Creates an intent with the given intent data, generates its hash and signs it
@@ -70,6 +68,7 @@ class Trading(ExchangeAPI):
         max_trading_fee_rate : decimal.Decimal
         good_until_time : datetime.datetime
         margin_account_id : str, optional
+        referral : str, optional
         rounding : str, optional
             A rounding mode of the `decimal` module or `None` for no rounding.
 
@@ -87,13 +86,18 @@ class Trading(ExchangeAPI):
             trading_protocol_id=self._trading_protocol_id,
             product_id=product.id,
             limit_price=validators.validate_limit_price(
-                Decimal(limit_price), product.tick_size, rounding
+                Decimal(limit_price),
+                product.min_price,
+                product.max_price,
+                product.tick_size,
+                rounding,
             ),
             quantity=quantity,
             max_trading_fee_rate=max_trading_fee_rate,
             side=OrderSide(side.upper()),
             good_until_time=good_until_time,
             nonce=self._generate_nonce(),
+            referral=(referral if referral is not None else CHECKSUM_ADDRESSS_ZERO),
         )
         intent_hash = hashing.generate_intent_hash(
             intent_data=intent_data,
@@ -124,8 +128,9 @@ class Trading(ExchangeAPI):
 
         Raises
         ------
-        afp.exceptions.ValidationError
-            If the exchange rejects the intent.
+        afp.exceptions.RateLimitExceeded
+            If the exchange rejects the order because of too many requests from the
+            authenticated account.
         """
         submission = OrderSubmission(
             type=OrderType.LIMIT_ORDER,
@@ -147,8 +152,13 @@ class Trading(ExchangeAPI):
 
         Raises
         ------
+        afp.exceptions.NotFoundError
+            If the exchange rejects the cancellation because the intent does not exist.
+        afp.exceptions.RateLimitExceeded
+            If the exchange rejects the cancellation because of too many requests from
+            the authenticated account.
         afp.exceptions.ValidationError
-            If the exchange rejects the cancellation.
+            If the exchange rejects the cancellation because it is invalid.
         """
         nonce = self._generate_nonce()
         cancellation_hash = hashing.generate_order_cancellation_hash(nonce, intent_hash)
@@ -295,19 +305,6 @@ class Trading(ExchangeAPI):
         )
         return self._exchange.get_orders(filter)
 
-    @refresh_token_on_expiry
-    def open_orders(self, product_id: str | None = None) -> list[Order]:
-        """Deprecated alias of Trading.orders(type_="LIMIT_ORDER", states=("OPEN", "PARTIAL"))."""
-        warnings.warn(
-            "Trading.open_orders() is deprecated. Use "
-            'Trading.orders(type_="LIMIT_ORDER", states=("OPEN", "PARTIAL")) instead.',
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self.orders(
-            type_="limit_order", states=("open", "partial"), product_id=product_id
-        )
-
     @refresh_token_on_expiry
     def order_fills(
         self,

afp/auth.py

@@ -9,6 +9,7 @@ from eth_account.signers.local import LocalAccount
 from eth_account.types import TransactionDictType
 from eth_typing.evm import ChecksumAddress
 from hexbytes import HexBytes
+from web3.constants import CHECKSUM_ADDRESSS_ZERO
 from web3.types import TxParams
 
 
@@ -20,6 +21,19 @@ class Authenticator(Protocol):
     def sign_transaction(self, params: TxParams) -> SignedTransaction: ...
 
 
+class NullAuthenticator(Authenticator):
+    """Authenticator stub as placeholder for testing."""
+
+    def __init__(self):
+        self.address = CHECKSUM_ADDRESSS_ZERO
+
+    def sign_message(self, message: bytes) -> HexBytes:
+        raise NotImplementedError()
+
+    def sign_transaction(self, params: TxParams) -> SignedTransaction:
+        raise NotImplementedError()
+
+
 class PrivateKeyAuthenticator(Authenticator):
     """Authenticates with a private key specified in a constructor argument.