afp-sdk 0.1.0__py3-none-any.whl

afp/config.py

@@ -0,0 +1,38 @@
+import os
+
+from web3 import Web3
+
+
+# Constants from clearing/contracts/lib/constants.sol
+RATE_MULTIPLIER = 10**4
+FEE_RATE_MULTIPLIER = 10**6
+FULL_PRECISION_MULTIPLIER = 10**18
+
+USER_AGENT = "afp-sdk"
+EXCHANGE_URL = os.getenv(
+    "AFP_EXCHANGE_URL", "https://afp-exchange-staging.up.railway.app"
+)
+
+CHAIN_ID = int(os.getenv("AFP_CHAIN_ID", 65010004))
+
+CLEARING_DIAMOND_ADDRESS = Web3.to_checksum_address(
+    os.getenv(
+        "AFP_CLEARING_DIAMOND_ADDRESS", "0xB894bFf368Bf1EA89c18612670B7E072866a5264"
+    )
+)
+MARGIN_ACCOUNT_REGISTRY_ADDRESS = Web3.to_checksum_address(
+    os.getenv(
+        "AFP_MARGIN_ACCOUNT_REGISTRY_ADDRESS",
+        "0xDA71FdE0E7cfFf445e848EAdB3B2255B68Ed6ef6",
+    )
+)
+ORACLE_PROVIDER_ADDRESS = Web3.to_checksum_address(
+    os.getenv(
+        "AFP_ORACLE_PROVIDER_ADDRESS", "0x626da921088a5A00C75C208Decbb60E816488481"
+    )
+)
+PRODUCT_REGISTRY_ADDRESS = Web3.to_checksum_address(
+    os.getenv(
+        "AFP_PRODUCT_REGISTRY_ADDRESS", "0x9b92EAC112c996a513e515Cf8c3BDd83619F730D"
+    )
+)

afp/decorators.py

@@ -0,0 +1,74 @@
+from collections.abc import Callable
+from itertools import chain
+from typing import Any
+
+import inflection
+from decorator import decorator
+from eth_typing.abi import ABI
+from eth_utils import abi
+from hexbytes import HexBytes
+from web3.exceptions import (
+    ContractLogicError,
+    ContractCustomError,
+    Web3Exception,
+    Web3RPCError,
+)
+
+from .api.base import ExchangeAPI
+from .exceptions import ClearingSystemError, AuthenticationError
+
+
+@decorator
+def refresh_token_on_expiry(
+    f: Callable[..., Any], *args: Any, **kwargs: Any
+) -> Callable[..., Any]:
+    exchange_api = args[0]
+    assert isinstance(exchange_api, ExchangeAPI)
+    try:
+        return f(*args, **kwargs)
+    except AuthenticationError:
+        exchange_api._login()  # type: ignore
+        return f(*args, **kwargs)
+
+
+def convert_web3_error(*contract_abis: ABI) -> Callable[..., Any]:
+    def caller(f: Callable[..., Any], *args: Any, **kwargs: Any) -> Callable[..., Any]:
+        try:
+            return f(*args, **kwargs)
+        except ContractLogicError as contract_error:
+            reason = None
+            if contract_error.data:
+                reason = str(contract_error.data)
+                if isinstance(contract_error, ContractCustomError):
+                    reason = _decode_custom_error(
+                        str(contract_error.data), *contract_abis
+                    )
+                if reason == "no data":
+                    reason = "Unspecified reason"
+            raise ClearingSystemError(
+                "Contract call reverted" + f": {reason}" if reason else ""
+            ) from contract_error
+        except Web3RPCError as rpc_error:
+            reason = None
+            if rpc_error.rpc_response:
+                reason = rpc_error.rpc_response.get("error", {}).get("message")
+            raise ClearingSystemError(
+                "Blockchain returned error" + f": {reason}" if reason else ""
+            ) from rpc_error
+        except Web3Exception as web3_exception:
+            raise ClearingSystemError(str(web3_exception)) from web3_exception
+
+    return decorator(caller)
+
+
+def _decode_custom_error(data: str, *contract_abis: ABI) -> str | None:
+    selector = HexBytes(data)[:4]
+    combined_abi = list(chain(*contract_abis))
+    for error_candidate in abi.filter_abi_by_type("error", combined_abi):
+        signature = abi.abi_to_signature(error_candidate)
+        selector_candidate = abi.function_signature_to_4byte_selector(signature)
+        if selector == selector_candidate:
+            error = error_candidate["name"]
+            # Convert 'ErrorType' to 'Error type'
+            return inflection.humanize(inflection.underscore(error))
+    return None

afp/enums.py

@@ -0,0 +1,27 @@
+from enum import StrEnum
+
+
+class OrderType(StrEnum):
+    LIMIT_ORDER = "LIMIT_ORDER"
+    CANCEL_ORDER = "CANCEL_ORDER"
+
+
+class OrderState(StrEnum):
+    RECEIVED = "RECEIVED"
+    PENDING = "PENDING"
+    OPEN = "OPEN"
+    PARTIAL = "PARTIAL"
+    COMPLETED = "COMPLETED"
+    CANCELLED = "CANCELLED"
+    REJECTED = "REJECTED"
+
+
+class OrderSide(StrEnum):
+    BID = "BID"
+    ASK = "ASK"
+
+
+class TradeState(StrEnum):
+    PENDING = "PENDING"
+    CLEARED = "CLEARED"
+    REJECTED = "REJECTED"

afp/exceptions.py

@@ -0,0 +1,26 @@
+class BaseException(Exception):
+    pass
+
+
+class ClearingSystemError(BaseException):
+    pass
+
+
+class ExchangeError(BaseException):
+    pass
+
+
+class AuthenticationError(ExchangeError):
+    pass
+
+
+class AuthorizationError(ExchangeError):
+    pass
+
+
+class NotFoundError(ExchangeError):
+    pass
+
+
+class ValidationError(ExchangeError):
+    pass

afp/exchange.py

@@ -0,0 +1,151 @@
+import json
+from typing import Any, Generator
+
+import requests
+from requests import Response, Session
+
+from . import config
+from .exceptions import (
+    AuthenticationError,
+    AuthorizationError,
+    ExchangeError,
+    NotFoundError,
+    ValidationError,
+)
+from .schemas import (
+    ExchangeParameters,
+    ExchangeProduct,
+    ExchangeProductSubmission,
+    LoginSubmission,
+    MarketDepthData,
+    Order,
+    OrderFill,
+    OrderFillFilter,
+    OrderSubmission,
+)
+
+
+class ExchangeClient:
+    _session: Session
+
+    def __init__(self):
+        self._session = Session()
+
+    # POST /nonce
+    def generate_login_nonce(self) -> str:
+        response = self._send_request("GET", "/nonce")
+        return response.json()["message"]
+
+    # POST /login
+    def login(self, login_submission: LoginSubmission) -> ExchangeParameters:
+        response = self._send_request(
+            "POST", "/login", data=login_submission.model_dump_json()
+        )
+        return ExchangeParameters(**response.json())
+
+    # GET /products
+    def get_approved_products(self) -> list[ExchangeProduct]:
+        response = self._send_request("GET", "/products")
+        return [ExchangeProduct(**item) for item in response.json()["products"]]
+
+    # GET /products/{product_id}
+    def get_product_by_id(self, product_id: str) -> ExchangeProduct:
+        response = self._send_request("GET", f"/products/{product_id}")
+        return ExchangeProduct(**response.json())
+
+    # POST /products
+    def approve_product(self, product_submission: ExchangeProductSubmission) -> None:
+        self._send_request(
+            "POST", "/products", data=product_submission.model_dump_json()
+        )
+
+    # DELETE /products
+    def delist_product(self, product_id: str) -> None:
+        self._send_request("DELETE", f"/products/{product_id}")
+
+    # POST /orders
+    def submit_order(self, order_submission: OrderSubmission) -> Order:
+        response = self._send_request(
+            "POST", "/orders", data=order_submission.model_dump_json()
+        )
+        return Order(**response.json())
+
+    # GET /orders
+    def get_open_orders(self) -> list[Order]:
+        response = self._send_request("GET", "/orders")
+        return [Order(**item) for item in response.json()["orders"]]
+
+    # GET /orders/{order_id}
+    def get_order_by_id(self, order_id: str) -> Order:
+        response = self._send_request("GET", f"/orders/{order_id}")
+        return Order(**response.json())
+
+    # GET /order-fills
+    def get_order_fills(self, filter: OrderFillFilter) -> list[OrderFill]:
+        response = self._send_request(
+            "GET", "/order-fills", params=filter.model_dump(exclude_none=True)
+        )
+        return [OrderFill(**item) for item in response.json()["orderFills"]]
+
+    # GET /stream/order-fills
+    def iter_order_fills(
+        self, filter: OrderFillFilter
+    ) -> Generator[OrderFill, None, None]:
+        response = self._send_request(
+            "GET",
+            "/stream/order-fills",
+            params=filter.model_dump(exclude_none=True),
+            stream=True,
+        )
+        for line in response.iter_lines():
+            yield OrderFill.model_validate_json(line)
+
+    # GET /market-depth/{product_id}
+    def get_market_depth_data(self, product_id: str) -> MarketDepthData:
+        response = self._send_request("GET", f"/market-depth/{product_id}")
+        return MarketDepthData(**response.json())
+
+    # GET /stream/market-depth/{product_id}
+    def iter_market_depth_data(
+        self, product_id: str
+    ) -> Generator[MarketDepthData, None, None]:
+        response = self._send_request(
+            "GET", f"/stream/market-depth/{product_id}", stream=True
+        )
+        for line in response.iter_lines():
+            yield MarketDepthData.model_validate_json(line)
+
+    def _send_request(
+        self, method: str, endpoint: str, stream: bool = False, **kwargs: Any
+    ) -> Response:
+        kwargs["headers"] = {
+            "Content-Type": "application/json",
+            "Accept": "application/x-ndjson" if stream else "application/json",
+            "User-Agent": config.USER_AGENT,
+        }
+
+        try:
+            response = self._session.request(
+                method, f"{config.EXCHANGE_URL}{endpoint}", stream=stream, **kwargs
+            )
+        except requests.exceptions.RequestException as request_exception:
+            raise ExchangeError(
+                "Failed to send request to the exchange"
+            ) from request_exception
+        try:
+            response.raise_for_status()
+        except requests.exceptions.HTTPError as http_error:
+            if http_error.response.status_code == requests.codes.UNAUTHORIZED:
+                raise AuthenticationError(http_error) from http_error
+            if http_error.response.status_code == requests.codes.FORBIDDEN:
+                raise AuthorizationError(http_error) from http_error
+            if http_error.response.status_code == requests.codes.NOT_FOUND:
+                raise NotFoundError(http_error) from http_error
+
+            try:
+                reason = response.json()["detail"]
+            except (json.JSONDecodeError, KeyError):
+                reason = response.text
+            raise ValidationError(reason) from http_error
+
+        return response

afp/schemas.py

@@ -0,0 +1,207 @@
+from datetime import datetime
+from decimal import Decimal
+from functools import partial
+from typing import Annotated, Any
+
+import inflection
+from pydantic import (
+    AfterValidator,
+    AliasGenerator,
+    BaseModel,
+    BeforeValidator,
+    ConfigDict,
+    Field,
+    PlainSerializer,
+)
+
+from . import validators
+from .enums import OrderSide, OrderState, OrderType, TradeState
+
+
+# Use datetime internally but UNIX timestamp in client-server communication
+Timestamp = Annotated[
+    datetime,
+    BeforeValidator(validators.ensure_datetime),
+    PlainSerializer(validators.ensure_timestamp, return_type=int, when_used="json"),
+]
+
+
+class Model(BaseModel):
+    model_config = ConfigDict(
+        alias_generator=AliasGenerator(
+            alias=partial(inflection.camelize, uppercase_first_letter=False),
+        ),
+        frozen=True,
+        populate_by_name=True,
+    )
+
+    # Change the default value of by_alias to True
+    def model_dump_json(self, by_alias: bool = True, **kwargs: Any) -> str:
+        return super().model_dump_json(by_alias=by_alias, **kwargs)
+
+
+# Authentication
+
+
+class LoginSubmission(Model):
+    message: str
+    signature: str
+
+
+class ExchangeParameters(Model):
+    trading_protocol_id: str
+    trading_fee_rate: Decimal
+
+
+# Trading API
+
+
+class ExchangeProductSubmission(Model):
+    id: Annotated[str, AfterValidator(validators.validate_hexstr32)]
+
+
+class ExchangeProduct(Model):
+    id: str
+    symbol: str
+    tick_size: int
+    collateral_asset: str
+
+
+class IntentData(Model):
+    trading_protocol_id: str
+    product_id: str
+    limit_price: Annotated[Decimal, Field(gt=0)]
+    quantity: Annotated[int, Field(gt=0)]
+    max_trading_fee_rate: Annotated[Decimal, Field(ge=0)]
+    side: OrderSide
+    good_until_time: Timestamp
+    nonce: int
+
+
+class Intent(Model):
+    hash: str
+    margin_account_id: str
+    intent_account_id: str
+    signature: str
+    data: IntentData
+
+
+class Order(Model):
+    id: str
+    type: OrderType
+    timestamp: Timestamp
+    state: OrderState
+    fill_quantity: int
+    intent: Intent
+
+
+class OrderCancellationData(Model):
+    intent_hash: Annotated[str, AfterValidator(validators.validate_hexstr32)]
+    nonce: int
+    intent_account_id: str
+    signature: str
+
+
+class OrderSubmission(Model):
+    type: OrderType
+    intent: Intent | None = None
+    cancellation_data: OrderCancellationData | None = None
+
+
+class Trade(Model):
+    id: int
+    product_id: str
+    price: Decimal
+    timestamp: Timestamp
+    state: TradeState
+    transaction_id: str | None
+    rejection_reason: str | None
+
+
+class OrderFill(Model):
+    order: Order
+    trade: Trade
+    quantity: int
+    price: Decimal
+
+
+class OrderFillFilter(Model):
+    intent_account_id: str
+    product_id: None | Annotated[str, AfterValidator(validators.validate_hexstr32)]
+    margin_account_id: (
+        None | Annotated[str, AfterValidator(validators.validate_address)]
+    )
+    intent_hash: None | Annotated[str, AfterValidator(validators.validate_hexstr32)]
+    start: None | Timestamp
+    end: None | Timestamp
+    trade_state: None | TradeState
+
+
+class MarketDepthItem(Model):
+    price: Decimal
+    quantity: int
+
+
+class MarketDepthData(Model):
+    product_id: str
+    bids: list[MarketDepthItem]
+    asks: list[MarketDepthItem]
+
+
+# Clearing API
+
+
+class Position(Model):
+    id: str
+    quantity: int
+    cost_basis: Decimal
+    maintenance_margin: Decimal
+    pnl: Decimal
+
+
+# Builder API
+
+
+class ProductSpecification(Model):
+    id: str
+    # Product Metadata
+    builder_id: str
+    symbol: str
+    description: str
+    # Orace Specification
+    oracle_address: Annotated[str, AfterValidator(validators.validate_address)]
+    fsv_decimals: Annotated[int, Field(ge=0, lt=256)]  # uint8
+    fsp_alpha: Decimal
+    fsp_beta: int
+    fsv_calldata: Annotated[str, AfterValidator(validators.validate_hexstr)]
+    # Product
+    start_time: Timestamp
+    earliest_fsp_submission_time: Timestamp
+    collateral_asset: Annotated[str, AfterValidator(validators.validate_address)]
+    price_quotation: str
+    tick_size: Annotated[int, Field(ge=0)]
+    unit_value: Annotated[Decimal, Field(gt=0)]
+    initial_margin_requirement: Annotated[Decimal, Field(gt=0)]
+    maintenance_margin_requirement: Annotated[Decimal, Field(gt=0)]
+    offer_price_buffer: Annotated[Decimal, Field(ge=0, lt=1)]
+    auction_bounty: Annotated[Decimal, Field(ge=0, le=1)]
+    tradeout_interval: Annotated[int, Field(ge=0)]
+    extended_metadata: str
+
+
+# Liquidation API
+
+
+class Bid(Model):
+    product_id: Annotated[str, AfterValidator(validators.validate_hexstr32)]
+    price: Annotated[Decimal, Field(gt=0)]
+    quantity: Annotated[int, Field(gt=0)]
+    side: OrderSide
+
+
+class AuctionData(Model):
+    start_block: int
+    margin_account_equity_at_initiation: Decimal
+    maintenance_margin_used_at_initiation: Decimal
+    margin_account_equity_now: Decimal
+    maintenance_margin_used_now: Decimal

afp/signing.py

@@ -0,0 +1,69 @@
+from typing import Any, cast
+
+from eth_abi.packed import encode_packed
+from eth_account import messages
+from eth_typing.evm import ChecksumAddress
+from eth_account.signers.local import LocalAccount
+from hexbytes import HexBytes
+from web3 import Web3
+
+from . import config
+from .bindings import clearing_facet
+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,
+}
+
+
+def generate_intent_hash(
+    intent_data: IntentData,
+    margin_account_id: ChecksumAddress,
+    intent_account_id: ChecksumAddress,
+    tick_size: int,
+) -> HexBytes:
+    types = [
+        "address",  # margin_account_id
+        "address",  # intent_account_id
+        "uint256",  # nonce
+        "address",  # trading_protocol_id
+        "bytes32",  # product_id
+        "uint256",  # limit_price
+        "uint256",  # quantity
+        "uint256",  # max_trading_fee_rate
+        "uint256",  # good_until_time
+        "uint8",  # side
+    ]
+    values: list[Any] = [
+        margin_account_id,
+        intent_account_id,
+        intent_data.nonce,
+        cast(ChecksumAddress, intent_data.trading_protocol_id),
+        HexBytes(intent_data.product_id),
+        int(intent_data.limit_price * 10**tick_size),
+        intent_data.quantity,
+        int(intent_data.max_trading_fee_rate * config.FEE_RATE_MULTIPLIER),
+        int(intent_data.good_until_time.timestamp()),
+        ORDER_SIDE_MAPPING[intent_data.side],
+    ]
+    return Web3.keccak(encode_packed(types, values))
+
+
+def generate_order_cancellation_hash(nonce: int, intent_hash: str) -> HexBytes:
+    types = ["uint256", "bytes32"]
+    values: list[Any] = [nonce, HexBytes(intent_hash)]
+    return Web3.keccak(encode_packed(types, values))
+
+
+def generate_product_id(builder: LocalAccount, symbol: str) -> HexBytes:
+    types = ["address", "string"]
+    values: list[Any] = [builder.address, symbol]
+    return Web3.keccak(encode_packed(types, values))
+
+
+def sign_message(account: LocalAccount, message: bytes) -> HexBytes:
+    eip191_message = messages.encode_defunct(message)
+    signed_message = account.sign_message(eip191_message)
+    return signed_message.signature

afp/validators.py

@@ -0,0 +1,43 @@
+from datetime import datetime, timedelta
+
+from binascii import Error
+from eth_typing.evm import ChecksumAddress
+from hexbytes import HexBytes
+from web3 import Web3
+
+
+def ensure_timestamp(value: int | datetime) -> int:
+    return int(value.timestamp()) if isinstance(value, datetime) else value
+
+
+def ensure_datetime(value: datetime | int) -> datetime:
+    return value if isinstance(value, datetime) else datetime.fromtimestamp(value)
+
+
+def validate_timedelta(value: timedelta) -> timedelta:
+    if value.total_seconds() < 0:
+        raise ValueError(f"{value} should be positive")
+    return value
+
+
+def validate_hexstr(value: str, length: int | None = None) -> str:
+    if not value.startswith("0x"):
+        raise ValueError(f"{value} should start with '0x'")
+    try:
+        byte_value = HexBytes(value)
+    except Error:
+        raise ValueError(f"{value} includes non-hexadecimal characters")
+    if length is not None and len(byte_value) != length:
+        raise ValueError(f"{value} should be 32 bytes long")
+    return value
+
+
+def validate_hexstr32(value: str) -> str:
+    return validate_hexstr(value, length=32)
+
+
+def validate_address(value: str) -> ChecksumAddress:
+    try:
+        return Web3.to_checksum_address(value)
+    except ValueError:
+        raise ValueError(f"{value} is not a valid blockchain address")