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

afp/validators.py

@@ -1,18 +1,22 @@
-from datetime import datetime, timedelta
+import re
+from datetime import date, datetime, timedelta
 from decimal import Decimal
+from functools import reduce
+from operator import getitem
+from typing import Any, Iterable
 
+import requests
 from binascii import Error
 from eth_typing.evm import ChecksumAddress
 from hexbytes import HexBytes
+from pydantic import AnyUrl
 from web3 import Web3
 
+from .constants import MINIMUM_ORACLE_FALLBACK_INTERVAL, MONTH_CODES
+from .exceptions import ValidationError
 
-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)
+# Generic type validators
 
 
 def validate_timedelta(value: timedelta) -> timedelta:
@@ -21,6 +25,12 @@ def validate_timedelta(value: timedelta) -> timedelta:
     return value
 
 
+def validate_non_negative_timestamp(value: datetime) -> datetime:
+    if value.timestamp() < 0:
+        raise ValueError(f"{value} should be greater than {datetime.fromtimestamp(0)}")
+    return value
+
+
 def validate_hexstr(value: str, length: int | None = None) -> str:
     value = str(value)
     if not value.startswith("0x"):
@@ -45,13 +55,213 @@ def validate_address(value: str) -> ChecksumAddress:
         raise ValueError(f"{value} is not a valid blockchain address")
 
 
+def validate_url(value: str) -> str:
+    AnyUrl(value)
+    return value
+
+
+def validate_all_caps(value: str) -> str:
+    if value != value.upper():
+        raise ValueError(f"{value} should use capital letters only")
+    return value
+
+
+# Live data verifiers
+
+
+def verify_collateral_asset(w3: Web3, address: str) -> ChecksumAddress:
+    address = validate_address(address)
+    if len(w3.eth.get_code(address)) == 0:
+        raise ValidationError(
+            f"No contract found at collateral asset address {address}"
+        )
+    return address
+
+
+def verify_oracle(w3: Web3, address: str) -> ChecksumAddress:
+    address = validate_address(address)
+    if len(w3.eth.get_code(address)) == 0:
+        raise ValidationError(f"No contract found at oracle address {address}")
+    return address
+
+
+def verify_url(value: str) -> str:
+    try:
+        requests.head(value)
+    except requests.RequestException as ex:
+        raise ValidationError(f"Not possible to connect to URL {value}") from ex
+    return value
+
+
+# Schema-specific model validators
+
+
 def validate_limit_price(
-    value: Decimal, tick_size: int, rounding: str | None = None
+    value: Decimal,
+    min_price: Decimal,
+    max_price: Decimal,
+    tick_size: int,
+    rounding: str | None = None,
 ) -> Decimal:
+    if value < min_price:
+        raise ValueError(
+            f"IntentData: limit_price: {value} should be greater than "
+            f"the product's minimum price {min_price}"
+        )
+    if value > max_price:
+        raise ValueError(
+            f"IntentData: limit_price: {value} should be less than the product's "
+            f"maximum price {max_price}"
+        )
     if rounding is None:
         num_fractional_digits = abs(int(value.normalize().as_tuple().exponent))
         if num_fractional_digits > tick_size:
             raise ValueError(
-                f"Limit price {value} can have at most {tick_size} fractional digits"
+                f"IntentData: limit_price: {value} should have at most "
+                f"{tick_size} fractional digits"
             )
     return value.quantize(Decimal("10") ** -tick_size, rounding=rounding)
+
+
+def validate_price_limits(min_price: Decimal, max_price: Decimal) -> None:
+    if min_price >= max_price:
+        raise ValueError(
+            f"PredictionProductV1.min_price {min_price} "
+            f"should be less than PredictionProductV1.max_price {max_price}"
+        )
+
+
+def validate_time_limits(
+    start_time: datetime, earliest_fsp_submission_time: datetime
+) -> None:
+    if start_time >= earliest_fsp_submission_time:
+        raise ValueError(
+            f"BaseProduct.start_time {start_time} should be less than "
+            "ExpirySpecification.earliest_fsp_submission_time "
+            f"{earliest_fsp_submission_time}"
+        )
+
+
+def validate_matching_fsp_types(
+    outcome_space_fsp_type: str, outcome_point_fsp_type: str
+) -> None:
+    if outcome_space_fsp_type != outcome_point_fsp_type:
+        raise ValueError(
+            f"OutcomeSpace.fsp_type '{outcome_space_fsp_type}' should match "
+            f"OutcomePoint.fsp_type '{outcome_point_fsp_type}'"
+        )
+
+
+def validate_oracle_fallback_time(
+    fallback_time: datetime, earliest_fsp_submission_time: datetime
+) -> None:
+    earliest_fallback_time = (
+        earliest_fsp_submission_time + MINIMUM_ORACLE_FALLBACK_INTERVAL
+    )
+    if fallback_time < earliest_fallback_time:
+        raise ValueError(
+            f"OracleFallback: fallback_time {fallback_time} "
+            f"should be at least {MINIMUM_ORACLE_FALLBACK_INTERVAL} after "
+            "ExpirySpecification.earliest_fsp_submission_time "
+            f"{earliest_fsp_submission_time}"
+        )
+
+
+def validate_oracle_fallback_fsp(
+    fallback_fsp: Decimal, min_price: Decimal, max_price: Decimal
+) -> None:
+    if not (min_price <= fallback_fsp <= max_price):
+        raise ValueError(
+            f"OracleFallback: fallback_fsp {fallback_fsp} should be between "
+            f"PredictionProductV1.min_price {min_price} and "
+            f"PredictionProductV1.max_price {max_price}"
+        )
+
+
+def validate_outcome_space_template_variables(
+    values: Iterable[str], outcome_point_dict: dict[Any, Any]
+) -> None:
+    for value in values:
+        for variable in re.findall(r"{(.*?)}", value):
+            try:
+                referred_value = reduce(
+                    getitem, variable.split("."), outcome_point_dict
+                )
+            except (TypeError, KeyError):
+                raise ValueError(
+                    f"OutcomeSpace: Invalid template variable '{variable}'"
+                )
+            if isinstance(referred_value, dict) or isinstance(referred_value, list):  # type: ignore
+                raise ValueError(
+                    f"OutcomeSpace: Template variable '{variable}' "
+                    "should not refer to a nested object or list"
+                )
+
+
+def validate_symbol(symbol: str, frequency: str, release_date: date) -> None:
+    match frequency:
+        case "daily":
+            pattern = (
+                r"[A-Z]{1,8}(?P<day>(0[1-9]|[1-2][0-9]|3[01]))"
+                r"(?P<month>[FGHJKMNQUVXZ])(?P<year>[0-9]{2})"
+            )
+        case "weekly" | "fortnightly":
+            pattern = (
+                r"[A-Z]{1,8}(?P<weekno>(0[1-9]|[1-4][0-9]|5[0-3]))"
+                r"W(?P<year>[0-9]{2})"
+            )
+        case "semimonthly":
+            pattern = (
+                r"[A-Z]{1,8}(?P<occurrence>[12])"
+                r"(?P<month>[FGHJKMNQUVXZ])(?P<year>[0-9]{2})"
+            )
+        case "monthly" | "quarterly":
+            pattern = r"[A-Z]{1,8}(?P<month>[FGHJKMNQUVXZ])(?P<year>[0-9]{2})"
+        case "yearly":
+            pattern = r"[A-Z]{1,8}(?P<year>[0-9]{4})"
+        case _:
+            raise ValueError(
+                f"OutcomeSpaceTimeSeries: frequency: Unexpected value '{frequency}'"
+            )
+    if match := re.fullmatch(pattern, symbol):
+        groups = match.groupdict()
+
+        if "day" in groups and int(groups["day"]) != release_date.day:
+            raise ValueError(
+                f"ProductMetadata: symbol: Day component of symbol '{symbol}' "
+                f"should match TemporalObservation.release_date {release_date}"
+            )
+        if "month" in groups and MONTH_CODES[groups["month"]] != release_date.month:
+            raise ValueError(
+                f"ProductMetadata: symbol: Month component of symbol '{symbol}' "
+                f"should match TemporalObservation.release_date {release_date}"
+            )
+        if "year" in groups and int(groups["year"]) % 2000 != release_date.year % 2000:
+            raise ValueError(
+                f"ProductMetadata: symbol: Year component of symbol '{symbol}' "
+                f"should match TemporalObservation.release_date {release_date}"
+            )
+        if (
+            "weekno" in groups
+            and int(groups["weekno"]) != release_date.isocalendar().week
+        ):
+            raise ValueError(
+                f"ProductMetadata: symbol: Week number component of symbol '{symbol}' "
+                f"should match TemporalObservation.release_date {release_date}"
+            )
+        if "occurrence" in groups and int(
+            groups["occurrence"]
+        ) != _semimonthly_occurrence(release_date.day):
+            raise ValueError(
+                f"ProductMetadata: symbol: Occurrence component of symbol '{symbol}' "
+                f"should match TemporalObservation.release_date {release_date}"
+            )
+    else:
+        raise ValueError(
+            f"ProductMetadata: symbol: Symbol '{symbol}' should match regexp pattern "
+            f"'{pattern}' for OutcomeSpaceTimeSeries.frequency '{frequency}'"
+        )
+
+
+def _semimonthly_occurrence(day_of_month: int) -> int:
+    return 1 if day_of_month <= 15 else 2

{afp_sdk-0.5.4.dist-info → afp_sdk-0.6.1.dist-info}/METADATA

@@ -1,22 +1,26 @@
 Metadata-Version: 2.4
 Name: afp-sdk
-Version: 0.5.4
+Version: 0.6.1
 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,75 @@ fills = trading.order_fills(product_id=PRODUCT_ID)
 print(fills)
 ```
 
-See further code examples in the [examples](./examples/) directory.
+### Product API
 
-## Development
+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.
 
-The package uses [`uv`](https://docs.astral.sh/uv/) as project manager.
+```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](https://github.com/autonity/afp-sdk/tree/master/examples/) directory.
+
+## Development
 
-- 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](https://github.com/autonity/afp-sdk/blob/master/DEVELOPMENT.md)
+for developer documentation.

afp_sdk-0.6.1.dist-info/RECORD

@@ -0,0 +1,50 @@
+afp/__init__.py,sha256=ESBx9plb3ESlRQgTPSFbwQHuqIETv4biDN22CBhQp6g,423
+afp/afp.py,sha256=onXjJX6I45oOS5jxWpLipBfKiYMdTxc6IU0oTQ0CHl4,9781
+afp/api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+afp/api/admin.py,sha256=r5B1aQLBKy3VOiJxFU7Q6jAGau0E2QbxhBoXrl2Wm3Q,2167
+afp/api/base.py,sha256=IIkCslGziKRN8FVPVMwSHYKmIxFbj4GO2ivA_puavrU,4696
+afp/api/margin_account.py,sha256=lHj1d1E4SgKlmffFa7c3wD430XokEe2pDJZDfIegpiU,10927
+afp/api/product.py,sha256=WT886LGLU7qNAbuTrrvcHfhTVvCDzrN-OnFZrZ8-x60,16175
+afp/api/trading.py,sha256=UhiasWbexPK_4HWBTgQSmt54MrddfHkYi-ocPdvITPQ,17385
+afp/auth.py,sha256=WX4IhwdLdTU1DZsE88xFxyjolKN82hOQLB6-MczJKg0,2476
+afp/bindings/__init__.py,sha256=GGEdCeRvCX5BviL59ogv_zD8zumr2a6VAp9ReGp2zpU,1318
+afp/bindings/admin_facet.py,sha256=6WHLgaqfFO_IfA5B3u9CICMfHxZH7nA4DAxXQEgJ0Ug,31285
+afp/bindings/clearing_facet.py,sha256=LXOcXBCh4Mu_I_t9edTXz-h5Mtt6CQwrjVYAckS3nT0,22096
+afp/bindings/erc20.py,sha256=-jw7ohcEbUL7g3PpK3-a5_7ClUDCDHt1bezm-w7exzo,10822
+afp/bindings/facade.py,sha256=oMJts0LlkOG58EZuw20WeBquSF96gDvg2KGzea0QEH8,2696
+afp/bindings/final_settlement_facet.py,sha256=M7d3HllvU2ZHCiro9X_2hWYzLCFFb5WoKaemlKO9YJI,14934
+afp/bindings/margin_account.py,sha256=wdbXVYshAjklo08f-j2FxMsbigrpy9LiWki1O1ZWAyQ,35371
+afp/bindings/margin_account_facet.py,sha256=pT2Hkluq1qLOQ5Qm71UR3j6GO_OAwAjIy51k1DDe8Os,23839
+afp/bindings/margin_account_registry.py,sha256=-3beQiHtk-lz4lVTwZPZU9K9vHRlUEfzvbbVk9KMdCg,15182
+afp/bindings/mark_price_tracker_facet.py,sha256=KWbPS-1JxyzctVoXH3Df8N12obqd4dxjnMe8E1r30SQ,5323
+afp/bindings/oracle_provider.py,sha256=CMpVAXdUuTP_W9ZE297B-m9MjuW90yCOhNLMVl3kCf0,15863
+afp/bindings/product_registry.py,sha256=2rGNVG_GxGIJfW5xOhIIVzq_IT5aVCmMrC46jm1ewh8,86610
+afp/bindings/product_registry_facet.py,sha256=CE3vpSFIj54d3tQdHMfQz-kquqhhzjvQsAqzD_oKhIU,58313
+afp/bindings/system_viewer.py,sha256=Cs2yNe3kBe833I_NnWg1nABIIan6iPQO9ot5U5naWe0,49734
+afp/bindings/types.py,sha256=97x8_Nqfj13PJ2MVzIQ5afeynWiNlMUI2N0L8-8YTbc,4853
+afp/config.py,sha256=xsMgKL1bvxt1wzdln2D9mSX5Eutz87CqF2xct0Xpzwk,780
+afp/constants.py,sha256=2ntRfbRM6N1oIuotxXUBHDMF_aqmemTHVRRl2kHmRgE,3448
+afp/decorators.py,sha256=r_wXmqNExg_inDRFg7rD2qMdWzDmZylyf8v_TPc2wvk,3650
+afp/dtos.py,sha256=oNTWZloMkCX2wfbd5yLe53zLm8U1u6WBwM6OF5UmhLc,3618
+afp/enums.py,sha256=9JhwdLcTNhyKabKdrALAlCeL3C5XfeXYSSSXSCsuTzE,688
+afp/exceptions.py,sha256=UpGb0U9K-5q41wT3PH4bTKGzhxkKCtLR2Dn0hTc907M,540
+afp/exchange.py,sha256=sNayosHN6WxVDH4cUDrt76agdrzPjTVFC2ANNtitQkU,7695
+afp/hashing.py,sha256=4qNPJalunK5KLiu4hRDRv32QiuErPQYKCMMkSExZoWo,2020
+afp/ipfs.py,sha256=fZr3-BGy7BYpM_D8JNme543-Cb1WZi7yqSFJE0Al4j0,9619
+afp/json-schemas/bafyreiaw34o6l3rmatabzbds2i2myazdw2yolevcpsoyd2i2g3ms7wa2eq.json,sha256=yfPc3gzknuKbGoF97uECbf_VdDfKxROhc_oFLc-Hm1U,6683
+afp/json-schemas/bafyreibnfg6nq74dvpkre5rakkccij7iadp5rxpim7omsatjnrpmj3y7v4.json,sha256=IBMLm62G6JkyblvCLfyM4tjWyOH2bDLslDh2WdozFe8,674
+afp/json-schemas/bafyreicgr6dfo5yduixjkcifghiulskfegwojvuwodtouvivl362zndhxe.json,sha256=UALQI3ttQoNSSFcbr5dCAd537dwqGkwKEB59dhtj9bA,1324
+afp/json-schemas/bafyreicheoypx6synljushh7mq2572iyhlolf4nake2p5dwobgnj3r5eua.json,sha256=-MN9Qh0XZFBv3R8JFiMiHSInyJnN9riE4VkkrA22Z8o,3060
+afp/json-schemas/bafyreid35a67db4sqh4fs6boddyt2xvscbqy6nqvsp5jjur56qhkw4ixre.json,sha256=FtJuOsQpsAGNUIHo88PccuABJcuaUdljyWv128iNt7I,10833
+afp/json-schemas/bafyreidzs7okcpqiss6ztftltyptqwnw5e5opsy5yntospekjha4kpykaa.json,sha256=be7XVUuH1mLEoar_A-AAUpH5xrFEUNCeQRkqfOWyDPY,2470
+afp/json-schemas/bafyreifcec2km7hxwq6oqzjlspni2mgipetjb7pqtaewh2efislzoctboi.json,sha256=iJGiFgmbyVyAyG5ty-3tbhHay4Ucb5nvKzVV9N2s864,783
+afp/json-schemas/bafyreihn3oiaxffe4e2w7pwtreadpw3obfd7gqlogbcxm56jc2hzfvco74.json,sha256=_tEqw3mqsdUP_sFwr8S1QZCbXxd3yJYjCHRuYnvoV2Y,4343
+afp/json-schemas/bafyreihur3dzwhja6uxsbcw6eeoj3xmmc4e3zkmyzpot5v5dleevxe5zam.json,sha256=q-JNlC9Znh983Lp0qU8RYdj7VMtKCo4QRUS9OzchEeE,1427
+afp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+afp/schemas.py,sha256=Qqjkx9IoKJPni_Tup_cgBPTTVfyfexyAjAe5CAU75RM,9456
+afp/types.py,sha256=mI_PFMlVQvP9BJ50jzgvmUQPhTuP7TPP-JQOLvJr6mY,4691
+afp/validators.py,sha256=ogUzfJcqOsjosP0KncbxfbWVAOcjwEsE3LMmK4aeBFI,9256
+afp_sdk-0.6.1.dist-info/licenses/LICENSE,sha256=ZdaKItgc2ppfqta2OJV0oHpSJiK87PUxmUkUo-_0SB8,1065
+afp_sdk-0.6.1.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+afp_sdk-0.6.1.dist-info/METADATA,sha256=S286Fl-xYd50GYH4HnY_XdNXwi15IvXzICi15KvQKb0,8107
+afp_sdk-0.6.1.dist-info/RECORD,,