flexvaults 0.1.5__py3-none-any.whl

flexvaults/__init__.py

@@ -0,0 +1,168 @@
+from .client import (
+    AccountingApiError,
+    FlexvaultsClient,
+    HttpClient,
+    NetworkError,
+    ValidationError,
+)
+from .signatures import (
+    LOCK_TYPES,
+    TRANSFER_LOCKED_TYPES,
+    TRANSFER_TYPES,
+    WITHDRAW_TYPES,
+    EIP712Domain,
+    LockMessage,
+    SignLockParams,
+    SignTransferLockedParams,
+    SignTransferParams,
+    SignWithdrawParams,
+    TransferLockedMessage,
+    TransferMessage,
+    WithdrawMessage,
+    create_domain,
+    create_lock_expiry,
+    sign_lock_message,
+    sign_transfer_locked_message,
+    sign_transfer_message,
+    sign_withdraw_message,
+)
+from .types import (
+    NETWORK_CONFIG,
+    SUPPORTED_CHAINS,
+    SUPPORTED_TOKENS,
+    Address,
+    BalanceResponse,
+    BatchBalancesRequest,
+    BatchBalancesResponse,
+    Bytes32,
+    ChainConfig,
+    DepositQuoteRequest,
+    DepositQuoteResponse,
+    ExpiredLocksResponse,
+    HexString,
+    IncludeDepositRequest,
+    IncludeDepositResponse,
+    LockedFundsResponse,
+    LockFundsRequest,
+    LockInfo,
+    Network,
+    NetworkConfig,
+    PendingWithdrawal,
+    PendingWithdrawalsResponse,
+    SupportedToken,
+    TokenBalance,
+    TokenConfig,
+    TokenInfoResponse,
+    TotalLockedBalanceResponse,
+    TransactionData,
+    TransactionSubmissionResponse,
+    TransferFundsRequest,
+    TransferLockedFundsRequest,
+    UnlockAllExpiredRequest,
+    UnlockFundsRequest,
+    WithdrawalInfoResponse,
+    WithdrawalRequest,
+    get_accounting_contract,
+    get_all_tokens,
+    get_api_url,
+    get_chain_by_id,
+    get_chain_id,
+    get_explorer_address_url,
+    get_token_by_id,
+    get_token_config,
+    is_valid_token,
+    normalize_address,
+    normalize_hex,
+)
+from .utils import (
+    format_relative_time,
+    format_time_remaining,
+    format_timestamp,
+    format_token_amount,
+    is_expired,
+    parse_token_amount,
+    shorten_address,
+)
+
+__version__ = "0.1.5"
+
+__all__ = [
+    "__version__",
+    "Address",
+    "Bytes32",
+    "HexString",
+    "Network",
+    "NetworkConfig",
+    "NETWORK_CONFIG",
+    "get_chain_id",
+    "get_accounting_contract",
+    "get_api_url",
+    "normalize_hex",
+    "normalize_address",
+    "TokenConfig",
+    "SupportedToken",
+    "SUPPORTED_TOKENS",
+    "get_token_config",
+    "get_token_by_id",
+    "is_valid_token",
+    "ChainConfig",
+    "SUPPORTED_CHAINS",
+    "get_chain_by_id",
+    "get_explorer_address_url",
+    "get_all_tokens",
+    "DepositQuoteRequest",
+    "IncludeDepositRequest",
+    "LockFundsRequest",
+    "UnlockFundsRequest",
+    "UnlockAllExpiredRequest",
+    "TransferFundsRequest",
+    "TransferLockedFundsRequest",
+    "WithdrawalRequest",
+    "BatchBalancesRequest",
+    "TransactionData",
+    "DepositQuoteResponse",
+    "IncludeDepositResponse",
+    "TransactionSubmissionResponse",
+    "BalanceResponse",
+    "TokenBalance",
+    "BatchBalancesResponse",
+    "TokenInfoResponse",
+    "LockInfo",
+    "LockedFundsResponse",
+    "ExpiredLocksResponse",
+    "TotalLockedBalanceResponse",
+    "PendingWithdrawal",
+    "PendingWithdrawalsResponse",
+    "WithdrawalInfoResponse",
+    "FlexvaultsClient",
+    "HttpClient",
+    "AccountingApiError",
+    "NetworkError",
+    "ValidationError",
+    "EIP712Domain",
+    "create_domain",
+    "LOCK_TYPES",
+    "TRANSFER_TYPES",
+    "TRANSFER_LOCKED_TYPES",
+    "WITHDRAW_TYPES",
+    "LockMessage",
+    "TransferMessage",
+    "TransferLockedMessage",
+    "WithdrawMessage",
+    "SignLockParams",
+    "sign_lock_message",
+    "create_lock_expiry",
+    "SignTransferParams",
+    "sign_transfer_message",
+    "SignTransferLockedParams",
+    "sign_transfer_locked_message",
+    "SignWithdrawParams",
+    "sign_withdraw_message",
+    "format_token_amount",
+    "parse_token_amount",
+    "shorten_address",
+    "format_timestamp",
+    "is_expired",
+    "format_time_remaining",
+    "format_relative_time",
+]

flexvaults/client/__init__.py

@@ -0,0 +1,11 @@
+from .errors import AccountingApiError, NetworkError, ValidationError
+from .flexvaults_client import FlexvaultsClient
+from .http_client import HttpClient
+
+__all__ = [
+    "AccountingApiError",
+    "NetworkError",
+    "ValidationError",
+    "HttpClient",
+    "FlexvaultsClient",
+]

flexvaults/client/errors.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+
+class AccountingApiError(Exception):
+    def __init__(
+        self,
+        message: str,
+        status_code: int,
+        detail: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.detail = detail
+
+
+class NetworkError(Exception):
+    def __init__(
+        self,
+        message: str,
+        cause: Exception | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.__cause__ = cause
+
+
+class ValidationError(Exception):
+    def __init__(
+        self,
+        message: str,
+        field: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.field = field

flexvaults/client/flexvaults_client.py

@@ -0,0 +1,358 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..types import (
+    normalize_address,
+    normalize_hex,
+)
+from ..types.requests import (
+    BatchBalancesRequest,
+    DepositQuoteRequest,
+    IncludeDepositRequest,
+    LockFundsRequest,
+    TransferFundsRequest,
+    TransferLockedFundsRequest,
+    UnlockAllExpiredRequest,
+    UnlockFundsRequest,
+    WithdrawalRequest,
+)
+from ..types.responses import (
+    BalanceResponse,
+    BatchBalancesResponse,
+    DepositQuoteResponse,
+    ExpiredLocksResponse,
+    IncludeDepositResponse,
+    LockedFundsResponse,
+    LockInfo,
+    PendingWithdrawal,
+    PendingWithdrawalsResponse,
+    TokenBalance,
+    TokenInfoResponse,
+    TotalLockedBalanceResponse,
+    TransactionData,
+    TransactionSubmissionResponse,
+    WithdrawalInfoResponse,
+)
+from .http_client import HttpClient
+
+
+def _parse_transaction_data(data: dict[str, Any]) -> TransactionData:
+    return TransactionData(
+        to=data["to"],
+        value=data["value"],
+        data=data["data"],
+        chain_id=data["chain_id"],
+    )
+
+
+def _parse_deposit_quote(data: dict[str, Any]) -> DepositQuoteResponse:
+    return DepositQuoteResponse(
+        user_address=data["user_address"],
+        token_id=data["token_id"],
+        amount=data["amount"],
+        deposit_address=data["deposit_address"],
+        transaction=_parse_transaction_data(data["transaction"]),
+        instructions=data["instructions"],
+    )
+
+
+def _parse_lock_info(data: dict[str, Any]) -> LockInfo:
+    return LockInfo(
+        lock_index=data["lock_index"],
+        user_address=data["user_address"],
+        service_address=data["service_address"],
+        token_id=data["token_id"],
+        amount=data["amount"],
+        expiry=data["expiry"],
+        is_expired=data["is_expired"],
+    )
+
+
+def _parse_token_balance(data: dict[str, Any]) -> TokenBalance:
+    return TokenBalance(
+        token_id=data["token_id"],
+        balance=data["balance"],
+        token_symbol=data["token_symbol"],
+        chain_id=data["chain_id"],
+    )
+
+
+def _parse_pending_withdrawal(data: dict[str, Any]) -> PendingWithdrawal:
+    return PendingWithdrawal(
+        index=data["index"],
+        user_address=data["user_address"],
+        token_id=data["token_id"],
+        amount=data["amount"],
+        status=data["status"],
+        created_at=data["created_at"],
+    )
+
+
+class FlexvaultsClient:
+    def __init__(
+        self,
+        base_url: str,
+        timeout: float = 30.0,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        self._http = HttpClient(
+            base_url=base_url,
+            timeout=timeout,
+            headers=headers,
+        )
+
+    async def get_deposit_quote(self, request: DepositQuoteRequest) -> DepositQuoteResponse:
+        data = await self._http.post(
+            "/v1/accounting/quote/deposit",
+            {
+                "user_address": normalize_address(request.user_address),
+                "token_id": normalize_hex(request.token_id),
+                "amount": request.amount,
+            },
+        )
+        return _parse_deposit_quote(data)
+
+    async def include_deposit(self, request: IncludeDepositRequest) -> IncludeDepositResponse:
+        body: dict[str, Any] = {
+            "user_address": normalize_address(request.user_address),
+            "token_id": normalize_hex(request.token_id),
+            "evm_transaction_data": normalize_hex(request.evm_transaction_data),
+        }
+        if request.rlp_block_header is not None:
+            body["rlp_block_header"] = normalize_hex(request.rlp_block_header)
+        if request.transaction_index_rlp is not None:
+            body["transaction_index_rlp"] = normalize_hex(request.transaction_index_rlp)
+        if request.transaction_proof_stack is not None:
+            body["transaction_proof_stack"] = normalize_hex(request.transaction_proof_stack)
+
+        data = await self._http.post("/v1/accounting/deposits", body)
+        return IncludeDepositResponse(
+            submission_id=data["submission_id"],
+            status=data["status"],
+        )
+
+    async def get_balance(
+        self,
+        user_address: str,
+        token_id: str,
+    ) -> BalanceResponse:
+        user = normalize_address(user_address)
+        token = normalize_hex(token_id)
+        data = await self._http.get(f"/v1/accounting/balances/{user}/{token}")
+        return BalanceResponse(
+            user_address=data["user_address"],
+            token_id=data["token_id"],
+            balance=data["balance"],
+            token_symbol=data["token_symbol"],
+            chain_id=data["chain_id"],
+        )
+
+    async def get_batch_balances(
+        self, request: BatchBalancesRequest
+    ) -> BatchBalancesResponse:
+        data = await self._http.post(
+            "/v1/accounting/balances/batch",
+            {
+                "user_address": normalize_address(request.user_address),
+                "token_ids": [normalize_hex(tid) for tid in request.token_ids],
+            },
+        )
+        return BatchBalancesResponse(
+            user_address=data["user_address"],
+            balances=[_parse_token_balance(b) for b in data.get("balances", [])],
+        )
+
+    async def get_token_info(self, token_id: str) -> TokenInfoResponse:
+        token = normalize_hex(token_id)
+        data = await self._http.get(f"/v1/accounting/tokens/{token}")
+        return TokenInfoResponse(
+            token_id=data["token_id"],
+            symbol=data["symbol"],
+            decimals=data["decimals"],
+            chain_id=data["chain_id"],
+            contract_address=data.get("contract_address"),
+        )
+
+    async def lock_funds(
+        self, request: LockFundsRequest
+    ) -> TransactionSubmissionResponse:
+        data = await self._http.post(
+            "/v1/accounting/funds/lock",
+            {
+                "user_address": normalize_address(request.user_address),
+                "service_address": normalize_address(request.service_address),
+                "token_id": normalize_hex(request.token_id),
+                "amount": request.amount,
+                "expiry": request.expiry,
+                "signature": normalize_hex(request.signature),
+            },
+        )
+        return TransactionSubmissionResponse(
+            submission_id=data["submission_id"],
+            status=data["status"],
+            detail=data.get("detail"),
+        )
+
+    async def unlock_funds(
+        self, request: UnlockFundsRequest
+    ) -> TransactionSubmissionResponse:
+        data = await self._http.post(
+            "/v1/accounting/funds/unlock",
+            {
+                "user_address": normalize_address(request.user_address),
+                "lock_index": request.lock_index,
+            },
+        )
+        return TransactionSubmissionResponse(
+            submission_id=data["submission_id"],
+            status=data["status"],
+            detail=data.get("detail"),
+        )
+
+    async def unlock_all_expired(
+        self, request: UnlockAllExpiredRequest
+    ) -> TransactionSubmissionResponse:
+        data = await self._http.post(
+            "/v1/accounting/funds/unlock-all-expired",
+            {
+                "user_address": normalize_address(request.user_address),
+            },
+        )
+        return TransactionSubmissionResponse(
+            submission_id=data["submission_id"],
+            status=data["status"],
+            detail=data.get("detail"),
+        )
+
+    async def get_locked_funds(
+        self,
+        user_address: str,
+        service_address: str | None = None,
+    ) -> LockedFundsResponse:
+        user = normalize_address(user_address)
+        query_params = ""
+        if service_address:
+            query_params = f"?service_address={normalize_address(service_address)}"
+        data = await self._http.get(f"/v1/accounting/funds/locked/{user}{query_params}")
+        return LockedFundsResponse(
+            user_address=data["user_address"],
+            service_address=data.get("service_address"),
+            locks=[_parse_lock_info(lock) for lock in data.get("locks", [])],
+            total_locked=data.get("total_locked", 0),
+        )
+
+    async def get_total_locked_balance(
+        self,
+        user_address: str,
+        token_id: str,
+    ) -> TotalLockedBalanceResponse:
+        user = normalize_address(user_address)
+        token = normalize_hex(token_id)
+        data = await self._http.get(
+            f"/v1/accounting/funds/locked/total/{user}/{token}"
+        )
+        return TotalLockedBalanceResponse(
+            user_address=data["user_address"],
+            token_id=data["token_id"],
+            total_locked=data["total_locked"],
+        )
+
+    async def get_expired_locks(self, user_address: str) -> ExpiredLocksResponse:
+        user = normalize_address(user_address)
+        data = await self._http.get(f"/v1/accounting/funds/expired/{user}")
+        return ExpiredLocksResponse(
+            user_address=data["user_address"],
+            expired_locks=[_parse_lock_info(lock) for lock in data.get("expired_locks", [])],
+        )
+
+    async def transfer_funds(
+        self, request: TransferFundsRequest
+    ) -> TransactionSubmissionResponse:
+        data = await self._http.post(
+            "/v1/accounting/funds/transfer",
+            {
+                "user_address": normalize_address(request.user_address),
+                "to_address": normalize_address(request.to_address),
+                "token_id": normalize_hex(request.token_id),
+                "amount": request.amount,
+                "signature": normalize_hex(request.signature),
+            },
+        )
+        return TransactionSubmissionResponse(
+            submission_id=data["submission_id"],
+            status=data["status"],
+            detail=data.get("detail"),
+        )
+
+    async def transfer_locked_funds(
+        self, request: TransferLockedFundsRequest
+    ) -> TransactionSubmissionResponse:
+        data = await self._http.post(
+            "/v1/accounting/funds/transfer-locked",
+            {
+                "user_address": normalize_address(request.user_address),
+                "lock_index": request.lock_index,
+                "to_address": normalize_address(request.to_address),
+                "amount": request.amount,
+                "signature": normalize_hex(request.signature),
+            },
+        )
+        return TransactionSubmissionResponse(
+            submission_id=data["submission_id"],
+            status=data["status"],
+            detail=data.get("detail"),
+        )
+
+    async def request_withdrawal(
+        self, request: WithdrawalRequest
+    ) -> TransactionSubmissionResponse:
+        data = await self._http.post(
+            "/v1/accounting/withdraw",
+            {
+                "user_address": normalize_address(request.user_address),
+                "token_id": normalize_hex(request.token_id),
+                "amount": request.amount,
+                "nonce": request.nonce,
+                "signature": normalize_hex(request.signature),
+            },
+        )
+        return TransactionSubmissionResponse(
+            submission_id=data["submission_id"],
+            status=data["status"],
+            detail=data.get("detail"),
+        )
+
+    async def get_pending_withdrawals(
+        self, user_address: str
+    ) -> PendingWithdrawalsResponse:
+        user = normalize_address(user_address)
+        data = await self._http.get(f"/v1/accounting/withdraw/pending/{user}")
+        return PendingWithdrawalsResponse(
+            user_address=data["user_address"],
+            withdrawals=[
+                _parse_pending_withdrawal(w) for w in data.get("withdrawals", [])
+            ],
+        )
+
+    async def get_withdrawal_info(self, index: int) -> WithdrawalInfoResponse:
+        data = await self._http.get(f"/v1/accounting/withdraw/{index}")
+        return WithdrawalInfoResponse(
+            index=data["index"],
+            user_address=data["user_address"],
+            token_id=data["token_id"],
+            amount=data["amount"],
+            status=data["status"],
+            created_at=data["created_at"],
+            completed_at=data.get("completed_at"),
+            transaction_hash=data.get("transaction_hash"),
+        )
+
+    async def close(self) -> None:
+        await self._http.close()
+
+    async def __aenter__(self) -> FlexvaultsClient:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()

flexvaults/client/http_client.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .errors import AccountingApiError, NetworkError
+
+
+class HttpClient:
+    def __init__(
+        self,
+        base_url: str,
+        timeout: float = 30.0,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._headers = {
+            "Content-Type": "application/json",
+            **(headers or {}),
+        }
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers=self._headers,
+            timeout=httpx.Timeout(self._timeout),
+        )
+
+    async def get(self, path: str) -> Any:
+        return await self._request("GET", path)
+
+    async def post(self, path: str, body: Any | None = None) -> Any:
+        return await self._request("POST", path, body)
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        body: Any | None = None,
+    ) -> Any:
+        try:
+            response = await self._client.request(
+                method=method,
+                url=path,
+                json=body,
+            )
+
+            if not response.is_success:
+                detail: str | None = None
+                try:
+                    error_body = response.json()
+                    detail = error_body.get("detail") or error_body.get("message")
+                except Exception:
+                    try:
+                        detail = response.text
+                    except Exception:
+                        pass
+
+                raise AccountingApiError(
+                    f"API request failed: {response.status_code} {response.reason_phrase}",
+                    response.status_code,
+                    detail,
+                )
+
+            return response.json()
+
+        except AccountingApiError:
+            raise
+        except httpx.TimeoutException:
+            raise NetworkError(f"Request timeout after {self._timeout}s")
+        except httpx.HTTPError as e:
+            raise NetworkError(f"Network request failed: {str(e)}", e)
+        except Exception as e:
+            if isinstance(e, (AccountingApiError, NetworkError)):
+                raise
+            cause = e if isinstance(e, Exception) else None
+            raise NetworkError(f"Unknown network error occurred: {str(e)}", cause)
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> HttpClient:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()

flexvaults/signatures/__init__.py

@@ -0,0 +1,38 @@
+from .eip712_types import (
+    LOCK_TYPES,
+    TRANSFER_LOCKED_TYPES,
+    TRANSFER_TYPES,
+    WITHDRAW_TYPES,
+    EIP712Domain,
+    LockMessage,
+    TransferLockedMessage,
+    TransferMessage,
+    WithdrawMessage,
+    create_domain,
+)
+from .sign_lock import SignLockParams, create_lock_expiry, sign_lock_message
+from .sign_transfer import SignTransferParams, sign_transfer_message
+from .sign_transfer_locked import SignTransferLockedParams, sign_transfer_locked_message
+from .sign_withdraw import SignWithdrawParams, sign_withdraw_message
+
+__all__ = [
+    "EIP712Domain",
+    "create_domain",
+    "LOCK_TYPES",
+    "TRANSFER_TYPES",
+    "TRANSFER_LOCKED_TYPES",
+    "WITHDRAW_TYPES",
+    "LockMessage",
+    "TransferMessage",
+    "TransferLockedMessage",
+    "WithdrawMessage",
+    "SignLockParams",
+    "sign_lock_message",
+    "create_lock_expiry",
+    "SignTransferParams",
+    "sign_transfer_message",
+    "SignTransferLockedParams",
+    "sign_transfer_locked_message",
+    "SignWithdrawParams",
+    "sign_withdraw_message",
+]