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

afp/bindings/types.py

@@ -0,0 +1,223 @@
+import enum
+import typing
+from dataclasses import dataclass
+
+import eth_typing
+import hexbytes
+
+
+class Side(enum.IntEnum):
+    """Port of `enum Side` on the ClearingFacet contract."""
+
+    BID = 0
+    ASK = 1
+
+
+class ProductState(enum.IntEnum):
+    """Port of `enum ProductState` on the ProductRegistry contract."""
+
+    NOT_EXIST = 0
+    PENDING = 1
+    LIVE = 2
+    TRADEOUT = 3
+    FINAL_SETTLEMENT = 4
+    EXPIRED = 5
+
+
+@dataclass
+class ClearingConfig:
+    """Port of `struct ClearingConfig` on the AdminFacet contract."""
+
+    clearing_fee_rate: int
+    max_trading_fee_rate: int
+
+
+@dataclass
+class MarkPriceConfig:
+    """Port of `struct MarkPriceConfig` on the AdminFacet contract."""
+
+    mark_price_interval: int
+
+
+@dataclass
+class FinalSettlementConfig:
+    """Port of `struct FinalSettlementConfig` on the AdminFacet contract."""
+
+    closeout_fee_rate: int
+    closeout_reward_rate: int
+
+
+@dataclass
+class ProductConfig:
+    """Port of `struct ProductConfig` on the AdminFacet contract."""
+
+    clearing_payout_ratio: int
+    maintenance_deposit_interval: int
+    min_product_maintenance_fee: int
+
+
+@dataclass
+class Config:
+    """Port of `struct Config` on the AdminFacet contract."""
+
+    clearing_config: ClearingConfig
+    mark_price_config: MarkPriceConfig
+    final_settlement_config: FinalSettlementConfig
+    product_config: ProductConfig
+
+
+@dataclass
+class IntentData:
+    """Port of `struct IntentData` on the ClearingFacet contract."""
+
+    nonce: int
+    trading_protocol_id: eth_typing.ChecksumAddress
+    product_id: hexbytes.HexBytes
+    limit_price: int
+    quantity: int
+    max_trading_fee_rate: int
+    good_until: int
+    side: Side
+    referral: eth_typing.ChecksumAddress
+
+
+@dataclass
+class Intent:
+    """Port of `struct Intent` on the ClearingFacet contract."""
+
+    margin_account_id: eth_typing.ChecksumAddress
+    intent_account_id: eth_typing.ChecksumAddress
+    hash: hexbytes.HexBytes
+    data: IntentData
+    signature: hexbytes.HexBytes
+
+
+@dataclass
+class Trade:
+    """Port of `struct Trade` on the ClearingFacet contract."""
+
+    product_id: hexbytes.HexBytes
+    protocol_id: eth_typing.ChecksumAddress
+    trade_id: int
+    price: int
+    timestamp: int
+    quantity: int
+    accounts: typing.List[eth_typing.ChecksumAddress]
+    quantities: typing.List[int]
+    fee_rates: typing.List[int]
+    intents: typing.List[Intent]
+
+
+@dataclass
+class Settlement:
+    """Port of `struct Settlement` on the MarginAccountFacet contract."""
+
+    product_id: hexbytes.HexBytes
+    quantity: int
+    price: int
+
+
+@dataclass
+class MarginData:
+    """Port of `struct MarginData` on the IMarginAccountFacet contract."""
+
+    capital: int
+    mae: int
+    mmu: int
+    pnl: int
+
+
+@dataclass
+class PositionData:
+    """Port of `struct PositionData` on the MarginAccountFacet contract."""
+
+    product_id: hexbytes.HexBytes
+    quantity: int
+    cost_basis: int
+    maintenance_margin: int
+    pnl: int
+
+
+@dataclass
+class ExpirySpecification:
+    """Port of `struct ExpirySpecification` on the ProductRegistryFacet contract."""
+
+    earliest_fsp_submission_time: int
+    tradeout_interval: int
+
+
+@dataclass
+class PendingStakeData:
+    """Port of `struct PendingStakeData` on the ProductRegistry contract."""
+
+    payout: int
+    active_at: int
+
+
+@dataclass
+class BuilderStakeData:
+    """Port of `struct BuilderStakeData` on the ProductRegistry contract."""
+
+    payout_remaining: int
+    claimable_rewards: int
+    pending_stake_data: PendingStakeData
+
+
+@dataclass
+class ProductMetadata:
+    """Port of `struct ProductMetadata` on the ProductRegistryFacet contract."""
+
+    builder: eth_typing.ChecksumAddress
+    symbol: str
+    description: str
+
+
+@dataclass
+class OracleSpecification:
+    """Port of `struct OracleSpecification` on the ProductRegistryFacet contract."""
+
+    oracle_address: eth_typing.ChecksumAddress
+    fsv_decimals: int
+    fsp_alpha: int
+    fsp_beta: int
+    fsv_calldata: hexbytes.HexBytes
+
+
+@dataclass
+class BaseProduct:
+    """Port of `struct BaseProduct` on the ProductRegistryFacet contract."""
+
+    metadata: ProductMetadata
+    oracle_spec: OracleSpecification
+    collateral_asset: eth_typing.ChecksumAddress
+    start_time: int
+    point_value: int
+    price_decimals: int
+    extended_metadata: str
+
+
+@dataclass
+class MarginSpecification:
+    """Port of `struct MarginSpecification` on the ProductRegistryFacet contract."""
+
+    imr: int
+    mmr: int
+
+
+@dataclass
+class FuturesProductV1:
+    """Port of `struct FuturesProductV1` on the ProductRegistryFacet contract."""
+
+    base: BaseProduct
+    expiry_spec: ExpirySpecification
+    margin_spec: MarginSpecification
+
+
+@dataclass
+class PredictionProductV1:
+    """Port of `struct PredictionProductV1` on the ProductRegistryFacet contract."""
+
+    base: BaseProduct
+    expiry_spec: ExpirySpecification
+    max_price: int
+    min_price: int

afp/config.py

@@ -9,6 +9,10 @@ from .auth import Authenticator
 class Config:
     authenticator: Authenticator | None
 
+    # IPFS client parameters
+    ipfs_api_url: str
+    ipfs_api_key: str | None
+
     # Venue parameters
     exchange_url: str
 

afp/constants.py

@@ -1,4 +1,5 @@
 import os
+from datetime import timedelta
 from importlib import metadata
 from types import SimpleNamespace
 
@@ -17,6 +18,45 @@ RATE_MULTIPLIER = 10**4
 FEE_RATE_MULTIPLIER = 10**6
 FULL_PRECISION_MULTIPLIER = 10**18
 
+# IPFS client constants
+IPFS_CID_ENCODING = "base32"
+IPFS_REQUEST_TIMEOUT = 30
+JSON_SCHEMAS_DIRECTORY = os.path.join(os.path.dirname(__file__), "json-schemas")
+
+# Product schema constants
+MINIMUM_ORACLE_FALLBACK_INTERVAL = timedelta(days=7)
+MONTH_CODES = {
+    "F": 1,
+    "G": 2,
+    "H": 3,
+    "J": 4,
+    "K": 5,
+    "M": 6,
+    "N": 7,
+    "Q": 8,
+    "U": 9,
+    "V": 10,
+    "X": 11,
+    "Z": 12,
+}
+
+schema_cids = SimpleNamespace(
+    # afp-product-schemas v0.2.0
+    ORACLE_CONFIG_V020="bafyreifcec2km7hxwq6oqzjlspni2mgipetjb7pqtaewh2efislzoctboi",
+    ORACLE_CONFIG_PROTOTYPE1_V020="bafyreiaw34o6l3rmatabzbds2i2myazdw2yolevcpsoyd2i2g3ms7wa2eq",
+    ORACLE_FALLBACK_V020="bafyreicgr6dfo5yduixjkcifghiulskfegwojvuwodtouvivl362zndhxe",
+    OUTCOME_POINT_V020="bafyreibnfg6nq74dvpkre5rakkccij7iadp5rxpim7omsatjnrpmj3y7v4",
+    OUTCOME_POINT_EVENT_V020="bafyreihur3dzwhja6uxsbcw6eeoj3xmmc4e3zkmyzpot5v5dleevxe5zam",
+    OUTCOME_POINT_TIME_SERIES_V020=(
+        "bafyreidzs7okcpqiss6ztftltyptqwnw5e5opsy5yntospekjha4kpykaa"
+    ),
+    OUTCOME_SPACE_V020="bafyreicheoypx6synljushh7mq2572iyhlolf4nake2p5dwobgnj3r5eua",
+    OUTCOME_SPACE_SCALAR_V020="bafyreihn3oiaxffe4e2w7pwtreadpw3obfd7gqlogbcxm56jc2hzfvco74",
+    OUTCOME_SPACE_TIME_SERIES_V020=(
+        "bafyreid35a67db4sqh4fs6boddyt2xvscbqy6nqvsp5jjur56qhkw4ixre"
+    ),
+)
+
 defaults = SimpleNamespace(
     # Authentication parameters
     KEYFILE=os.getenv("AFP_KEYFILE", None),
@@ -24,8 +64,11 @@ defaults = SimpleNamespace(
     PRIVATE_KEY=os.getenv("AFP_PRIVATE_KEY", None),
     # Venue parameters
     EXCHANGE_URL=os.getenv(
-        "AFP_EXCHANGE_URL", "https://afp-exchange-stable.up.railway.app"
+        "AFP_EXCHANGE_URL", "https://afp-exchange-stable.up.railway.app/"
     ),
+    # IPFS client parameters
+    IPFS_API_URL=os.getenv("AFP_IPFS_API_URL", "http://localhost:5001"),
+    IPFS_API_KEY=os.getenv("AFP_IPFS_API_KEY", None),
     # Blockchain parameters
     RPC_URL=os.getenv("AFP_RPC_URL", None),
     CHAIN_ID=int(os.getenv("AFP_CHAIN_ID", 65000000)),
@@ -37,19 +80,19 @@ defaults = SimpleNamespace(
     TIMEOUT_SECONDS=int(os.getenv("AFP_TIMEOUT_SECONDS", 10)),
     # Clearing System parameters
     CLEARING_DIAMOND_ADDRESS=os.getenv(
-        "AFP_CLEARING_DIAMOND_ADDRESS", "0x5B5411F1548254d25360d71FE40cFc1cC983B2A2"
+        "AFP_CLEARING_DIAMOND_ADDRESS", "0x08e725d38BCABCf62806E84bE044dF67E8b476Ae"
     ),
     MARGIN_ACCOUNT_REGISTRY_ADDRESS=os.getenv(
         "AFP_MARGIN_ACCOUNT_REGISTRY_ADDRESS",
-        "0x99f4FA9Cdce7AD227eB84907936a8FeF2095D846",
+        "0x1FAa342Ea34332ee1186FE48f03894F70F7fFc4f",
     ),
     ORACLE_PROVIDER_ADDRESS=os.getenv(
-        "AFP_ORACLE_PROVIDER_ADDRESS", "0xF2A2A27da33D30B4BF38D7e186E7B0b1e964e55c"
+        "AFP_ORACLE_PROVIDER_ADDRESS", "0x06CaDDDf6CC08048596aE051c8ce644725219C73"
     ),
     PRODUCT_REGISTRY_ADDRESS=os.getenv(
-        "AFP_PRODUCT_REGISTRY_ADDRESS", "0x86B3829471929B115367DA0958f56A6AB844b08e"
+        "AFP_PRODUCT_REGISTRY_ADDRESS", "0xB605fc6B76eA4592CaA3AEd26EFd3edbAc5A3A24"
     ),
     SYSTEM_VIEWER_ADDRESS=os.getenv(
-        "AFP_SYSTEM_VIEWER_ADDRESS", "0xfF2DFcC44a95cce96E03EfC33C65c8Be671Bae5B"
+        "AFP_SYSTEM_VIEWER_ADDRESS", "0xBeC22149650CcaC2a1233c7b489aFF3ea24df36d"
     ),
 )

afp/decorators.py

@@ -1,10 +1,12 @@
 from collections.abc import Callable
 from itertools import chain
-from typing import Any
+from typing import Any, cast
 
 import inflection
 from decorator import decorator
-from eth_typing.abi import ABI
+from eth_abi.exceptions import InsufficientDataBytes
+from eth_typing.abi import ABI, ABIError, ABIFunction
+from eth_typing.encoding import HexStr
 from eth_utils import abi
 from hexbytes import HexBytes
 from web3.exceptions import (
@@ -13,6 +15,7 @@ from web3.exceptions import (
     Web3Exception,
     Web3RPCError,
 )
+from web3._utils import contracts, normalizers
 
 from .api.base import ExchangeAPI
 from .exceptions import ClearingSystemError, AuthenticationError
@@ -71,6 +74,25 @@ def _decode_custom_error(data: str, *contract_abis: ABI) -> str | None:
         selector_candidate = abi.function_signature_to_4byte_selector(signature)
         if selector == selector_candidate:
             error = error_candidate["name"]
+            args = _decode_transaction_args(error_candidate, data)
             # Convert 'ErrorType' to 'Error type'
-            return inflection.humanize(inflection.underscore(error))
+            error = inflection.humanize(inflection.underscore(error))
+            if args:
+                error += ": " + ", ".join(f"{key}='{val}'" for key, val in args.items())
+            return error
     return None
+
+
+def _decode_transaction_args(error_abi: ABIError, data: str) -> dict[str, str]:
+    try:
+        args = contracts.decode_transaction_data(  # type: ignore
+            cast(ABIFunction, error_abi),
+            cast(HexStr, data),
+            normalizers=normalizers.BASE_RETURN_NORMALIZERS,  # type: ignore
+        )
+    except InsufficientDataBytes:
+        return {}
+    return {
+        key: HexBytes(val).to_0x_hex() if isinstance(val, bytes) else str(val)
+        for key, val in args.items()
+    }

afp/dtos.py

@@ -0,0 +1,142 @@
+"""Internal schemas."""
+
+from decimal import Decimal
+from typing import Annotated, Literal
+
+from pydantic import AfterValidator, ConfigDict, Field, computed_field
+
+from . import validators
+from .enums import ListingState, OrderSide, OrderState, OrderType, TradeState
+from .schemas import (
+    Intent,
+    OracleConfig,
+    OracleConfigPrototype1,
+    OracleFallback,
+    OrderCancellationData,
+    OutcomePoint,
+    OutcomePointEvent,
+    OutcomePointTimeSeries,
+    OutcomeSpace,
+    OutcomeSpaceScalar,
+    OutcomeSpaceTimeSeries,
+    Timestamp,
+)
+from .types import IPLD_LINK, AliasedModel, Model
+
+
+class PaginationFilter(Model):
+    batch: Annotated[None | int, Field(gt=0, exclude=True)]
+    batch_size: Annotated[None | int, Field(gt=0, exclude=True)]
+    newest_first: Annotated[None | bool, Field(exclude=True)]
+
+    @computed_field
+    @property
+    def page(self) -> None | int:
+        return self.batch
+
+    @computed_field
+    @property
+    def page_size(self) -> None | int:
+        return self.batch_size
+
+    @computed_field
+    @property
+    def sort(self) -> None | Literal["ASC", "DESC"]:
+        match self.newest_first:
+            case None:
+                return None
+            case True:
+                return "DESC"
+            case False:
+                return "ASC"
+
+
+# Authentication
+
+
+class LoginSubmission(AliasedModel):
+    message: str
+    signature: str
+
+
+class ExchangeParameters(AliasedModel):
+    trading_protocol_id: str
+    maker_trading_fee_rate: Decimal
+    taker_trading_fee_rate: Decimal
+
+
+# Admin API
+
+
+class ExchangeProductListingSubmission(AliasedModel):
+    id: Annotated[str, AfterValidator(validators.validate_hexstr32)]
+
+
+class ExchangeProductUpdateSubmission(AliasedModel):
+    listing_state: ListingState
+
+
+# Trading API
+
+
+class ExchangeProductFilter(PaginationFilter):
+    pass
+
+
+class OrderFilter(PaginationFilter):
+    intent_account_id: str
+    product_id: None | Annotated[str, AfterValidator(validators.validate_hexstr32)]
+    type: None | OrderType
+    states: Annotated[list[OrderState], Field(exclude=True)]
+    side: None | OrderSide
+    start: None | Timestamp
+    end: None | Timestamp
+
+    @computed_field
+    @property
+    def state(self) -> str | None:
+        return ",".join(self.states) if self.states else None
+
+
+class OrderSubmission(AliasedModel):
+    type: OrderType
+    intent: Intent | None = None
+    cancellation_data: OrderCancellationData | None = None
+
+
+class OrderFillFilter(PaginationFilter):
+    intent_account_id: str
+    product_id: None | Annotated[str, AfterValidator(validators.validate_hexstr32)]
+    intent_hash: None | Annotated[str, AfterValidator(validators.validate_hexstr32)]
+    start: None | Timestamp
+    end: None | Timestamp
+    trade_states: Annotated[list[TradeState], Field(exclude=True)]
+
+    @computed_field
+    @property
+    def trade_state(self) -> str | None:
+        return ",".join(self.trade_states) if self.trade_states else None
+
+
+# IPFS Client
+
+
+class ExtendedMetadata(Model):
+    outcome_space: OutcomeSpaceTimeSeries | OutcomeSpaceScalar | OutcomeSpace
+    outcome_point: OutcomePointEvent | OutcomePointTimeSeries | OutcomePoint
+    oracle_config: OracleConfigPrototype1 | OracleConfig
+    oracle_fallback: OracleFallback
+
+
+class ComponentLink(AliasedModel):
+    model_config = AliasedModel.model_config | ConfigDict(arbitrary_types_allowed=True)
+
+    data: IPLD_LINK
+    schema_: Annotated[IPLD_LINK, Field(alias="schema")]
+
+
+class ExtendedMetadataDAG(Model):
+    outcome_space: ComponentLink
+    outcome_point: ComponentLink
+    oracle_config: ComponentLink
+    oracle_fallback: ComponentLink

afp/exceptions.py

@@ -2,6 +2,9 @@ class AFPException(Exception):
     pass
 
 
+# API-specific exceptions
+
+
 class ConfigurationError(AFPException):
     pass
 
@@ -10,10 +13,17 @@ class ClearingSystemError(AFPException):
     pass
 
 
+class IPFSError(AFPException):
+    pass
+
+
 class ExchangeError(AFPException):
     pass
 
 
+# Exchange error sub-types
+
+
 class AuthenticationError(ExchangeError):
     pass
 

afp/exchange.py

@@ -6,6 +6,16 @@ import requests
 from requests import Response, Session
 
 from . import constants
+from .dtos import (
+    ExchangeParameters,
+    ExchangeProductFilter,
+    ExchangeProductListingSubmission,
+    ExchangeProductUpdateSubmission,
+    LoginSubmission,
+    OrderFilter,
+    OrderFillFilter,
+    OrderSubmission,
+)
 from .exceptions import (
     AuthenticationError,
     AuthorizationError,
@@ -15,19 +25,11 @@ from .exceptions import (
     ValidationError,
 )
 from .schemas import (
-    ExchangeParameters,
     ExchangeProduct,
-    ExchangeProductFilter,
-    ExchangeProductListingSubmission,
-    ExchangeProductUpdateSubmission,
-    LoginSubmission,
     MarketDepthData,
     OHLCVItem,
     Order,
-    OrderFilter,
     OrderFill,
-    OrderFillFilter,
-    OrderSubmission,
 )
 
 

afp/hashing.py

@@ -6,13 +6,13 @@ from hexbytes import HexBytes
 from web3 import Web3
 
 from . import constants
-from .bindings import clearing_facet
+from .bindings import Side as OnChainSide
 from .schemas import IntentData, OrderSide
 
 
 ORDER_SIDE_MAPPING: dict[OrderSide, int] = {
-    OrderSide.BID: clearing_facet.Side.BID.value,
-    OrderSide.ASK: clearing_facet.Side.ASK.value,
+    OrderSide.BID: OnChainSide.BID.value,
+    OrderSide.ASK: OnChainSide.ASK.value,
 }
 
 
@@ -28,11 +28,12 @@ def generate_intent_hash(
         "uint256",  # nonce
         "address",  # trading_protocol_id
         "bytes32",  # product_id
-        "uint256",  # limit_price
+        "int256",  # limit_price
         "uint256",  # quantity
-        "uint256",  # max_trading_fee_rate
+        "uint32",  # max_trading_fee_rate
         "uint256",  # good_until_time
         "uint8",  # side
+        "address",  # referral
     ]
     values: list[Any] = [
         margin_account_id,
@@ -45,6 +46,7 @@ def generate_intent_hash(
         int(intent_data.max_trading_fee_rate * constants.FEE_RATE_MULTIPLIER),
         int(intent_data.good_until_time.timestamp()),
         ORDER_SIDE_MAPPING[intent_data.side],
+        cast(ChecksumAddress, intent_data.referral),
     ]
     return Web3.keccak(encode_packed(types, values))