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

afp/schemas.py

@@ -1,127 +1,57 @@
-from datetime import datetime
-from decimal import Decimal
-from functools import partial
-from typing import Annotated, Any, Literal
-
-import inflection
-from pydantic import (
-    AfterValidator,
-    AliasGenerator,
-    BaseModel,
-    BeforeValidator,
-    ConfigDict,
-    Field,
-    PlainSerializer,
-    computed_field,
-)
-
-from . import validators
-from .enums import ListingState, 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)
-
-
-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(Model):
-    message: str
-    signature: str
-
-
-class ExchangeParameters(Model):
-    trading_protocol_id: str
-    trading_fee_rate: Decimal
-
-
-# Admin API
+"""AFP data structures."""
 
+from decimal import Decimal
+from typing import Annotated, Any, ClassVar, Literal, Self
 
-class ExchangeProductListingSubmission(Model):
-    id: Annotated[str, AfterValidator(validators.validate_hexstr32)]
-
+from pydantic import AfterValidator, BeforeValidator, Field, model_validator
 
-class ExchangeProductUpdateSubmission(Model):
-    listing_state: ListingState
+from . import constants, validators
+from .constants import schema_cids
+from .enums import ListingState, OrderSide, OrderState, OrderType, TradeState
+from .types import (
+    CID,
+    URL,
+    AliasedModel,
+    ISODate,
+    ISODateTime,
+    Model,
+    PinnedModel,
+    Timestamp,
+)
 
 
 # Trading API
 
 
-class ExchangeProduct(Model):
+class ExchangeProduct(AliasedModel):
     id: str
-    symbol: str
+    symbol: Annotated[str, AfterValidator(validators.validate_all_caps)]
     tick_size: int
     collateral_asset: str
     listing_state: ListingState
+    min_price: Decimal
+    max_price: Decimal
 
     def __str__(self) -> str:
         return self.id
 
 
-class ExchangeProductFilter(PaginationFilter):
-    pass
-
-
-class IntentData(Model):
+class IntentData(AliasedModel):
     trading_protocol_id: str
     product_id: str
-    limit_price: Annotated[Decimal, Field(gt=0)]
+    limit_price: Decimal
     quantity: Annotated[int, Field(gt=0)]
-    max_trading_fee_rate: Annotated[Decimal, Field(ge=0)]
+    max_trading_fee_rate: Annotated[
+        Decimal,
+        Field(le=Decimal((2**32 - 1) / constants.FEE_RATE_MULTIPLIER)),  # uint32
+    ]
     side: OrderSide
     good_until_time: Timestamp
     nonce: int
+    referral: Annotated[str, AfterValidator(validators.validate_address)]
 
 
-class Intent(Model):
+class Intent(AliasedModel):
     hash: str
     margin_account_id: str
     intent_account_id: str
@@ -129,7 +59,7 @@ class Intent(Model):
     data: IntentData
 
 
-class Order(Model):
+class Order(AliasedModel):
     id: str
     type: OrderType
     timestamp: Timestamp
@@ -138,35 +68,14 @@ class Order(Model):
     intent: Intent
 
 
-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 OrderCancellationData(Model):
+class OrderCancellationData(AliasedModel):
     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):
+class Trade(AliasedModel):
     # Convert ID from int to str for backward compatibility
     id: Annotated[str, BeforeValidator(str)]
     product_id: str
@@ -177,39 +86,26 @@ class Trade(Model):
     rejection_reason: str | None
 
 
-class OrderFill(Model):
+class OrderFill(AliasedModel):
     order: Order
     trade: Trade
     quantity: int
     price: Decimal
+    trading_fee_rate: Decimal
 
 
-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
-
-
-class MarketDepthItem(Model):
+class MarketDepthItem(AliasedModel):
     price: Decimal
     quantity: int
 
 
-class MarketDepthData(Model):
+class MarketDepthData(AliasedModel):
     product_id: str
     bids: list[MarketDepthItem]
     asks: list[MarketDepthItem]
 
 
-class OHLCVItem(Model):
+class OHLCVItem(AliasedModel):
     timestamp: Timestamp
     open: Decimal
     high: Decimal
@@ -218,7 +114,7 @@ class OHLCVItem(Model):
     volume: int
 
 
-# Clearing API
+# Margin Account API
 
 
 class Transaction(Model):
@@ -235,51 +131,207 @@ class Position(Model):
     pnl: Decimal
 
 
-# Builder API
+# Product API
 
 
-class ProductSpecification(Model):
-    id: str
-    # Product Metadata
-    builder_id: str
-    symbol: str
-    description: str
-    # Orace Specification
+class ExpirySpecification(AliasedModel):
+    earliest_fsp_submission_time: Annotated[
+        ISODateTime, Field(alias="earliestFSPSubmissionTime")
+    ]
+    tradeout_interval: Annotated[int, Field(ge=0)]
+
+
+class OracleSpecification(AliasedModel):
     oracle_address: Annotated[str, AfterValidator(validators.validate_address)]
-    fsv_decimals: Annotated[int, Field(ge=0, lt=256)]  # uint8
+    fsv_decimals: Annotated[int, Field(ge=0, le=255)]  # uint8
     fsp_alpha: Decimal
     fsp_beta: Decimal
     fsv_calldata: Annotated[str, AfterValidator(validators.validate_hexstr)]
-    # Product
-    start_time: Timestamp
-    earliest_fsp_submission_time: Timestamp
+
+
+class ProductMetadata(AliasedModel):
+    builder: Annotated[str, AfterValidator(validators.validate_address)]
+    symbol: Annotated[
+        str,
+        Field(pattern=r"^[A-Z0-9]{1,16}$", min_length=1, max_length=16),
+    ]
+    description: str
+
+
+class BaseProduct(AliasedModel):
+    metadata: ProductMetadata
+    oracle_spec: OracleSpecification
     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)]
-    auction_bounty: Annotated[Decimal, Field(ge=0, le=1)]
-    tradeout_interval: Annotated[int, Field(ge=0)]
-    extended_metadata: str
+    start_time: ISODateTime
+    point_value: Decimal
+    price_decimals: Annotated[int, Field(ge=0, le=255)]  # uint8
+    extended_metadata: CID | None = None
 
-    def __str__(self) -> str:
-        return self.id
 
+class PredictionProductV1(AliasedModel):
+    base: BaseProduct
+    expiry_spec: ExpirySpecification
+    min_price: Decimal
+    max_price: Decimal
 
-# Liquidation API
+    @model_validator(mode="after")
+    def _cross_validate(self) -> Self:
+        validators.validate_price_limits(self.min_price, self.max_price)
+        validators.validate_time_limits(
+            self.base.start_time, self.expiry_spec.earliest_fsp_submission_time
+        )
+        return self
 
 
-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
+# Extended metadata schemas
+
+
+class ApiSpec(Model):
+    standard: Literal["JSONPath", "GraphQL"]
+    spec_variant: Literal["underlying-history", "product-fsv"] | None = None
+
+
+class ApiSpecJSONPath(ApiSpec):
+    standard: Literal["JSONPath"] = "JSONPath"  # type: ignore
+    url: URL
+    date_path: str
+    value_path: str
+    auth_param_location: Literal["query", "header", "none"] = "none"
+    auth_param_name: str | None = None
+    auth_param_prefix: str | None = None
+    continuation_token_param: str | None = None
+    continuation_token_path: str | None = None
+    date_format_custom: str | None = None
+    date_format_type: Literal["iso_8601", "unix_timestamp", "custom"] = "iso_8601"
+    headers: dict[str, str] | None = None
+    max_pages: Annotated[int | None, Field(ge=1)] = 10
+    timestamp_scale: Annotated[int | float, Field(ge=1)] = 1
+    timezone: Annotated[
+        str,
+        Field(pattern=r"^[A-Za-z][A-Za-z0-9_+-]*(/[A-Za-z][A-Za-z0-9_+-]*)*$"),
+    ] = "UTC"
+
+
+class BaseCaseResolution(Model):
+    condition: Annotated[str, Field(min_length=1)]
+    fsp_resolution: Annotated[str, Field(min_length=1)]
+
+
+class EdgeCase(Model):
+    condition: Annotated[str, Field(min_length=1)]
+    fsp_resolution: Annotated[str, Field(min_length=1)]
+
+
+class OutcomeSpace(PinnedModel):
+    SCHEMA_CID: ClassVar[CID] = schema_cids.OUTCOME_SPACE_V020
+
+    fsp_type: Literal["scalar", "binary", "ternary"]
+    description: Annotated[str, Field(min_length=1)]
+    base_case: BaseCaseResolution
+    edge_cases: Annotated[list[EdgeCase], Field(default_factory=list)]
+
+
+class OutcomeSpaceScalar(OutcomeSpace):
+    SCHEMA_CID: ClassVar[CID] = schema_cids.OUTCOME_SPACE_SCALAR_V020
+
+    fsp_type: Literal["scalar"] = "scalar"  # type: ignore
+    units: Annotated[str, Field(min_length=1)]
+    source_name: Annotated[str, Field(min_length=1)]
+    source_uri: URL
+
+
+class OutcomeSpaceTimeSeries(OutcomeSpaceScalar):
+    SCHEMA_CID: ClassVar[CID] = schema_cids.OUTCOME_SPACE_TIME_SERIES_V020
+
+    frequency: Literal[
+        "daily",
+        "weekly",
+        "fortnightly",
+        "semimonthly",
+        "monthly",
+        "quarterly",
+        "yearly",
+    ]
+    history_api_spec: ApiSpecJSONPath | ApiSpec | None = None
+
+
+class TemporalObservation(Model):
+    reference_date: ISODate
+    release_date: ISODate
+
+
+class OutcomePoint(PinnedModel):
+    SCHEMA_CID: ClassVar[CID] = schema_cids.OUTCOME_POINT_V020
+
+    fsp_type: Literal["scalar", "binary", "ternary"]
+
+
+class OutcomePointTimeSeries(OutcomePoint):
+    SCHEMA_CID: ClassVar[CID] = schema_cids.OUTCOME_POINT_TIME_SERIES_V020
+
+    fsp_type: Literal["scalar"] = "scalar"  # type: ignore
+    observation: TemporalObservation
+
+
+class OutcomePointEvent(OutcomePoint):
+    SCHEMA_CID: ClassVar[CID] = schema_cids.OUTCOME_POINT_EVENT_V020
+
+    fsp_type: Literal["binary", "ternary"]  # type: ignore
+    outcome: Annotated[str, Field(min_length=1)]
+
+
+class OracleConfig(PinnedModel):
+    SCHEMA_CID: ClassVar[CID] = schema_cids.ORACLE_CONFIG_V020
+
+    description: Annotated[str, Field(min_length=1)]
+    project_url: URL | None = None
+
+
+class OracleConfigPrototype1(OracleConfig):
+    SCHEMA_CID: ClassVar[CID] = schema_cids.ORACLE_CONFIG_PROTOTYPE1_V020
+
+    evaluation_api_spec: ApiSpecJSONPath | ApiSpec
+
+
+class OracleFallback(PinnedModel):
+    SCHEMA_CID: ClassVar[CID] = schema_cids.ORACLE_FALLBACK_V020
+
+    fallback_time: ISODateTime
+    fallback_fsp: Decimal
+
 
+class PredictionProduct(Model):
+    product: PredictionProductV1
+    outcome_space: OutcomeSpaceTimeSeries | OutcomeSpaceScalar | OutcomeSpace
+    outcome_point: OutcomePointEvent | OutcomePointTimeSeries | OutcomePoint
+    oracle_config: OracleConfigPrototype1 | OracleConfig
+    oracle_fallback: OracleFallback
 
-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
+    @model_validator(mode="after")
+    def _cross_validate(self) -> Self:
+        validators.validate_matching_fsp_types(
+            self.outcome_space.fsp_type, self.outcome_point.fsp_type
+        )
+        validators.validate_oracle_fallback_time(
+            self.oracle_fallback.fallback_time,
+            self.product.expiry_spec.earliest_fsp_submission_time,
+        )
+        validators.validate_oracle_fallback_fsp(
+            self.oracle_fallback.fallback_fsp,
+            self.product.min_price,
+            self.product.max_price,
+        )
+        validators.validate_outcome_space_conditions(
+            self.outcome_space.base_case.condition,
+            [case.condition for case in self.outcome_space.edge_cases],
+            self.outcome_point.model_dump(),
+        )
+        if isinstance(self.outcome_space, OutcomeSpaceTimeSeries) and isinstance(
+            self.outcome_point, OutcomePointTimeSeries
+        ):
+            validators.validate_symbol(
+                self.product.base.metadata.symbol,
+                self.outcome_space.frequency,
+                self.outcome_point.observation.release_date,
+            )
+        return self

afp/types.py

@@ -0,0 +1,169 @@
+from datetime import date, datetime, UTC
+from functools import partial
+from typing import Annotated, Any, ClassVar, Self
+
+import inflection
+import multiformats
+import rfc8785
+from pydantic import (
+    AfterValidator,
+    AliasGenerator,
+    BaseModel,
+    BeforeValidator,
+    ConfigDict,
+    Field,
+    PlainSerializer,
+    model_validator,
+)
+
+from . import constants, validators
+
+CID_MODEL_MAP: dict[str, type["PinnedModel"]] = {}
+
+
+# Conversions
+
+
+def ensure_py_datetime(value: datetime | int | float | str) -> datetime:
+    if isinstance(value, datetime):
+        return value.astimezone(UTC)
+    if isinstance(value, int) or isinstance(value, float):
+        return datetime.fromtimestamp(value, UTC)
+    return datetime.fromisoformat(value).astimezone(UTC)
+
+
+def ensure_py_date(value: date | str) -> date:
+    if isinstance(value, date):
+        return value
+    return date.fromisoformat(value)
+
+
+def ensure_timestamp(value: datetime) -> int:
+    return int(value.timestamp())
+
+
+def ensure_iso_datetime(value: datetime) -> str:
+    assert value.tzinfo is UTC, f"{value} should be in UTC timezone"
+    return value.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def ensure_iso_date(value: date) -> str:
+    return value.isoformat()
+
+
+# Custom types
+
+
+URL = Annotated[
+    str,
+    Field(min_length=1, max_length=2083),
+    BeforeValidator(validators.validate_url),
+    AfterValidator(validators.verify_url),
+]
+
+CID = Annotated[
+    str,
+    Field(
+        pattern=r"^(Qm[1-9A-HJ-NP-Za-km-z]{44}|b[a-z2-7]{58,}|z[1-9A-HJ-NP-Za-km-z]{48,})$"
+    ),
+]
+
+# Decode CIDs for serialization so that the DAG-CBOR encoder will convert them
+# into IPLD Link format
+IPLD_LINK = Annotated[
+    CID,
+    BeforeValidator(  # Ensure the same encoding is used consistently
+        lambda cid: multiformats.CID.decode(str(cid)).encode(
+            constants.IPFS_CID_ENCODING
+        )
+    ),
+    PlainSerializer(multiformats.CID.decode, return_type=multiformats.CID),
+]
+
+# Use datetime internally but UNIX timestamp in serialized format
+Timestamp = Annotated[
+    datetime,
+    BeforeValidator(ensure_py_datetime),
+    AfterValidator(validators.validate_non_negative_timestamp),
+    PlainSerializer(ensure_timestamp, return_type=int),
+]
+
+# Use datetime internally but ISO string in serialized format
+ISODateTime = Annotated[
+    datetime,
+    BeforeValidator(ensure_py_datetime),
+    AfterValidator(validators.validate_non_negative_timestamp),
+    PlainSerializer(ensure_iso_datetime, return_type=str),
+]
+
+# Use date internally but ISO string in serialized format
+ISODate = Annotated[
+    date,
+    BeforeValidator(ensure_py_date),
+    PlainSerializer(ensure_iso_date, return_type=str),
+]
+
+
+# Base models
+
+
+class Model(BaseModel):
+    """Base immutable schema."""
+
+    model_config = ConfigDict(frozen=True)
+
+    # Always serialize/deserialize by alias
+
+    def model_dump(self, by_alias: bool = True, **kwargs: Any) -> dict[Any, Any]:
+        return super().model_dump(by_alias=by_alias, **kwargs)
+
+    def model_dump_json(self, by_alias: bool = True, **kwargs: Any) -> str:
+        return super().model_dump_json(by_alias=by_alias, **kwargs)
+
+    def model_dump_canonical_json(self, **kwargs: Any) -> str:
+        obj = self.model_dump(mode="json", **kwargs)
+        return rfc8785.dumps(obj).decode("utf-8")
+
+    @classmethod
+    def model_validate(cls, *args: Any, by_alias: bool = True, **kwargs: Any) -> Self:
+        return super().model_validate(*args, by_alias=by_alias, **kwargs)
+
+    @classmethod
+    def model_validate_json(
+        cls, *args: Any, by_alias: bool = True, **kwargs: Any
+    ) -> Self:
+        return super().model_validate_json(*args, by_alias=by_alias, **kwargs)
+
+
+class AliasedModel(Model):
+    """Schema that converts property names from snake case to camel case for
+    serialization.
+    """
+
+    model_config = Model.model_config | ConfigDict(
+        alias_generator=AliasGenerator(
+            alias=partial(inflection.camelize, uppercase_first_letter=False),
+        ),
+        populate_by_name=True,
+    )
+
+
+class PinnedModel(Model):
+    """Extended metadata schema that has an IPFS CID."""
+
+    SCHEMA_CID: ClassVar[CID]
+
+    def __init_subclass__(cls, **kwargs: Any):
+        super().__init_subclass__(**kwargs)
+        if "SCHEMA_CID" in cls.__dict__:
+            assert cls.SCHEMA_CID not in CID_MODEL_MAP, (
+                f"{cls.__name__} model does not have unique CID"
+            )
+        CID_MODEL_MAP[cls.SCHEMA_CID] = cls
+
+    @model_validator(mode="after")
+    def _ensure_schema_cid(self) -> Self:
+        assert "SCHEMA_CID" in self.__class__.__dict__, (
+            f"SCHEMA_CID is missing from {self.__class__.__name__} schema"
+        )
+        return self