afp-sdk 0.4.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

afp/api/{clearing.py → margin_account.py}

@@ -1,5 +1,6 @@
 from decimal import Decimal
 from functools import cache
+from typing import Iterable
 
 from eth_typing.evm import ChecksumAddress
 from hexbytes import HexBytes
@@ -8,10 +9,12 @@ from web3.exceptions import ContractCustomError
 
 from .. import validators
 from ..bindings import (
+    BidData,
     ClearingDiamond,
-    MarginAccount,
+    MarginAccount as MarginContract,
     MarginAccountRegistry,
     ProductRegistry,
+    Side as OnChainOrderSide,
 )
 from ..bindings.erc20 import ERC20
 from ..bindings.facade import CLEARING_DIAMOND_ABI
@@ -20,26 +23,41 @@ from ..bindings.margin_account_registry import ABI as MARGIN_ACCOUNT_REGISTRY_AB
 from ..bindings.product_registry import ABI as PRODUCT_REGISTRY_ABI
 from ..decorators import convert_web3_error
 from ..exceptions import NotFoundError
-from ..schemas import Position
+from ..schemas import AuctionData, Bid, OrderSide, Position, Transaction
 from .base import ClearingSystemAPI
-from .builder import Builder
 
 
-class Clearing(ClearingSystemAPI):
-    """API for managing margin accounts.
+class MarginAccount(ClearingSystemAPI):
+    """API for managing margin accounts."""
 
-    Parameters
-    ----------
-    private_key : str
-        The private key of the blockchain account that manages the margin account.
-    autonity_rpc_url : str
-        The URL of a JSON-RPC provider for Autonity. (HTTPS only.)
-    """
+    ### Factories ###
+
+    @staticmethod
+    def create_bid(product_id: str, price: Decimal, quantity: int, side: str) -> Bid:
+        """Create a bid to be submitted to a liquidation auction.
+
+        Parameters
+        ----------
+        product_id : str
+        price: Decimal
+        quantity: int
+        side: str
+
+        Returns
+        -------
+        afp.schemas.Bid
+        """
+        return Bid(
+            product_id=product_id,
+            price=price,
+            quantity=quantity,
+            side=getattr(OrderSide, side.upper()),
+        )
 
     ### Transactions ###
 
     @convert_web3_error(MARGIN_CONTRACT_ABI)
-    def authorize(self, collateral_asset: str, intent_account_id: str) -> str:
+    def authorize(self, collateral_asset: str, intent_account_id: str) -> Transaction:
         """Authorizes a blockchain account to submit intents to the clearing system
         using the margin account associated with the collateral asset.
 
@@ -52,24 +70,19 @@ class Clearing(ClearingSystemAPI):
 
         Returns
         -------
-        str
-            The hash of the transaction.
+        afp.schemas.Transaction
+            Transaction parameters.
         """
         collateral_asset = validators.validate_address(collateral_asset)
         intent_account_id = validators.validate_address(intent_account_id)
-
-        tx_hash = (
-            self._margin_contract(collateral_asset)
-            .authorize(intent_account_id)
-            .transact()
+        return self._transact(
+            self._margin_contract(collateral_asset).authorize(intent_account_id)
         )
-        self._w3.eth.wait_for_transaction_receipt(tx_hash)
-        return Web3.to_hex(tx_hash)
 
     @convert_web3_error(MARGIN_CONTRACT_ABI)
-    def deposit_into_margin_account(
+    def deposit(
         self, collateral_asset: str, amount: Decimal
-    ) -> tuple[str, str]:
+    ) -> tuple[Transaction, Transaction]:
         """Deposits the specified amount of collateral tokens into the margin account
         associated with the collateral asset.
 
@@ -85,32 +98,28 @@ class Clearing(ClearingSystemAPI):
 
         Returns
         -------
-        str
-            The hash of the approval transaction.
-        str
-            The hash of the deposit transaction.
+        afp.schemas.Transaction
+            Parameters of the approval transaction.
+        afp.schemas.Transaction
+            Parameters of the deposit transaction.
         """
         collateral_asset = validators.validate_address(collateral_asset)
         token_amount = int(amount * 10 ** self._decimals(collateral_asset))
         token_contract = ERC20(self._w3, collateral_asset)
 
-        tx1_hash = token_contract.approve(
-            self._margin_contract(collateral_asset)._contract.address,  # type: ignore
-            token_amount,
-        ).transact()
-        self._w3.eth.wait_for_transaction_receipt(tx1_hash)
-
-        tx2_hash = (
-            self._margin_contract(collateral_asset).deposit(token_amount).transact()
+        tx1 = self._transact(
+            token_contract.approve(
+                self._margin_contract(collateral_asset)._contract.address,  # type: ignore
+                token_amount,
+            )
         )
-        self._w3.eth.wait_for_transaction_receipt(tx2_hash)
-
-        return (Web3.to_hex(tx1_hash), Web3.to_hex(tx2_hash))
+        tx2 = self._transact(
+            self._margin_contract(collateral_asset).deposit(token_amount)
+        )
+        return (tx1, tx2)
 
     @convert_web3_error(MARGIN_CONTRACT_ABI)
-    def withdraw_from_margin_account(
-        self, collateral_asset: str, amount: Decimal
-    ) -> str:
+    def withdraw(self, collateral_asset: str, amount: Decimal) -> Transaction:
         """Withdraws the specified amount of collateral tokens from the margin account
         associated with the collateral asset.
 
@@ -123,46 +132,83 @@ class Clearing(ClearingSystemAPI):
 
         Returns
         -------
-        str
-            The hash of the transaction.
+        afp.schemas.Transaction
+            Transaction parameters.
         """
         collateral_asset = validators.validate_address(collateral_asset)
         token_amount = int(amount * 10 ** self._decimals(collateral_asset))
-        tx_hash = (
-            self._margin_contract(collateral_asset).withdraw(token_amount).transact()
+        return self._transact(
+            self._margin_contract(collateral_asset).withdraw(token_amount)
         )
-        self._w3.eth.wait_for_transaction_receipt(tx_hash)
-        return Web3.to_hex(tx_hash)
 
     @convert_web3_error(CLEARING_DIAMOND_ABI)
-    def initiate_final_settlement(self, product_id: str, accounts: list[str]) -> str:
-        """Initiate final settlement (closeout) process for the specified accounts.
+    def request_liquidation(
+        self, margin_account_id: str, collateral_asset: str
+    ) -> Transaction:
+        """Request a liquidation auction to be started.
 
-        The product must be in Final Settlement state. The accounts must hold non-zero
-        positions in the product that offset each other (i.e. the sum of their position
-        sizes is 0.)
+        Parameters
+        ----------
+        margin_account_id : str
+            The ID of the margin account to be liquidated.
+        collateral_asset : str
+            The address of the collateral token that the margin account is trading with.
+
+        Returns
+        -------
+        afp.schemas.Transaction
+            Transaction parameters.
+        """
+        margin_account_id = validators.validate_address(margin_account_id)
+        collateral_asset = validators.validate_address(collateral_asset)
+
+        clearing_contract = ClearingDiamond(
+            self._w3, self._config.clearing_diamond_address
+        )
+        return self._transact(
+            clearing_contract.request_liquidation(margin_account_id, collateral_asset)
+        )
+
+    @convert_web3_error(CLEARING_DIAMOND_ABI, PRODUCT_REGISTRY_ABI)
+    def submit_bids(
+        self, margin_account_id: str, collateral_asset: str, bids: Iterable[Bid]
+    ) -> Transaction:
+        """Submit bids to a liquidation auction.
 
         Parameters
         ----------
-        product_id : str
-            The ID of the product.
-        accounts : list of str
-            List of margin account IDs to initiate settlement for.
+        margin_account_id : str
+            The ID of the margin account that is being liquidated.
+        collateral_asset : str
+            The address of the collateral token that the margin account is trading with.
+        bids: list of afp.schemas.Bid
 
         Returns
         -------
-        str
-            The hash of the transaction.
+        afp.schemas.Transaction
+            Transaction parameters.
         """
-        product_id = validators.validate_hexstr32(product_id)
-        addresses = [validators.validate_address(account) for account in accounts]
+        margin_account_id = validators.validate_address(margin_account_id)
+        collateral_asset = validators.validate_address(collateral_asset)
 
-        clearing_contract = ClearingDiamond(self._w3)
-        tx_hash = clearing_contract.initiate_final_settlement(
-            HexBytes(product_id), addresses
-        ).transact()
-        self._w3.eth.wait_for_transaction_receipt(tx_hash)
-        return Web3.to_hex(tx_hash)
+        converted_bids = [
+            BidData(
+                product_id=HexBytes(bid.product_id),
+                price=int(bid.price * 10 ** self._tick_size(bid.product_id)),
+                quantity=bid.quantity,
+                side=getattr(OnChainOrderSide, bid.side.name),
+            )
+            for bid in bids
+        ]
+
+        clearing_contract = ClearingDiamond(
+            self._w3, self._config.clearing_diamond_address
+        )
+        return self._transact(
+            clearing_contract.bid_auction(
+                margin_account_id, collateral_asset, converted_bids
+            )
+        )
 
     ### Views ###
 
@@ -181,7 +227,9 @@ class Clearing(ClearingSystemAPI):
         Decimal
         """
         collateral_asset = validators.validate_address(collateral_asset)
-        amount = self._margin_contract(collateral_asset).capital(self._account.address)
+        amount = self._margin_contract(collateral_asset).capital(
+            self._authenticator.address
+        )
         return Decimal(amount) / 10 ** self._decimals(collateral_asset)
 
     @convert_web3_error(MARGIN_CONTRACT_ABI)
@@ -202,7 +250,7 @@ class Clearing(ClearingSystemAPI):
         """
         validators.validate_hexstr32(position_id)
         data = self._margin_contract(collateral_asset).position_data(
-            self._account.address, HexBytes(position_id)
+            self._authenticator.address, HexBytes(position_id)
         )
         decimals = self._decimals(collateral_asset)
         return Position(
@@ -229,12 +277,12 @@ class Clearing(ClearingSystemAPI):
         """
         collateral_asset = validators.validate_address(collateral_asset)
         position_ids = self._margin_contract(collateral_asset).positions(
-            self._account.address
+            self._authenticator.address
         )
         return [self.position(collateral_asset, Web3.to_hex(id)) for id in position_ids]
 
     @convert_web3_error(MARGIN_CONTRACT_ABI)
-    def margin_account_equity(self, collateral_asset: str) -> Decimal:
+    def equity(self, collateral_asset: str) -> Decimal:
         """Returns the margin account equity in the margin account associated with the
         collateral asset.
 
@@ -248,7 +296,9 @@ class Clearing(ClearingSystemAPI):
         Decimal
         """
         collateral_asset = validators.validate_address(collateral_asset)
-        amount = self._margin_contract(collateral_asset).mae(self._account.address)
+        amount = self._margin_contract(collateral_asset).mae(
+            self._authenticator.address
+        )
         return Decimal(amount) / 10 ** self._decimals(collateral_asset)
 
     @convert_web3_error(MARGIN_CONTRACT_ABI)
@@ -266,7 +316,9 @@ class Clearing(ClearingSystemAPI):
         Decimal
         """
         collateral_asset = validators.validate_address(collateral_asset)
-        amount = self._margin_contract(collateral_asset).mma(self._account.address)
+        amount = self._margin_contract(collateral_asset).mma(
+            self._authenticator.address
+        )
         return Decimal(amount) / 10 ** self._decimals(collateral_asset)
 
     @convert_web3_error(MARGIN_CONTRACT_ABI)
@@ -284,7 +336,9 @@ class Clearing(ClearingSystemAPI):
         Decimal
         """
         collateral_asset = validators.validate_address(collateral_asset)
-        amount = self._margin_contract(collateral_asset).mmu(self._account.address)
+        amount = self._margin_contract(collateral_asset).mmu(
+            self._authenticator.address
+        )
         return Decimal(amount) / 10 ** self._decimals(collateral_asset)
 
     @convert_web3_error(MARGIN_CONTRACT_ABI)
@@ -302,7 +356,9 @@ class Clearing(ClearingSystemAPI):
         Decimal
         """
         collateral_asset = validators.validate_address(collateral_asset)
-        amount = self._margin_contract(collateral_asset).pnl(self._account.address)
+        amount = self._margin_contract(collateral_asset).pnl(
+            self._authenticator.address
+        )
         return Decimal(amount) / 10 ** self._decimals(collateral_asset)
 
     @convert_web3_error(MARGIN_CONTRACT_ABI)
@@ -321,51 +377,56 @@ class Clearing(ClearingSystemAPI):
         """
         collateral_asset = validators.validate_address(collateral_asset)
         amount = self._margin_contract(collateral_asset).withdrawable(
-            self._account.address
+            self._authenticator.address
         )
         return Decimal(amount) / 10 ** self._decimals(collateral_asset)
 
-    @convert_web3_error(PRODUCT_REGISTRY_ABI)
-    def collateral_asset(self, product_id: str) -> str:
-        """Returns the collateral asset of a product.
+    @convert_web3_error(CLEARING_DIAMOND_ABI)
+    def auction_data(
+        self, margin_account_id: str, collateral_asset: str
+    ) -> AuctionData:
+        """Returns information on a liquidation auction.
 
         Parameters
         ----------
-        product_id : str
-            The ID of the product.
+        margin_account_id : str
+            The ID of the margin account to be liquidated.
+        collateral_asset : str
+            The address of the collateral token that the margin account is trading with.
 
         Returns
         -------
         str
+            The hash of the transaction.
         """
-        product_registry_contract = ProductRegistry(self._w3)
-        collateral_asset = product_registry_contract.collateral_asset(
-            HexBytes(product_id)
-        )
-        if Web3.to_int(hexstr=collateral_asset) == 0:
-            raise NotFoundError("Product not found in the product registry")
-        return collateral_asset
-
-    def product_state(self, product_id: str) -> str:
-        """Returns the current state of a product.
-
-        Parameters
-        ----------
-        product_id : str
-            The ID of the product.
+        margin_account_id = validators.validate_address(margin_account_id)
+        collateral_asset = validators.validate_address(collateral_asset)
 
-        Returns
-        -------
-        str
-        """
-        return Builder.product_state(self, product_id)
+        clearing_contract = ClearingDiamond(
+            self._w3, self._config.clearing_diamond_address
+        )
+        data = clearing_contract.auction_data(margin_account_id, collateral_asset)
+        divisor = 10 ** self._decimals(collateral_asset)
+        return AuctionData(
+            start_block=data.start_block,
+            margin_account_equity_at_initiation=(
+                Decimal(data.mae_at_initiation) / divisor
+            ),
+            maintenance_margin_used_at_initiation=(
+                Decimal(data.mmu_at_initiation) / divisor
+            ),
+            margin_account_equity_now=(Decimal(data.mae_now) / divisor),
+            maintenance_margin_used_now=(Decimal(data.mmu_now) / divisor),
+        )
 
     ### Internal getters ###
 
     @cache
     @convert_web3_error(MARGIN_ACCOUNT_REGISTRY_ABI)
-    def _margin_contract(self, collateral_asset: ChecksumAddress) -> MarginAccount:
-        margin_account_registry_contract = MarginAccountRegistry(self._w3)
+    def _margin_contract(self, collateral_asset: ChecksumAddress) -> MarginContract:
+        margin_account_registry_contract = MarginAccountRegistry(
+            self._w3, self._config.margin_account_registry_address
+        )
         try:
             margin_contract_address = (
                 margin_account_registry_contract.get_margin_account(
@@ -374,4 +435,11 @@ class Clearing(ClearingSystemAPI):
             )
         except ContractCustomError:
             raise NotFoundError("No margin account found for collateral asset")
-        return MarginAccount(self._w3, margin_contract_address)
+        return MarginContract(self._w3, margin_contract_address)
+
+    @cache
+    def _tick_size(self, product_id: str) -> int:
+        product_registry_contract = ProductRegistry(
+            self._w3, self._config.product_registry_address
+        )
+        return product_registry_contract.tick_size(HexBytes(product_id))

afp/api/{builder.py → product.py}

@@ -6,31 +6,27 @@ from eth_typing.evm import ChecksumAddress
 from hexbytes import HexBytes
 from web3 import Web3
 
-from .. import config, signing, validators
+from .. import constants, hashing, validators
 from ..bindings import (
+    ClearingDiamond,
     OracleSpecification,
-    Product,
+    Product as OnChainProduct,
     ProductMetadata,
     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
+from ..schemas import ProductSpecification, Transaction
 from .base import ClearingSystemAPI
 
 
-class Builder(ClearingSystemAPI):
-    """API for building and submitting new products.
+class Product(ClearingSystemAPI):
+    """API for managing products."""
 
-    Parameters
-    ----------
-    private_key : str
-        The private key of the blockchain account that submits the product.
-    autonity_rpc_url : str
-        The URL of a JSON-RPC provider for Autonity. (HTTPS only.)
-    """
+    ### Factories ###
 
     @convert_web3_error()
     def create_product(
@@ -38,7 +34,6 @@ class Builder(ClearingSystemAPI):
         *,
         symbol: str,
         description: str,
-        oracle_address: str,
         fsv_decimals: int,
         fsp_alpha: Decimal,
         fsp_beta: Decimal,
@@ -53,6 +48,7 @@ class Builder(ClearingSystemAPI):
         auction_bounty: Decimal,
         tradeout_interval: int,
         extended_metadata: str,
+        oracle_address: str | None = None,
     ) -> ProductSpecification:
         """Creates a product specification with the given product data.
 
@@ -63,7 +59,6 @@ class Builder(ClearingSystemAPI):
         ----------
         symbol : str
         description : str
-        oracle_address: str
         fsv_decimals: int
         fsp_alpha: Decimal
         fsp_beta: int
@@ -78,25 +73,30 @@ class Builder(ClearingSystemAPI):
         auction_bounty : Decimal
         tradeout_interval : int
         extended_metadata : str
+        oracle_address: str, optional
 
         Returns
         -------
         afp.schemas.ProductSpecification
         """
-        product_id = Web3.to_hex(signing.generate_product_id(self._account, symbol))
+        if oracle_address is None:
+            oracle_address = self._config.oracle_provider_address
 
-        erc20_contract = ERC20(self._w3, Web3.to_checksum_address(collateral_asset))
-        price_quotation = erc20_contract.symbol()
-
-        if not price_quotation:
+        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}")
 
+        erc20_contract = ERC20(self._w3, Web3.to_checksum_address(collateral_asset))
+        price_quotation = erc20_contract.symbol()
+
+        product_id = Web3.to_hex(
+            hashing.generate_product_id(self._authenticator.address, symbol)
+        )
+
         return ProductSpecification(
             id=product_id,
-            builder_id=self._account.address,
+            builder_id=self._authenticator.address,
             symbol=symbol,
             description=description,
             oracle_address=oracle_address,
@@ -117,8 +117,10 @@ class Builder(ClearingSystemAPI):
             extended_metadata=extended_metadata,
         )
 
+    ### Transactions ###
+
     @convert_web3_error(PRODUCT_REGISTRY_ABI)
-    def register_product(self, product: ProductSpecification) -> str:
+    def register_product(self, product: ProductSpecification) -> Transaction:
         """Submits a product specification to the clearing system.
 
         Parameters
@@ -127,20 +129,56 @@ class Builder(ClearingSystemAPI):
 
         Returns
         -------
-        str
-            The hash of the transaction.
+        afp.schemas.Transaction
+            Transaction parameters.
         """
         erc20_contract = ERC20(
             self._w3, cast(ChecksumAddress, product.collateral_asset)
         )
         decimals = erc20_contract.decimals()
 
-        product_registry_contract = ProductRegistry(self._w3)
-        tx_hash = product_registry_contract.register(
-            self._convert_product_specification(product, decimals)
-        ).transact()
-        self._w3.eth.wait_for_transaction_receipt(tx_hash)
-        return Web3.to_hex(tx_hash)
+        product_registry_contract = ProductRegistry(
+            self._w3, self._config.product_registry_address
+        )
+        return self._transact(
+            product_registry_contract.register(
+                self._convert_product_specification(product, decimals)
+            )
+        )
+
+    @convert_web3_error(CLEARING_DIAMOND_ABI)
+    def initiate_final_settlement(
+        self, product_id: str, accounts: list[str]
+    ) -> Transaction:
+        """Initiate final settlement (closeout) process for the specified accounts.
+
+        The product must be in Final Settlement state. The accounts must hold non-zero
+        positions in the product that offset each other (i.e. the sum of their position
+        sizes is 0.)
+
+        Parameters
+        ----------
+        product_id : str
+            The ID of the product.
+        accounts : list of str
+            List of margin account IDs to initiate settlement for.
+
+        Returns
+        -------
+        afp.schemas.Transaction
+            Transaction parameters.
+        """
+        product_id = validators.validate_hexstr32(product_id)
+        addresses = [validators.validate_address(account) for account in accounts]
+
+        clearing_contract = ClearingDiamond(
+            self._w3, self._config.clearing_diamond_address
+        )
+        return self._transact(
+            clearing_contract.initiate_final_settlement(HexBytes(product_id), addresses)
+        )
+
+    ### Views ###
 
     @convert_web3_error(PRODUCT_REGISTRY_ABI)
     def product_state(self, product_id: str) -> str:
@@ -156,15 +194,43 @@ class Builder(ClearingSystemAPI):
         str
         """
         product_id = validators.validate_hexstr32(product_id)
-        product_registry_contract = ProductRegistry(self._w3)
+        product_registry_contract = ProductRegistry(
+            self._w3, self._config.product_registry_address
+        )
         state = product_registry_contract.state(HexBytes(product_id))
         return state.name
 
+    @convert_web3_error(PRODUCT_REGISTRY_ABI)
+    def collateral_asset(self, product_id: str) -> str:
+        """Returns the collateral asset of a product.
+
+        Parameters
+        ----------
+        product_id : str
+            The ID of the product.
+
+        Returns
+        -------
+        str
+        """
+        product_id = validators.validate_hexstr32(product_id)
+        product_registry_contract = ProductRegistry(
+            self._w3, self._config.product_registry_address
+        )
+        collateral_asset = product_registry_contract.collateral_asset(
+            HexBytes(product_id)
+        )
+        if Web3.to_int(hexstr=collateral_asset) == 0:
+            raise NotFoundError("Product not found in the product registry")
+        return collateral_asset
+
+    ### Internal helpers ###
+
     @staticmethod
     def _convert_product_specification(
         product: ProductSpecification, decimals: int
-    ) -> Product:
-        return Product(
+    ) -> OnChainProduct:
+        return OnChainProduct(
             metadata=ProductMetadata(
                 builder=cast(ChecksumAddress, product.builder_id),
                 symbol=product.symbol,
@@ -173,7 +239,7 @@ class Builder(ClearingSystemAPI):
             oracle_spec=OracleSpecification(
                 oracle_address=cast(ChecksumAddress, product.oracle_address),
                 fsv_decimals=product.fsv_decimals,
-                fsp_alpha=int(product.fsp_alpha * config.FULL_PRECISION_MULTIPLIER),
+                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),
             ),
@@ -186,12 +252,12 @@ class Builder(ClearingSystemAPI):
             tick_size=product.tick_size,
             unit_value=int(product.unit_value * 10**decimals),
             initial_margin_requirement=int(
-                product.initial_margin_requirement * config.RATE_MULTIPLIER
+                product.initial_margin_requirement * constants.RATE_MULTIPLIER
             ),
             maintenance_margin_requirement=int(
-                product.maintenance_margin_requirement * config.RATE_MULTIPLIER
+                product.maintenance_margin_requirement * constants.RATE_MULTIPLIER
             ),
-            auction_bounty=int(product.auction_bounty * config.RATE_MULTIPLIER),
+            auction_bounty=int(product.auction_bounty * constants.RATE_MULTIPLIER),
             tradeout_interval=product.tradeout_interval,
             extended_metadata=product.extended_metadata,
         )